feat: finalize local OpenAI key flow and MCP docs

- add server-side .env.local OpenAI key management for the open-source app
- route AI features through the preferred local key path and lazy-load embed recovery
- rewrite README and docs for current MCP setup, schema, and fully-local guidance

Generated with Claude Code

docs/8_mcp.md

@@ -1,6 +1,94 @@
 # MCP Surface
 
-RA-H exposes MCP tools for direct graph work against the local database or app API.
+This is the full practical setup page for the standalone open-source MCP path.
+
+## 1. What MCP Gives You In RA-H OS
+
+MCP lets an external agent:
+- search your existing graph
+- ground a broader task in relevant graph context
+- create or update nodes
+- propose and confirm edges
+- read and write shared skills
+
+The graph contract is:
+- no runtime `dimensions`
+- optional `contexts`
+- direct lookup first
+- broader retrieval only when useful
+- confirmation-gated durable writeback and edge changes
+
+## 2. Choose Your Assistant / Client
+
+Best-supported path:
+- Claude Code
+- Claude Desktop
+
+Also reasonable:
+- Cursor and similar MCP-capable coding assistants
+
+Prefer a client that:
+- supports local stdio MCP servers well
+- reliably restarts after config changes
+- lets you pin one package version in config
+
+## 3. Install The Standalone MCP Server
+
+Requirements:
+- Node.js 18-22 LTS recommended
+- existing RA-H DB created by running the app once
+- pinned package version in client config
+
+Package:
+
+```bash
+npx --yes ra-h-mcp-server@2.1.2
+```
+
+If `better-sqlite3` fails to load:
+- use Node 18-22 LTS
+- rebuild native modules if you are developing locally
+
+## 4. Configure The Assistant With A Pinned Version
+
+Claude config example:
+
+```json
+{
+  "mcpServers": {
+    "ra-h": {
+      "command": "npx",
+      "args": ["--yes", "ra-h-mcp-server@2.1.2"]
+    }
+  }
+}
+```
+
+Contributor local-path example:
+
+```json
+{
+  "mcpServers": {
+    "ra-h": {
+      "command": "node",
+      "args": ["/absolute/path/to/ra-h_os/apps/mcp-server-standalone/index.js"]
+    }
+  }
+}
+```
+
+## 5. Restart And Verify The Tools Are Available
+
+After editing config:
+- fully restart the client
+- do not trust a soft window close
+- ask the assistant whether RA-H tools are available
+
+Healthy verification usually means you can see tools like:
+- `queryNodes`
+- `retrieveQueryContext`
+- `createNode`
+- `readSkill`
 
 ## Core MCP Contract
 
@@ -11,8 +99,8 @@ RA-H exposes MCP tools for direct graph work against the local database or app A
 - 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.
+- `createEdge` is a post-confirmation execution tool.
+- `updateEdge` is also post-confirmation only.
 - `queryNodes` searches title, description, and source, with optional context filters.
 - `dimensions` are removed from the MCP contract.
 
@@ -39,18 +127,61 @@ Write:
 - `writeSkill`
 - `deleteSkill`
 
-## Tool Behavior
+## 6. How The Agent Should Behave With RA-H
 
-- 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`.
-- 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.
+- always search before creating
+- use `queryNodes` first for specific-node intent
+- use `retrieveQueryContext` when broader graph grounding would help
+- keep context optional by default
+- use `context_name` only when context is intentionally provided
+- 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
+- keep writeback prompts terse and selective
+
+Do not assume MCP node creation immediately produces chunks or embeddings. The canonical contract is:
+- write node data first
+- app-owned pipeline later creates chunks, FTS rows, and vectors
+
+## 7. Optional Memory-File Reinforcement
+
+Important distinction:
+- `CLAUDE.md` is an assistant-native memory/instruction file for Claude Code
+- `AGENTS.md` is a repo-local instruction file many teams already use
+- other clients may have their own memory or instruction surfaces
+
+Rules:
+- the MCP/tool/docs contract should work without user prompt surgery
+- optional reinforcement can still improve consistency
+- do not create contradictory instruction files
+
+Short recommended reinforcement pattern:
+
+```md
+Retrieve relevant RA-H context before substantive work, search before creating, and keep durable writeback prompts brief and confirmation-gated.
+```
+
+## 8. Troubleshooting And Common Failure Cases
+
+`Tools not found`
+- fully restart the client
+- verify the config path is the one your client actually uses
+- run the pinned package manually once
+
+`Database not found`
+- run the RA-H app once first so the DB exists
+- confirm `RAH_DB_PATH` if using a custom path
+
+`Node writes land but embeddings/chunks are missing`
+- this is usually expected when the app is closed
+- standalone MCP writes node data first
+- the app later processes pending `nodes.source` work
+
+`Native module load failure`
+- use Node 18-22 LTS
+- rebuild `better-sqlite3` if needed for local development
+
+`Version drift`
+- pin the package version in client config
+- bump the pinned version intentionally when testing a new release