feat: port MCP retrieval and write hardening

- align os MCP/runtime/docs with ra-h contract
- add safe direct node lookup and context-optional flows
- gate edge and context writes behind confirmation

docs/0_overview.md

@@ -63,15 +63,15 @@ RA-OS is designed to be the knowledge backend for your AI workflows:
   "mcpServers": {
     "ra-h": {
       "command": "npx",
-      "args": ["ra-h-mcp-server"]
+      "args": ["--yes", "ra-h-mcp-server@2.1.1"]
     }
   }
 }
 ```
 
-Add this to `~/.claude.json` and restart Claude. Works without RA-OS running.
+Add this to `~/.claude.json` and restart Claude. Works without RA-OS running. If you publish a newer MCP release and need clients to pick it up immediately, bump the pinned version here and restart the client.
 
-Core tools include: `createNode`, `queryNodes`, `updateNode`, `getNodesById`, `createEdge`, `queryEdge`, `queryContexts`, `listSkills`, `readSkill`
+Core tools include: `queryNodes`, `retrieveQueryContext`, `createNode`, `writeContext`, `updateNode`, `getNodesById`, `createEdge`, `updateEdge`, `queryEdge`, `queryContexts`, `listSkills`, `readSkill`
 
 ## Documentation
 

docs/4_tools-and-guides.md

@@ -15,13 +15,15 @@ RA-OS exposes these core standalone MCP tools:
 | Tool | Description |
 |------|-------------|
 | `getContext` | Graph overview: stats, contexts, hub nodes, recent activity, skills |
-| `queryNodes` | Search nodes by keyword/date/context |
+| `retrieveQueryContext` | Pull relevant graph context for a broader current-turn task |
+| `queryNodes` | Find specific existing nodes by title, description, or source |
 | `getNodesById` | Fetch full nodes by ID |
 | `createNode` | Create a node |
-| `updateNode` | Update a node |
-| `createEdge` | Create an edge between nodes |
+| `writeContext` | Save one confirmed durable context node after explicit user approval |
+| `updateNode` | Update a node while preserving context by default |
+| `createEdge` | Create a confirmed edge between nodes |
 | `queryEdge` | Query edges |
-| `updateEdge` | Update edge explanation |
+| `updateEdge` | Update an edge explanation after explicit confirmation |
 | `queryContexts` | List contexts and optional attached nodes |
 
 ### Skills + Search

docs/8_mcp.md

@@ -7,8 +7,12 @@ RA-H exposes MCP tools for direct graph work against the local database or app A
 - `queryNodes` is the primary tool for direct node retrieval when the user is trying to find a specific existing node.
 - `retrieveQueryContext` is the primary retrieval entrypoint for substantive current-turn work when the agent needs graph context to support a broader answer.
 - `getContext` returns graph orientation: stats, contexts, hubs, and skills.
-- `createNode` and `updateNode` accept optional `context_id` but do not require context. Omitting `context_id` is the normal default.
+- `createNode`, `updateNode`, and `queryNodes` leave context blank by default.
+- If context is intentionally provided, prefer `context_name`.
+- `context_id` is an internal implementation detail, not the normal agent-facing field.
 - `writeContext` writes one confirmed durable context node and must never be called before explicit user approval.
+- `createEdge` is a post-confirmation execution tool. Agents should propose likely edges first and only write them after the user explicitly confirms.
+- `updateEdge` is also a post-confirmation execution tool. Agents should only correct an edge after the user explicitly confirms the corrected relationship.
 - `queryNodes` searches title, description, and source, with optional context filters.
 - `dimensions` are removed from the MCP contract.
 
@@ -40,8 +44,13 @@ Write:
 - Always search before creating.
 - If the user is trying to find a specific existing node, use `queryNodes` first.
 - If the user is asking a broader question that would benefit from graph context, use `retrieveQueryContext`.
-- Prefer explicit context assignment only when the primary scope is clear and a real context is already known.
-- Do not send `context_id: null` unless the tool call is intentionally clearing an existing context.
+- Optional user memory reinforcement can help, but the MCP tools, instructions, skills, and docs should be enough for the core retrieval and writeback contract to work.
+- Prefer explicit context assignment only when the user clearly wants it and a real context is already known.
+- Use `context_name` when context is intentionally provided.
+- Do not assume the agent needs to think about context during normal node creation, lookup, or update flows.
 - Do not assume the server will infer a best-fit context.
+- If the user explicitly asked to save or update something and the target artifact is clear, the agent can write after duplicate/update checks.
+- If the agent is only suggesting a save, it should propose the node first and wait for confirmation.
+- When obvious relationships appear, propose candidate edges briefly rather than writing them automatically.
 - Judge graph quality by node quality and edges, not taxonomy completeness.
 - Keep writeback prompts terse and selective. The goal is not to ask constantly whether every useful sentence should be saved.

docs/README.md

@@ -49,12 +49,14 @@ Add to your `~/.claude.json`:
   "mcpServers": {
     "ra-h": {
       "command": "npx",
-      "args": ["ra-h-mcp-server"]
+      "args": ["--yes", "ra-h-mcp-server@2.1.1"]
     }
   }
 }
 ```
 
+If you publish a newer MCP release and need clients to use it immediately, bump the pinned version here and restart the client. Do not assume plain `npx ra-h-mcp-server` always refreshes instantly.
+
 Works without RA-OS running. See [MCP docs](./8_mcp.md) for alternatives.
 
 ## Questions?