memtrace-skills 1.2.8 → 1.2.10

package/dist/transformers/claude.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'url';
 import { copyCanonicalPluginAssets, copyCanonicalPluginManifest, readCanonicalPluginVersion, } from '../../plugin-assets/index.js';
 import { execCommand, commandExists } from '../utils.js';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
-import { railIsActive, railHookInvocation, railHookCommand, RAIL_GUARD_MARKER } from '../rail-runtime.js';
+import { railIsActive, railHookInvocation, railHookCommand, RAIL_GUARD_MARKER, enrichEnabled, railMode } from '../rail-runtime.js';
 import { LEGACY_MCP_SERVER_NAME, MEMTRACE_MCP_ENV, removeLegacyMcpServer, } from './shared.js';
 const PLUGIN_NAME = 'memtrace-skills';
 const MARKETPLACE_NAME = 'memtrace';
@@ -27,6 +27,17 @@ const MARKETPLACE_SETTING_CONTAINERS = [
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function existingMcpArgs(entry) {
+    if (!isRecord(entry) || !Array.isArray(entry.args) || entry.args.length === 0)
+        return undefined;
+    return entry.args.every((arg) => typeof arg === 'string') ? [...entry.args] : undefined;
+}
+function readExistingMemtraceArgs(filePath) {
+    const { value, corrupted } = safeReadJson(filePath);
+    if (corrupted || !isRecord(value?.mcpServers))
+        return undefined;
+    return existingMcpArgs(value.mcpServers.memtrace);
+}
 /**
  * Read the existing env block (if any) for the memtrace MCP entry in a Claude
  * settings/mcp.json file. Returns an empty object if the file or entry is
@@ -82,7 +93,8 @@ async function tryMcpAddJson(memtraceBinary) {
     const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
     const config = JSON.stringify({
         command: memtraceBinary,
-        args: ['mcp'],
+        args: readExistingMemtraceArgs(claudeUserConfigFile())
+            ?? readExistingMemtraceArgs(settingsFile) ?? ['mcp'],
         env: mergedEnv,
     });
     // Shell-quote the JSON. Use single quotes; escape any embedded single quote.
@@ -185,7 +197,7 @@ async function tryClaudeCliInstall() {
  * Merge-add the memtrace MCP server into a Claude settings.json file.
  * Never overwrites a malformed file — backs it up and returns registered=false.
  */
-export function registerMcpInSettingsAt(settingsPath, memtraceBinary, legacyEnv = {}) {
+export function registerMcpInSettingsAt(settingsPath, memtraceBinary, legacyEnv = {}, legacyArgs) {
     const { value, corrupted, backupPath } = safeReadJson(settingsPath);
     if (corrupted) {
         console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped MCP registration for Claude.`);
@@ -209,7 +221,9 @@ export function registerMcpInSettingsAt(settingsPath, memtraceBinary, legacyEnv
     // text can overcome. alwaysLoad opts the memtrace tools back into turn one.
     settings.mcpServers['memtrace'] = {
         command: memtraceBinary,
-        args: ['mcp'],
+        // Workspace and transport flags belong to the user. Replacing these on
+        // upgrade can send every editor into its own store instead of the owner.
+        args: existingMcpArgs(existing) ?? legacyArgs ?? ['mcp'],
         env: mergedEnv,
         alwaysLoad: true,
     };
@@ -257,7 +271,7 @@ export function claudeRailHookCommand(_memtraceBinary, platform = process.platfo
  * is replaced, and unrelated PreToolUse hooks are preserved. Never overwrites
  * a malformed file.
  */
-export function registerRailHookInSettingsAt(settingsPath, memtraceBinary, platform = process.platform) {
+export function registerRailHookInSettingsAt(settingsPath, memtraceBinary, platform = process.platform, options = {}) {
     if (!railIsActive()) {
         removeRailHookFromSettingsAt(settingsPath);
         return { registered: false };
@@ -270,26 +284,39 @@ export function registerRailHookInSettingsAt(settingsPath, memtraceBinary, platf
     const settings = (value ?? {});
     settings.hooks = isRecord(settings.hooks) ? settings.hooks : {};
     pruneMemtraceOwnedHookEntries(settings.hooks);
-    const existing = Array.isArray(settings.hooks.PreToolUse)
-        ? settings.hooks.PreToolUse
-        : [];
-    // Drop any prior memtrace Rail entry so re-install doesn't duplicate it.
-    const preserved = existing.filter((entry) => !isMemtraceOwnedHookEntry(entry));
-    preserved.push({
-        matcher: RAIL_HOOK_MATCHER,
-        hooks: [
-            {
-                type: 'command',
-                ...(platform === 'win32'
-                    ? railHookInvocation('claude-code')
-                    : { command: claudeRailHookCommand(memtraceBinary, platform) }),
-            },
-        ],
+    const enrich = options.enrich ?? enrichEnabled();
+    const mode = options.mode ?? railMode();
+    const hookFor = (extra) => ({
+        type: 'command',
+        ...(platform === 'win32'
+            ? railHookInvocation('claude-code', extra)
+            : { command: railHookCommand('claude-code', platform, extra) }),
     });
-    settings.hooks.PreToolUse = preserved;
+    const append = (event, entry) => {
+        const existing = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+        // Drop any prior memtrace entry so re-install doesn't duplicate it.
+        settings.hooks[event] = [...existing.filter((e) => !isMemtraceOwnedHookEntry(e)), entry];
+    };
+    // With grep enrichment on, the post hook carries the work and the Rail
+    // PreToolUse router is only needed when it can deny (rail/strict): each
+    // Grep/Bash call then costs exactly one node process (design section 3).
+    if (!enrich || mode === 'rail' || mode === 'strict') {
+        append('PreToolUse', { matcher: RAIL_HOOK_MATCHER, hooks: [hookFor([])] });
+    }
+    if (enrich) {
+        append('PostToolUse', { matcher: ENRICH_HOOK_MATCHER, hooks: [{ ...hookFor(['--phase', 'post']), timeout: ENRICH_HOOK_TIMEOUT_S }] });
+        // Compacted context no longer holds earlier blocks: reset the dedupe.
+        append('PreCompact', { hooks: [{ ...hookFor(['--event', 'precompact']), timeout: ENRICH_HOOK_TIMEOUT_S }] });
+    }
     writeJsonAtomic(settingsPath, settings);
     return { registered: true };
 }
+/** Grep enrichment rides PostToolUse on these tools (design section 9). Claude Code on
+ * Windows runs shell commands through its PowerShell tool, so rg/grep/git grep there
+ * arrive as PowerShell calls. */
+export const ENRICH_HOOK_MATCHER = 'Grep|Bash|PowerShell';
+/** Claude hook timeout for the enrichment hooks, in seconds. */
+export const ENRICH_HOOK_TIMEOUT_S = 2;
 /** True when a PreToolUse entry is a memtrace-owned Rail hook (any generation). */
 function isRailHookEntry(entry) {
     return hookCommands(entry).some((command) => command.includes(RAIL_GUARD_MARKER) || RAIL_HOOK_MARKERS.some((marker) => command.includes(marker)));
@@ -510,7 +537,7 @@ export async function registerMcpServer(memtraceBinaryPath) {
     // Desktop-only installs have no `claude` CLI. Claude Code reads user MCP
     // registrations from ~/.claude.json, not ~/.claude/settings.json (hooks).
     // Migrate legacy env values without overriding the authoritative user entry.
-    registerMcpInSettingsAt(claudeUserConfigFile(), memtraceBinaryPath, readExistingMemtraceEnv(settingsFile));
+    registerMcpInSettingsAt(claudeUserConfigFile(), memtraceBinaryPath, readExistingMemtraceEnv(settingsFile), readExistingMemtraceArgs(settingsFile));
     // Retain staging's mirror for older tooling after migrating the user entry.
     registerMcpInSettingsAt(settingsFile, memtraceBinaryPath);
 }
@@ -663,7 +690,7 @@ function writeClaudeLocalMcp(mcpPath, binary) {
     const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
     cfg.mcpServers['memtrace'] = {
         command: binary,
-        args: ['mcp'],
+        args: existingMcpArgs(existing) ?? ['mcp'],
         env: mergedEnv,
     };
     writeJsonAtomic(mcpPath, cfg);

package/dist/transformers/opencode.js

@@ -2,7 +2,7 @@ import fs from 'fs';
 import { railIsActive } from '../rail-runtime.js';
 import path from 'path';
 import { registerOpenCodeMcpAt, removeMemtraceSkills, removeOpenCodeMcpAt, writeSkills, } from './shared.js';
-import { openCodeConfigDir, openCodeRailPluginPaths, openCodePluginSource, } from './rail-hooks.js';
+import { openCodeConfigDir, openCodeRailPluginPaths, openCodePluginSource, writeOpenCodeRailPlugin, } from './rail-hooks.js';
 function skillsRoot(ctx) {
     return ctx.scope === 'global'
         ? path.join(openCodeConfigDir(ctx), 'skills')
@@ -32,13 +32,13 @@ export const opencodeTransformer = {
         // has no stdio hook). Defaults to observe; fail-open. Best effort.
         try {
             const src = openCodePluginSource(ctx.memtraceBinary);
-            for (const pluginPath of openCodeRailPluginPaths(ctx)) {
-                if (!railIsActive()) {
+            if (railIsActive()) {
+                writeOpenCodeRailPlugin(ctx, src);
+            }
+            else {
+                for (const pluginPath of openCodeRailPluginPaths(ctx)) {
                     fs.rmSync(pluginPath, { force: true });
-                    continue;
                 }
-                fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
-                fs.writeFileSync(pluginPath, src);
             }
         }
         catch (e) {

package/dist/transformers/rail-hooks.d.ts

@@ -18,6 +18,7 @@ export declare function openCodeHomeDir(options?: OpenCodePathOptions): string;
 export declare function openCodeGlobalConfigDir(options?: OpenCodePathOptions): string;
 export declare function openCodeConfigDir(ctx: OpenCodePathContext, options?: OpenCodePathOptions): string;
 export declare function openCodeRailPluginPaths(ctx: OpenCodePathContext, options?: OpenCodePathOptions): string[];
+export declare function writeOpenCodeRailPlugin(ctx: OpenCodePathContext, source: string): string;
 export declare function isRailHookEntry(entry: unknown): boolean;
 export interface HookResult {
     registered: boolean;
@@ -40,7 +41,11 @@ export declare function removeSettingsHook(settingsPath: string, eventName: stri
  * schema: `{version, hooks: {beforeShellExecution: [{command}]}}`. We intercept
  * both shell execution (where rg/grep/find run) and file reads.
  */
-export declare function registerCursorRailHook(hooksPath: string, binary: string): HookResult;
+export declare function registerCursorRailHook(hooksPath: string, binary: string, options?: {
+    enrich?: boolean;
+}): HookResult;
+export declare const CURSOR_ENRICH_EVENT = "postToolUse";
+export declare const CURSOR_ENRICH_MATCHER = "Shell|Grep";
 /** Remove the Cursor Rail hook entries. */
 /** Windsurf Cascade hooks path (user-level). */
 export declare function windsurfHooksPath(): string;

package/dist/transformers/rail-hooks.js

@@ -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,26 @@ 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). Opt-in like everywhere.
+    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 +327,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];
@@ -342,14 +364,14 @@ import { execFileSync } from 'node:child_process';
 const BIN = ${JSON.stringify(hook.command)};
 const ARGS = ${JSON.stringify([...hook.args, '--json'])};
 
-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 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',

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

@@ -78,27 +78,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.8",
+  "version": "1.2.10",
   "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",
     "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

@@ -10,8 +10,9 @@ matters. Retrieval is evidence, not a guarantee of complete coverage.
 
 ## 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 +53,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 +69,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 +81,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.
 
@@ -208,8 +213,9 @@ 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 IDs only where the specific schema asks for one. 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`.
 

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