memtrace 0.5.15 → 0.6.10

package/hooks/userprompt-claude.sh

@@ -28,8 +28,10 @@
 #   0  : success (stdout is parsed for hook output)
 #   2  : would block the prompt (we never want this)
 #
-# Hook output JSON shape (per code.claude.com/docs/en/hooks-guide.md):
-#   { "decision": "continue", "additionalContext": "..." }
+# Hook output JSON shape (Claude Code UserPromptSubmit validator):
+#   { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit",
+#       "additionalContext": "..." } }
+# To inject nothing: exit 0 with empty stdout (or print "{}").
 #
 # Override:
 #   MEMTRACE_HOOK_MODE=off              → unconditional no-op (skips lock too)
@@ -172,8 +174,10 @@ if (( DEBOUNCE_SECS > 0 )) && [[ -f "$LOCK_FILE" ]]; then
             # hook output and exit. We do NOT probe the daemon.
             cat <<'EOF'
 {
-  "decision": "continue",
-  "additionalContext": ""
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": ""
+  }
 }
 EOF
             exit 0
@@ -253,7 +257,9 @@ shopt -u nocasematch
 # to context for every matching prompt, so token cost is real.
 cat <<'EOF'
 {
-  "decision": "continue",
-  "additionalContext": "Memtrace is active for this repository. For this code-discovery question, prefer the Memtrace MCP tools FIRST — `mcp__memtrace__find_code` for natural-language search, `mcp__memtrace__find_symbol` for exact lookup, `mcp__memtrace__get_symbol_context` for callers/callees, `mcp__memtrace__get_impact` for blast radius. They return exact file:start_line:end_line in one round-trip. Fall back to Read/Grep/Glob only for: (a) config files (.env, package.json, README, raw JSON/YAML/TOML), (b) file inventory questions, (c) paths confirmed outside any indexed repo, (d) reading exact lines you already have from a Memtrace result."
+  "hookSpecificOutput": {
+    "hookEventName": "UserPromptSubmit",
+    "additionalContext": "Memtrace is active for this repository. For this code-discovery question, prefer the Memtrace MCP tools FIRST - `mcp__memtrace__find_code` for natural-language search, `mcp__memtrace__find_symbol` for exact lookup, `mcp__memtrace__get_symbol_context` for callers/callees, `mcp__memtrace__get_impact` for blast radius. They return exact file:start_line:end_line in one round-trip. Fall back to Read/Grep/Glob only for: (a) config files (.env, package.json, README, raw JSON/YAML/TOML), (b) file inventory questions, (c) paths confirmed outside any indexed repo, (d) reading exact lines you already have from a Memtrace result."
+  }
 }
 EOF

package/install.js

@@ -294,25 +294,6 @@ if (require.main === module) {
     console.warn(`memtrace: failed to persist uninstall script: ${e.message}`);
   }
 
-  // 6. Background-daemon discovery hint (Leaf H / fortress-round-2).
-  //    Operators on long-running setups (Sivant on Windows, Orbit on
-  //    Linux, macOS lab hosts) shouldn't have to keep a terminal open
-  //    to keep the indexer alive — point them at the subcommand. The
-  //    hint is post-install only, never on update; CI systems don't
-  //    benefit and we don't want to nag.
-  //
-  //    The exact substring `memtrace daemon install` is contract-pinned
-  //    by the F2F test row H-035
-  //    (`npm_shim_post_install_prints_daemon_install_hint`). Renaming
-  //    the subcommand here without updating that test is a regression.
-  try {
-    if (process.env.MEMTRACE_SUPPRESS_DAEMON_HINT !== "1") {
-      console.log(
-        "memtrace: want it to run as a background service? `memtrace daemon install` " +
-          "(macOS launchd / Linux systemd-user / Windows Service)."
-      );
-    }
-  } catch { /* best-effort — never fail install on a logging hiccup */ }
 }
 
 module.exports = {

package/installer/dist/commands/rail-install.d.ts

@@ -0,0 +1,7 @@
+export interface RailInstallOptions {
+    /** Explicit memtrace binary (from `memtrace rail enable`); wins over PATH lookup. */
+    binary?: string;
+    scope?: 'global' | 'local';
+}
+export declare function runInstallRail(options?: RailInstallOptions): Promise<void>;
+export declare function runUninstallRail(options?: RailInstallOptions): Promise<void>;

package/installer/dist/commands/rail-install.js

@@ -0,0 +1,37 @@
+import { resolveMemtraceBinary } from './install.js';
+import { installRailHooks, printRailInstallSummary, uninstallRailHooks, } from '../rail-install.js';
+export async function runInstallRail(options = {}) {
+    const memtraceBin = options.binary?.trim() ||
+        (await resolveMemtraceBinary()) ||
+        '';
+    if (!memtraceBin) {
+        console.error('  Error: memtrace binary not found. Pass --binary or ensure memtrace is on PATH.\n');
+        process.exit(1);
+    }
+    const ctx = {
+        scope: options.scope ?? 'global',
+        cwd: process.cwd(),
+        memtraceBinary: memtraceBin,
+        skipMcp: true,
+    };
+    const results = installRailHooks(ctx);
+    printRailInstallSummary(results, 'installed');
+    const wired = results.filter((r) => r.registered).map((r) => r.host);
+    if (wired.length > 0) {
+        console.log('  Next steps:');
+        console.log('    1. memtrace start          (daemon for find_code)');
+        console.log('    2. Reload your IDE         (Cursor: reload window; Claude: new session)');
+        console.log('    3. Shell-based search      (Cursor native Grep is not hooked)\n');
+    }
+}
+export async function runUninstallRail(options = {}) {
+    const ctx = {
+        scope: options.scope ?? 'global',
+        cwd: process.cwd(),
+        memtraceBinary: options.binary?.trim() ?? '',
+        skipMcp: true,
+    };
+    const results = uninstallRailHooks(ctx);
+    printRailInstallSummary(results, 'removed');
+    console.log('');
+}

package/installer/dist/index.js

@@ -2,6 +2,7 @@
 import { Command } from 'commander';
 import { runInstall, runUninstall } from './commands/install.js';
 import { runDoctor } from './commands/doctor.js';
+import { runInstallRail, runUninstallRail } from './commands/rail-install.js';
 const program = new Command();
 program
     .name('memtrace-skills')
@@ -13,7 +14,7 @@ function parseOnly(val) {
 program
     .command('install')
     .description('Install memtrace skills and register MCP for selected agents')
-    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex,windsurf,vscode,hermes,opencode,kiro)', parseOnly)
+    .option('--only <agents>', 'comma-separated agent names (claude,cursor,codex,gemini,windsurf,vscode,hermes,opencode,kiro)', parseOnly)
     .option('--local', 'install into the current project where the selected agent supports project scope', false)
     .option('--global', 'install globally (~/.claude/, ~/.cursor/, ~/.agents/) [default]', false)
     .option('--skip-mcp', 'write skills only, skip MCP server registration', false)
@@ -45,6 +46,24 @@ program
         only: opts.only,
     });
 });
+program
+    .command('install-rail')
+    .description('Wire Memtrace Rail discovery hooks for Claude, Cursor, Codex, Gemini, OpenCode')
+    .option('--binary <path>', 'memtrace executable (default: on PATH)')
+    .option('--local', 'project-scoped paths where supported', false)
+    .action(async (opts) => {
+    await runInstallRail({
+        binary: opts.binary,
+        scope: opts.local ? 'local' : 'global',
+    });
+});
+program
+    .command('uninstall-rail')
+    .description('Remove Memtrace Rail hooks only (not skills/MCP)')
+    .option('--local', 'project-scoped paths where supported', false)
+    .action(async (opts) => {
+    await runUninstallRail({ scope: opts.local ? 'local' : 'global' });
+});
 // Default: `memtrace-skills` with no subcommand → install with defaults (global, all agents)
 program.action(async () => {
     await runInstall({ scope: 'global' });

package/installer/dist/rail-install.d.ts

@@ -0,0 +1,20 @@
+import type { InstallContext } from './transformers/types.js';
+export interface RailHostResult {
+    host: string;
+    registered: boolean;
+    path?: string;
+    skipped?: string;
+}
+/** Hosts with no Rail hook surface yet (MCP/skills only). */
+export declare const RAIL_UNSUPPORTED: ReadonlyArray<{
+    host: string;
+    reason: string;
+}>;
+/**
+ * Wire Rail discovery hooks for Claude, Cursor, Codex, Gemini, and OpenCode.
+ * Idempotent. Does not install skills or MCP — hooks only.
+ */
+export declare function installRailHooks(ctx: InstallContext): RailHostResult[];
+/** Remove only Memtrace-owned Rail hook entries (not skills/MCP). */
+export declare function uninstallRailHooks(ctx: InstallContext): RailHostResult[];
+export declare function printRailInstallSummary(results: RailHostResult[], action: 'installed' | 'removed'): void;

package/installer/dist/rail-install.js

@@ -0,0 +1,183 @@
+/**
+ * Memtrace Rail hook wiring for every host that supports discovery interception.
+ * Called from `memtrace rail enable` (via `install-rail` CLI) and from full
+ * `memtrace install` (per-transformer, same helpers).
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { registerRailHookInSettingsAt, removeRailHookFromSettingsAt, } from './transformers/claude.js';
+import { geminiSettingsPath } from './transformers/gemini.js';
+import { registerCursorRailHook, removeCursorRailHook, registerSettingsHook, removeSettingsHook, registerWindsurfRailHook, removeWindsurfRailHook, registerVsCodeRailHook, removeVsCodeRailHook, windsurfHooksPath, vscodeCopilotRailHookPath, CODEX_MATCHER, GEMINI_MATCHER, openCodePluginSource, } from './transformers/rail-hooks.js';
+/** Hosts with no Rail hook surface yet (MCP/skills only). */
+export const RAIL_UNSUPPORTED = [
+    { host: 'hermes', reason: 'Hermes pre_tool_call adapter not wired yet' },
+    { host: 'kiro', reason: 'Kiro IDE hooks omit tool stdin (CLI-only for now)' },
+];
+function codexHooksPath(ctx) {
+    const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
+    return path.join(base, 'hooks.json');
+}
+function cursorHooksPath(ctx) {
+    const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
+    return path.join(base, '.cursor', 'hooks.json');
+}
+function opencodeConfigDir(ctx) {
+    const xdg = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), '.config');
+    return ctx.scope === 'global' ? path.join(xdg, 'opencode') : path.join(ctx.cwd, '.opencode');
+}
+function opencodeRailPluginPaths(ctx) {
+    const base = opencodeConfigDir(ctx);
+    return [
+        path.join(base, 'plugin', 'memtrace-rail.js'),
+        path.join(base, 'plugins', 'memtrace-rail.js'),
+    ];
+}
+/**
+ * Wire Rail discovery hooks for Claude, Cursor, Codex, Gemini, and OpenCode.
+ * Idempotent. Does not install skills or MCP — hooks only.
+ */
+export function installRailHooks(ctx) {
+    const bin = ctx.memtraceBinary?.trim() ?? '';
+    if (!bin) {
+        throw new Error('memtrace binary path is required to install Rail hooks');
+    }
+    const results = [];
+    const claudePath = path.join(os.homedir(), '.claude', 'settings.json');
+    const claude = registerRailHookInSettingsAt(claudePath, bin);
+    results.push({
+        host: 'claude',
+        registered: claude.registered,
+        path: claudePath,
+        skipped: claude.registered ? undefined : 'settings.json malformed or unreadable',
+    });
+    const cursorPath = cursorHooksPath(ctx);
+    const cursor = registerCursorRailHook(cursorPath, bin);
+    results.push({
+        host: 'cursor',
+        registered: cursor.registered,
+        path: cursorPath,
+        skipped: cursor.registered ? undefined : 'hooks.json malformed or unreadable',
+    });
+    const codexPath = codexHooksPath(ctx);
+    const codex = registerSettingsHook(codexPath, bin, 'codex', 'PreToolUse', CODEX_MATCHER);
+    results.push({
+        host: 'codex',
+        registered: codex.registered,
+        path: codexPath,
+        skipped: codex.registered ? undefined : 'hooks.json malformed or unreadable',
+    });
+    const geminiPath = geminiSettingsPath(ctx);
+    const gemini = registerSettingsHook(geminiPath, bin, 'gemini', 'BeforeTool', GEMINI_MATCHER, {
+        enableHooks: true,
+        enableMessageBusIntegration: true,
+    });
+    results.push({
+        host: 'gemini',
+        registered: gemini.registered,
+        path: geminiPath,
+        skipped: gemini.registered ? undefined : 'settings.json malformed or unreadable',
+    });
+    try {
+        const src = openCodePluginSource(bin);
+        for (const pluginPath of opencodeRailPluginPaths(ctx)) {
+            fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
+            fs.writeFileSync(pluginPath, src);
+        }
+        results.push({
+            host: 'opencode',
+            registered: true,
+            path: opencodeRailPluginPaths(ctx)[0],
+        });
+    }
+    catch (e) {
+        results.push({
+            host: 'opencode',
+            registered: false,
+            skipped: e.message,
+        });
+    }
+    const windsurfPath = windsurfHooksPath();
+    fs.mkdirSync(path.dirname(windsurfPath), { recursive: true });
+    const windsurf = registerWindsurfRailHook(windsurfPath, bin);
+    results.push({
+        host: 'windsurf',
+        registered: windsurf.registered,
+        path: windsurfPath,
+        skipped: windsurf.registered ? undefined : 'hooks.json malformed or unreadable',
+    });
+    const vscodePath = vscodeCopilotRailHookPath();
+    fs.mkdirSync(path.dirname(vscodePath), { recursive: true });
+    const vscode = registerVsCodeRailHook(vscodePath, bin);
+    results.push({
+        host: 'vscode',
+        registered: vscode.registered,
+        path: vscodePath,
+        skipped: vscode.registered ? undefined : 'hook file malformed or unreadable',
+    });
+    for (const { host, reason } of RAIL_UNSUPPORTED) {
+        results.push({ host, registered: false, skipped: reason });
+    }
+    return results;
+}
+/** Remove only Memtrace-owned Rail hook entries (not skills/MCP). */
+export function uninstallRailHooks(ctx) {
+    const results = [];
+    const claudePath = path.join(os.homedir(), '.claude', 'settings.json');
+    const claude = removeRailHookFromSettingsAt(claudePath);
+    results.push({ host: 'claude', registered: false, path: claudePath, skipped: claude.changed ? undefined : 'no rail hook' });
+    const cursorPath = cursorHooksPath(ctx);
+    const cursor = removeCursorRailHook(cursorPath);
+    results.push({ host: 'cursor', registered: false, path: cursorPath, skipped: cursor.changed ? undefined : 'no rail hook' });
+    const codexPath = codexHooksPath(ctx);
+    const codex = removeSettingsHook(codexPath, 'PreToolUse');
+    results.push({ host: 'codex', registered: false, path: codexPath, skipped: codex.changed ? undefined : 'no rail hook' });
+    const geminiPath = geminiSettingsPath(ctx);
+    const gemini = removeSettingsHook(geminiPath, 'BeforeTool');
+    results.push({ host: 'gemini', registered: false, path: geminiPath, skipped: gemini.changed ? undefined : 'no rail hook' });
+    for (const p of opencodeRailPluginPaths(ctx)) {
+        try {
+            fs.rmSync(p, { force: true });
+        }
+        catch { /* best effort */ }
+    }
+    results.push({ host: 'opencode', registered: false });
+    const windsurfPath = windsurfHooksPath();
+    const windsurf = removeWindsurfRailHook(windsurfPath);
+    results.push({
+        host: 'windsurf',
+        registered: false,
+        path: windsurfPath,
+        skipped: windsurf.changed ? undefined : 'no rail hook',
+    });
+    const vscodePath = vscodeCopilotRailHookPath();
+    const vscode = removeVsCodeRailHook(vscodePath);
+    results.push({
+        host: 'vscode',
+        registered: false,
+        path: vscodePath,
+        skipped: vscode.changed ? undefined : 'no rail hook',
+    });
+    for (const { host, reason } of RAIL_UNSUPPORTED) {
+        results.push({ host, registered: false, skipped: reason });
+    }
+    return results;
+}
+export function printRailInstallSummary(results, action) {
+    console.log(`\n  Memtrace Rail hooks ${action}:\n`);
+    for (const r of results) {
+        if (r.registered && action === 'installed') {
+            console.log(`    \x1b[32m✓\x1b[0m ${r.host}${r.path ? ` → ${r.path}` : ''}`);
+        }
+        else if (action === 'removed' && r.skipped === undefined) {
+            console.log(`    \x1b[32m✓\x1b[0m ${r.host} (removed)`);
+        }
+        else if (r.skipped) {
+            console.log(`    \x1b[2m–\x1b[0m ${r.host}: ${r.skipped}`);
+        }
+        else {
+            console.log(`    \x1b[33m!\x1b[0m ${r.host}: not ${action}${r.path ? ` (${r.path})` : ''}`);
+        }
+    }
+    console.log('');
+}

package/installer/dist/transformers/claude.d.ts

@@ -18,6 +18,27 @@ export interface SettingsMutationResult {
  * Never overwrites a malformed file — backs it up and returns registered=false.
  */
 export declare function registerMcpInSettingsAt(settingsPath: string, memtraceBinary: string): SettingsMutationResult;
+/**
+ * Register the Memtrace Rail PreToolUse hook in a Claude settings.json.
+ *
+ * This is what makes Rail "part of memtrace" rather than a manual install:
+ * `memtrace install` wires a PreToolUse hook that pipes every Grep/Glob/Bash
+ * attempt through `memtrace route --hook`. The hook defaults to **observe**
+ * (zero behavior change) — `MEMTRACE_RAIL=nudge|rail|strict` opts into more.
+ * Mode is intentionally NOT baked into the command so the user can change it
+ * via env without re-installing.
+ *
+ * Idempotent: any prior Rail entry (identified by {@link RAIL_HOOK_MARKER}) is
+ * replaced, and unrelated PreToolUse hooks are preserved. Never overwrites a
+ * malformed file.
+ */
+export declare function registerRailHookInSettingsAt(settingsPath: string, memtraceBinary: string): SettingsMutationResult;
+/**
+ * Remove the Memtrace Rail PreToolUse hook from a Claude settings.json.
+ * Preserves unrelated hooks; prunes empty containers. Never touches a
+ * malformed file.
+ */
+export declare function removeRailHookFromSettingsAt(settingsPath: string): SettingsCleanupResult;
 /**
  * Merge-add plugin + marketplace entries into a Claude settings.json file.
  * Never overwrites a malformed file.

package/installer/dist/transformers/claude.js

@@ -216,6 +216,92 @@ export function registerMcpInSettingsAt(settingsPath, memtraceBinary) {
     writeJsonAtomic(settingsPath, settings);
     return { registered: true };
 }
+/**
+ * The tool surfaces Rail intercepts. Native `Grep`/`Glob` are the high-volume
+ * offenders; `Bash` catches rg/grep/find/fd commands.
+ */
+const RAIL_HOOK_MATCHER = 'Grep|Glob|Bash';
+/** Substring that identifies a memtrace-owned Rail hook entry (for idempotent
+ * re-register + clean removal). */
+const RAIL_HOOK_MARKER = 'route --hook';
+/**
+ * Register the Memtrace Rail PreToolUse hook in a Claude settings.json.
+ *
+ * This is what makes Rail "part of memtrace" rather than a manual install:
+ * `memtrace install` wires a PreToolUse hook that pipes every Grep/Glob/Bash
+ * attempt through `memtrace route --hook`. The hook defaults to **observe**
+ * (zero behavior change) — `MEMTRACE_RAIL=nudge|rail|strict` opts into more.
+ * Mode is intentionally NOT baked into the command so the user can change it
+ * via env without re-installing.
+ *
+ * Idempotent: any prior Rail entry (identified by {@link RAIL_HOOK_MARKER}) is
+ * replaced, and unrelated PreToolUse hooks are preserved. Never overwrites a
+ * malformed file.
+ */
+export function registerRailHookInSettingsAt(settingsPath, memtraceBinary) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Rail hook registration.`);
+        return { registered: false, backupPath };
+    }
+    const settings = (value ?? {});
+    settings.hooks = 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) => !isRailHookEntry(entry));
+    preserved.push({
+        matcher: RAIL_HOOK_MATCHER,
+        hooks: [
+            {
+                type: 'command',
+                command: `${memtraceBinary} route --hook`,
+            },
+        ],
+    });
+    settings.hooks.PreToolUse = preserved;
+    writeJsonAtomic(settingsPath, settings);
+    return { registered: true };
+}
+/** True when a PreToolUse entry is a memtrace-owned Rail hook. */
+function isRailHookEntry(entry) {
+    if (!isRecord(entry) || !Array.isArray(entry.hooks))
+        return false;
+    return entry.hooks.some((h) => isRecord(h) && typeof h.command === 'string' && h.command.includes(RAIL_HOOK_MARKER));
+}
+/**
+ * Remove the Memtrace Rail PreToolUse hook from a Claude settings.json.
+ * Preserves unrelated hooks; prunes empty containers. Never touches a
+ * malformed file.
+ */
+export function removeRailHookFromSettingsAt(settingsPath) {
+    const { value, corrupted, backupPath } = safeReadJson(settingsPath);
+    if (corrupted) {
+        console.warn(`memtrace: ${settingsPath} is malformed; backed up to ${backupPath}. Skipped Rail hook cleanup.`);
+        return { changed: false, backupPath };
+    }
+    if (!value)
+        return { changed: false };
+    const settings = value;
+    if (!isRecord(settings.hooks) || !Array.isArray(settings.hooks.PreToolUse)) {
+        return { changed: false };
+    }
+    const before = settings.hooks.PreToolUse;
+    const after = before.filter((entry) => !isRailHookEntry(entry));
+    if (after.length === before.length)
+        return { changed: false };
+    if (after.length === 0) {
+        delete settings.hooks.PreToolUse;
+    }
+    else {
+        settings.hooks.PreToolUse = after;
+    }
+    if (Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
+    writeJsonAtomic(settingsPath, settings);
+    return { changed: true };
+}
 /**
  * Merge-add plugin + marketplace entries into a Claude settings.json file.
  * Never overwrites a malformed file.
@@ -275,6 +361,22 @@ export function removeClaudeSettingsEntriesAt(settingsPath) {
         if (Object.keys(mcpServers).length === 0)
             delete settings.mcpServers;
     }
+    // ─── memtrace-rail ─── Remove the Rail PreToolUse hook on uninstall.
+    if (isRecord(settings.hooks) && Array.isArray(settings.hooks.PreToolUse)) {
+        const pre = settings.hooks.PreToolUse;
+        const after = pre.filter((entry) => !isRailHookEntry(entry));
+        if (after.length !== pre.length) {
+            changed = true;
+            if (after.length === 0) {
+                delete settings.hooks.PreToolUse;
+            }
+            else {
+                settings.hooks.PreToolUse = after;
+            }
+            if (Object.keys(settings.hooks).length === 0)
+                delete settings.hooks;
+        }
+    }
     for (const containerName of MARKETPLACE_SETTING_CONTAINERS) {
         const container = settings[containerName];
         if (!isRecord(container))
@@ -321,12 +423,24 @@ function removeClaudeInstalledPluginMetadata() {
  * This adds the MCP server config so Claude Code can connect to memtrace tools.
  */
 async function registerMcpServer(memtraceBinaryPath) {
+    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
+    // ─── memtrace-rail ─── Always wire the Memtrace-first discovery hook so it
+    // ships as part of `memtrace install` (not a manual step). Hooks live in
+    // settings.json regardless of which MCP-registration strategy wins, and the
+    // hook defaults to observe mode (zero behavior change) until the user opts
+    // into MEMTRACE_RAIL=nudge|rail|strict. Failure here must not block MCP
+    // registration.
+    try {
+        registerRailHookInSettingsAt(settingsFile, memtraceBinaryPath);
+    }
+    catch (e) {
+        console.warn(`memtrace: failed to register Rail hook: ${e.message}`);
+    }
     // Strategy 1 (preferred): claude CLI's own add-json path
     const viaCli = await tryMcpAddJson(memtraceBinaryPath);
     if (viaCli)
         return;
     // Strategy 2 (fallback): direct settings.json merge (safe + atomic)
-    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
     registerMcpInSettingsAt(settingsFile, memtraceBinaryPath);
 }
 /**
@@ -380,8 +494,9 @@ export async function installClaudePlugin(skills, memtraceBinaryPath) {
     enablePluginInSettings();
     // Step 6: Register MCP server
     await registerMcpServer(memtraceBinaryPath);
-    // Step 7: Write user-level skills for SDK-based integrations
-    writeUserLevelSkills(skills);
+    // Skills ship via the memtrace-skills@memtrace plugin only. Writing
+    // bare copies to ~/.claude/skills/memtrace-* duplicates every skill
+    // in Claude Code when the plugin is also enabled (issue #11).
     return { cacheDir, skillCount: skills.length };
 }
 /**

package/installer/dist/transformers/codex.js

@@ -2,7 +2,12 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import { commandExists, execCommand } from '../utils.js';
+import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
+function codexRailHooksPath(ctx) {
+    const base = ctx.scope === 'global' ? path.join(os.homedir(), '.codex') : path.join(ctx.cwd, '.codex');
+    return path.join(base, 'hooks.json');
+}
 function skillsRoot(ctx) {
     const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
     return path.join(base, '.agents', 'skills');
@@ -173,6 +178,14 @@ export const codexTransformer = {
                 }
             }
         }
+        // ─── memtrace-rail ─── Wire the discovery hook into .codex/hooks.json
+        // (PreToolUse, Bash matcher — Codex code discovery runs through the shell).
+        try {
+            registerSettingsHook(codexRailHooksPath(ctx), ctx.memtraceBinary, 'codex', 'PreToolUse', CODEX_MATCHER);
+        }
+        catch (e) {
+            warnings.push(`failed to register Codex Rail hook: ${e.message}`);
+        }
         return {
             agent: 'codex',
             skillsWritten: skills.length,
@@ -191,6 +204,10 @@ export const codexTransformer = {
                 }
             }
         }
+        try {
+            removeSettingsHook(codexRailHooksPath(ctx), 'PreToolUse');
+        }
+        catch { /* best effort */ }
         const configFile = codexConfigPath(ctx);
         if (fs.existsSync(configFile)) {
             const next = stripCodexMcpServer(fs.readFileSync(configFile, 'utf-8'));

package/installer/dist/transformers/cursor.js

@@ -3,6 +3,7 @@ import os from 'os';
 import path from 'path';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
 import { MEMTRACE_MCP_ENV } from './shared.js';
+import { registerCursorRailHook, removeCursorRailHook } from './rail-hooks.js';
 function skillsRoot(ctx) {
     const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
     return path.join(base, '.cursor', 'skills');
@@ -11,6 +12,10 @@ function mcpPath(ctx) {
     const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
     return path.join(base, '.cursor', 'mcp.json');
 }
+function railHooksPath(ctx) {
+    const base = ctx.scope === 'global' ? os.homedir() : ctx.cwd;
+    return path.join(base, '.cursor', 'hooks.json');
+}
 function writeSkill(skill, rootDir) {
     const name = skill.filename.replace(/\.md$/, '');
     const outDir = path.join(rootDir, name);
@@ -37,7 +42,11 @@ export function registerCursorMcpAt(mcpFile, binary) {
     const existingEnv = (isRecord(existing) && isRecord(existing.env))
         ? existing.env
         : {};
-    const mergedEnv = { ...existingEnv, ...MEMTRACE_MCP_ENV };
+    const mergedEnv = {
+        ...existingEnv,
+        ...MEMTRACE_MCP_ENV,
+        MEMTRACE_WORKSPACE_ROOT: '${workspaceFolder}',
+    };
     cfg.mcpServers['memtrace'] = {
         command: binary,
         args: ['mcp'],
@@ -64,6 +73,14 @@ export const cursorTransformer = {
             const result = registerCursorMcpAt(mcpPath(ctx), ctx.memtraceBinary);
             mcpRegistered = result.registered;
         }
+        // ─── memtrace-rail ─── Wire the Memtrace-first discovery hook (default
+        // observe). Failure must not block the rest of the install.
+        try {
+            registerCursorRailHook(railHooksPath(ctx), ctx.memtraceBinary);
+        }
+        catch (e) {
+            console.warn(`memtrace: failed to register Cursor Rail hook: ${e.message}`);
+        }
         return {
             agent: 'cursor',
             skillsWritten: skills.length,
@@ -83,6 +100,11 @@ export const cursorTransformer = {
                 }
             }
         }
+        // 1b. Remove the Rail hook.
+        try {
+            removeCursorRailHook(railHooksPath(ctx));
+        }
+        catch { /* best effort */ }
         // 2. Remove memtrace entry from mcp.json; delete file if empty
         const mcpFile = mcpPath(ctx);
         const { value, corrupted } = safeReadJson(mcpFile);

package/installer/dist/transformers/gemini.d.ts

@@ -0,0 +1,3 @@
+import { Transformer, InstallContext } from './types.js';
+export declare function geminiSettingsPath(ctx: InstallContext): string;
+export declare const geminiTransformer: Transformer;