memtrace-skills 1.2.9 → 1.2.11

package/dist/transformers/rail-hooks.js

@@ -3,8 +3,8 @@
  * hook. Each supported agent intercepts tool calls differently, so each gets a
  * thin host-specific registration that points at the SAME router
  * (`memtrace route --hook --host <h>`). All entries are idempotent and remove
- * cleanly. Hooks default to observe mode (zero behavior change); the user opts
- * into more via `MEMTRACE_RAIL=nudge|rail|strict`.
+ * cleanly. Hooks default to nudge mode (context without suppressing ordinary
+ * tools); explicit `MEMTRACE_RAIL` and rail.json modes remain authoritative.
  *
  * Host families:
  *  - Claude Code   → `.claude/settings.json` hooks.PreToolUse (in claude.ts)
@@ -19,7 +19,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
-import { railIsActive, railHookCommand, railHookInvocation, isRailCommand } from '../rail-runtime.js';
+import { railIsActive, railHookCommand, railHookInvocation, isRailCommand, enrichEnabled } from '../rail-runtime.js';
 /** Substring identifying a memtrace-owned Rail hook entry. */
 export const RAIL_HOOK_MARKER = 'route --hook';
 /** The discovery tools each host surfaces. */
@@ -68,10 +68,8 @@ export function openCodeConfigDir(ctx, options = {}) {
         ? openCodeGlobalConfigDir(options)
         : path.join(ctx.cwd, '.opencode');
 }
-// OpenCode's plugin directory name changed across versions: current official
-// docs use `plugins/` (plural) while older/community builds load `plugin/`
-// (singular). We write the plugin to BOTH so it loads regardless of version;
-// uninstall removes both. (Identical content — whichever the runtime reads.)
+// Enumerate both locations for upgrade/uninstall cleanup. OpenCode loads both,
+// so installation must write only the current plural directory (public #82).
 export function openCodeRailPluginPaths(ctx, options = {}) {
     const base = openCodeConfigDir(ctx, options);
     return [
@@ -79,6 +77,13 @@ export function openCodeRailPluginPaths(ctx, options = {}) {
         path.join(base, 'plugins', 'memtrace-rail.js'),
     ];
 }
+export function writeOpenCodeRailPlugin(ctx, source) {
+    const [legacy, current] = openCodeRailPluginPaths(ctx);
+    fs.mkdirSync(path.dirname(current), { recursive: true });
+    fs.writeFileSync(current, source);
+    fs.rmSync(legacy, { force: true });
+    return current;
+}
 function isRecord(v) {
     return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
@@ -154,7 +159,7 @@ export function removeSettingsHook(settingsPath, eventName) {
  * schema: `{version, hooks: {beforeShellExecution: [{command}]}}`. We intercept
  * both shell execution (where rg/grep/find run) and file reads.
  */
-export function registerCursorRailHook(hooksPath, binary) {
+export function registerCursorRailHook(hooksPath, binary, options = {}) {
     if (!railIsActive()) {
         removeCursorRailHook(hooksPath);
         return { registered: false };
@@ -176,9 +181,27 @@ export function registerCursorRailHook(hooksPath, binary) {
     const preserved = existing.filter((e) => !(isRecord(e) && typeof e.command === 'string' && isRailCommand(e.command)));
     preserved.push({ command: cmd });
     cfg.hooks[event] = preserved;
+    // Grep enrichment: Cursor `postToolUse` on its Shell and Grep tools answers
+    // with `additional_context` (design section 9). Fresh Nudge enables it;
+    // explicit mode/enrichment settings keep their existing meaning.
+    const post = Array.isArray(cfg.hooks[CURSOR_ENRICH_EVENT]) ? cfg.hooks[CURSOR_ENRICH_EVENT] : [];
+    const postPreserved = post.filter((e) => !(isRecord(e) && typeof e.command === 'string' && isRailCommand(e.command)));
+    if (options.enrich ?? enrichEnabled()) {
+        postPreserved.push({
+            matcher: CURSOR_ENRICH_MATCHER,
+            command: railHookCommand('cursor', process.platform, ['--phase', 'post']),
+            timeout: 2,
+        });
+    }
+    if (postPreserved.length)
+        cfg.hooks[CURSOR_ENRICH_EVENT] = postPreserved;
+    else
+        delete cfg.hooks[CURSOR_ENRICH_EVENT];
     writeJsonAtomic(hooksPath, cfg);
     return { registered: true };
 }
+export const CURSOR_ENRICH_EVENT = 'postToolUse';
+export const CURSOR_ENRICH_MATCHER = 'Shell|Grep';
 /** Remove the Cursor Rail hook entries. */
 /** Windsurf Cascade hooks path (user-level). */
 export function windsurfHooksPath() {
@@ -305,7 +328,7 @@ export function removeCursorRailHook(hooksPath) {
     if (!isRecord(cfg.hooks))
         return { changed: false };
     let changed = false;
-    for (const event of ['beforeShellExecution', 'beforeReadFile']) {
+    for (const event of ['beforeShellExecution', 'beforeReadFile', CURSOR_ENRICH_EVENT]) {
         if (!Array.isArray(cfg.hooks[event]))
             continue;
         const before = cfg.hooks[event];
@@ -334,22 +357,31 @@ export function removeCursorRailHook(hooksPath) {
  */
 export function openCodePluginSource(binary) {
     const hook = railHookInvocation('open-code');
+    const runtimeModule = new URL('../rail-runtime.js', import.meta.url).href;
     return `// AUTO-GENERATED by memtrace install — Memtrace Rail discovery hook.
-// Routes OpenCode tool calls through \`${binary} route\`. Defaults to observe
-// (no-op) unless MEMTRACE_RAIL=nudge|rail|strict. Remove via 'memtrace uninstall'.
+// Routes OpenCode tool calls through \`${binary} route\`.
+// Defaults to non-blocking context; explicit Rail mode overrides are retained.
+// Remove via 'memtrace uninstall'.
 import { execFileSync } from 'node:child_process';
+import { enrichEnabled, railConfig, railMode } from ${JSON.stringify(runtimeModule)};
 
 const BIN = ${JSON.stringify(hook.command)};
 const ARGS = ${JSON.stringify([...hook.args, '--json'])};
+const POST_ARGS = ${JSON.stringify([...hook.args, '--phase', 'post'])};
 
-export const MemtraceRail = async ({ project, client, $ }) => ({
+export const MemtraceRail = async ({ directory }) => ({
   'tool.execute.before': async (input, output) => {
     try {
       const tool = input?.tool;
       if (tool !== 'bash' && tool !== 'grep' && tool !== 'glob') return;
+      const config = railConfig();
+      const mode = railMode(process.env, config);
+      // The post hook supplies Nudge context once, after the ordinary search.
+      // Rail and Strict retain their existing pre-execution enforcement.
+      if (enrichEnabled(process.env, config) && mode !== 'rail' && mode !== 'strict') return;
       const attempt = {
         host: 'open-code',
-        cwd: output?.args?.cwd || process.cwd(),
+        cwd: output?.args?.cwd || directory || process.cwd(),
         tool: tool === 'bash' ? 'Bash' : tool === 'grep' ? 'Grep' : 'Glob',
         input: output?.args || {},
         session_id: input?.sessionID || 'opencode',
@@ -367,6 +399,33 @@ export const MemtraceRail = async ({ project, client, $ }) => ({
       if (e && String(e.message || '').startsWith('[Memtrace Rail]')) throw e;
     }
   },
+  // OpenCode @opencode-ai/plugin 1.19.4: native registry tools expose the
+  // mutable {title, output, metadata} tool.execute.after contract.
+  'tool.execute.after': async (input, output) => {
+    try {
+      const tool = input?.tool;
+      if ((tool !== 'bash' && tool !== 'grep') || typeof output?.output !== 'string'
+          || !enrichEnabled() || typeof input?.sessionID !== 'string') return;
+      const payload = {
+        cwd: input?.args?.cwd || directory || process.cwd(),
+        session_id: input.sessionID,
+        tool_use_id: input.callID,
+        tool_name: tool === 'bash' ? 'Bash' : 'Grep',
+        tool_input: input.args || {},
+        tool_response: { ...(output.metadata || {}), stdout: output.output },
+      };
+      const raw = execFileSync(BIN, POST_ARGS, {
+        input: JSON.stringify(payload), timeout: 2000, encoding: 'utf8', windowsHide: true,
+      });
+      const text = JSON.parse(raw)?.hookSpecificOutput?.additionalContext;
+      if (typeof text === 'string' && text.trim() && Buffer.byteLength(text, 'utf8') <= 4000) {
+        output.output += '\\n\\n' + text;
+      }
+    } catch {
+      // Missing owner, invalid query, timeout or malformed output leaves the
+      // original ordinary-tool response byte-for-byte unchanged.
+    }
+  },
 });
 `;
 }

package/dist/transformers/shared.d.ts

@@ -14,7 +14,8 @@ export interface JsonMcpResult {
 }
 export declare function registerMcpServersJsonAt(filePath: string, binary: string): JsonMcpResult;
 export declare function removeMcpServersJsonAt(filePath: string): void;
-export declare function registerVsCodeMcpAt(filePath: string, binary: string): JsonMcpResult;
+export type VsCodeMcpScope = 'user' | 'workspace';
+export declare function registerVsCodeMcpAt(filePath: string, binary: string, scope?: VsCodeMcpScope): JsonMcpResult;
 export declare function removeVsCodeMcpAt(filePath: string): void;
 export declare function registerOpenCodeMcpAt(filePath: string, binary: string): JsonMcpResult;
 export declare function removeOpenCodeMcpAt(filePath: string): void;

package/dist/transformers/shared.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import path from 'path';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
+import { writeManagedSkill, removeManagedSkills } from '../managed-skills.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
@@ -27,23 +28,15 @@ export function skillMarkdown(skill, extraFrontmatter = {}) {
     return `---\nname: ${name}\ndescription: "${safeDesc}"${extra ? `\n${extra}` : ''}\n---\n\n${skill.body}`;
 }
 export function writeSkills(skills, rootDir, extraFrontmatter = {}) {
-    removeMemtraceSkills(rootDir);
+    let written = 0;
     for (const skill of skills) {
-        const name = skillName(skill);
-        const outDir = path.join(rootDir, name);
-        fs.mkdirSync(outDir, { recursive: true });
-        fs.writeFileSync(path.join(outDir, 'SKILL.md'), skillMarkdown(skill, extraFrontmatter));
+        if (writeManagedSkill(rootDir, skillName(skill), skillMarkdown(skill, extraFrontmatter)))
+            written++;
     }
-    return skills.length;
+    return written;
 }
 export function removeMemtraceSkills(rootDir) {
-    if (!fs.existsSync(rootDir))
-        return;
-    for (const entry of fs.readdirSync(rootDir)) {
-        if (entry.startsWith('memtrace-')) {
-            fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
-        }
-    }
+    removeManagedSkills(rootDir);
 }
 export function writeTextAtomic(filePath, content) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -78,27 +71,39 @@ export function removeMcpServersJsonAt(filePath) {
     else
         writeJsonAtomic(filePath, value);
 }
-export function registerVsCodeMcpAt(filePath, binary) {
+export function registerVsCodeMcpAt(filePath, binary, scope = 'workspace') {
     const { value, corrupted, backupPath } = safeReadJson(filePath);
     if (corrupted)
         return { registered: false, backupPath };
     const cfg = (value ?? {});
     cfg.servers = cfg.servers ?? {};
     removeLegacyMcpServer(cfg.servers);
-    cfg.servers[MCP_SERVER_NAME] = {
+    // MEMBIZ-50 D2: `cwd` is the ONE anchor that drives both store resolution
+    // and repository discovery in `memtrace mcp`. Without it the server spawns
+    // in the editor's own working directory (often the user profile), where it
+    // can resolve a stale user-level `.memdb` instead of the project's.
+    //
+    // MEMBIZ-95: but VS Code only resolves `${workspaceFolder}` in a
+    // WORKSPACE-scoped file. In the user-level `Code/User/mcp.json` it refuses
+    // outright —
+    //
+    //     Error starting memtrace: CodeExpectedError:
+    //     Variable workspaceFolder can not be resolved. Please open a folder.
+    //
+    // — and Memtrace never launches at all, in any window. A server that cannot
+    // start anchors nothing, so keeping the variable there trades a narrow
+    // wrong-store risk for a total outage. Omitted at user scope: a server
+    // spawned without an anchor joins the unique live `memtrace start` instead
+    // (see `mcp_from_home_cwd_lists_the_unique_live_estate`), which is the
+    // normal case and what the field workaround relied on.
+    const entry = {
         type: 'stdio',
         command: binary,
         args: ['mcp'],
-        // MEMBIZ-50 D2: `cwd` is the ONE anchor that drives both store
-        // resolution and repository discovery in `memtrace mcp`. Without it a
-        // user-scope entry spawns the server in the editor's own working
-        // directory (often the user profile), where it resolves a stale
-        // user-level `.memdb` instead of the project's — every project then
-        // shares one wrong, empty store. VS Code substitutes the variable per
-        // window, so one global entry serves every project correctly.
-        cwd: '${workspaceFolder}',
+        ...(scope === 'workspace' ? { cwd: '${workspaceFolder}' } : {}),
         env: MEMTRACE_MCP_ENV,
     };
+    cfg.servers[MCP_SERVER_NAME] = entry;
     writeJsonAtomic(filePath, cfg);
     return { registered: true };
 }

package/dist/transformers/vscode.js

@@ -31,7 +31,9 @@ export const vscodeTransformer = {
         const warnings = [];
         const mcpConfigPath = mcpPath(ctx);
         if (!ctx.skipMcp) {
-            const result = registerVsCodeMcpAt(mcpConfigPath, ctx.memtraceBinary);
+            // MEMBIZ-95: the user-level file cannot carry `${workspaceFolder}` —
+            // VS Code refuses to resolve it there and never starts the server.
+            const result = registerVsCodeMcpAt(mcpConfigPath, ctx.memtraceBinary, ctx.scope === 'global' ? 'user' : 'workspace');
             mcpRegistered = result.registered;
             if (!mcpRegistered && result.backupPath) {
                 warnings.push(`VS Code MCP config was malformed; backed up to ${result.backupPath}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace-skills",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "description": "Memtrace skills for AI coding agents — codebase exploration, temporal evolution, impact analysis, and more.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "prebuild": "node scripts/copy-skills.js",
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "vitest run && tsc && node --test tests/runtime/rail-lifecycle.test.mjs",
+    "test": "vitest run && tsc && node --test tests/runtime/rail-lifecycle.test.mjs tests/runtime/rail-enrich-hook.test.mjs tests/runtime/opencode-rail-plugin.test.mjs",
     "test:watch": "vitest"
   },
   "dependencies": {

package/plugins/memtrace-skills/references/mcp-parameters.md

@@ -91,6 +91,9 @@ the repository.
 | `include_diagnostics` | boolean | no | `false` | Include `id`, `score` in results |
 | `include_dependency_checks` | boolean | no | `true` | With diagnostics, set false for scores without pre-edit risk checks |
 | `include_context` | boolean | no | auto | Bounded processes, communities and selected callers/callees; default on for concepts, off for identifiers |
+| `verbose` | boolean | no | `false` | Full uncompacted answer (row provenance, ranking constants); `context.next_calls` is kept either way |
+
+Rows are `name`, `kind`, `file_path`, `start_line`, `end_line` (`symbol_start_line`/`symbol_end_line` when a long symbol was narrowed). `context.processes[].id` is the `process` argument for `get_process_flow`.
 
 No `kind` param — use `find_symbol(kind=...)` instead.
 
@@ -131,10 +134,13 @@ No parameters. Call once at session start to get `repo_id` values.
 | `as_of` | string | no | now |
 | `view` | string | no | `"live"` |
 | `include_content` | boolean | no | `false` |
-| `limit` | integer | no | `20` (max `200`) |
+| `limit` | integer | no | `5` (max `200`; `20` with `verbose`) |
 | `offset` | integer | no | `0` |
+| `include_references` | boolean | no | `false` |
+| `include_details` | boolean | no | `false` |
+| `verbose` | boolean | no | `false` |
 
-Returns compact symbol locations, relationship sections, community and process context. Source bodies require `include_content: true`, or use `get_source_window`. Each section has `pagination` metadata with `available`, `returned`, `offset`, and `next_offset`. The offset applies independently to each section; repeat with that section's `next_offset` to continue it. These pages cover the bounded graph result: `graph_truncated` and `available_is_lower_bound` remain true when an internal graph cap was reached.
+Returns the subject (location, signature, doc, `node_id`), callers and callees with edge evidence (`via`: `rel`, `reason`, `confidence`, call-site `lines`), process memberships and community. Source bodies require `include_content: true`, or use `get_source_window`. `pagination` lists only sections with more rows: `available`, `next_offset`, and `lower_bound` when an internal graph cap was reached; the offset applies to every section. References are counted in `omitted.references` and returned with `include_references: true`. `verbose: true` returns the full uncompacted answer. An answer over the response budget drops whole rows, sets `truncated: true` and names each shortened list in `omitted` with how to fetch it.
 
 ### `analyze_relationships`
 | Field | Type | Required | Default | Notes |
@@ -276,8 +282,13 @@ Returns `cochanged_files[]` with `file_path`, `cochange_count`, `last_cochanged_
 | `branch` | string | no | `"main"` |
 | `limit` | integer | no | `20` (max `200`) |
 | `offset` | integer | no | `0` |
+| `focus_symbol` | string | no | — |
+| `query` | string | no | — |
+| `from_symbol` | boolean | no | `false` |
+| `path_nodes` | array of string | no | — |
+| `verbose` | boolean | no | `false` |
 
-Returns ordered steps, `total_steps`, `returned_steps`, `next_offset`, and `scan_truncated`. Follow `next_offset` to continue. The existing internal scan cap still applies; `scan_truncated` signals when pagination cannot expose the entire process.
+Returns ordered steps, `total_steps`, `returned_steps`, `next_offset`, and `scan_truncated`. Follow `next_offset` to continue. `focus_symbol` (a member `node_id`) returns its call neighborhood; `query` searches the members and returns matches with short previews. Without a catalog process pass `from_symbol: true` and a callable `node_id` as `process`. To search one `flow_paths.choices` path pass `from_symbol: true`, `process` = `flow_paths.anchor_symbol`, `path_nodes` = the choice's `nodes`, and `query`. `connections` name their endpoints with `rel`, `reason`, `confidence` and call-site `lines`. `verbose: true` returns the full uncompacted answer.
 
 ### `find_dependency_path`
 | Field | Type | Required | Default | Notes |

package/plugins/memtrace-skills/skills/memtrace-codebase-exploration/SKILL.md

@@ -5,6 +5,10 @@ description: "Map an indexed source-code repo into a structured overview — sca
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for a narrative overview and onboarding. For a specific algorithm such as PageRank, bridge detection, communities, or dependency paths, use `memtrace-graph`. A broad overview and an algorithm query remain distinct entry points.
+
 Full codebase exploration workflow — from indexing through architectural understanding. Chains indexing, graph algorithms, community detection, and temporal analysis into a structured onboarding experience. Use this when someone is new to a codebase and needs to build a mental model.
 
 ## Steps

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

@@ -5,6 +5,10 @@ description: "Orient at the start of a coding session, review what recently chan
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for the fixed last-24-hour briefing, hotspots, and session self-audit. To resume from your own saved anchor, use `memtrace-session-continuity`; do not substitute a 24-hour window for time since the user's last session.
+
 Session bookends: orient before you start, audit before you finish. All
 three tools read the bi-temporal version history — every save is a change
 event with complexity deltas, so "what happened" includes "did it make the

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

@@ -1,17 +1,31 @@
 ---
 name: memtrace-first
-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 the miss first, then allow one targeted reformulation and bounded source verification or fallback, and reindex only on evidence of stale or incomplete coverage — never in a loop. A `repo_not_in_store` refusal means a different store holds the repository: route to that store, never grep and never re-index here."
+description: "Use indexed graph and decision context for nontrivial code discovery, debugging, caller or consumer analysis, cross-file changes, impact, history, and recorded contracts. Follow useful retrieval with relevant relationships and current-source verification. Ordinary tools remain available; explicit user and project workflows take precedence."
 ---
 # Memtrace First
 
-Use Memtrace first for code discovery in indexed repositories. Use its graph to
-understand relationships, processes and impact; verify source when exact behavior
-matters. Retrieval is evidence, not a guarantee of complete coverage.
+Use Memtrace when indexed context helps resolve a concrete question about code,
+relationships, processes, change impact or recorded decisions. Retrieval is
+evidence, not a guarantee of complete coverage or correct behavior.
+
+## Respect the chosen workflow
+
+This is the managed contextual default. Explicit user and project instructions,
+including custom strict workflows and opt-outs, take precedence. Keep the existing
+Rail setting: `off`, `observe`, `nudge`, `rail` or `strict`. Do not change a user's
+mode or treat this default as authorization for indexing or other external actions.
+
+Ordinary source search, reads, edits and tests remain available. Use them directly
+for small, known local changes, exact text searches, or questions the graph cannot
+answer. There is no mandatory first call, query quota or minimum tool count. For
+nontrivial discovery or shared behavior, prefer Memtrace's indexed context and
+follow useful hits with the relationships that answer the open question.
 
 ## Establish scope
 
-Call `list_indexed_repositories` once per session. Select the actual repository
-and branch; pass `repo_id` explicitly when possible. It lists this session's
+Select the actual repository and branch; pass `repo_id` explicitly when
+possible. When the task already names the repository, use it directly; call
+`list_indexed_repositories` only when the repository or branch is unknown. It lists this session's
 store only, so a repository missing from it may still be indexed and live in
 another store. Do not index a parent containing unrelated repositories. For a
 deliberately shared workspace, verify its workspace marker and scope before
@@ -52,7 +66,7 @@ answer from stale repos.
 ## Search, then investigate
 
 - Exact symbol: `find_symbol(name=..., repo_id=...)`.
-- Behavior or concept: `find_code(query=..., repo_id=...)`.
+- Behavior or concept: `find_code(query=..., repo_id=..., limit=10)` (default 20 rows).
 - Relationships: `get_symbol_context` or `analyze_relationships` on the useful hit.
 - Change impact: `get_impact`; confirm relevant callers against source.
 - Execution path: `get_process_flow`; follow its `next_offset` for further steps.
@@ -68,7 +82,8 @@ Treat partial context, truncation and unavailable overlay context as incomplete
 evidence; selected static flows are not complete runtime traces.
 
 `context.next_calls` provides scoped follow-up arguments for the useful symbol
-and process. Before changing shared behavior, inspect relevant callers and
+and process; copy them rather than rebuilding arguments. A `context.processes[].id`
+is the `process` for `get_process_flow`. Before changing shared behavior, inspect relevant callers and
 callees to identify contracts the patch must preserve. Use process IDs for
 flow navigation. No sampled flow is not proof that no call path exists.
 
@@ -79,8 +94,11 @@ Run related existing tests to detect regressions before claiming completion.
 
 Read the bounded source span when verifying behavior, editing or quoting. Do not
 fetch whole files or entire process traces when a local span answers the question.
-`get_symbol_context` omits source bodies by default; use `include_content: true`
-for explicit expansion, and `limit`/`offset` for relationship pages. An omitted
+`get_symbol_context` returns 5 rows per relationship section and omits source
+bodies and references by default: `pagination` names sections with more
+(`limit`/`offset`), `omitted` names what was left out (`include_references: true`,
+`include_details: true`), and `include_content: true` returns the symbol's body whole
+with short neighbour previews. An omitted
 risk diagnostic means unknown, not zero callers or low risk. Check truncation and
 pagination metadata before describing a neighborhood as complete.
 
@@ -124,9 +142,11 @@ searched nothing. The `diagnostic` block names the store that answered, its
    problem: the id matches more than one repository in *this* store, and the
    message says to pass the exact id. Do that and stop here. Everything below
    applies to the `not_in_store` reason.
-2. Do not fall back to file search. The refusal says so itself, in `_note`:
-   "Wrong store for this repo_id; do not fall back to filesystem search, ask
-   the session attached to the store named in diagnostic.repo_lives_in."
+2. Route graph questions to the owning store. A filesystem match cannot turn
+   this refusal into successful graph retrieval or prove that graph edges are
+   absent. Ordinary source work may continue when the actual checkout, path and
+   branch have been verified; keep that evidence separate from the unavailable
+   graph answer. Do not freeze the user's workflow while waiting for a store.
 3. Do not call `index_directory`. The repository is already indexed in the
    store `repo_lives_in` names. Indexing it here would build a second copy in
    the wrong store — writes are never routed to another store, so the call
@@ -138,7 +158,9 @@ searched nothing. The `diagnostic` block names the store that answered, its
    or `--workspace <name>` when a manifest or a Named Workspace owns its
    scope.
 5. If `repo_lives_in` is absent, no live Memtrace runtime declares the
-   repository. Running `memtrace start` in its own workspace is the fix.
+   repository. If graph access is needed and setup is authorized, start Memtrace
+   in that repository's own workspace. Ordinary verified source work need not
+   wait; a retrieval refusal is not authorization to create another index.
 
 A refusal is not the only outcome. When the runtime whose store declares the
 repository is live and publishes a reachable control port, the same read is
@@ -167,8 +189,9 @@ that sets no `repo_in_store` key, is handled in the section above, not here.
    tool that sets no `repo_in_store` key, missing scope, wrong branch, pending
    index/embedding job, stale index and a valid empty result. Do not treat an
    error as a clean miss, and do not treat a refusal or a keyless zero as one
-   either — re-ask through `find_code` or `find_symbol` before reading
-   anything into a keyless zero.
+   either. Use a membership-checking tool when a membership or absence claim
+   matters; a keyless zero alone cannot establish it. Ordinary source
+   verification remains available without an extra graph-call prerequisite.
 2. For an ambiguous query, make at most one targeted reformulation, using an
    identifier or path hint where available, and a `file_path` filter such as
    `ui/`, `memtrace-ui/`, `src/` or the framework directory when one applies.
@@ -195,8 +218,9 @@ are also appropriate uses of file tools.
 
 ## Check rationale before changing code
 
-BEFORE you edit/refactor/delete existing code or choose another pattern, call
-Cortex `recall_decision("<symbol/subsystem/approach>")` when available. If a symbol
+When changing shared behavior, deleting code, or revisiting an approach that may
+have a recorded contract, use Cortex `recall_decision("<symbol/subsystem/approach>")`
+when available and relevant. If a symbol
 ID is available, consult `why_is_this_here(symbol_id)` and
 `governing_contracts(symbol_id)`. Verify a
 matching decision with `verify_intent` before relying on it. Unknown rationale
@@ -208,8 +232,10 @@ when choosing among competing local idioms.
 
 Use JSON numbers for limits/depths and booleans for switches. Use symbol names
 for `get_symbol_context.symbol`, `get_impact.target` and relationship targets;
-use IDs only where the specific schema asks for one. Prefer the live schema over
-remembered parameters. `find_code` has no `kind` filter; use `find_symbol` for it.
+use a returned exact UUID when that tool supports identity-based recovery. Check
+the actual schema rather than guessing an argument name. When a call is rejected,
+check that tool's schema rather than retrying from memory; do not pre-read schemas.
+`find_code` has no `kind` filter; use `find_symbol` for it.
 Search without an explicit repository uses safe scope inference, not an implicit
 search of every repository. `get_evolution` uses `from`, not `days`.
 
@@ -222,12 +248,17 @@ receipts; preserve evidence internally and report meaningful findings and limits
 - The right repository and branch were used.
 - Graph claims are supported by retrieved edges, with missing/truncated data
   made explicit, and exact behavioral claims are checked against source.
-- A `repo_not_in_store` refusal was routed on `diagnostic.repo_lives_in`, not
-  answered by grep and not answered by indexing the repository into this store.
+- A `repo_not_in_store` graph question was routed on `diagnostic.repo_lives_in`,
+  not answered by indexing another copy into this store. Any ordinary source
+  fallback verified the actual checkout and was not reported as graph evidence.
 - A zero from a tool that sets no `repo_in_store` key was re-checked through a
   membership-checking tool before it was called an absence.
 - Failed retrieval on a genuine zero (`repo_in_store: true`) is diagnosed and
   bounded; it does not trigger query or reindex loops, and fallbacks remain
   distinguishable from retrieval successes.
-- Any source read was bounded to the span Memtrace returned.
-- Existing rationale and contracts were checked when the tools were available.
+- Source inspection was scoped to the question; exact claims and edits were
+  verified against the current source rather than inferred from graph edges.
+- Relevant recorded rationale and contracts were checked when available.
+- Before finishing, compare the requested requirements with the implementation
+  and verification: state any remaining unverified behavior. This checklist is
+  a review aid, not machine-verified correctness or an extra approval gate.

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

@@ -5,6 +5,10 @@ description: "Map source-code architecture with graph algorithms — PageRank ce
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for a specific graph algorithm or structural question: centrality, bridges, communities, or dependency paths. For a narrative introduction spanning scale, architecture, APIs, and recent activity, use `memtrace-codebase-exploration`.
+
 Graph algorithms over the knowledge graph — communities (Louvain), PageRank centrality, bridge symbols (articulation points), shortest paths, and execution flows.
 
 ## Quick Reference

package/plugins/memtrace-skills/skills/memtrace-guided-refactor/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: memtrace-guided-refactor
+description: "Run a saved, staged refactor shared with Memtrace's Quality page. Use for splitting tangled functions, extracting helpers, or continuing a guided refactor run with fixed file scope and checks between edits."
+---
+
+Use the `guided_refactor` MCP tool to track the same run shown in Quality. This
+skill coordinates the agent's edits and language tools; Memtrace does not execute
+shell commands or rewrite source on behalf of the browser. Never invent check
+results. Recorded checks are agent-reported evidence, not proof of equivalence.
+
+## Diagnose
+
+1. Resolve the repository and exact symbol/file with `find_symbol` and
+   `get_symbol_context`. Use the runtime attached to that repository.
+2. If a run ID was supplied, call `guided_refactor` with `action: "get"`,
+   `repo_id`, and `run_id`. Otherwise call `action: "list"` and reuse a relevant
+   unfinished run; create one with `file_path` and `symbol` only when needed.
+3. Inspect function complexity, affected callers, evolution/churn, module
+   boundaries, existing tests, and decision-memory constraints. Use
+   `get_function_quality_metrics`, `get_impact`, `get_evolution`, and
+   `get_symbol_context` as available; read the selected source. Record missing
+   evidence explicitly. LOC alone is never a reason to split code.
+4. Respect the returned classification. `Manual` runs permit diagnosis and
+   blueprint only. In this first version, staged source work is available for
+   Rust, TypeScript, JavaScript, Python, and Go in Git checkouts. Other indexed
+   languages and configuration files still get a saved manual plan. Nothing is
+   classified Automatic.
+
+## Blueprint
+
+Call `get` before running baseline checks and retain its `snapshot`. Run the
+project's compiler/type checker and relevant behavior tests. Compare the exported
+API and affected callers. If a check fails or is unavailable, record that fact;
+do not label it passed or begin source work.
+
+Submit `action: "blueprint"` with the returned `revision`, retained `snapshot`,
+diagnostic evidence in `note`, baseline `checks`, and 1–12 ordered `steps`:
+
+```json
+{
+  "title": "Capture diagnostic behavior",
+  "operation": "capture_tests",
+  "files": ["src/parser.rs", "tests/parser.rs"],
+  "boundary": "Add cases for existing diagnostics; preserve parsing behavior"
+}
+```
+
+The only staged operations are `capture_tests` and `extract_helper`. Name every
+file a step can change, including planned new files, with repository-relative
+paths. Keep each step small enough to review. Do not change generated code,
+ownership or lifetime contracts, macros, import side effects, public APIs, or
+configuration semantics as an incidental extraction. If those boundaries cannot
+be justified, pause and explain the manual decision needed.
+
+Every check has `kind` (`compiler`, `tests`, or `api`), `command`, `passed`, and
+`evidence`. All three kinds are required. Evidence should include exact commands,
+results/counts, and uncertainty. API evidence can be a documented source/caller
+comparison when the project has no API-check command.
+
+## Execute one step
+
+1. Call `get`, inspect saved state, and send `action: "begin"` with `revision`,
+   `snapshot`, and one stable `agent_id`. The coordinator refuses overlapping
+   active runs and source changes between steps. Do not delegate overlapping edits.
+2. Make only the active step's bounded change. Preserve existing unrelated edits.
+   Do not commit during a run: a changed Git HEAD requires a fresh diagnosis.
+3. Call `get` after editing and **before** running the checks. Retain that snapshot,
+   run the compiler, tests, and API comparison, then send `action: "checkpoint"`
+   with that same `snapshot`, current `revision`, `agent_id`, `checks`, and `note`.
+   Never refresh the snapshot after tests merely to get past a stale-source gate.
+4. Inspect the response. A paused run is not a passed checkpoint. Stop editing
+   until the failure is understood. Keep failed evidence visible. To resume after
+   fixing the active step, obtain a fresh snapshot, rerun all checks, and send
+   `action: "resume"` with checks and an explanation, then checkpoint the step.
+   Restore an accidental scope escape without discarding someone else's work;
+   otherwise create a new diagnosis with an explicitly reviewed scope.
+5. Begin the next step only after the preceding checkpoint is accepted.
+
+## Verify
+
+After every step is checked, the run enters Verify. Compare before/after
+complexity, callers, public API, test results, and the actual diff. Get a snapshot,
+run final checks, then submit `action: "complete"` with `revision`, `snapshot`,
+`agent_id`, `checks`, and the comparison in `note`. State what remains unproven.
+
+The Quality page shows saved stages, agent, scope, current tracked-file diff,
+failed checks, and the final comparison. Closing the browser does not discard the
+run. Use `pause` with a reason whenever the next safe step needs a decision.

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

@@ -5,6 +5,10 @@ description: "Compute the blast radius of modifying a symbol through transitive
 
 ## Overview
 
+### Choose the scope
+
+Use this entry for a quick upstream/downstream blast radius. For the bundled pre-edit gate, including co-change, complexity, churn, and a verification checklist, use `memtrace-preflight`. Keep the narrower impact query available when a full preflight is unnecessary.
+
 Compute the blast radius of changing a specific symbol. Traces upstream (what depends on this) and downstream (what this depends on) through the knowledge graph to quantify risk before making modifications.
 
 ## Quick Reference