memtrace 0.8.3 → 0.8.5

package/installer/skills/workflows/memtrace-first.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-first
-description: "Route code discovery, debugging, flow tracing, and how-code-works questions in indexed source-code repos to Memtrace graph tools. Use first — before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results, missing languages, or partial-looking stats are not permission to grep; diagnose/reindex with Memtrace."
+description: "Route code discovery, debugging, flow tracing, how-code-works questions, and pre-edit rationale checks in indexed source-code repos to Memtrace graph plus Cortex decision tools. Use first before searching/reading code, and before editing, refactoring, deleting, or re-picking an approach that may have a recorded decision, ban, convention, or contract. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results are not permission to grep; diagnose/reindex with Memtrace."
 allowed-tools:
   - mcp__memtrace__list_indexed_repositories
   - mcp__memtrace__index_directory
@@ -23,6 +23,10 @@ allowed-tools:
   - mcp__memtrace__get_style_fingerprint
   - mcp__memtrace__find_most_complex_functions
   - mcp__memtrace__get_source_window
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__verify_intent
+  - mcp__memtrace__why_is_this_here
+  - mcp__memtrace__governing_contracts
   - Read
   - Grep
   - Glob
@@ -44,6 +48,12 @@ ONLY when you're about to edit or quote, and read only the bounded span
 returned by Memtrace (start_line .. end_line + small context). Do not
 Grep/Glob/Find to "locate" anything already in the graph, and do not read
 the whole file when Memtrace has given you exact lines.
+
+BEFORE you edit/refactor/delete existing code or choose/re-pick a pattern,
+call Cortex decision memory: recall_decision for the symbol/subsystem/approach,
+and use provenance/contracts when a symbol_id is available. Use Memtrace's graph
+tools for structure and blast radius; use Cortex for rationale, bans, and
+contracts.
 ```
 
 Memtrace is the **memory layer** of the codebase, not a search engine that returns code. It has the full knowledge graph — every symbol, call, import, community, process, and API — with a time dimension. The point is to navigate that graph: who calls this, what's the blast radius, when did this change, what community is it part of. File tools are blind to all of that.
@@ -103,6 +113,8 @@ For everything else inside the indexed repo, memtrace is the right tool.
 | "Find the function that uses `STRIPE_KEY_FOO_BAR`" | `find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
 | "Where's that error message `'connection refused for tenant'`?" | `find_code(query="connection refused for tenant")` → semantic catches it. |
 | "What breaks if I change `foo`?" | `get_impact(repo_id, target="foo")` → blast radius. |
+| "Should I change/delete/refactor `foo`?" | `find_symbol`/`get_symbol_context` → `recall_decision("foo / subsystem / approach")`; if a symbol id is available, `why_is_this_here` + `governing_contracts`; then `get_impact`. |
+| "Can I use/switch to pattern or library X?" | `recall_decision("X")` FIRST; bans and conventions are decisions. Verify a matching decision with `verify_intent(decision_id)` before relying on it. |
 | "What changed in `auth.ts` last week?" | `get_evolution(repo_id, from="7d ago", mode="recent", file_path="auth.ts")`. |
 | "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
 | "Find this string in my `.env`." | `Grep` (non-source artifact). |
@@ -160,6 +172,8 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 | What files change together? | `get_cochange_context` |
 | Architecture overview | `list_communities` + `find_central_symbols` |
 | About to edit / quote — need exact lines | Bounded `Read(file, offset=start_line, limit=N)` (preferred), or `get_source_window` for path-resolution parity |
+| About to edit/refactor/delete existing code | `recall_decision` for the intent + `why_is_this_here`/`governing_contracts` when a symbol id is available, then `get_impact` |
+| About to choose or replace a library/pattern/architecture | `recall_decision` first; use `verify_intent` on any matching decision before contradicting it |
 | About to choose between competing idioms (ternary vs if-else, arrow vs fn-decl, const vs let, await vs `.then`) | `get_style_fingerprint(repo_id, file_path)` — empirical codebase norm; see `memtrace-style-fingerprint` workflow |
 
 ## Standard Workflows
@@ -185,8 +199,10 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 ### Before any code modification
 1. `find_symbol` → confirm you have the right target
 2. `get_symbol_context` → understand full context
-3. `get_impact` → know blast radius before touching anything
-4. `get_style_fingerprint(repo_id, file_path=<file>)` → match the codebase's empirical idiom (ternary vs if-else, arrow vs fn-decl, etc.) — see `memtrace-style-fingerprint` workflow for the full decision rule
+3. `recall_decision("<symbol/subsystem/approach>")` → surface recorded choices, bans, and conventions before deciding what to do
+4. If a `symbol_id` is available, `why_is_this_here(symbol_id)` + `governing_contracts(symbol_id)` before deleting, rewriting, or "cleaning up" odd code
+5. `get_impact` → know blast radius before touching anything
+6. `get_style_fingerprint(repo_id, file_path=<file>)` → match the codebase's empirical idiom (ternary vs if-else, arrow vs fn-decl, etc.) — see `memtrace-style-fingerprint` workflow for the full decision rule
 
 ## Red Flags — STOP, Use Memtrace Instead
 
@@ -197,6 +213,9 @@ You are violating this skill if you think:
 | "Let me grep for this" | `find_code` or `find_symbol` is faster and structurally aware |
 | "Let me glob for the file" | `find_symbol` returns exact location with context |
 | "Let me read the whole file" | `get_symbol_context` for the WHY (callers/callees/community); a bounded source read at start_line..end_line for the WHAT |
+| "I know why this is written this way" | Check Cortex first. Use `recall_decision`; use `why_is_this_here`/`governing_contracts` when you have a symbol id. |
+| "This looks unused/weird; I'll remove it" | `why_is_this_here` + `governing_contracts` first, then blast radius. CannotProve is unknown, not permission. |
+| "I'll just switch to library/pattern X" | `recall_decision("X")` first — you may be reintroducing a banned approach. |
 | "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
 | "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
 | "Memtrace returned 0 results" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
@@ -210,6 +229,7 @@ Use Grep/Glob/Read ONLY for:
 - Non-source files or paths outside every indexed source repo
 - Files that are config, data, or docs (not source code symbols)
 - Repos or paths confirmed outside every Memtrace indexed root
+- **Official Memtrace product documentation** — use `memtrace-docs` (`ask_docs` / `search_docs` / `read_doc`), not file tools or web search
 
 For source-code spans already located by Memtrace, use a **bounded** read —
 your harness's `Read(file, offset, limit)` with the returned `start_line` /
@@ -227,9 +247,11 @@ When this skill applies, it overrides default file-search behavior. Use the spec
 - Discovery → `memtrace-search`
 - Impact analysis → `memtrace-impact`
 - Temporal / change analysis → `memtrace-evolution`
+- Rationale / prior decisions / bans / contracts → `memtrace-decision-memory`
 - Incident investigation → `memtrace-incident-investigation`
 - Architecture overview → `memtrace-codebase-exploration`
 - Refactoring → `memtrace-refactoring-guide`
+- Memtrace **product docs** (install, CLI, MCP, enterprise) → `memtrace-docs`
 
 ## Output
 

package/installer/skills/workflows/memtrace-refactoring-guide.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-refactoring-guide
-description: "Build a phased, risk-scored refactoring plan from Memtrace complexity, dead-code, bridge, and impact analysis. Use when the user wants to refactor source code, reduce complexity, clean technical debt, split large functions, extract modules, reorganize code, or choose refactoring priorities. Do not use Grep or manual reference search to plan refactors; Memtrace provides complexity, dead-code, relationships, and impact context."
+description: "Build a phased, risk-scored refactoring plan from Memtrace complexity, dead-code, bridge, impact analysis, and Cortex decision-memory constraints. Use when the user wants to refactor source code, reduce complexity, clean technical debt, delete dead code, split large functions, extract modules, reorganize code, or choose refactoring priorities. Do not plan refactors from grep/manual reference search alone; check graph impact and decision rationale/bans/contracts before changing existing code."
 allowed-tools:
   - mcp__memtrace__find_most_complex_functions
   - mcp__memtrace__find_dead_code
@@ -10,6 +10,10 @@ allowed-tools:
   - mcp__memtrace__get_symbol_context
   - mcp__memtrace__analyze_relationships
   - mcp__memtrace__list_communities
+  - mcp__memtrace__recall_decision
+  - mcp__memtrace__why_is_this_here
+  - mcp__memtrace__governing_contracts
+  - mcp__memtrace__verify_intent
 metadata:
   author: "Syncable <support@syncable.dev>"
   version: "1.0.0"
@@ -19,7 +23,7 @@ user-invocable: true
 
 ## Overview
 
-Guided refactoring workflow — identifies refactoring candidates using structural analysis, scores them by risk and priority, and produces a phased refactoring plan. Combines complexity metrics, dead code detection, bridge analysis, and temporal evolution to prioritize what to refactor first and how to do it safely.
+Guided refactoring workflow — identifies refactoring candidates using structural analysis, scores them by risk and priority, checks Cortex decision memory for rationale/bans/contracts, and produces a phased refactoring plan. Combines complexity metrics, dead code detection, bridge analysis, temporal evolution, and decision memory to prioritize what to refactor first and how to do it safely.
 
 ## Steps
 
@@ -63,7 +67,17 @@ Also call `get_symbol_context` to check:
 - How many processes does this symbol participate in? (More = more testing needed)
 - Is it part of a cross-repo API? (If yes, coordinate with consumers)
 
-### 4. Understand the neighbourhood
+### 4. Check decision memory before refactoring/removing
+
+For each top candidate, call `recall_decision("<symbol/subsystem/refactor intent>")`.
+If you have a numeric `symbol_id`, call `why_is_this_here(symbol_id)` and
+`governing_contracts(symbol_id)`.
+
+- A matching held decision/ban can veto or reshape the refactor.
+- Contracts become acceptance criteria for the new design.
+- CannotProve is unknown, not permission to delete.
+
+### 5. Understand the neighbourhood
 
 For each refactoring target, call `analyze_relationships`:
 - `find_callees` — what does it depend on? These become candidates for extraction
@@ -72,13 +86,13 @@ For each refactoring target, call `analyze_relationships`:
 
 Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bundled at the memtrace-skills plugin root).
 
-### 5. Check community boundaries
+### 6. Check community boundaries
 
 Call `list_communities` and check: does the refactoring target sit at a community boundary?
 - If yes, the refactoring may involve splitting responsibilities across modules
 - If it belongs clearly to one community, the refactoring is more contained
 
-### 6. Produce the refactoring plan
+### 7. Produce the refactoring plan
 
 Synthesize into a phased plan:
 
@@ -98,8 +112,9 @@ For each item, include:
 1. **Target** — function/class name, file, current complexity score
 2. **Why** — complexity + volatility + blast radius rationale
 3. **How** — specific refactoring approach (extract method, split class, introduce interface)
-4. **Risk** — impact analysis rating + affected processes
-5. **Test Plan** — which callers/processes to verify
+4. **Decision Memory** — relevant Cortex decisions/bans/contracts, or CannotProve as unknown
+5. **Risk** — impact analysis rating + affected processes
+6. **Test Plan** — which callers/processes to verify
 
 ## Decision Points
 
@@ -107,9 +122,10 @@ For each item, include:
 |-----------|--------|
 | Complex + volatile + high blast radius | Highest priority — but plan carefully; incremental approach |
 | Complex + stable + low blast radius | Can wait; refactor when you're already touching nearby code |
-| Dead code with zero callers | Safe to delete — quick win |
+| Dead code with zero callers | Run Cortex provenance/recall first; zero callers is not proof that no decision/contract keeps it |
 | Bridge symbol with many dependents | Extract interface first, then refactor implementation behind it |
 | Symbol in cross-repo API | Coordinate with consumers; backward-compatible changes only |
+| Cortex returns a held ban/contract | Preserve it or ask before overriding it |
 
 ## Output
 
@@ -123,7 +139,7 @@ A phased plan (Phases 1–3). One worked entry:
 | Risk | High — upstream spans 3 processes incl. `checkout_flow`; incremental migration |
 
 Acceptance criteria:
-- Every plan item cites complexity, volatility, and blast radius — no gut-feel picks.
+- Every plan item cites complexity, volatility, blast radius, and decision-memory status — no gut-feel picks.
 - High/Critical-risk items include a test plan naming affected callers/processes.
 
 ## Common Mistakes

package/lib/child-supervisor.js

@@ -0,0 +1,104 @@
+"use strict";
+
+// Signal-forwarding supervisor for the native memtrace binary.
+//
+// The npm shim (bin/memtrace.js) spawns the Rust `memtrace` binary as a
+// child. When the shim itself receives a signal — from a supervisor
+// (systemd, npm, Warp's agent runner, CI), a terminal close (SIGHUP), or a
+// Ctrl-C the OS delivers to the shim PID rather than the whole foreground
+// process group — the child MUST receive the same signal so a long-running
+// `memtrace start` daemon shuts down cleanly instead of being orphaned
+// (still holding port 3030, the MemDB lock, and the embed model).
+//
+// Pre-fix, the `mcp` branch spawned the child async but forwarded NO
+// signals, and the `else` branch that serves `start` used `spawnSync`,
+// which can't forward at all. Both orphaned the daemon when the shim was
+// killed by anything other than a foreground-process-group Ctrl-C. The next
+// `memtrace start` then hit "already running" / port-in-use — the root
+// cause of the "`npx memtrace@latest start` isn't working" reports under
+// npx / Warp / supervisors.
+//
+// Contract this module pins:
+//   * For every signal in the forwarded set, install ONE listener on
+//     `process` that calls `child.kill(signal)`.
+//   * Never throw — a signal handler that throws would terminate the shim
+//     with an uncaught exception AND orphan the child we're trying to
+//     signal. Swallow; let the child's own exit drive the shim's exit.
+//   * Stop forwarding once the child exits (so a reused process object
+//     doesn't leak listeners / kill a reaped PID).
+//   * Idempotent WITHIN one call — a signal listed twice in the `signals`
+//     array registers a single listener. Cross-call dedup is deliberately
+//     NOT promised (one forwarder per child is the contract the bin relies
+//     on; a shared global listener could not disambiguate which child to
+//     kill).
+//   * Do NOT forward memtrace-internal signals (SIGUSR1 embed-breaker
+//     reset, SIGUSR2, SIGPIPE) — the child handles those on its own PID.
+//
+// The only side effect is registering/deregistering listeners on the
+// `process` and `child` objects you pass in. Both are injectable so the
+// unit + property tests drive fake EventEmitters without real signals.
+
+const DEFAULT_SIGNALS = Object.freeze(["SIGINT", "SIGTERM", "SIGHUP"]);
+
+/**
+ * Forward a set of signals from `process` (or an injectable stand-in) to a
+ * spawned child. Returns a handle with a `detach()` that removes every
+ * listener. Auto-detaches on the child's `exit` event so a late signal on a
+ * long-lived shim never reaches a reaped PID.
+ *
+ * @param {object} child            Node ChildProcess (or EventEmitter fake
+ *                                  with `.pid`, `.kill(signal)`, `.on`/`.off`).
+ * @param {string[]} [signals]      Signals to forward. Defaults to
+ *                                  DEFAULT_SIGNALS (SIGINT, SIGTERM, SIGHUP).
+ * @param {object} [opts]
+ * @param {object} [opts.process]   Process-like EventEmitter to listen on.
+ *                                  Defaults to the real `process`.
+ * @returns {{ detach(): void }}
+ */
+function forwardSignalsTo(child, signals, opts) {
+    const sigs = Array.isArray(signals) && signals.length > 0 ? signals : DEFAULT_SIGNALS;
+    const proc = (opts && opts.process) || process;
+    const handlers = new Map();
+
+    const install = (sig) => {
+        // Idempotent: a second call for an already-installed signal is a
+        // no-op, so overlapping installs (e.g. if a future caller wires
+        // both the mcp and start branches) never double-fire on one
+        // emission.
+        if (handlers.has(sig)) return;
+        const handler = () => {
+            try {
+                if (child && typeof child.kill === "function" && child.pid != null) {
+                    child.kill(sig);
+                }
+            } catch (_) {
+                // A signal handler must never throw — that would orphan the
+                // child AND crash the shim with an uncaught exception.
+            }
+        };
+        handlers.set(sig, handler);
+        if (typeof proc.on === "function") proc.on(sig, handler);
+    };
+    for (const sig of sigs) install(sig);
+
+    const detach = () => {
+        for (const [sig, handler] of handlers) {
+            try {
+                if (typeof proc.removeListener === "function") proc.removeListener(sig, handler);
+            } catch (_) { /* best effort */ }
+        }
+        handlers.clear();
+        try {
+            if (typeof child.off === "function") child.off("exit", detach);
+            else if (typeof child.removeListener === "function") child.removeListener("exit", detach);
+        } catch (_) { /* best effort */ }
+    };
+    if (typeof child.on === "function") child.on("exit", detach);
+
+    return { detach };
+}
+
+module.exports = {
+    forwardSignalsTo,
+    DEFAULT_SIGNALS,
+};

package/lib/install-consent.js

@@ -85,7 +85,7 @@ function buildMutationList({ home, cwd, projectOnly = false, noHooks = false })
         { path: path.join(claude, "plugins", "installed_plugins.json"), change: "plugin registry entry (written by the `claude` CLI when available)" },
         { path: path.join(home, ".claude.json"), change: "possible memtrace MCP entry (written by `claude mcp add-json --scope user` when the `claude` CLI is available)" },
         { path: path.join(home, ".memtrace") + path.sep, change: "create memtrace data dir: persisted uninstall.js + install-backup/ (backups + manifest)" },
-        { path: path.join(home, "{.cursor,.codex,.gemini,.codeium,.hermes,.kiro,.copilot,.config/opencode,VS Code user config}"), change: "skills + memtrace MCP registration for other detected agents (same merge-add pattern)" },
+        { path: path.join(home, "{.cursor,.codex,.gemini,.codeium,.hermes,.kiro,.copilot,.warp,.config/opencode,VS Code user config}"), change: "skills + memtrace MCP registration for other detected agents (same merge-add pattern)" },
     );
     return list;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -39,12 +39,12 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.8.3",
-    "@memtrace/linux-x64": "0.8.3",
-    "@memtrace/linux-arm64": "0.8.3",
-    "@memtrace/win32-x64": "0.8.3",
-    "@memtrace/linux-x64-noavx2": "0.8.3",
-    "@memtrace/win32-x64-noavx2": "0.8.3"
+    "@memtrace/darwin-arm64": "0.8.5",
+    "@memtrace/linux-x64": "0.8.5",
+    "@memtrace/linux-arm64": "0.8.5",
+    "@memtrace/win32-x64": "0.8.5",
+    "@memtrace/linux-x64-noavx2": "0.8.5",
+    "@memtrace/win32-x64-noavx2": "0.8.5"
   },
   "engines": {
     "node": ">=18"

package/skills/commands/memtrace-decision-recall.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-decision-recall
-description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query. Use when the user asks what was decided, what was chosen or rejected, whether there's a convention/ban/policy on something, or before re-picking a library, pattern, or approach that may already be settled. Do not reconstruct past decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol-scoped decision lineage/contracts, use memtrace-provenance."
+description: "Recall ranked decisions, bans, and conventions from Cortex decision memory by free-text query through the normal Memtrace MCP server. Use when the user asks what was decided/chosen/rejected, whether there is a convention/ban/policy, and before any non-trivial edit/refactor/delete or re-picking a library, pattern, architecture, or subsystem behavior that may already be settled. Do not reconstruct decisions from git log or guesswork. To verify whether a known decision held, use memtrace-intent-verification; for symbol lineage/contracts, use memtrace-provenance."
 allowed-tools:
   - mcp__memtrace__recall_decision
   - mcp__memtrace__verify_intent
@@ -16,7 +16,8 @@ metadata:
 `recall_decision` is the **free-text entry point** to decision memory. Given a query,
 it returns the statistically-ranked set of decisions/conversations that bear on it —
 including **bans** ("never use X", "don't do Y"), which are recorded as decisions.
-Use it before re-litigating a settled choice or contradicting a convention.
+Use it before re-litigating a settled choice, changing existing behavior, or
+contradicting a convention.
 
 This is the one decision-memory tool that takes plain text. The ranked decisions it
 returns carry the `decision_id`s the other tools (`verify_intent`, `get_arc`) need.
@@ -41,7 +42,8 @@ Full parameter spec for every Memtrace tool: `references/mcp-parameters.md` (bun
 
 `recall_decision(query)` — `query` is free text. Use the noun phrase of the thing in
 question: a library (`"redis vs in-memory cache"`), a pattern (`"error handling
-strategy"`), a subsystem (`"auth tokens"`), or the exact thing you're about to do.
+strategy"`), a subsystem (`"auth tokens"`), a symbol, or the exact edit/refactor/delete
+you are about to do.
 
 ### 2. Read the ranked result
 
@@ -71,7 +73,8 @@ require a Decision node and will honestly return CannotProve. See
 
 | Situation | Action |
 |-----------|--------|
-| About to choose a library/pattern/approach | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
+| About to edit/refactor/delete existing code where intent may matter | `recall_decision("<symbol/subsystem/behavior>")` FIRST — you may be crossing a recorded decision, ban, or convention |
+| About to choose or replace a library/pattern/architecture | `recall_decision` FIRST — you may be undoing a deliberate choice or ban |
 | User asks "did we decide X?" / "what's our convention on Y?" | `recall_decision("X" / "Y")` |
 | You suspect a "don't do this" rule exists | `recall_decision` — bans are decisions and will surface |
 | Recall returns a decision you're about to contradict | Surface it to the user verbatim; don't silently override |

package/skills/commands/memtrace-docs-ask.md

@@ -0,0 +1,99 @@
+---
+name: memtrace-docs-ask
+description: "Answer questions from official Memtrace documentation only — installation, CLI, MCP tools, fleet, Cortex, enterprise MemDB deploy, skills, configuration. Use when the user asks how Memtrace works or wants a cited explanation. Calls ask_docs on memtrace.io (RAG + guardrails). Do not guess product behavior from training data."
+allowed-tools:
+  - mcp__memtrace__ask_docs
+  - mcp__memtrace__search_docs
+  - mcp__memtrace__read_doc
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+`ask_docs` sends the user's question to the hosted docs RAG backend. The server
+retrieves relevant doc chunks, generates an answer **only from that context**, and
+returns citations. Off-topic or ungrounded questions return `refused: true`.
+
+This is the **default** tool for "how does Memtrace X work?" questions.
+
+Umbrella routing: `memtrace-docs` workflow.
+
+## `ask_docs` parameters
+
+| Param | Required | Notes |
+|---|---|---|
+| `question` | yes | Pass the user's question verbatim when possible |
+
+```json
+{ "question": "How do I deploy MemDB with Docker Compose?" }
+```
+
+## Response shape
+
+```json
+{
+  "ok": true,
+  "answer": "…markdown with /docs/… links…",
+  "citations": ["enterprise/memdb-deploy", "cli/connect"],
+  "refused": false
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `answer` | Grounded response text |
+| `citations` | Doc slugs used as context |
+| `refused` | `true` when no context or injection detected |
+| `refusalReason` | `no_context` or `injection` when refused |
+
+## Steps
+
+### 1. Ask
+
+Use the user's exact wording when it is already a clear question:
+
+```json
+{ "question": "What MCP tools are available?" }
+```
+
+### 2. Handle refusal
+
+If `refused: true` with `no_context`:
+
+1. Retry `search_docs` with shorter keywords
+2. `read_doc` on the best slug
+3. If still empty — tell the user docs did not cover it; do not invent
+
+### 3. Deepen with read_doc
+
+When the user needs exhaustive tables (e.g. all MCP tools):
+
+```json
+{ "slug": "mcp/tools" }
+```
+
+After `ask_docs` gave a summary.
+
+## Example questions → ask_docs
+
+| User asks | ask_docs question |
+|---|---|
+| How to install Memtrace? | `"How do I install Memtrace?"` |
+| What is Rail? | `"What is Memtrace Rail and how do I enable it?"` |
+| Enterprise MemDB on Azure | `"How do I deploy self-hosted MemDB on Azure?"` |
+| How to connect local memtrace to shared MemDB | `"How do engineers connect with memtrace connect?"` |
+| What skills exist? | `"What agent skills does Memtrace ship?"` |
+
+## Privacy note
+
+`ask_docs` sends the **question string** to memtrace.io, which runs retrieval and
+calls a hosted LLM (DeepSeek) server-side. No repo source code is transmitted.
+Do not paste secrets into questions.
+
+## Offline behavior
+
+`ok: false` → network or API error. Quote the `error` and `hint` fields; suggest
+checking connectivity or `MEMTRACE_DOCS_API_URL`.

package/skills/commands/memtrace-docs-read.md

@@ -0,0 +1,91 @@
+---
+name: memtrace-docs-read
+description: "Read the full plain-text body of an official Memtrace docs page by slug. Use when you know the page path (from search_docs, ask_docs citations, or user link) and need complete content — CLI reference, enterprise deploy guide, MCP tool tables. Calls read_doc or memtrace://docs/* resources on memtrace.io."
+allowed-tools:
+  - mcp__memtrace__read_doc
+  - mcp__memtrace__search_docs
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+`read_doc` fetches the full rendered text of one docs page. Use after `search_docs`
+or `ask_docs` when excerpts are not enough — long flag tables, deploy runbooks,
+MCP tool inventories.
+
+Alternative: MCP resource `memtrace://docs/<slug>` via `read_resource` if your
+client prefers resources over tools.
+
+Umbrella routing: `memtrace-docs` workflow.
+
+## `read_doc` parameters
+
+| Param | Required | Notes |
+|---|---|---|
+| `slug` | yes | Path without `/docs/` prefix |
+
+```json
+{ "slug": "enterprise/memdb-deploy" }
+```
+
+Valid examples:
+
+- `getting-started`
+- `cli/start`
+- `mcp/tools`
+- `enterprise/connect`
+- `cli/rail` (hidden from sidebar but indexed)
+
+## Response shape
+
+```json
+{
+  "ok": true,
+  "slug": "enterprise/memdb-deploy",
+  "title": "Deploy MemDB",
+  "body": "…full plain text…"
+}
+```
+
+## Steps
+
+### 1. Resolve slug
+
+From user URL `https://memtrace.io/docs/cli/connect` → slug `cli/connect`.
+
+From `ask_docs` citations array → use slug directly.
+
+From unknown topic → `search_docs` first, then `read_doc` on top hit.
+
+### 2. Read and summarize
+
+Read the `body`, answer the user, keep `/docs/<slug>` links when citing.
+
+### 3. Multi-page topics
+
+Enterprise deploy + engineer connect:
+
+```json
+{ "slug": "enterprise/memdb-deploy" }
+```
+
+then
+
+```json
+{ "slug": "enterprise/connect" }
+```
+
+## When NOT to use read_doc
+
+| Situation | Use instead |
+|---|---|
+| User asked a natural-language question | `ask_docs` first |
+| You don't know which page | `search_docs` first |
+| User's **source code** in their repo | `memtrace-search` / `memtrace-first` |
+
+## Offline behavior
+
+`ok: false` → docs API unreachable. Do not substitute local README guesses.

package/skills/commands/memtrace-docs-search.md

@@ -0,0 +1,94 @@
+---
+name: memtrace-docs-search
+description: "Search official Memtrace documentation with semantic full-text search. Use when the user wants to find doc pages, locate a guide, or discover which docs cover a topic (fleet, MCP, CLI, enterprise MemDB, skills). Calls search_docs on memtrace.io. Do not grep local files or web-search for Memtrace product docs."
+allowed-tools:
+  - mcp__memtrace__search_docs
+  - mcp__memtrace__read_doc
+metadata:
+  author: "Syncable <support@syncable.dev>"
+  version: "1.0.0"
+  category: development
+---
+
+## Overview
+
+`search_docs` queries the hosted Memtrace docs corpus (same index as memtrace.io/docs
+and the Ask AI widget). Returns ranked **chunks** — not full pages. Follow with
+`read_doc` when you need the complete page.
+
+Umbrella routing: `memtrace-docs` workflow.
+
+## Quick Reference
+
+| Tool | Best for |
+|------|----------|
+| `search_docs` | Find which doc pages/sections match a topic |
+| `read_doc` | Load full page text after search hits |
+
+## `search_docs` parameters
+
+| Param | Required | Default | Notes |
+|---|---|---|---|
+| `query` | yes | — | Natural-language search string |
+| `limit` | no | 8 | Max chunks to return |
+
+```json
+{ "query": "deploy MemDB helm azure", "limit": 8 }
+```
+
+## Steps
+
+### 1. Search
+
+```json
+{ "query": "memtrace rail enable hook", "limit": 6 }
+```
+
+### 2. Inspect results
+
+Each hit includes:
+
+```json
+{
+  "slug": "cli/rail",
+  "pageTitle": "memtrace rail & route",
+  "h2Title": "Subcommands",
+  "h2Id": "enable-sub",
+  "excerpt": "…",
+  "distance": 0.12
+}
+```
+
+Lower `distance` ≈ better match.
+
+### 3. Read full pages when needed
+
+```json
+{ "slug": "cli/rail" }
+```
+
+Slug uses forward slashes: `enterprise/memdb-deploy`, `mcp/tools`, `getting-started`.
+
+## Common slugs
+
+| Topic | Slug |
+|---|---|
+| Getting started | `getting-started` |
+| MCP tools list | `mcp/tools` |
+| MCP docs tools | `mcp/docs-tools` |
+| Agent skills | `mcp/skills` |
+| Deploy MemDB (enterprise) | `enterprise/memdb-deploy` |
+| Connect to shared MemDB | `enterprise/connect` |
+| memtrace connect CLI | `cli/connect` |
+| Rail | `cli/rail` |
+
+## Offline behavior
+
+If `ok: false`, the docs API is unreachable. Report the error; do not fall back to
+hallucinated documentation. Local code-graph tools are unaffected.
+
+## Hand off
+
+- Natural-language "how do I…" → `memtrace-docs-ask` (`ask_docs`) instead
+- Found the right slug → `memtrace-docs-read` (`read_doc`)
+- User's **source code** → `memtrace-first` / `memtrace-search` (different corpus)