memtrace-skills 0.8.61 → 0.8.63

package/dist/transformers/claude.js

@@ -3,7 +3,7 @@ import path from 'path';
 import os from 'os';
 import { execCommand, commandExists } from '../utils.js';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
-import { MEMTRACE_MCP_ENV } from './shared.js';
+import { LEGACY_MCP_SERVER_NAME, MEMTRACE_MCP_ENV, removeLegacyMcpServer, } from './shared.js';
 const PLUGIN_NAME = 'memtrace-skills';
 const MARKETPLACE_NAME = 'memtrace';
 const MARKETPLACE_REPO = 'syncable-dev/memtrace-public';
@@ -64,6 +64,12 @@ function readExistingMemtraceEnv(filePath, serverKey = 'mcpServers') {
 async function tryMcpAddJson(memtraceBinary) {
     if (!(await commandExists('claude')))
         return false;
+    try {
+        await execCommand(`claude mcp remove --scope user ${LEGACY_MCP_SERVER_NAME}`, { timeoutMs: 5_000 });
+    }
+    catch {
+        // The legacy server is normally absent. Removal is a best-effort upgrade migration.
+    }
     const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
     const existingEnv = readExistingMemtraceEnv(settingsFile);
     const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
@@ -200,6 +206,7 @@ export function registerMcpInSettingsAt(settingsPath, memtraceBinary) {
     }
     const settings = (value ?? {});
     settings.mcpServers = settings.mcpServers ?? {};
+    removeLegacyMcpServer(settings.mcpServers);
     // Deep-merge env so user-set keys (e.g. MEMTRACE_LICENSE_KEY) survive
     // re-registration. memtrace-owned keys (MEMTRACE_MCP_ENV) override on
     // conflict so installer-managed values stay authoritative.
@@ -611,6 +618,7 @@ function writeClaudeLocalMcp(mcpPath, binary) {
     }
     const cfg = (value ?? {});
     cfg.mcpServers = cfg.mcpServers ?? {};
+    removeLegacyMcpServer(cfg.mcpServers);
     // Deep-merge env: preserve user-set keys, memtrace defaults win on conflict.
     const existing = cfg.mcpServers['memtrace'];
     const existingEnv = (isRecord(existing) && isRecord(existing.env))

package/dist/transformers/codex.js

@@ -4,6 +4,7 @@ import path from 'path';
 import { commandExists, execCommand } from '../utils.js';
 import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
+const LEGACY_MCP_SERVER_NAME = 'memfleet';
 function codexRailHooksPath(ctx) {
     const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
     return path.join(base, 'hooks.json');
@@ -43,6 +44,12 @@ function isMemtraceMcpTable(tableName) {
         || tableName.startsWith(`mcp_servers.${MCP_SERVER_NAME}.`)
         || tableName.startsWith(`mcp_servers."${MCP_SERVER_NAME}".`);
 }
+function isLegacyMemfleetMcpTable(tableName) {
+    return tableName === `mcp_servers.${LEGACY_MCP_SERVER_NAME}`
+        || tableName === `mcp_servers."${LEGACY_MCP_SERVER_NAME}"`
+        || tableName.startsWith(`mcp_servers.${LEGACY_MCP_SERVER_NAME}.`)
+        || tableName.startsWith(`mcp_servers."${LEGACY_MCP_SERVER_NAME}".`);
+}
 /**
  * Tables we want stripped on re-registration.
  *
@@ -51,6 +58,8 @@ function isMemtraceMcpTable(tableName) {
  * Only the top-level table + non-env sub-tables get stripped.
  */
 function isMemtraceMcpTableToStrip(tableName) {
+    if (isLegacyMemfleetMcpTable(tableName))
+        return true;
     if (tableName === `mcp_servers.${MCP_SERVER_NAME}.env`)
         return false;
     if (tableName === `mcp_servers."${MCP_SERVER_NAME}".env`)

package/dist/transformers/cursor.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
-import { MEMTRACE_MCP_ENV } from './shared.js';
+import { MEMTRACE_MCP_ENV, removeLegacyMcpServer } from './shared.js';
 import { registerCursorRailHook, removeCursorRailHook } from './rail-hooks.js';
 function skillsRoot(ctx) {
     const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
@@ -71,6 +71,7 @@ export function registerCursorMcpAt(mcpFile, binary) {
     }
     const cfg = (value ?? {});
     cfg.mcpServers = cfg.mcpServers ?? {};
+    removeLegacyMcpServer(cfg.mcpServers);
     // Deep-merge env: preserve user-set keys (e.g. MEMTRACE_LICENSE_KEY) across
     // re-registration; memtrace-owned defaults (MEMTRACE_MCP_ENV) win on conflict.
     const existing = cfg.mcpServers['memtrace'];

package/dist/transformers/hermes.js

@@ -1,7 +1,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { MEMTRACE_MCP_ENV, MCP_SERVER_NAME, removeMemtraceSkills, writeSkills, writeTextAtomic, } from './shared.js';
+import { LEGACY_MCP_SERVER_NAME, MEMTRACE_MCP_ENV, MCP_SERVER_NAME, removeMemtraceSkills, writeSkills, writeTextAtomic, } from './shared.js';
 function skillsRoot(ctx) {
     void ctx;
     return path.join(os.homedir(), '.hermes', 'skills');
@@ -43,7 +43,7 @@ function removeMemtraceYamlBlock(raw) {
             out.push(line);
             continue;
         }
-        if (inMcpServers && new RegExp(`^\\s{2}${MCP_SERVER_NAME}:\\s*$`).test(line)) {
+        if (inMcpServers && new RegExp(`^\\s{2}(?:${MCP_SERVER_NAME}|${LEGACY_MCP_SERVER_NAME}):\\s*$`).test(line)) {
             skippingMemtrace = true;
             continue;
         }

package/dist/transformers/shared.d.ts

@@ -1,6 +1,8 @@
 import { Skill } from '../skills.js';
 export declare const MCP_SERVER_NAME = "memtrace";
+export declare const LEGACY_MCP_SERVER_NAME = "memfleet";
 export declare const MEMTRACE_MCP_ENV: Record<string, string>;
+export declare function removeLegacyMcpServer(servers: Record<string, unknown>): void;
 export declare function skillName(skill: Skill): string;
 export declare function skillMarkdown(skill: Skill, extraFrontmatter?: Record<string, string>): string;
 export declare function writeSkills(skills: Skill[], rootDir: string, extraFrontmatter?: Record<string, string>): number;

package/dist/transformers/shared.js

@@ -2,12 +2,19 @@ import fs from 'fs';
 import path from 'path';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
 export const MCP_SERVER_NAME = 'memtrace';
+// MemFleet coordination now lives on the Memtrace MCP server. Replace this
+// retired registration during install so clients do not load the same graph
+// catalogue twice after upgrading from the standalone MemFleet plugin.
+export const LEGACY_MCP_SERVER_NAME = 'memfleet';
 // The binary reads its configuration (workspace anchors, mode) directly, so no
 // env vars are required at MCP-registration time. Kept as an empty constant so
 // any future env-var plumbing (e.g. RUST_LOG, MEMTRACE_DATA_DIR overrides) has
 // one place to land. The upgrade migration in install.js also prunes stale env
 // keys from pre-existing MCP entries.
 export const MEMTRACE_MCP_ENV = {};
+export function removeLegacyMcpServer(servers) {
+    delete servers[LEGACY_MCP_SERVER_NAME];
+}
 export function skillName(skill) {
     return skill.filename.replace(/\.md$/, '');
 }
@@ -50,6 +57,7 @@ export function registerMcpServersJsonAt(filePath, binary) {
         return { registered: false, backupPath };
     const cfg = (value ?? {});
     cfg.mcpServers = cfg.mcpServers ?? {};
+    removeLegacyMcpServer(cfg.mcpServers);
     cfg.mcpServers[MCP_SERVER_NAME] = {
         command: binary,
         args: ['mcp'],
@@ -76,6 +84,7 @@ export function registerVsCodeMcpAt(filePath, binary) {
         return { registered: false, backupPath };
     const cfg = (value ?? {});
     cfg.servers = cfg.servers ?? {};
+    removeLegacyMcpServer(cfg.servers);
     cfg.servers[MCP_SERVER_NAME] = {
         type: 'stdio',
         command: binary,
@@ -104,6 +113,7 @@ export function registerOpenCodeMcpAt(filePath, binary) {
     const cfg = (value ?? {});
     cfg.$schema = cfg.$schema ?? 'https://opencode.ai/config.json';
     cfg.mcp = cfg.mcp ?? {};
+    removeLegacyMcpServer(cfg.mcp);
     cfg.mcp[MCP_SERVER_NAME] = {
         type: 'local',
         command: [binary, 'mcp'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "0.8.61",
+  "version": "0.8.63",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {

package/plugins/memtrace-skills/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memtrace-skills",
   "description": "Memtrace skills for codebase exploration, code search, relationship analysis, temporal evolution, blast radius impact, code quality, graph algorithms, API topology, GitHub PR code review, multi-agent fleet coordination (branch-scoped intents, conflict classification, and agent-judged Class C resolution), and multi-step workflows for change impact, incident investigation, refactoring, session continuity, co-change analysis, and episode replay, Cortex decision memory (decision recall, provenance, intent verification), session bookends (daily briefing, hotspots, self-audit), and single-symbol pre-edit preflight checks.",
-  "version": "0.8.61",
+  "version": "0.8.63",
   "author": {
     "name": "Syncable",
     "email": "support@syncable.dev"

package/plugins/memtrace-skills/skills/memtrace-change-impact-analysis/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: memtrace-change-impact-analysis
-description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers, temporal stability, and Cortex decision-memory constraints — and produce a risk-rated change plan. Use before edits, refactors, API changes, renames, removals, PR reviews, or risk assessments, especially when changing established behavior or deleting code. Do not manually grep references or browse files for impact; use Memtrace graph context, change history, and decision recall/provenance."
+description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers, temporal stability, and Cortex decision-memory constraints — and produce a risk-rated change plan. Use for multi-symbol or multi-part edits, refactors, API changes, renames, removals, PR reviews, or risk assessments that need a plan; for one symbol's raw blast radius, call get_impact directly. Do not manually grep references or browse files for impact; use Memtrace graph context, change history, and decision recall/provenance."
 ---
 
 ## Overview
 
 Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, checks Cortex decision memory for recorded decisions/bans/contracts, and produces a risk-rated change plan.
 
+Use this workflow when the change spans multiple symbols or needs a risk-rated plan. For a quick raw upstream/downstream radius around one known symbol, call `get_impact` directly.
+
 ## Steps
 
 ### 1. Identify what's being changed

package/plugins/memtrace-skills/skills/memtrace-decision-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-decision-memory
-description: "Check Cortex decision memory through the normal Memtrace MCP tools — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before any non-trivial edit/refactor/delete of existing code, before re-picking a library/pattern/architecture, or before contradicting an apparent convention. Route: free-text decisions/bans/conventions → memtrace-decision-recall; symbol lineage/contracts → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log."
+description: "Use Cortex decision memory through the normal Memtrace MCP tools. Trigger for free-text questions about what was decided, chosen, rejected, banned, or established as a convention; for why a symbol exists or which contracts constrain it; for whether a known decision held, drifted, or was violated; and for the implementation arc behind a decision. Use before non-trivial edits, refactors, deletions, or re-picking a library, pattern, architecture, or subsystem behavior. Routes internally across recall_decision, why_is_this_here, governing_contracts, verify_intent, and get_arc. Do not guess rationale from a diff or git log."
 ---
 
 # Decision Memory First
@@ -53,16 +53,16 @@ with `memtrace-first`; do not fabricate decisions.
 
 ## The decision rule
 
-| What you're about to do / be asked | Right tool | Sub-skill |
+| What you're about to do / be asked | Right tool | Procedure |
 |---|---|---|
-| "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | `memtrace-decision-recall` |
-| "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | `memtrace-decision-recall` |
-| About to edit behavior, re-pick a library/pattern/architecture, or change a subsystem policy | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
-| "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | `memtrace-provenance` |
-| About to delete/refactor/clean up existing code, especially odd or "dead" code | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
-| "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | `memtrace-provenance` |
-| "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | `memtrace-intent-verification` |
-| "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | `memtrace-intent-verification` |
+| "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | Free-text recall |
+| "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | Free-text recall |
+| About to edit behavior, re-pick a library/pattern/architecture, or change a subsystem policy | `recall_decision` FIRST — don't re-litigate a settled call | Free-text recall |
+| "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | Symbol provenance |
+| About to delete/refactor/clean up existing code, especially odd or "dead" code | `why_is_this_here` + `governing_contracts` before touching it | Symbol provenance |
+| "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | Symbol contracts |
+| "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | Intent verification |
+| "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | Implementation arc |
 
 ## How the tools chain (ids come from recall, not from names)
 
@@ -126,8 +126,8 @@ The routing outcome: which sibling skill/tool to invoke, and the evidence to quo
 
 ```
 Ask:    "Should I switch to library X?"
-Route:  recall_decision("library X")   →  memtrace-decision-recall
+Route:  recall_decision("library X")   →  free-text recall
 Hit:    { id: 4217, kind: "decision", ... }   (a ban exists)
-Next:   verify_intent(4217)            →  memtrace-intent-verification
+Next:   verify_intent(4217)            →  intent verification
 Quote:  Verdict + Evidence (FactStatus, proof path) — or CannotProve = unknown, not permission
 ```

package/plugins/memtrace-skills/skills/memtrace-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-docs
-description: "Route Memtrace product documentation questions to the hosted docs MCP tools before guessing, searching the web, or reading stale local copies. Use when the user asks how Memtrace works, how to install/configure CLI/MCP/fleet/Cortex/enterprise MemDB, what tools or skills exist, what a command does, or wants the agent to read up on official docs. Calls search_docs, ask_docs, or read_doc on memtrace.io (override with MEMTRACE_DOCS_API_URL). Do not hallucinate Memtrace behavior — query docs first. Separate from memtrace-first (your repo's code graph)."
+description: "Use official hosted Memtrace documentation before guessing, web search, or stale local copies. Trigger when the user asks how Memtrace works; how to install, configure, or deploy CLI, MCP, fleet, Cortex, or enterprise MemDB; what tools, skills, or commands exist; wants to find or locate official docs for a topic; or provides/asks to read a full docs page or slug. Routes internally across ask_docs for cited natural-language answers, search_docs for page discovery, and read_doc for complete page text. Separate from memtrace-first, which searches the user's indexed source code."
 ---
 
 # Memtrace Docs First
@@ -37,15 +37,15 @@ Override API host: `MEMTRACE_DOCS_API_URL` (default `https://memtrace.io`).
 
 ## The decision rule
 
-| User is asking | Right tool | Sub-skill |
+| User is asking | Right tool |
 |---|---|---|
-| "How do I install / configure / deploy X in Memtrace?" | `ask_docs(question=…)` | `memtrace-docs-ask` |
-| "What MCP tools / skills / CLI commands exist?" | `ask_docs` or `search_docs` then `read_doc` on hit slugs | `memtrace-docs-ask` / `memtrace-docs-search` |
-| "What does `memtrace rail enable` do?" | `ask_docs` | `memtrace-docs-ask` |
-| "Find docs about fleet coordination" | `search_docs(query=…)` | `memtrace-docs-search` |
-| "Read the full getting-started page" | `read_doc(slug="getting-started")` | `memtrace-docs-read` |
-| "Read enterprise MemDB deploy guide" | `read_doc(slug="enterprise/memdb-deploy")` | `memtrace-docs-read` |
-| Need several related sections | `search_docs` → `read_doc` on top slugs | `memtrace-docs-search` + `memtrace-docs-read` |
+| "How do I install / configure / deploy X in Memtrace?" | `ask_docs(question=…)` |
+| "What MCP tools / skills / CLI commands exist?" | `ask_docs` or `search_docs` then `read_doc` on hit slugs |
+| "What does `memtrace rail enable` do?" | `ask_docs` |
+| "Find docs about fleet coordination" | `search_docs(query=…)` |
+| "Read the full getting-started page" | `read_doc(slug="getting-started")` |
+| "Read enterprise MemDB deploy guide" | `read_doc(slug="enterprise/memdb-deploy")` |
+| Need several related sections | `search_docs` → `read_doc` on top slugs |
 
 **Default for natural-language questions:** `ask_docs` — it retrieves context and
 returns a cited answer in one call.
@@ -80,6 +80,41 @@ if you need the full page.
 2. Follow-up `read_doc(slug="enterprise/memdb-deploy")` for operator steps
 3. Engineer connect → `read_doc(slug="enterprise/connect")` or `cli/connect`
 
+## Tool procedures
+
+### ask_docs — cited answers
+
+Pass the user's question verbatim when it is already clear:
+
+```json
+{ "question": "How do I deploy MemDB with Docker Compose?" }
+```
+
+The response is `{ ok, answer, citations[], refused, refusalReason? }`. If
+`refused: true` with `no_context`, retry `search_docs` with shorter keywords and
+then `read_doc` on the best slug. `ask_docs` sends only the question string to
+memtrace.io's hosted RAG service; do not include secrets or repo source.
+
+### search_docs — page discovery
+
+```json
+{ "query": "deploy MemDB helm azure", "limit": 8 }
+```
+
+Results are ranked chunks with `slug`, `pageTitle`, `h2Title`, `excerpt`, and
+`distance` (lower is a better match). They are not full pages. Follow with
+`read_doc` when you need the complete reference.
+
+### read_doc — complete page text
+
+```json
+{ "slug": "enterprise/memdb-deploy" }
+```
+
+Use a slug from a user URL, `ask_docs` citations, or `search_docs` results. The
+response is `{ ok, slug, title, body }`. For multi-page topics, read each slug you
+will rely on rather than extrapolating from one page.
+
 ## Red flags — STOP, use docs tools
 
 | Thought | Reality |
@@ -113,9 +148,3 @@ read_doc → { ok: true, slug, title, body }
 
 When `refused: true`, tell the user the docs did not cover it and suggest browsing
 https://memtrace.io/docs or rephrasing.
-
-## Sub-skills
-
-- Discovery / chunk search → `memtrace-docs-search`
-- Grounded Q&A → `memtrace-docs-ask`
-- Full page read → `memtrace-docs-read`

package/plugins/memtrace-skills/skills/memtrace-fleet-first/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-fleet-first
-description: "Coordinate fleets of coding agents sharing one repo+branch: declare typed intents, classify edit episodes, and resolve conflicts before they collide. Use FIRST when more than one coding agent works the same repo+branch at once (a 'fleet'), before reading code, planning a refactor, or making an edit — triggered by 'I'm about to edit X', 'rename Y across the codebase', joining a running fleet/session branch, coordinating with other agents, or prose hand-offs. Do not grep for 'who else is touching this' and do not skip fleet_publish_intent because 'it's a small change'. Fleet coordination is branch-scoped: pass your session branch so your fleet coordinates and stays isolated from agents on other branches. Skip ONLY for genuinely solo sessions or pure docs-only edits where coordination has zero value."
+description: "Coordinate fleets of coding agents sharing one repo+branch: publish typed intents, classify edit episodes, and resolve conflicts before they collide. Use FIRST when multiple agents work the same repo+branch, before reading/planning/editing, when joining a fleet or handing work off, and when the user says two agents are changing the same thing, asks who should proceed, has a decision waiting, or asks you to mediate a Class C conflict. Covers branch-scoped publish-edit-record plus verdict, human-resolution, and directive polling. Do not grep for who else is touching a symbol or skip coordination because a change looks small. Skip only genuinely solo sessions or docs-only edits with no coordination value."
 ---
 
 # Fleet First
@@ -115,6 +115,8 @@ degrades to "a human reviews a suggestion," never a silent bad merge.
 | Finish an edit | `fleet_record_episode` (get A/B/C) |
 | Got a Class C as the judge | `fleet_submit_verdict` (reconcile/recommend/defer) |
 | Blocked on a Class C | poll `fleet_get_escalation` until `your_directive ≠ wait` |
+| A human chose the outcome | `fleet_resolve_escalation` (record the decision) |
+| See the needs-human queue | `fleet_list_escalations` |
 | See who's in the fleet | `fleet_status` (active_agents, pending decisions) |
 | Inspect a symbol's coordination state | `fleet_get_node_state` |
 

package/plugins/memtrace-skills/skills/memtrace-fleet-record-episode/SKILL.md

@@ -41,7 +41,7 @@ never make your edit a Class C.
 ## After recording
 
 - Class A/B → continue.
-- Class C → enter the decision loop (see `memtrace-fleet-coordination`). Don't keep
+- Class C → enter the decision loop (see `memtrace-fleet-first`). Don't keep
   editing the contested symbols until your directive is `proceed`.
 - Every recorded episode is logged and persists as the fleet's reviewable audit
   trail. Review history with `fleet_query_episodes({repo_id, node?, conflict_class?})`.

package/plugins/memtrace-skills/skills/memtrace-fleet-resolve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-fleet-resolve
-description: "Resolve a Class C fleet decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Use when the user says 'a decision is waiting' or 'who should proceed', when you are handed a mediation_request, when acting as a mediator between two agents, or when a human chooses a winner in the dashboard. For the underlying conflict-class model and decision loop, see memtrace-fleet-coordination."
+description: "Resolve a Class C fleet decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Use when the user says 'a decision is waiting' or 'who should proceed', when you are handed a mediation_request, when acting as a mediator between two agents, or when a human chooses a winner in the dashboard. For the underlying conflict-class model and decision loop, see memtrace-fleet-first."
 ---
 
 ## Overview

package/skills/commands/memtrace-fleet-record-episode.md

@@ -50,7 +50,7 @@ never make your edit a Class C.
 ## After recording
 
 - Class A/B → continue.
-- Class C → enter the decision loop (see `memtrace-fleet-coordination`). Don't keep
+- Class C → enter the decision loop (see `memtrace-fleet-first`). Don't keep
   editing the contested symbols until your directive is `proceed`.
 - Every recorded episode is logged and persists as the fleet's reviewable audit
   trail. Review history with `fleet_query_episodes({repo_id, node?, conflict_class?})`.

package/skills/commands/memtrace-fleet-resolve.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-fleet-resolve
-description: "Resolve a Class C fleet decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Use when the user says 'a decision is waiting' or 'who should proceed', when you are handed a mediation_request, when acting as a mediator between two agents, or when a human chooses a winner in the dashboard. For the underlying conflict-class model and decision loop, see memtrace-fleet-coordination."
+description: "Resolve a Class C fleet decision: submit your verdict as an agent judge (fleet_submit_verdict), poll your own directive (fleet_get_escalation), see the needs-human queue (fleet_list_escalations), or record a human decision (fleet_resolve_escalation). Use when the user says 'a decision is waiting' or 'who should proceed', when you are handed a mediation_request, when acting as a mediator between two agents, or when a human chooses a winner in the dashboard. For the underlying conflict-class model and decision loop, see memtrace-fleet-first."
 allowed-tools:
   - mcp__memtrace__fleet_submit_verdict
   - mcp__memtrace__fleet_get_escalation

package/skills/workflows/memtrace-change-impact-analysis.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-change-impact-analysis
-description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers, temporal stability, and Cortex decision-memory constraints — and produce a risk-rated change plan. Use before edits, refactors, API changes, renames, removals, PR reviews, or risk assessments, especially when changing established behavior or deleting code. Do not manually grep references or browse files for impact; use Memtrace graph context, change history, and decision recall/provenance."
+description: "Compute what a planned source-code change will break — blast radius, affected processes, cross-repo callers, temporal stability, and Cortex decision-memory constraints — and produce a risk-rated change plan. Use for multi-symbol or multi-part edits, refactors, API changes, renames, removals, PR reviews, or risk assessments that need a plan; for one symbol's raw blast radius, call get_impact directly. Do not manually grep references or browse files for impact; use Memtrace graph context, change history, and decision recall/provenance."
 allowed-tools:
   - mcp__memtrace__find_symbol
   - mcp__memtrace__find_code
@@ -24,6 +24,8 @@ user-invocable: true
 
 Pre-change risk assessment workflow. Before modifying code, this workflow maps the full blast radius, identifies affected processes, checks recent change history for instability signals, checks Cortex decision memory for recorded decisions/bans/contracts, and produces a risk-rated change plan.
 
+Use this workflow when the change spans multiple symbols or needs a risk-rated plan. For a quick raw upstream/downstream radius around one known symbol, call `get_impact` directly.
+
 ## Steps
 
 ### 1. Identify what's being changed

package/skills/workflows/memtrace-decision-memory.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-decision-memory
-description: "Check Cortex decision memory through the normal Memtrace MCP tools — the umbrella entry point for decision recall, provenance (why is this here), intent verification, and governing contracts. Use before assuming WHY code exists, before any non-trivial edit/refactor/delete of existing code, before re-picking a library/pattern/architecture, or before contradicting an apparent convention. Route: free-text decisions/bans/conventions → memtrace-decision-recall; symbol lineage/contracts → memtrace-provenance; did the decision hold → memtrace-intent-verification. Do not guess rationale from the diff or git log."
+description: "Use Cortex decision memory through the normal Memtrace MCP tools. Trigger for free-text questions about what was decided, chosen, rejected, banned, or established as a convention; for why a symbol exists or which contracts constrain it; for whether a known decision held, drifted, or was violated; and for the implementation arc behind a decision. Use before non-trivial edits, refactors, deletions, or re-picking a library, pattern, architecture, or subsystem behavior. Routes internally across recall_decision, why_is_this_here, governing_contracts, verify_intent, and get_arc. Do not guess rationale from a diff or git log."
 allowed-tools:
   - mcp__memtrace__recall_decision
   - mcp__memtrace__why_is_this_here
@@ -63,16 +63,16 @@ with `memtrace-first`; do not fabricate decisions.
 
 ## The decision rule
 
-| What you're about to do / be asked | Right tool | Sub-skill |
+| What you're about to do / be asked | Right tool | Procedure |
 |---|---|---|
-| "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | `memtrace-decision-recall` |
-| "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | `memtrace-decision-recall` |
-| About to edit behavior, re-pick a library/pattern/architecture, or change a subsystem policy | `recall_decision` FIRST — don't re-litigate a settled call | `memtrace-decision-recall` |
-| "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | `memtrace-provenance` |
-| About to delete/refactor/clean up existing code, especially odd or "dead" code | `why_is_this_here` + `governing_contracts` before touching it | `memtrace-provenance` |
-| "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | `memtrace-provenance` |
-| "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | `memtrace-intent-verification` |
-| "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | `memtrace-intent-verification` |
+| "Did we already decide/choose/reject X?" "What's our convention on Y?" | `recall_decision("X")` | Free-text recall |
+| "Is there a ban / a 'don't do this' on Z?" | `recall_decision("Z")` — bans surface as decisions | Free-text recall |
+| About to edit behavior, re-pick a library/pattern/architecture, or change a subsystem policy | `recall_decision` FIRST — don't re-litigate a settled call | Free-text recall |
+| "Why is this code here?" "Why is it done this odd way?" | `why_is_this_here(symbol_id)` | Symbol provenance |
+| About to delete/refactor/clean up existing code, especially odd or "dead" code | `why_is_this_here` + `governing_contracts` before touching it | Symbol provenance |
+| "What rules/contracts constrain this symbol?" | `governing_contracts(symbol_id)` | Symbol contracts |
+| "Did decision D actually hold, or did we drift?" | `verify_intent(decision_id)` | Intent verification |
+| "What commits/episodes implemented decision D?" | `get_arc(decision_id)` | Implementation arc |
 
 ## How the tools chain (ids come from recall, not from names)
 
@@ -136,8 +136,8 @@ The routing outcome: which sibling skill/tool to invoke, and the evidence to quo
 
 ```
 Ask:    "Should I switch to library X?"
-Route:  recall_decision("library X")   →  memtrace-decision-recall
+Route:  recall_decision("library X")   →  free-text recall
 Hit:    { id: 4217, kind: "decision", ... }   (a ban exists)
-Next:   verify_intent(4217)            →  memtrace-intent-verification
+Next:   verify_intent(4217)            →  intent verification
 Quote:  Verdict + Evidence (FactStatus, proof path) — or CannotProve = unknown, not permission
 ```

package/skills/workflows/memtrace-docs.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-docs
-description: "Route Memtrace product documentation questions to the hosted docs MCP tools before guessing, searching the web, or reading stale local copies. Use when the user asks how Memtrace works, how to install/configure CLI/MCP/fleet/Cortex/enterprise MemDB, what tools or skills exist, what a command does, or wants the agent to read up on official docs. Calls search_docs, ask_docs, or read_doc on memtrace.io (override with MEMTRACE_DOCS_API_URL). Do not hallucinate Memtrace behavior — query docs first. Separate from memtrace-first (your repo's code graph)."
+description: "Use official hosted Memtrace documentation before guessing, web search, or stale local copies. Trigger when the user asks how Memtrace works; how to install, configure, or deploy CLI, MCP, fleet, Cortex, or enterprise MemDB; what tools, skills, or commands exist; wants to find or locate official docs for a topic; or provides/asks to read a full docs page or slug. Routes internally across ask_docs for cited natural-language answers, search_docs for page discovery, and read_doc for complete page text. Separate from memtrace-first, which searches the user's indexed source code."
 allowed-tools:
   - mcp__memtrace__search_docs
   - mcp__memtrace__ask_docs
@@ -45,15 +45,15 @@ Override API host: `MEMTRACE_DOCS_API_URL` (default `https://memtrace.io`).
 
 ## The decision rule
 
-| User is asking | Right tool | Sub-skill |
+| User is asking | Right tool |
 |---|---|---|
-| "How do I install / configure / deploy X in Memtrace?" | `ask_docs(question=…)` | `memtrace-docs-ask` |
-| "What MCP tools / skills / CLI commands exist?" | `ask_docs` or `search_docs` then `read_doc` on hit slugs | `memtrace-docs-ask` / `memtrace-docs-search` |
-| "What does `memtrace rail enable` do?" | `ask_docs` | `memtrace-docs-ask` |
-| "Find docs about fleet coordination" | `search_docs(query=…)` | `memtrace-docs-search` |
-| "Read the full getting-started page" | `read_doc(slug="getting-started")` | `memtrace-docs-read` |
-| "Read enterprise MemDB deploy guide" | `read_doc(slug="enterprise/memdb-deploy")` | `memtrace-docs-read` |
-| Need several related sections | `search_docs` → `read_doc` on top slugs | `memtrace-docs-search` + `memtrace-docs-read` |
+| "How do I install / configure / deploy X in Memtrace?" | `ask_docs(question=…)` |
+| "What MCP tools / skills / CLI commands exist?" | `ask_docs` or `search_docs` then `read_doc` on hit slugs |
+| "What does `memtrace rail enable` do?" | `ask_docs` |
+| "Find docs about fleet coordination" | `search_docs(query=…)` |
+| "Read the full getting-started page" | `read_doc(slug="getting-started")` |
+| "Read enterprise MemDB deploy guide" | `read_doc(slug="enterprise/memdb-deploy")` |
+| Need several related sections | `search_docs` → `read_doc` on top slugs |
 
 **Default for natural-language questions:** `ask_docs` — it retrieves context and
 returns a cited answer in one call.
@@ -88,6 +88,41 @@ if you need the full page.
 2. Follow-up `read_doc(slug="enterprise/memdb-deploy")` for operator steps
 3. Engineer connect → `read_doc(slug="enterprise/connect")` or `cli/connect`
 
+## Tool procedures
+
+### ask_docs — cited answers
+
+Pass the user's question verbatim when it is already clear:
+
+```json
+{ "question": "How do I deploy MemDB with Docker Compose?" }
+```
+
+The response is `{ ok, answer, citations[], refused, refusalReason? }`. If
+`refused: true` with `no_context`, retry `search_docs` with shorter keywords and
+then `read_doc` on the best slug. `ask_docs` sends only the question string to
+memtrace.io's hosted RAG service; do not include secrets or repo source.
+
+### search_docs — page discovery
+
+```json
+{ "query": "deploy MemDB helm azure", "limit": 8 }
+```
+
+Results are ranked chunks with `slug`, `pageTitle`, `h2Title`, `excerpt`, and
+`distance` (lower is a better match). They are not full pages. Follow with
+`read_doc` when you need the complete reference.
+
+### read_doc — complete page text
+
+```json
+{ "slug": "enterprise/memdb-deploy" }
+```
+
+Use a slug from a user URL, `ask_docs` citations, or `search_docs` results. The
+response is `{ ok, slug, title, body }`. For multi-page topics, read each slug you
+will rely on rather than extrapolating from one page.
+
 ## Red flags — STOP, use docs tools
 
 | Thought | Reality |
@@ -121,9 +156,3 @@ read_doc → { ok: true, slug, title, body }
 
 When `refused: true`, tell the user the docs did not cover it and suggest browsing
 https://memtrace.io/docs or rephrasing.
-
-## Sub-skills
-
-- Discovery / chunk search → `memtrace-docs-search`
-- Grounded Q&A → `memtrace-docs-ask`
-- Full page read → `memtrace-docs-read`

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

@@ -1,6 +1,6 @@
 ---
 name: memtrace-fleet-first
-description: "Coordinate fleets of coding agents sharing one repo+branch: declare typed intents, classify edit episodes, and resolve conflicts before they collide. Use FIRST when more than one coding agent works the same repo+branch at once (a 'fleet'), before reading code, planning a refactor, or making an edit — triggered by 'I'm about to edit X', 'rename Y across the codebase', joining a running fleet/session branch, coordinating with other agents, or prose hand-offs. Do not grep for 'who else is touching this' and do not skip fleet_publish_intent because 'it's a small change'. Fleet coordination is branch-scoped: pass your session branch so your fleet coordinates and stays isolated from agents on other branches. Skip ONLY for genuinely solo sessions or pure docs-only edits where coordination has zero value."
+description: "Coordinate fleets of coding agents sharing one repo+branch: publish typed intents, classify edit episodes, and resolve conflicts before they collide. Use FIRST when multiple agents work the same repo+branch, before reading/planning/editing, when joining a fleet or handing work off, and when the user says two agents are changing the same thing, asks who should proceed, has a decision waiting, or asks you to mediate a Class C conflict. Covers branch-scoped publish-edit-record plus verdict, human-resolution, and directive polling. Do not grep for who else is touching a symbol or skip coordination because a change looks small. Skip only genuinely solo sessions or docs-only edits with no coordination value."
 allowed-tools:
   - mcp__memtrace__fleet_status
   - mcp__memtrace__fleet_branch_context
@@ -128,6 +128,8 @@ degrades to "a human reviews a suggestion," never a silent bad merge.
 | Finish an edit | `fleet_record_episode` (get A/B/C) |
 | Got a Class C as the judge | `fleet_submit_verdict` (reconcile/recommend/defer) |
 | Blocked on a Class C | poll `fleet_get_escalation` until `your_directive ≠ wait` |
+| A human chose the outcome | `fleet_resolve_escalation` (record the decision) |
+| See the needs-human queue | `fleet_list_escalations` |
 | See who's in the fleet | `fleet_status` (active_agents, pending decisions) |
 | Inspect a symbol's coordination state | `fleet_get_node_state` |