memtrace-skills 1.2.10 → 1.2.11

package/dist/managed-skills.d.ts

@@ -0,0 +1,4 @@
+export declare const RECEIPT_SUFFIX = ".memtrace-managed.sha256";
+export declare function skillDigest(content: string): string;
+export declare function writeManagedSkill(rootDir: string, name: string, content: string, steering?: boolean): boolean;
+export declare function removeManagedSkills(rootDir: string, steering?: boolean): void;

package/dist/managed-skills.js

@@ -0,0 +1,95 @@
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'url';
+// A name is not ownership. Receipts bind the exact last-installed bytes; the
+// stock catalogue admits upgrades from installers that predate receipts.
+const stockFile = fileURLToPath(new URL('../skills/managed-stock-sha256.txt', import.meta.url));
+const stock = new Set(fs.readFileSync(stockFile, 'utf8').split(/\r?\n/).filter(line => !line.startsWith('#')));
+export const RECEIPT_SUFFIX = '.memtrace-managed.sha256';
+export function skillDigest(content) {
+    return createHash('sha256').update(content.replace(/\r\n/g, '\n')).digest('hex');
+}
+function safeFile(rootDir, relative) {
+    const parts = relative.split(/[\\/]/);
+    if (parts.some(part => !part || part === '.' || part === '..'))
+        return;
+    let current = path.resolve(rootDir);
+    if (fs.existsSync(current) && (!fs.lstatSync(current).isDirectory() || fs.lstatSync(current).isSymbolicLink()))
+        return;
+    for (const part of parts) {
+        current = path.join(current, part);
+        try {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink() || (!stat.isDirectory() && current !== path.resolve(rootDir, relative)))
+                return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    try {
+        const receipt = fs.lstatSync(current + RECEIPT_SUFFIX);
+        if (!receipt.isFile() || receipt.isSymbolicLink())
+            return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return current;
+}
+function owned(file, name, content) {
+    const digest = skillDigest(content);
+    if (stock.has(`${name} ${digest}`))
+        return true;
+    try {
+        return fs.readFileSync(file + RECEIPT_SUFFIX, 'utf8').trim() === digest;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return false;
+    }
+}
+export function writeManagedSkill(rootDir, name, content, steering = false) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name))
+        throw new Error(`Invalid managed skill name: ${name}`);
+    const file = safeFile(rootDir, steering ? `${name}.md` : `${name}/SKILL.md`);
+    if (!file)
+        return false;
+    if (fs.existsSync(file)) {
+        if (!fs.lstatSync(file).isFile())
+            return false;
+        const prior = fs.readFileSync(file, 'utf8');
+        if (prior !== content && !owned(file, name, prior)) {
+            console.warn(`memtrace: preserved customized skill ${file}`);
+            return false;
+        }
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    fs.writeFileSync(file + RECEIPT_SUFFIX, `${skillDigest(content)}\n`);
+    return true;
+}
+export function removeManagedSkills(rootDir, steering = false) {
+    if (!fs.existsSync(rootDir) || fs.lstatSync(rootDir).isSymbolicLink())
+        return;
+    for (const entry of fs.readdirSync(rootDir)) {
+        const name = steering ? entry.replace(/\.md$/, '') : entry;
+        if (!/^memtrace-[a-z0-9-]+$/.test(name) || (steering && !entry.endsWith('.md')))
+            continue;
+        const file = safeFile(rootDir, steering ? entry : `${entry}/SKILL.md`);
+        if (!file || !fs.existsSync(file) || !fs.lstatSync(file).isFile())
+            continue;
+        if (!owned(file, name, fs.readFileSync(file, 'utf8')))
+            continue;
+        fs.unlinkSync(file);
+        if (fs.existsSync(file + RECEIPT_SUFFIX))
+            fs.unlinkSync(file + RECEIPT_SUFFIX);
+        // Never recursively delete a skill folder: user references/assets survive.
+        if (!steering && fs.readdirSync(path.dirname(file)).length === 0)
+            fs.rmdirSync(path.dirname(file));
+    }
+}

package/dist/rail-hook.js

@@ -118,7 +118,8 @@ async function main() {
     const phase = arg('--phase');
     const event = arg('--event');
     const enrichPath = phase === 'post' || event === 'precompact';
-    // Grep enrichment is opt-in: off means no stdin parse, no lease read, no HTTP.
+    // Explicit off (or a non-Nudge mode without opt-in) means no stdin parse,
+    // no lease read and no HTTP. Fresh Nudge enables bounded context by default.
     if (enrichPath && !enrichEnabled(env))
         return;
     const input = await readStdin();
@@ -169,7 +170,7 @@ async function main() {
     // JSON-mode/OpenCode and Windsurf retain their CLI response contracts.
     // Other hosts use the in-process daemon router with no native binary spawn.
     if (!jsonMode && host !== 'windsurf' && !runtime.routeBinary) {
-        const query = new URLSearchParams({ host, mode: env.MEMTRACE_RAIL || '',
+        const query = new URLSearchParams({ host, mode: env.MEMTRACE_RAIL || '', enrich: env.MEMTRACE_ENRICH || '',
             escape: env.MEMTRACE_RAW_SEARCH || '' });
         const result = await postToDaemon(runtime, `/api/rail/hook?${query}`, input, 5500);
         if (result.status === 200 && result.body && alive()) {

package/dist/rail-runtime.d.ts

@@ -34,10 +34,11 @@ export interface RailConfig {
 export declare function railConfig(): RailConfig;
 /**
  * Grep enrichment on/off: `MEMTRACE_ENRICH`, then rail.json `"enrich"`, then
- * OFF — the default stays off until the A/B gate passes.
+ * non-blocking Nudge mode. Explicit Observe, Off, Rail and Strict modes do
+ * not implicitly enable this additional post-search path.
  */
 export declare function enrichEnabled(env?: NodeJS.ProcessEnv, config?: RailConfig): boolean;
-/** Rail mode: `MEMTRACE_RAIL`, then rail.json `"mode"`, then observe. */
+/** Rail mode: `MEMTRACE_RAIL`, then rail.json `"mode"`, then non-blocking nudge. */
 export declare function railMode(env?: NodeJS.ProcessEnv, config?: RailConfig): string;
 /**
  * Live leases. Reading them also deletes garbage: a lease whose owner and

package/dist/rail-runtime.js

@@ -93,19 +93,28 @@ function flag(value) {
 }
 /**
  * Grep enrichment on/off: `MEMTRACE_ENRICH`, then rail.json `"enrich"`, then
- * OFF — the default stays off until the A/B gate passes.
+ * non-blocking Nudge mode. Explicit Observe, Off, Rail and Strict modes do
+ * not implicitly enable this additional post-search path.
  */
 export function enrichEnabled(env = process.env, config = railConfig()) {
-    return flag(env.MEMTRACE_ENRICH) ?? (typeof config.enrich === 'boolean' ? config.enrich : false);
+    // Durable opt-outs remain effective even when an old agent inherited an
+    // enabling environment. This is the same no-hooks gate used by the lease.
+    if (env.MEMTRACE_INSTALL_NO_HOOKS === '1' || config.hooksEnabled === false
+        || (typeof config.mode === 'string' && config.mode.trim().toLowerCase() === 'off')
+        || env.MEMTRACE_RAIL?.trim().toLowerCase() === 'off'
+        || env.MEMTRACE_RAW_SEARCH?.trim().toLowerCase() === 'allow')
+        return false;
+    return flag(env.MEMTRACE_ENRICH)
+        ?? (typeof config.enrich === 'boolean' ? config.enrich : railMode(env, config) === 'nudge');
 }
-/** Rail mode: `MEMTRACE_RAIL`, then rail.json `"mode"`, then observe. */
+/** Rail mode: `MEMTRACE_RAIL`, then rail.json `"mode"`, then non-blocking nudge. */
 export function railMode(env = process.env, config = railConfig()) {
     const valid = ['off', 'observe', 'nudge', 'rail', 'strict'];
     const fromEnv = env.MEMTRACE_RAIL?.trim().toLowerCase();
     if (fromEnv && valid.includes(fromEnv))
         return fromEnv;
     const fromConfig = typeof config.mode === 'string' ? config.mode.trim().toLowerCase() : '';
-    return valid.includes(fromConfig) ? fromConfig : 'observe';
+    return valid.includes(fromConfig) ? fromConfig : 'nudge';
 }
 /**
  * Live leases. Reading them also deletes garbage: a lease whose owner and

package/dist/transformers/claude.d.ts

@@ -32,8 +32,8 @@ export declare function claudeRailHookCommand(_memtraceBinary: string, platform?
  * 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.
  *
@@ -49,7 +49,7 @@ export declare const ENRICH_HOOK_MATCHER = "Grep|Bash|PowerShell";
 /** Claude hook timeout for the enrichment hooks, in seconds. */
 export declare const ENRICH_HOOK_TIMEOUT_S = 2;
 export interface RailHookOptions {
-    /** Register the grep-enrichment hooks. Default: `MEMTRACE_ENRICH`, then rail.json, then off. */
+    /** Register grep-enrichment hooks. Explicit env/config wins; implicit on only in Nudge. */
     enrich?: boolean;
     /** The Rail mode the PreToolUse decision depends on. Default: env, then rail.json. */
     mode?: string;

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'
@@ -553,6 +555,9 @@ export function claudeUserConfigFile() {
  *  3. Register MCP server for memtrace tools
  */
 export async function installClaudePlugin(skills, memtraceBinaryPath) {
+    // 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,15 +587,12 @@ 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();
@@ -599,27 +601,16 @@ export async function installClaudePlugin(skills, 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 };
 }
 /**
  * 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 +643,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.
@@ -712,22 +689,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 +717,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.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 { commandExists, execCommand } from '../utils.js';
 import { registerSettingsHook, removeSettingsHook, CODEX_MATCHER, } from './rail-hooks.js';
 const MCP_SERVER_NAME = 'memtrace';
@@ -19,11 +20,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
@@ -168,15 +167,7 @@ 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);
@@ -198,7 +189,7 @@ export const codexTransformer = {
         }
         return {
             agent: 'codex',
-            skillsWritten: skills.length,
+            skillsWritten: written,
             skillsDir: rootDir,
             mcpConfigPath,
             mcpRegistered,
@@ -207,13 +198,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);
@@ -123,7 +114,7 @@ export const cursorTransformer = {
         }
         return {
             agent: 'cursor',
-            skillsWritten: skills.length,
+            skillsWritten: written,
             skillsDir: rootDir,
             mcpConfigPath: mcpPath(ctx),
             mcpRegistered,
@@ -133,13 +124,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/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/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')

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.
+    }
+  },
 });
 `;
 }