memtrace-skills 1.2.10 → 1.2.13

package/dist/transformers/claude.js

@@ -3,9 +3,10 @@ import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
 import { copyCanonicalPluginAssets, copyCanonicalPluginManifest, readCanonicalPluginVersion, } from '../../plugin-assets/index.js';
+import { writeManagedSkill, removeManagedSkills } from '../managed-skills.js';
 import { execCommand, commandExists } from '../utils.js';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
-import { railIsActive, railHookInvocation, railHookCommand, RAIL_GUARD_MARKER, enrichEnabled, railMode } from '../rail-runtime.js';
+import { railIsActive, railHookInvocation, railHookCommand, RAIL_GUARD_MARKER, enrichEnabled, railMode, railConfig } 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';
@@ -262,8 +263,8 @@ export function claudeRailHookCommand(_memtraceBinary, platform = process.platfo
  * 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 the Rail router (see {@link claudeRailHookCommand} for the
- * transport). While a daemon is running the hook defaults to **observe** —
- * `MEMTRACE_RAIL=nudge|rail|strict` opts into more. Mode is intentionally NOT
+ * transport). While a daemon is running the hook defaults to **nudge** —
+ * context alongside ordinary tools. Explicit modes are preserved. Mode is intentionally NOT
  * baked into the command so the user can change it via env without
  * re-installing.
  *
@@ -284,8 +285,9 @@ export function registerRailHookInSettingsAt(settingsPath, memtraceBinary, platf
     const settings = (value ?? {});
     settings.hooks = isRecord(settings.hooks) ? settings.hooks : {};
     pruneMemtraceOwnedHookEntries(settings.hooks);
-    const enrich = options.enrich ?? enrichEnabled();
-    const mode = options.mode ?? railMode();
+    const config = railConfig();
+    const mode = options.mode ?? railMode(process.env, config);
+    const enrich = options.enrich ?? enrichEnabled(process.env, { ...config, mode });
     const hookFor = (extra) => ({
         type: 'command',
         ...(platform === 'win32'
@@ -552,7 +554,10 @@ export function claudeUserConfigFile() {
  *  2. Fall back to manual: write cache files + update settings.json
  *  3. Register MCP server for memtrace tools
  */
-export async function installClaudePlugin(skills, memtraceBinaryPath) {
+export async function installClaudePlugin(skills, memtraceBinaryPath, options = {}) {
+    // Retire known stock bare copies when moving to plugin delivery. Customized
+    // strict policies/opt-outs survive; names alone never prove ownership.
+    removeManagedSkills(path.join(os.homedir(), '.claude', 'skills'));
     // Step 1: make sure Claude sees the public HTTPS marketplace source before
     // the CLI attempts to clone/update it.
     enablePluginInSettings();
@@ -582,44 +587,57 @@ export async function installClaudePlugin(skills, memtraceBinaryPath) {
     // Step 5: Write plugin assets and skills
     copyBundledPluginAssetsAt(cacheDir);
     const skillsDir = path.join(cacheDir, 'skills');
-    if (fs.existsSync(skillsDir)) {
-        fs.rmSync(skillsDir, { recursive: true });
-    }
+    let skillCount = 0;
     for (const skill of skills) {
         const results = transformForClaude(skill);
         for (const { relativePath, content } of results) {
-            const fullPath = path.join(cacheDir, relativePath);
-            fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-            fs.writeFileSync(fullPath, content);
+            if (writeManagedSkill(skillsDir, path.basename(path.dirname(relativePath)), content))
+                skillCount++;
         }
     }
     enablePluginInSettings();
     // Step 6: Register MCP server
-    await registerMcpServer(memtraceBinaryPath);
+    if (!options.skipMcp)
+        await registerMcpServer(memtraceBinaryPath);
     // 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 };
+    return { cacheDir, skillCount };
+}
+function refreshEnabledClaudePlugin(skills) {
+    const settingsFile = path.join(os.homedir(), '.claude', 'settings.json');
+    if (!fs.existsSync(settingsFile))
+        return 0;
+    const settings = JSON.parse(fs.readFileSync(settingsFile, 'utf8'));
+    if (settings.enabledPlugins?.[PLUGIN_KEY] !== true)
+        return 0;
+    const root = getPluginCacheRoot();
+    if (!fs.existsSync(root))
+        return 0;
+    let skillCount = 0;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const cacheDir = path.join(root, entry.name);
+        copyBundledPluginAssetsAt(cacheDir);
+        for (const skill of skills) {
+            for (const asset of transformForClaude(skill)) {
+                const name = path.basename(path.dirname(asset.relativePath));
+                if (writeManagedSkill(path.join(cacheDir, 'skills'), name, asset.content))
+                    skillCount++;
+            }
+        }
+    }
+    return skillCount;
 }
 /**
  * Write skills to ~/.claude/skills/ for SDK-based integrations.
  */
 function writeUserLevelSkills(skills) {
     const userSkillsDir = path.join(os.homedir(), '.claude', 'skills');
-    if (fs.existsSync(userSkillsDir)) {
-        for (const entry of fs.readdirSync(userSkillsDir)) {
-            if (entry.startsWith('memtrace-')) {
-                fs.rmSync(path.join(userSkillsDir, entry), { recursive: true, force: true });
-            }
-        }
-    }
     for (const skill of skills) {
-        const skillName = skill.filename.replace(/\.md$/, '');
-        const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
-        const content = `---\nname: ${skillName}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
-        const outDir = path.join(userSkillsDir, skillName);
-        fs.mkdirSync(outDir, { recursive: true });
-        fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
+        const content = transformForClaude(skill)[0].content;
+        writeManagedSkill(userSkillsDir, skill.filename.replace(/\.md$/, ''), content);
     }
 }
 /**
@@ -652,22 +670,8 @@ export async function uninstallClaudePlugin() {
     }
     removeClaudeMarketplaceCacheDirs();
     removeClaudeInstalledPluginMetadata();
-    // Clean up user-level skills
-    const userSkillsDir = path.join(os.homedir(), '.claude', 'skills');
-    if (fs.existsSync(userSkillsDir)) {
-        for (const entry of fs.readdirSync(userSkillsDir)) {
-            if (entry.startsWith('memtrace-')) {
-                const entryPath = path.join(userSkillsDir, entry);
-                const stat = fs.statSync(entryPath);
-                if (stat.isDirectory()) {
-                    fs.rmSync(entryPath, { recursive: true });
-                }
-                else if (entry.endsWith('.md')) {
-                    fs.unlinkSync(entryPath);
-                }
-            }
-        }
-    }
+    // Customized skills and their extra assets are not installer-owned.
+    removeManagedSkills(path.join(os.homedir(), '.claude', 'skills'));
 }
 /**
  * Write/merge the memtrace MCP server entry into a project-local .mcp.json.
@@ -700,7 +704,9 @@ export const claudeTransformer = {
     name: 'claude',
     async install(skills, ctx) {
         if (ctx.scope === 'global') {
-            const { skillCount } = await installClaudePlugin(skills, ctx.memtraceBinary);
+            const skillCount = ctx.mode === 'refresh'
+                ? refreshEnabledClaudePlugin(skills)
+                : (await installClaudePlugin(skills, ctx.memtraceBinary, { skipMcp: ctx.skipMcp })).skillCount;
             return {
                 agent: 'claude',
                 skillsWritten: skillCount,
@@ -712,22 +718,11 @@ export const claudeTransformer = {
         }
         // Local scope: write skills into <cwd>/.claude/skills/
         const skillsDir = path.join(ctx.cwd, '.claude', 'skills');
-        if (fs.existsSync(skillsDir)) {
-            for (const entry of fs.readdirSync(skillsDir)) {
-                if (entry.startsWith('memtrace-')) {
-                    fs.rmSync(path.join(skillsDir, entry), { recursive: true, force: true });
-                }
-            }
-        }
         let count = 0;
         for (const skill of skills) {
-            const skillName = skill.filename.replace(/\.md$/, '');
-            const outDir = path.join(skillsDir, skillName);
-            fs.mkdirSync(outDir, { recursive: true });
-            const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
-            const content = `---\nname: ${skillName}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
-            fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
-            count++;
+            const content = transformForClaude(skill)[0].content;
+            if (writeManagedSkill(skillsDir, skill.filename.replace(/\.md$/, ''), content))
+                count++;
         }
         // MCP for local scope: .mcp.json at project root (Claude's project-level convention)
         const mcpConfigPath = path.join(ctx.cwd, '.mcp.json');
@@ -751,13 +746,7 @@ export const claudeTransformer = {
         }
         // Local: remove <cwd>/.claude/skills/memtrace-* and the memtrace entry from <cwd>/.mcp.json
         const skillsDir = path.join(ctx.cwd, '.claude', 'skills');
-        if (fs.existsSync(skillsDir)) {
-            for (const entry of fs.readdirSync(skillsDir)) {
-                if (entry.startsWith('memtrace-')) {
-                    fs.rmSync(path.join(skillsDir, entry), { recursive: true, force: true });
-                }
-            }
-        }
+        removeManagedSkills(skillsDir);
         const mcpPath = path.join(ctx.cwd, '.mcp.json');
         const { value, corrupted } = safeReadJson(mcpPath);
         if (!corrupted && value?.mcpServers?.['memtrace']) {

package/dist/transformers/codex-config.d.ts

@@ -0,0 +1,2 @@
+export declare function hasCodexMemtraceServer(raw: string): boolean;
+export declare function refreshCodexCommand(raw: string, command: string): string;

package/dist/transformers/codex-config.js

@@ -0,0 +1,33 @@
+import { isDeepStrictEqual } from 'node:util';
+import { parse } from 'smol-toml';
+const readConfig = (raw) => parse(raw, { integersAsBigInt: 'asNeeded' });
+function memtraceServer(config) {
+    const servers = config.mcp_servers;
+    if (!servers || typeof servers !== 'object' || Array.isArray(servers))
+        return undefined;
+    const server = servers.memtrace;
+    return server && typeof server === 'object' && !Array.isArray(server) ? server : undefined;
+}
+export function hasCodexMemtraceServer(raw) {
+    return memtraceServer(readConfig(raw)) !== undefined;
+}
+export function refreshCodexCommand(raw, command) {
+    const expected = readConfig(raw);
+    const server = memtraceServer(expected);
+    if (!server || typeof server.command !== 'string' || server.command === command)
+        return raw;
+    server.command = command;
+    let inServer = false;
+    const next = raw.split(/(?<=\n)/).map(line => {
+        if (/^\s*\[/.test(line)) {
+            inServer = /^\s*\[\s*mcp_servers\s*\.\s*(?:memtrace|"memtrace"|'memtrace')\s*\]\s*(?:#.*)?$/.test(line.trimEnd());
+        }
+        if (!inServer)
+            return line;
+        return line.replace(/^(\s*command\s*=\s*)(["'])(.*?)\2([ \t]*(?:#.*)?)(\r?\n)?$/, (_match, prefix, _quote, _value, comment, newline) => (`${prefix}${JSON.stringify(command)}${comment}${newline ?? ''}`));
+    }).join('');
+    if (!isDeepStrictEqual(readConfig(next), expected)) {
+        throw new Error('Cannot safely update the Codex MCP command; existing configuration was left unchanged.');
+    }
+    return next;
+}

package/dist/transformers/codex.js

@@ -1,7 +1,9 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { writeManagedSkill, removeManagedSkills } from '../managed-skills.js';
 import { commandExists, execCommand } from '../utils.js';
+import { hasCodexMemtraceServer, refreshCodexCommand } from './codex-config.js';
 import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
 const LEGACY_MCP_SERVER_NAME = 'memfleet';
@@ -19,11 +21,9 @@ export function codexConfigPath(ctx) {
 }
 function writeSkill(skill, rootDir) {
     const name = skill.filename.replace(/\.md$/, '');
-    const outDir = path.join(rootDir, name);
-    fs.mkdirSync(outDir, { recursive: true });
     const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
     const content = `---\nname: ${name}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
-    fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
+    return writeManagedSkill(rootDir, name, content);
 }
 function tomlString(value) {
     return `"${value
@@ -124,6 +124,12 @@ function extractMemtraceEnvBlock(raw) {
 }
 export function registerCodexMcpAt(configFile, binary) {
     const existing = fs.existsSync(configFile) ? fs.readFileSync(configFile, 'utf-8') : '';
+    if (hasCodexMemtraceServer(existing)) {
+        const next = refreshCodexCommand(existing, binary);
+        if (next !== existing)
+            writeTextAtomic(configFile, next);
+        return { registered: true };
+    }
     // Strip leaves the env sub-table intact; split it out so we can reorder it
     // after the freshly written parent block for readability.
     const stripped = stripCodexMcpServer(existing);
@@ -145,6 +151,8 @@ export function registerCodexMcpAt(configFile, binary) {
     if (envBlock)
         parts.push(envBlock);
     const next = `${parts.join('\n\n')}\n`;
+    if (!hasCodexMemtraceServer(next))
+        throw new Error('Codex MCP registration could not be validated.');
     writeTextAtomic(configFile, next);
     return { registered: true };
 }
@@ -168,20 +176,13 @@ export const codexTransformer = {
     name: 'codex',
     async install(skills, ctx) {
         const rootDir = skillsRoot(ctx);
-        if (fs.existsSync(rootDir)) {
-            for (const entry of fs.readdirSync(rootDir)) {
-                if (entry.startsWith('memtrace-')) {
-                    fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
-                }
-            }
-        }
-        for (const s of skills)
-            writeSkill(s, rootDir);
+        const written = skills.filter(skill => writeSkill(skill, rootDir)).length;
         let mcpRegistered = false;
         const warnings = [];
         const mcpConfigPath = codexConfigPath(ctx);
         if (!ctx.skipMcp) {
-            const cliRegistered = ctx.scope === 'global' && await tryCodexMcpAdd(ctx.memtraceBinary);
+            const cliRegistered = ctx.scope === 'global' && !fs.existsSync(mcpConfigPath)
+                && await tryCodexMcpAdd(ctx.memtraceBinary);
             registerCodexMcpAt(mcpConfigPath, ctx.memtraceBinary);
             mcpRegistered = true;
             if (ctx.scope === 'global' && !cliRegistered) {
@@ -191,14 +192,15 @@ 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);
+            if (ctx.mode !== 'refresh')
+                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,
+            skillsWritten: written,
             skillsDir: rootDir,
             mcpConfigPath,
             mcpRegistered,
@@ -207,13 +209,7 @@ export const codexTransformer = {
     },
     async uninstall(ctx) {
         const rootDir = skillsRoot(ctx);
-        if (fs.existsSync(rootDir)) {
-            for (const entry of fs.readdirSync(rootDir)) {
-                if (entry.startsWith('memtrace-')) {
-                    fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
-                }
-            }
-        }
+        removeManagedSkills(rootDir);
         try {
             removeSettingsHook(codexRailHooksPath(ctx), 'PreToolUse');
         }

package/dist/transformers/cursor.js

@@ -1,6 +1,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { writeManagedSkill, removeManagedSkills } from '../managed-skills.js';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
 import { MEMTRACE_MCP_ENV, removeLegacyMcpServer } from './shared.js';
 import { registerCursorRailHook, removeCursorRailHook } from './rail-hooks.js';
@@ -18,12 +19,10 @@ function railHooksPath(ctx) {
 }
 function writeSkill(skill, rootDir) {
     const name = skill.filename.replace(/\.md$/, '');
-    const outDir = path.join(rootDir, name);
-    fs.mkdirSync(outDir, { recursive: true });
     const safeDesc = skill.frontmatter.description.replace(/"/g, '\\"').trim();
     // Cursor requires frontmatter `name` matching the folder name.
     const content = `---\nname: ${name}\ndescription: "${safeDesc}"\n---\n\n${skill.body}`;
-    fs.writeFileSync(path.join(outDir, 'SKILL.md'), content);
+    return writeManagedSkill(rootDir, name, content);
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -96,15 +95,7 @@ export const cursorTransformer = {
     async install(skills, ctx) {
         const rootDir = skillsRoot(ctx);
         const warnings = cursorWorkspaceBoundaryWarnings(ctx);
-        if (fs.existsSync(rootDir)) {
-            for (const entry of fs.readdirSync(rootDir)) {
-                if (entry.startsWith('memtrace-')) {
-                    fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
-                }
-            }
-        }
-        for (const s of skills)
-            writeSkill(s, rootDir);
+        const written = skills.filter(skill => writeSkill(skill, rootDir)).length;
         let mcpRegistered = false;
         if (!ctx.skipMcp) {
             const result = registerCursorMcpAt(mcpPath(ctx), ctx.memtraceBinary);
@@ -116,14 +107,15 @@ export const cursorTransformer = {
         // ─── 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);
+            if (ctx.mode !== 'refresh')
+                registerCursorRailHook(railHooksPath(ctx), ctx.memtraceBinary);
         }
         catch (e) {
             console.warn(`memtrace: failed to register Cursor Rail hook: ${e.message}`);
         }
         return {
             agent: 'cursor',
-            skillsWritten: skills.length,
+            skillsWritten: written,
             skillsDir: rootDir,
             mcpConfigPath: mcpPath(ctx),
             mcpRegistered,
@@ -133,13 +125,7 @@ export const cursorTransformer = {
     async uninstall(ctx) {
         // 1. Remove memtrace-* skill dirs
         const rootDir = skillsRoot(ctx);
-        if (fs.existsSync(rootDir)) {
-            for (const entry of fs.readdirSync(rootDir)) {
-                if (entry.startsWith('memtrace-')) {
-                    fs.rmSync(path.join(rootDir, entry), { recursive: true, force: true });
-                }
-            }
-        }
+        removeManagedSkills(rootDir);
         // 1b. Remove the Rail hook.
         try {
             removeCursorRailHook(railHooksPath(ctx));

package/dist/transformers/gemini.js

@@ -46,10 +46,11 @@ export const geminiTransformer = {
         // (PR #14460) — without them a registered BeforeTool hook NEVER fires, so we
         // enable both here (only if the user hasn't already set them).
         try {
-            registerSettingsHook(settingsPath, ctx.memtraceBinary, 'gemini', 'BeforeTool', GEMINI_MATCHER, {
-                enableHooks: true,
-                enableMessageBusIntegration: true,
-            });
+            if (ctx.mode !== 'refresh')
+                registerSettingsHook(settingsPath, ctx.memtraceBinary, 'gemini', 'BeforeTool', GEMINI_MATCHER, {
+                    enableHooks: true,
+                    enableMessageBusIntegration: true,
+                });
         }
         catch (e) {
             warnings.push(`failed to register Gemini Rail hook: ${e.message}`);

package/dist/transformers/kiro.js

@@ -1,6 +1,6 @@
-import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { writeManagedSkill, removeManagedSkills } from '../managed-skills.js';
 import { registerMcpServersJsonAt, removeMcpServersJsonAt, skillName, } from './shared.js';
 function steeringRoot(ctx) {
     return ctx.scope === 'global'
@@ -24,25 +24,16 @@ function writeSteering(skill, rootDir) {
         '',
         skill.body,
     ].join('\n');
-    fs.mkdirSync(rootDir, { recursive: true });
-    fs.writeFileSync(path.join(rootDir, `${name}.md`), content);
+    return writeManagedSkill(rootDir, name, content, true);
 }
 function removeMemtraceSteering(rootDir) {
-    if (!fs.existsSync(rootDir))
-        return;
-    for (const entry of fs.readdirSync(rootDir)) {
-        if (entry.startsWith('memtrace-') && entry.endsWith('.md')) {
-            fs.rmSync(path.join(rootDir, entry), { force: true });
-        }
-    }
+    removeManagedSkills(rootDir, true);
 }
 export const kiroTransformer = {
     name: 'kiro',
     async install(skills, ctx) {
         const rootDir = steeringRoot(ctx);
-        removeMemtraceSteering(rootDir);
-        for (const skill of skills)
-            writeSteering(skill, rootDir);
+        const written = skills.filter(skill => writeSteering(skill, rootDir)).length;
         let mcpRegistered = false;
         const warnings = [];
         const mcpConfigPath = mcpPath(ctx);
@@ -55,7 +46,7 @@ export const kiroTransformer = {
         }
         return {
             agent: 'kiro',
-            skillsWritten: skills.length,
+            skillsWritten: written,
             skillsDir: rootDir,
             mcpConfigPath,
             mcpRegistered,

package/dist/transformers/opencode.js

@@ -31,13 +31,14 @@ export const opencodeTransformer = {
         // ─── memtrace-rail ─── Write the in-process discovery plugin (OpenCode
         // has no stdio hook). Defaults to observe; fail-open. Best effort.
         try {
-            const src = openCodePluginSource(ctx.memtraceBinary);
-            if (railIsActive()) {
-                writeOpenCodeRailPlugin(ctx, src);
-            }
-            else {
-                for (const pluginPath of openCodeRailPluginPaths(ctx)) {
-                    fs.rmSync(pluginPath, { force: true });
+            if (ctx.mode !== 'refresh') {
+                if (railIsActive()) {
+                    writeOpenCodeRailPlugin(ctx, openCodePluginSource(ctx.memtraceBinary));
+                }
+                else {
+                    for (const pluginPath of openCodeRailPluginPaths(ctx)) {
+                        fs.rmSync(pluginPath, { force: true });
+                    }
                 }
             }
         }

package/dist/transformers/pi.js

@@ -3,6 +3,7 @@ import os from 'os';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { removeMemtraceSkills, skillName } from './shared.js';
+import { writeManagedSkill } from '../managed-skills.js';
 import { safeReadJson, writeJsonAtomic } from '../fs-safe.js';
 import { commandExists } from '../utils.js';
 import { MEMTRACE_TOOL_NAMES } from '../tool-names.js';
@@ -80,15 +81,14 @@ function skillMarkdownForPi(skill, toolNames) {
     return `---\nname: ${name}\ndescription: "${safeDesc}"${toolsLine}\n---\n\n${body}`;
 }
 function writeSkillsForPi(skills, rootDir) {
-    removeMemtraceSkills(rootDir);
+    let written = 0;
     const toolNames = memtraceToolNames(skills);
     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'), skillMarkdownForPi(skill, toolNames));
+        if (writeManagedSkill(rootDir, name, skillMarkdownForPi(skill, toolNames)))
+            written++;
     }
-    return skills.length;
+    return written;
 }
 function packageEntrySource(entry) {
     if (typeof entry === 'string')
@@ -153,7 +153,9 @@ export const piTransformer = {
                 warnings: [`${e.message}`],
             };
         }
-        const result = registerPiPackageAt(settingsFile, packagePath);
+        const result = ctx.mode === 'refresh'
+            ? { registered: false, packagePath, backupPath: undefined }
+            : registerPiPackageAt(settingsFile, packagePath);
         if (!result.registered && result.backupPath) {
             warnings.push(`Pi settings.json was malformed; backed up to ${result.backupPath}.`);
         }

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)
@@ -182,7 +182,8 @@ export function registerCursorRailHook(hooksPath, binary, options = {}) {
     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.
+    // 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()) {
@@ -356,19 +357,28 @@ 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 ({ 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 || directory || process.cwd(),
@@ -389,6 +399,33 @@ export const MemtraceRail = async ({ directory }) => ({
       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.
+    }
+  },
 });
 `;
 }