feat: sync shared skills contract and graph-first discipline

docs/4_tools-and-guides.md

@@ -60,27 +60,31 @@ Metadata note for `createNode` / `updateNode`:
 Skills are markdown instruction documents shared by internal and external agents.
 
 Seeded defaults:
-- `db-operations`
-- `create-skill`
-- `audit`
-- `traverse`
 - `onboarding`
-- `persona`
-- `calibration`
-- `connect`
+- `create-skill`
+- `refine`
 
 Storage:
 - live skills: `~/Library/Application Support/RA-H/skills/`
 - bundled defaults: `src/config/skills/`
 
+## Memory-File Reinforcement
+
+Optional memory files like `AGENTS.md` or `CLAUDE.md` can reinforce the graph contract, but they should stay short and should not contradict the MCP docs or tool descriptions.
+
+Keep the reinforcement focused on:
+- `queryNodes` for direct node lookup
+- `retrieveQueryContext` for broader graph grounding
+- search before create
+- clear `description` quality
+- preserving user wording in `source` when capturing user-authored ideas
+
 ## API Surfaces
 
 | Route | Method | Purpose |
 |-------|--------|---------|
-| `/api/skills` | GET | List skills |
-| `/api/skills/[name]` | GET/PUT/DELETE | Skill CRUD |
-| `/api/guides` | GET | Legacy compatibility alias to skills |
-| `/api/guides/[name]` | GET/PUT/DELETE | Legacy compatibility alias to skills |
+| `/api/skills` | GET/POST | List skills or write a skill |
+| `/api/skills/[name]` | GET/DELETE | Read or delete a specific skill |
 
 ## Key Files
 

docs/8_mcp.md

@@ -73,4 +73,22 @@ Optional assistant memory files can reinforce good behavior, but they are not su
 Current rule:
 - MCP tools, server instructions, skills, and docs should be enough for the base contract
 - optional reinforcement can still improve consistency
+- keep one canonical memory file when possible
 - avoid contradictory instruction files across `CLAUDE.md`, `AGENTS.md`, and other client-specific memory surfaces
+
+Recommended guidance:
+- keep the language short and simple
+- focus on graph behavior, not tool micromanagement
+- prefer one shared snippet over separate client-specific doctrines
+
+Suggested memory-file snippet:
+
+```md
+You are helping build a thoughtful graph of atomic units of context.
+
+- Use `queryNodes` for direct lookup of a specific existing node.
+- Use `retrieveQueryContext` when broader graph context would help with the current turn.
+- Search before creating. Prefer updating the same artifact when it is clearly the same thing.
+- `description` should state plainly what the thing is first, then why it belongs and current status.
+- Preserve the user's wording in `source` for user-authored ideas unless they explicitly want a rewrite.
+```

docs/README.md

@@ -18,7 +18,7 @@
 | [Tools & Skills](./4_tools-and-guides.md) | MCP tools and skill system |
 | [Logging & Evals](./5_logging-and-evals.md) | Logs, evals, and debugging surfaces |
 | [UI](./6_ui.md) | Current pane and focus model |
-| [MCP](./8_mcp.md) | Full standalone MCP install and behavior guide |
+| [MCP](./8_mcp.md) | Full standalone MCP install, behavior guide, and memory-file guidance |
 | [Open Source](./9_open-source.md) | Scope, support boundary, contributor reality |
 | [Full Local](./10_full-local.md) | Supported local path vs community patterns |
 | [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and fixes |