feat: port holistic node refinement contract

apps/mcp-server-standalone/skills/audit.md

@@ -9,7 +9,7 @@ description: "Use for structured review, QA, cleanup, or governance checks acros
 
 1. Node quality: duplicates, vague descriptions, missing dates, weak titles.
 2. Edge quality: missing links, weak explanations, wrong directionality.
-3. Dimension quality: drift, overlap, low-signal categories.
+3. Context quality: drift, overlap, low-signal buckets, or contexts being overused where stronger node metadata should carry the meaning.
 4. Skill quality: trigger clarity, overlap, dead/unused skills.
 
 ## Output Format

apps/mcp-server-standalone/skills/db-operations.md

@@ -1,6 +1,6 @@
 ---
 name: DB Operations
-description: "Use this for all graph read/write operations with strict data quality standards."
+description: "Use for graph read, write, connect, classify, or traverse operations with strict data quality standards."
 ---
 
 # DB Operations
@@ -8,30 +8,72 @@ description: "Use this for all graph read/write operations with strict data qual
 ## Core Rules
 
 1. Search before create to avoid duplicates.
-2. Every create/update should aim for a natural description that makes clear what the thing is and any surrounding context available, but description quality is guidance only. RA-H should never block or rewrite a write because of description quality.
+2. Always try to include a natural description that clearly says what the thing is and any surrounding context available. But description quality is guidance only; RA-H should never block or rewrite a write because of description quality.
 3. Use event dates when known (when it happened, not when saved).
-4. Apply dimensions deliberately; prefer existing dimensions over creating noisy new ones.
+4. Apply contexts only when they are explicit and helpful. One node gets at most one context. If explicit context is missing on create, leave it empty instead of guessing.
+5. Do not rely on dimensions. Node quality comes from title, description, source, metadata, and strong edges.
 5. Create edges when relationships are meaningful; edge explanations should read as a sentence.
+6. For user-authored ideas, notes, or dictated thoughts, preserve the user's wording in `source` as fully as possible with only minimal cleanup.
 
 ## Write Quality Contract
 
 - `title`: clear and specific.
-- `description`: natural prose, not labels. It should still make what / why / status clear when possible.
-- `source`: full verbatim or canonical content of the node (transcript, article text, book passage, user's thoughts). This is what gets chunked and embedded for semantic search. For user-authored ideas or dictated notes, preserve the user's original wording with minimal cleanup.
+- `description`: concrete object-level description, not vague summaries.
+- `source`: full verbatim or canonical content of the node (transcript, article text, book passage, user's thoughts). This is what gets chunked and embedded for semantic search.
+- For idea capture from chat, the `source` should usually be the raw user thought, not a compressed assistant summary.
 - `link`: external source URL only.
-- `metadata`: prefer canonical keys `type`, `state`, `captured_method`, `captured_by`, and `source_metadata`.
+- `context_id`: the node's primary context. Prefer setting it when the scope is explicit. Leave it null rather than guessing.
+- `metadata`: use the canonical node metadata contract when metadata is needed:
+  - `type`
+  - `state` (`processed` or `not_processed`)
+  - `captured_method`
+  - `captured_by`
+  - `source_metadata`
+- `source_metadata`: factual source-specific details only. Keep it compact. No AI summaries or reasoning text.
+- metadata updates are merge-safe patches, not full-blob replacements. Do not assume `updateNode.metadata` wipes existing keys.
+- Derived analysis, briefs, and research notes should be stored in a separate linked node, not appended to the source node.
+
+## Description Standard
+
+Every node description should read like natural prose, not a template or checklist.
+
+It must still make three things clear:
+1. What — what the artifact is in simple explicit terms (format + creator + core claim)
+2. Why — why it is in the graph; what Brad is interested in; what it connects to
+3. Status — where it sits in his workflow (queued, in progress, processed, unknown)
+
+If the agent has graph context (active context, context anchor, context capsule, focused nodes), it should infer the why from that context and write it naturally.
+
+If the why genuinely cannot be inferred, say that naturally. Do not use labels like `WHAT:`, `WHY:`, or `STATUS:` and do not substitute vague filler like `insightful for understanding` or `relevant to Brad's work`.
+
+If status is unknown, say naturally that it has not been reviewed yet.
+
+Ask a clarification question only when a missing detail would materially change the node being created. If the user has already given enough substance to infer the artifact, title, and likely why, do the work instead of bouncing it back.
+
+For user-authored idea capture, do not treat the inferred description as final if the "why" or status was mostly inferred. Save the node first, then tell the user what description framing you inferred and invite one short correction pass on:
+- what this is
+- why it belongs here
+- where it sits in their workflow
+
+Keep it concise, but do not block the write over length or quality.
+
+## Metadata Semantics
+
+- Direct user creation, quick add, and user-requested agent capture should default to `captured_by = "human"`.
+- Only autonomous/background creation without direct user instruction should use `captured_by = "agent"`.
+- Prefer leaving `type` blank over forcing a weak label.
+- `state` is the user-visible processed flag. If no state is known, default to `not_processed`.
 
 ## Execution Pattern
 
 1. Read context (search + relevant nodes + relevant edges).
 2. Decide: create vs update vs connect.
 3. Execute minimum required writes.
-4. Verify result reflects user intent exactly.
-5. If description framing was materially inferred, complete the write first and then invite one concise user feedback pass instead of blocking creation.
+4. If the node is a user-authored idea and the contextual framing was inferred, offer one concise feedback pass after the write.
+5. Verify result reflects user intent exactly.
 
 ## Do Not
 
 - Create duplicate nodes when an update is correct.
 - Write vague descriptions ("discusses", "explores", "is about").
-- Replace a user's raw idea/source with a thin summary.
 - Create weak or directionless edges.

apps/mcp-server-standalone/skills/node-context-enrichment.md

@@ -1,6 +1,6 @@
 ---
 name: Node Context Enrichment
-description: "Use to rewrite thin node descriptions into natural prose that still makes what, why, and status clear, with dimension review and edge suggestions."
+description: "Use to rewrite thin node descriptions into natural prose that still makes what, why, and status clear, with context review and edge suggestions."
 ---
 
 # Node Context Enrichment
@@ -17,15 +17,21 @@ Replace weak descriptions with a single clean natural description that captures:
 2. Why it is in Brad's graph
 3. Status in Brad's workflow
 
-Also review whether the node needs dimension fixes or obvious edge suggestions.
+Also review whether the node needs context cleanup or obvious edge suggestions.
 
 ## Workflow
 
-1. Load the node and inspect title, description, source, link, metadata, dimensions, and nearby edges.
-2. Search for adjacent context before rewriting.
+1. Load the node and inspect title, description, source, link, metadata, context, and nearby edges.
+2. Search for adjacent context before rewriting:
+   - the node's primary context and its anchor node when present
+   - recently connected project or belief nodes
+   - related nodes with overlapping titles, creators, or neighboring context
 3. Infer the best available "why" from that context.
 4. Rewrite the full description from scratch in natural prose. Do not append to the old text or use labels like WHAT:, WHY:, or STATUS:.
-5. Review dimensions.
+5. Review context fit:
+   - keep the current context when it is clearly the primary scope
+   - suggest clearing context when it is weak or misleading
+   - suggest a different context only when the primary scope is explicit
 6. Suggest 1-3 high-signal edges when obvious.
 7. Update the node once the description is strong enough to be useful.
 8. After the update, tell the user what changed and ask whether they want to refine the important framing:
@@ -34,3 +40,52 @@ Also review whether the node needs dimension fixes or obvious edge suggestions.
    - status / current relevance / workflow position
 
 The user feedback pass is required whenever the enriched "why" or status was inferred rather than directly stated in the node/source.
+
+## Description Standard
+
+Every rewritten description must naturally cover:
+
+1. What
+   - explicit artifact type
+   - creator/author/speaker when known
+   - core subject, claim, or function
+2. Why
+   - why Brad saved it
+   - what project, belief, question, or theme it connects to
+   - if genuinely unknown, say that naturally without inventing context
+3. Status
+   - queued, in progress, processed, not yet reviewed, saved for later, etc.
+   - if unknown, say naturally that it has not been reviewed yet
+
+Max 500 characters.
+
+## Batch Mode
+
+Use batch enrichment when cleaning up many nodes with the same failure mode.
+
+1. Pull a tight node set first.
+2. Group by pattern:
+   - vague imported links
+   - thin quick-add captures
+   - old source nodes missing workflow state
+3. Enrich each node individually. Do not reuse boilerplate "why" text across unrelated nodes.
+4. Return a compact summary of:
+   - nodes updated
+   - context assignments to review
+   - edge suggestions not yet created
+
+## Quality Bar
+
+- No filler phrases like `insightful for understanding`, `relevant to`, or `important for`.
+- No generic summaries that only restate the topic.
+- No invented certainty. If context is weak, say so explicitly.
+- Prefer one compact 3-sentence description over bloated prose.
+
+## Output Pattern
+
+For each node:
+
+- New description
+- Context change: keep / change / clear
+- Edge suggestions: source -> target with explicit explanation
+- One short invitation for user feedback when contextual framing was inferred

apps/mcp-server-standalone/skills/onboarding.md

@@ -1,35 +1,166 @@
 ---
 name: Onboarding
-description: "Onboard a new user by mapping goals, projects, worldview, and preferences into a strong initial graph."
-when_to_use: "New user setup or major reset of account context."
-when_not_to_use: "User asks for a narrow tactical operation only."
-success_criteria: "User has an initial context structure, anchor candidates, and clear next steps for graph growth."
+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
 
-## Goal
+## Your Job
 
-Understand the user deeply enough to bootstrap a useful externalized context graph.
+Three things: help the user understand the basic structure of the system, help them start building useful context 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 how you'd like to create your context corpus, feel free to tell me what you'd like to add and I can help you set things up. Otherwise, I can guide you through bootstrapping your context 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
 
-1. Clarify outcomes: goals for this system and success horizon.
-2. Map active projects: responsibilities, timelines, decision pressure.
-3. Capture worldview: beliefs, principles, working assumptions, decision criteria.
-4. Capture identity/context anchors: roles, domains, recurring themes.
-5. Capture interaction preferences: style, rigor, speed vs depth, tone.
+Keep it conversational. Use these buckets and adapt based on what the user gives you.
 
-## Graph Bootstrap
+**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?
 
-1. Propose 3-6 primary contexts with clear rationale.
-2. Identify one strong anchor candidate per context.
-3. Propose starter dimensions as secondary metadata and filters.
-4. Create initial edges between anchor nodes and active project nodes.
-5. Confirm with user before writing.
+**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?
 
-## Output
+**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?
 
-- Initial context map
-- Suggested first write actions
-- Suggested weekly maintenance rhythm
+**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 the primary folders or scopes for the graph.
+- **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 primary context when one is clear. 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 should hold the primary scope when clear, 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