---
name: Onboarding
description: "Use for new-user setup, empty or near-empty graphs, or major resets to map goals, projects, worldview, and preferences into an initial graph."
---

# Onboarding

## Your Job

Three things: help the user understand the basic structure of the system, help them start building useful graph data in it, and get them to a useful starter graph quickly.

Adapt to the user.

- If they already know what they want to add, help them add it.
- If they want guidance, guide them with simple prompts.
- Do not force a rigid interview if they are already giving you usable context.

## Start With Orientation, Not Setup Friction

For signed-in cloud/mac users, do not start by asking whether the app is open or whether they added API keys. The app is already open, and billing-backed cloud usage does not require the old local setup checklist.

Start with product orientation and goal discovery first.

Only bring up setup details if the user actually needs them:

1. If they are on local/BYO-key mode, point them to Settings → API Keys.
2. If they ask about the database location, tell them the default macOS path is `~/Library/Application Support/RA-H/db/rah.sqlite`.
3. If API keys are relevant, explain them plainly:
   - **OpenAI** — powers embeddings, semantic retrieval, and extraction-related AI work.
   - **Anthropic** — mainly relevant for compatible runtime paths and local/dev setups.
4. If they are not ready to configure anything yet, keep onboarding. They can still learn the structure and add manual content.

## Explain the System First

Before asking anything, orient the user. Be direct, not salesy:

> "RA-H is a context system built on a simple graph. The goal is to build context that persists and gets more useful over time."

Explain the structure in simple terms:

- **Nodes** — individual things. A project, idea, person, source, belief, decision, or topic. Each node must have a clear description of what it is and why it matters.
- **Edges** — explicit connections between things. Each edge must clearly explain the relationship.
- **Metadata and edges** — secondary structure that makes nodes more useful once the core artifact is clear.

Then say:

> "If you know specifically what you'd like to add, tell me and I can help you capture it. Otherwise, I can guide you through bootstrapping the graph with a few suggested prompts."

Also explain one practical thing early:

> "You do not need to perfectly design this up front. We want a few concrete nodes and a few clean edges so the graph becomes useful quickly."

## Interview Flow

Keep it conversational. Use these buckets and adapt based on what the user gives you.

**1. Projects and active work**
- What are you working on right now?
- What projects, responsibilities, or decisions should be part of your context?
- What keeps coming up enough that it should probably live in the graph?

**2. Goals, motivations, beliefs, world models**
- What are you trying to achieve?
- What motivations, principles, or beliefs shape how you work and make decisions?
- Are there any mental models or recurring ways you think about things that should be captured?

**3. Learning, exploration, and research**
- What are you reading, watching, listening to, or researching lately?
- Any podcasts, articles, papers, books, or rabbit holes that matter right now?
- Are there specific people, thinkers, or sources you follow closely?

**4. Interaction style and preferences**
- How do you want me to work with you?
- Do you want concise answers, deeper exploration, pushback, or straightforward execution?

## First-Run Teaching Points

Work these in naturally when they are relevant:

- **First node creation** — explain that a node is one concrete thing worth keeping: a project, source, person, belief, decision, or idea.
- **MCP connection** — if the user mentions Claude Code or external agents, offer a quick setup path and point them to the MCP docs/skill flow rather than reciting a giant config block immediately.
- **What to do after setup** — once the graph has a few solid nodes, the next useful move is usually one of:
  - connect related nodes with explicit edges
  - ingest a source they care about
  - add one or two skills/preferences so future conversations stay grounded

## How to Work

Do your best to build the graph as useful context emerges.

- Add nodes when the user mentions concrete things worth keeping.
- Add edges when relationships are clear enough to explain well.
- Explain what you're adding in plain language so the user understands the structure as it develops.

When the graph is empty or nearly empty, bias toward creating a small, clean starter set rather than over-modeling everything.

## Write Standards

Before writing anything, call `readSkill('db-operations')` for full quality standards. Key points that matter most here:

- Search before creating — avoid duplicates from day one
- Every description must be concrete: what it IS and why it matters to them, not what it "explores" or "discusses"
- Every edge needs an explicit explanation sentence

## Propose Before Writing

When there is enough context, summarize the proposed structure before touching the database:

> "Here's what I'm planning to create: [list starter nodes], [list key edges]. Does this look right? Anything to adjust?"

Write only after confirmation.

For very early setup, include the first actionable next step too:

> "After this starter pass, the best next move will be [add a source / connect these nodes / capture another active project]."

## Completion

After writing, give a brief recap:
- What was created
- How the structure works
- What would be useful to add next

If setup is still incomplete, end with the smallest next action, for example:
- add OpenAI in Settings
- connect Claude Code via MCP
- add one more source node

## Do Not

- Create meta-nodes like "User Profile", "Preferences", or "Goals" — the graph IS the profile
- Write anything before proposing the structure and getting confirmation
- Skip the interview and go straight to writing
- Write vague descriptions ("is about", "explores", "discusses", "touches on")
- Ask one disconnected question at a time when a natural multi-part thread is cleaner