memtrace-skills 1.2.9 → 1.2.11

package/dist/transformers/claude.d.ts

@@ -19,7 +19,7 @@ export interface SettingsMutationResult {
  * 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 declare function registerMcpInSettingsAt(settingsPath: string, memtraceBinary: string, legacyEnv?: Record<string, string>): SettingsMutationResult;
+export declare function registerMcpInSettingsAt(settingsPath: string, memtraceBinary: string, legacyEnv?: Record<string, string>, legacyArgs?: string[]): SettingsMutationResult;
 /**
  * Every host enters a local liveness guard before contacting Memtrace. The
  * daemon lifecycle registers/removes this command; a cached registration is
@@ -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.
  *
@@ -41,7 +41,19 @@ export declare function claudeRailHookCommand(_memtraceBinary: string, platform?
  * is replaced, and unrelated PreToolUse hooks are preserved. Never overwrites
  * a malformed file.
  */
-export declare function registerRailHookInSettingsAt(settingsPath: string, memtraceBinary: string, platform?: NodeJS.Platform): SettingsMutationResult;
+export declare function registerRailHookInSettingsAt(settingsPath: string, memtraceBinary: string, platform?: NodeJS.Platform, options?: RailHookOptions): SettingsMutationResult;
+/** 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 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 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;
+}
 /**
  * Remove the Memtrace Rail PreToolUse hook from a Claude settings.json.
  * Preserves unrelated hooks; prunes empty containers. Never touches a

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 } 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';
@@ -27,6 +28,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 +94,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 +198,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 +222,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,
     };
@@ -248,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.
  *
@@ -257,7 +272,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 +285,40 @@ 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 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'
+            ? 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 +539,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);
 }
@@ -526,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();
@@ -555,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();
@@ -572,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);
     }
 }
 /**
@@ -625,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.
@@ -663,7 +667,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);
@@ -685,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');
@@ -724,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/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/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.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;