ra-h-os/apps/mcp-server-standalone/skills/onboarding.md

---
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 bootstrap the context capsule when durable cross-session facts become clear.

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.

## Capsule Bootstrap

As part of onboarding, also bootstrap the context capsule on the user's behalf.

When the user gives durable identity, preference, worldview, project, or agent-behavior information:

1. Call `readSkill('context-capsule')`
2. Call `readCapsule`
3. When you have enough confidence, call `writeCapsule`

Use the capsule for:
- preferred name
- agent name or greeting preference
- interaction style
- major projects
- major interests
- explicit worldview or belief signals
- what the user is using RA-H for

Do not write the capsule for tentative, one-off, or low-confidence statements.
Keep it compressed and canonical. Replace stale instructions instead of preserving contradictory history.

## 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:

- **Contexts** — an optional soft organization layer. These are broad areas like health, job, life, or research. A node can belong to one context when it is explicit and useful, but context is not required.
- **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, clear contexts when they matter, 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.
- **Contexts** — explain that contexts are optional helpers, not required setup. If the user has none, that is fine.
- **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.
- Assign a context only when it is an obvious match to one of the user's existing contexts. Prefer leaving context empty over low-confidence guessing.
- 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"
- Contexts are optional and should only be used for an obvious existing match; otherwise leave them empty
- 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 contexts with one-line rationale], [list starter nodes], [list key edges]. Does this look right? Anything to adjust?"

Write only after confirmation.

If onboarding also surfaced durable cross-session facts, include the capsule update in the proposal:

> "I also plan to bootstrap your context capsule with your name, interaction preferences, and current priorities so future chats start grounded. Sound right?"
> "I also plan to bootstrap your context capsule with your name and interaction preferences so future chats start grounded. Sound right?"

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