@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/mcp.js

@@ -10,10 +10,10 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { execSync } from 'child_process';
-import * as os from 'os';
-import { getMcpDir, getProjectAgentsDir } from './state.js';
+import { execFileSync } from 'child_process';
+import { getMcpDir, getUserMcpDir, getProjectAgentsDir, getVersionsDir } from './state.js';
 import { MCP_CAPABLE_AGENTS, AGENTS } from './agents.js';
+import { setGeminiAutoUpdateDisabled, updateGeminiSettings } from './gemini-settings.js';
 /**
  * Parse an MCP server config from a YAML file.
  */
@@ -53,6 +53,8 @@ export function listMcpServerConfigs(cwd = process.cwd()) {
     if (projectAgentsDir) {
         dirs.push({ scope: 'project', dir: path.join(projectAgentsDir, 'mcp') });
     }
+    // User dir first (wins on name collision), then system
+    dirs.push({ scope: 'user', dir: getUserMcpDir() });
     dirs.push({ scope: 'user', dir: getMcpDir() });
     const results = new Map();
     for (const { scope, dir } of dirs) {
@@ -113,7 +115,7 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
             server.config.command,
             ...(server.config.args || [])
         ];
-        execSync(`"${binaryPath}" ${args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`, {
+        execFileSync(binaryPath, args, {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
@@ -121,7 +123,7 @@ function installMcpViaClaude(binaryPath, server, versionHome) {
     }
     else {
         // claude mcp add --scope user --transport http <name> <url>
-        execSync(`"${binaryPath}" mcp add --scope user --transport http "${server.name}" "${server.config.url}"`, {
+        execFileSync(binaryPath, ['mcp', 'add', '--scope', 'user', '--transport', 'http', server.name, server.config.url], {
             stdio: 'pipe',
             timeout: 30000,
             env: execEnv,
@@ -141,7 +143,7 @@ function installMcpViaCodex(binaryPath, server, versionHome) {
             server.config.command,
             ...(server.config.args || [])
         ];
-        execSync(`"${binaryPath}" ${args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ')}`, {
+        execFileSync(binaryPath, args, {
             stdio: 'pipe',
             timeout: 30000,
             env: { ...process.env, HOME: versionHome },
@@ -154,28 +156,25 @@ function installMcpViaCodex(binaryPath, server, versionHome) {
  */
 function installMcpToGeminiConfig(server, versionHome) {
     const configPath = path.join(versionHome, '.gemini', 'settings.json');
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-    }
-    if (!config.mcpServers || typeof config.mcpServers !== 'object') {
-        config.mcpServers = {};
-    }
-    const mcpServers = config.mcpServers;
-    if (server.config.transport === 'stdio') {
-        mcpServers[server.name] = {
-            command: server.config.command,
-            args: server.config.args || [],
-            env: server.config.env || {},
-        };
-    }
-    else {
-        mcpServers[server.name] = {
-            url: server.config.url,
-        };
-    }
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    updateGeminiSettings(configPath, (config) => {
+        setGeminiAutoUpdateDisabled(config);
+        if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+            config.mcpServers = {};
+        }
+        const mcpServers = config.mcpServers;
+        if (server.config.transport === 'stdio') {
+            mcpServers[server.name] = {
+                command: server.config.command,
+                args: server.config.args || [],
+                env: server.config.env || {},
+            };
+        }
+        else {
+            mcpServers[server.name] = {
+                url: server.config.url,
+            };
+        }
+    });
 }
 /**
  * Install MCP server to Cursor config file.
@@ -260,10 +259,8 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
     const applied = [];
     const errors = [];
     // Get binary path for CLI-based agents
-    const homeDir = os.homedir();
-    const agentsDir = path.join(homeDir, '.agents');
     const cliCommand = AGENTS[agentId].cliCommand;
-    const binaryPath = path.join(agentsDir, 'versions', agentId, version, 'node_modules', '.bin', cliCommand);
+    const binaryPath = path.join(getVersionsDir(), agentId, version, 'node_modules', '.bin', cliCommand);
     for (const server of servers) {
         try {
             if (agentId === 'claude') {
@@ -304,7 +301,7 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
  * Write an MCP server config to ~/.agents/mcp/.
  */
 export function writeMcpServerConfig(config) {
-    const mcpDir = getMcpDir();
+    const mcpDir = getUserMcpDir();
     fs.mkdirSync(mcpDir, { recursive: true });
     const fileName = `${config.name.toLowerCase().replace(/[^a-z0-9]/g, '-')}.yaml`;
     const filePath = path.join(mcpDir, fileName);
@@ -324,4 +321,3 @@ export function removeMcpServerConfig(name) {
     fs.unlinkSync(server.path);
     return true;
 }
-//# sourceMappingURL=mcp.js.map

package/dist/lib/memory-compile.d.ts

@@ -1,11 +1,22 @@
+/**
+ * Rules file compilation -- resolving @-imports into a single flat file.
+ *
+ * Agents that do not natively resolve `@path/to/file` imports (Codex, Gemini)
+ * need a pre-compiled rules file with all imports inlined. This module
+ * handles that expansion.
+ */
 import type { AgentId } from './types.js';
+/** Sidecar manifest recording source file hashes for staleness detection. */
 export interface CompileManifest {
     compiledAt: string;
     sources: {
         path: string;
         sha256: string;
+        mtime?: number;
+        size?: number;
     }[];
 }
+/** Result of resolving @-imports in a rules file. */
 export interface ResolveResult {
     /** Fully-inlined content. */
     content: string;
@@ -22,7 +33,7 @@ export interface ResolveResult {
  * paths resolve against the filesystem root / home directory.
  */
 export declare function resolveImports(content: string, baseDir: string): ResolveResult;
-/** True if the agent's native runtime resolves `@path` imports in its memory file. */
+/** True if the agent's native runtime resolves `@path` imports in its rules file. */
 export declare function supportsMemoryImports(agentId: AgentId): boolean;
 /**
  * Fast staleness check. Returns true when:
@@ -35,7 +46,7 @@ export declare function supportsMemoryImports(agentId: AgentId): boolean;
  */
 export declare function isMemoryStale(agentId: AgentId, version: string): boolean;
 /**
- * Resolve the source `memory/AGENTS.md` (with all @-imports expanded) and
+ * Resolve the source `rules/AGENTS.md` (with all @-imports expanded) and
  * write the result into the version home, alongside a sidecar manifest that
  * records source file hashes for staleness detection.
  *
@@ -53,4 +64,3 @@ export declare function compileMemoryForAgent(agentId: AgentId, version: string)
  * true if a recompile happened, false otherwise.
  */
 export declare function ensureMemoryFresh(agentId: AgentId, version: string): boolean;
-//# sourceMappingURL=memory-compile.d.ts.map

package/dist/lib/memory-compile.js

@@ -1,16 +1,23 @@
+/**
+ * Rules file compilation -- resolving @-imports into a single flat file.
+ *
+ * Agents that do not natively resolve `@path/to/file` imports (Codex, Gemini)
+ * need a pre-compiled rules file with all imports inlined. This module
+ * handles that expansion.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import { AGENTS } from './agents.js';
-import { getMemoryDir, getVersionsDir } from './state.js';
+import { getResolvedRulesDir, getVersionsDir } from './state.js';
 // Match `@path` preceded by start-of-string or whitespace. This avoids
 // matching emails ("foo@bar.com") and the middle of words. The leading
 // whitespace (if any) is captured so we can preserve it in the output.
 const IMPORT_RE = /(^|\s)@(\S+)/g;
 const MAX_DEPTH = 5;
-const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/memory/AGENTS.md + imports.\n' +
-    '     Edit the source files under ~/.agents/memory/ — edits to this file will be overwritten on next sync. -->\n\n';
+const COMPILED_HEADER = '<!-- Auto-compiled by agents-cli from ~/.agents/rules/AGENTS.md + imports.\n' +
+    '     Edit the source files under ~/.agents/rules/ — edits to this file will be overwritten on next sync. -->\n\n';
 function expandTilde(p) {
     if (p === '~')
         return os.homedir();
@@ -79,7 +86,7 @@ export function resolveImports(content, baseDir) {
     const result = expand(content, baseDir, 0);
     return { content: result, sources };
 }
-/** True if the agent's native runtime resolves `@path` imports in its memory file. */
+/** True if the agent's native runtime resolves `@path` imports in its rules file. */
 export function supportsMemoryImports(agentId) {
     return !!AGENTS[agentId].capabilities.memoryImports;
 }
@@ -112,6 +119,13 @@ export function isMemoryStale(agentId, version) {
         for (const src of manifest.sources) {
             if (!fs.existsSync(src.path))
                 return true;
+            // Tier 1: mtime+size fast path (no file read needed)
+            if (src.mtime !== undefined && src.size !== undefined) {
+                const stat = fs.statSync(src.path);
+                if (stat.mtimeMs === src.mtime && stat.size === src.size)
+                    continue;
+            }
+            // Tier 2: content hash
             if (sha256(fs.readFileSync(src.path, 'utf8')) !== src.sha256)
                 return true;
         }
@@ -122,7 +136,7 @@ export function isMemoryStale(agentId, version) {
     }
 }
 /**
- * Resolve the source `memory/AGENTS.md` (with all @-imports expanded) and
+ * Resolve the source `rules/AGENTS.md` (with all @-imports expanded) and
  * write the result into the version home, alongside a sidecar manifest that
  * records source file hashes for staleness detection.
  *
@@ -133,20 +147,29 @@ export function compileMemoryForAgent(agentId, version) {
     if (supportsMemoryImports(agentId)) {
         return { compiled: false, compiledPath: '', sources: 0 };
     }
-    const memoryDir = getMemoryDir();
+    const memoryDir = getResolvedRulesDir();
     const sourceAgents = path.join(memoryDir, 'AGENTS.md');
     if (!fs.existsSync(sourceAgents)) {
         return { compiled: false, compiledPath: '', sources: 0 };
     }
     const rootContent = fs.readFileSync(sourceAgents, 'utf8');
     const { content, sources } = resolveImports(rootContent, memoryDir);
+    const newContent = COMPILED_HEADER + content;
     const compiledPath = getCompiledMemoryPath(agentId, version);
     fs.mkdirSync(path.dirname(compiledPath), { recursive: true });
-    fs.writeFileSync(compiledPath, COMPILED_HEADER + content);
+    const existing = fs.existsSync(compiledPath) ? fs.readFileSync(compiledPath, 'utf8') : null;
+    if (existing === newContent) {
+        return { compiled: false, compiledPath, sources: 0 };
+    }
+    fs.writeFileSync(compiledPath, newContent);
     const allSources = [sourceAgents, ...sources];
     const manifest = {
         compiledAt: new Date().toISOString(),
-        sources: allSources.map(p => ({ path: p, sha256: sha256(fs.readFileSync(p, 'utf8')) })),
+        sources: allSources.map(p => {
+            const content = fs.readFileSync(p, 'utf8');
+            const stat = fs.statSync(p);
+            return { path: p, sha256: sha256(content), mtime: stat.mtimeMs, size: stat.size };
+        }),
     };
     fs.writeFileSync(getManifestPath(compiledPath), JSON.stringify(manifest, null, 2));
     return { compiled: true, compiledPath, sources: allSources.length };
@@ -164,4 +187,3 @@ export function ensureMemoryFresh(agentId, version) {
     const result = compileMemoryForAgent(agentId, version);
     return result.compiled;
 }
-//# sourceMappingURL=memory-compile.js.map

package/dist/lib/memory.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Rules file management -- reading, writing, and syncing agent instructions.
+ *
+ * The canonical rules file (AGENTS.md) gets synced
+ * into each agent's config directory under their native name (CLAUDE.md,
+ * GEMINI.md, etc.). This module handles reading, managing includes, and
+ * refreshing rules files across version homes.
+ */
 import type { AgentId } from './types.js';
 export type InstructionsScope = 'user' | 'project';
 export interface InstalledInstructions {
@@ -12,12 +20,12 @@ export interface DiscoveredInstructions {
     filename: string;
 }
 /**
- * Central memory filename constant.
- * All agents map to this file in ~/.agents/memory/, renamed per-agent when synced.
+ * Central rules filename constant.
+ * All agents map to this file in ~/.agents/rules/, renamed per-agent when synced.
  */
 export declare const CENTRAL_MEMORY_FILENAME = "AGENTS.md";
 /**
- * Get the canonical central memory filename for an agent's instructionsFile.
+ * Get the canonical central rules filename for an agent's instructionsFile.
  * Central storage uses AGENTS.md, which gets renamed per-agent when syncing:
  *   - Claude: AGENTS.md → CLAUDE.md
  *   - Gemini: AGENTS.md → GEMINI.md
@@ -42,15 +50,14 @@ export declare function listInstalledInstructionsWithScope(agentId: AgentId, cwd
 }): InstalledInstructions[];
 export declare function getInstructionsContent(agentId: AgentId, scope?: InstructionsScope, cwd?: string): string | null;
 /**
- * Install memory files from repo memory/ to central ~/.agents/memory/ directory.
- * Shims will symlink these to per-agent directories for synced agents.
+ * Install rules files from repo rules/ to central ~/.agents/rules/ directory.
+ * Nested presets/ and rules/ fragments are preserved so @imports keep working.
  */
 export declare function installInstructionsCentrally(repoPath: string, filesToInstall?: string[]): {
     installed: string[];
     errors: string[];
 };
 /**
- * List memory files from central ~/.agents/memory/ directory.
+ * List top-level rules files from user and system dirs (user wins on collision).
  */
 export declare function listCentralMemory(): string[];
-//# sourceMappingURL=memory.d.ts.map

package/dist/lib/memory.js

@@ -1,15 +1,45 @@
+/**
+ * Rules file management -- reading, writing, and syncing agent instructions.
+ *
+ * The canonical rules file (AGENTS.md) gets synced
+ * into each agent's config directory under their native name (CLAUDE.md,
+ * GEMINI.md, etc.). This module handles reading, managing includes, and
+ * refreshing rules files across version homes.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS } from './agents.js';
-import { getMemoryDir, getProjectAgentsDir } from './state.js';
+import { getResolvedRulesDir, getUserRulesDir, getProjectAgentsDir } from './state.js';
 import { getEffectiveHome } from './versions.js';
 /**
- * Central memory filename constant.
- * All agents map to this file in ~/.agents/memory/, renamed per-agent when synced.
+ * Central rules filename constant.
+ * All agents map to this file in ~/.agents/rules/, renamed per-agent when synced.
  */
 export const CENTRAL_MEMORY_FILENAME = 'AGENTS.md';
+const RULES_DOC_FILENAME = 'README.md';
+function isSyncableRuleMarkdown(filename) {
+    return filename.endsWith('.md') && filename !== RULES_DOC_FILENAME;
+}
+const RULES_SUBDIRS = ['default', 'presets'];
+function listRuleMarkdownFiles(rulesDir) {
+    const files = [];
+    const readDir = (dir, prefix) => {
+        if (!fs.existsSync(dir))
+            return;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isFile() && isSyncableRuleMarkdown(entry.name)) {
+                files.push(prefix ? `${prefix}/${entry.name}` : entry.name);
+            }
+        }
+    };
+    readDir(rulesDir, '');
+    for (const sub of RULES_SUBDIRS) {
+        readDir(path.join(rulesDir, sub), sub);
+    }
+    return files.sort();
+}
 /**
- * Get the canonical central memory filename for an agent's instructionsFile.
+ * Get the canonical central rules filename for an agent's instructionsFile.
  * Central storage uses AGENTS.md, which gets renamed per-agent when syncing:
  *   - Claude: AGENTS.md → CLAUDE.md
  *   - Gemini: AGENTS.md → GEMINI.md
@@ -44,11 +74,11 @@ export function getInstructionsPath(agentId, scope, cwd = process.cwd()) {
     }
     const projectAgentsDir = getProjectAgentsDir(cwd);
     if (projectAgentsDir) {
-        const projectMemoryDir = path.join(projectAgentsDir, 'memory');
+        const projectRulesDir = path.join(projectAgentsDir, 'rules');
         const centralName = getCentralMemoryFileName(agentId);
         const candidates = [
-            path.join(projectMemoryDir, centralName),
-            path.join(projectMemoryDir, agent.instructionsFile),
+            path.join(projectRulesDir, centralName),
+            path.join(projectRulesDir, agent.instructionsFile),
         ];
         for (const candidate of candidates) {
             if (fs.existsSync(candidate)) {
@@ -68,20 +98,20 @@ export function instructionsExists(agentId, scope = 'user', cwd = process.cwd())
 }
 export function discoverInstructionsFromRepo(repoPath) {
     const instructions = [];
-    const memoryDir = path.join(repoPath, 'memory');
-    if (!fs.existsSync(memoryDir)) {
+    const rulesDir = path.join(repoPath, 'rules');
+    if (!fs.existsSync(rulesDir)) {
         return instructions;
     }
     for (const agentId of ALL_AGENT_IDS) {
         const agent = AGENTS[agentId];
-        // AGENTS.md is the canonical central memory file - don't claim it per-agent.
-        // It gets installed centrally to ~/.agents/memory/ and shims symlink it per-agent.
+        // AGENTS.md is the canonical central rules file - don't claim it per-agent.
+        // It gets installed centrally to ~/.agents/rules/ and synced per-agent.
         const possibleNames = [
             `${agentId}.md`,
             agent.instructionsFile,
         ].filter(name => name !== 'AGENTS.md');
         for (const filename of possibleNames) {
-            const sourcePath = path.join(memoryDir, filename);
+            const sourcePath = path.join(rulesDir, filename);
             if (fs.existsSync(sourcePath)) {
                 instructions.push({
                     agentId,
@@ -96,8 +126,8 @@ export function discoverInstructionsFromRepo(repoPath) {
 }
 export function resolveInstructionsSource(repoPath, agentId) {
     const agent = AGENTS[agentId];
-    const memoryDir = path.join(repoPath, 'memory');
-    if (!fs.existsSync(memoryDir)) {
+    const rulesDir = path.join(repoPath, 'rules');
+    if (!fs.existsSync(rulesDir)) {
         return null;
     }
     const possibleNames = [
@@ -105,7 +135,7 @@ export function resolveInstructionsSource(repoPath, agentId) {
         agent.instructionsFile,
     ].filter(name => name !== 'AGENTS.md');
     for (const filename of possibleNames) {
-        const sourcePath = path.join(memoryDir, filename);
+        const sourcePath = path.join(rulesDir, filename);
         if (fs.existsSync(sourcePath)) {
             return sourcePath;
         }
@@ -113,15 +143,12 @@ export function resolveInstructionsSource(repoPath, agentId) {
     return null;
 }
 export function discoverMemoryFilesFromRepo(repoPath) {
-    const memoryDir = path.join(repoPath, 'memory');
-    if (!fs.existsSync(memoryDir)) {
+    const rulesDir = path.join(repoPath, 'rules');
+    if (!fs.existsSync(rulesDir)) {
         return [];
     }
     try {
-        return fs
-            .readdirSync(memoryDir, { withFileTypes: true })
-            .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
-            .map((entry) => entry.name);
+        return listRuleMarkdownFiles(rulesDir);
     }
     catch {
         return [];
@@ -214,30 +241,31 @@ export function getInstructionsContent(agentId, scope = 'user', cwd = process.cw
     }
 }
 /**
- * Install memory files from repo memory/ to central ~/.agents/memory/ directory.
- * Shims will symlink these to per-agent directories for synced agents.
+ * Install rules files from repo rules/ to central ~/.agents/rules/ directory.
+ * Nested presets/ and rules/ fragments are preserved so @imports keep working.
  */
 export function installInstructionsCentrally(repoPath, filesToInstall) {
     const installed = [];
     const errors = [];
-    const centralDir = getMemoryDir();
+    const centralDir = getUserRulesDir();
     if (!fs.existsSync(centralDir)) {
         fs.mkdirSync(centralDir, { recursive: true });
     }
-    const memoryDir = path.join(repoPath, 'memory');
-    if (!fs.existsSync(memoryDir)) {
+    const rulesDir = path.join(repoPath, 'rules');
+    if (!fs.existsSync(rulesDir)) {
         return { installed, errors };
     }
     try {
-        const files = filesToInstall ?? fs.readdirSync(memoryDir);
+        const files = filesToInstall ?? listRuleMarkdownFiles(rulesDir);
         for (const file of files) {
-            if (!file.endsWith('.md'))
+            if (!isSyncableRuleMarkdown(path.basename(file)))
                 continue;
-            const sourcePath = path.join(memoryDir, file);
+            const sourcePath = path.join(rulesDir, file);
             const stat = fs.statSync(sourcePath);
             if (!stat.isFile())
                 continue;
             const targetPath = path.join(centralDir, file);
+            fs.mkdirSync(path.dirname(targetPath), { recursive: true });
             try {
                 fs.copyFileSync(sourcePath, targetPath);
                 installed.push(file);
@@ -248,20 +276,21 @@ export function installInstructionsCentrally(repoPath, filesToInstall) {
         }
     }
     catch (err) {
-        errors.push(`Failed to read memory directory: ${err.message}`);
+        errors.push(`Failed to read rules directory: ${err.message}`);
     }
     return { installed, errors };
 }
 /**
- * List memory files from central ~/.agents/memory/ directory.
+ * List top-level rules files from user and system dirs (user wins on collision).
  */
 export function listCentralMemory() {
-    const centralDir = getMemoryDir();
-    if (!fs.existsSync(centralDir)) {
-        return [];
+    const seen = new Set();
+    for (const dir of [getUserRulesDir(), getResolvedRulesDir()]) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const f of fs.readdirSync(dir).filter((f) => isSyncableRuleMarkdown(f))) {
+            seen.add(f);
+        }
     }
-    return fs
-        .readdirSync(centralDir)
-        .filter((f) => f.endsWith('.md'));
+    return Array.from(seen);
 }
-//# sourceMappingURL=memory.js.map

package/dist/lib/migrate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * One-shot idempotent migrations for the FOUNDATION refactor.
+ *
+ * Called from postinstall and as a command-time fallback from agents view/use/pull.
+ * Each migration is guarded by an existence check so re-running is safe.
+ */
+/** Run all idempotent migrations. Safe to call multiple times. */
+export declare function runMigration(): void;

package/dist/lib/migrate.js

@@ -0,0 +1,85 @@
+/**
+ * One-shot idempotent migrations for the FOUNDATION refactor.
+ *
+ * Called from postinstall and as a command-time fallback from agents view/use/pull.
+ * Each migration is guarded by an existence check so re-running is safe.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+const HOME = os.homedir();
+const SYSTEM_DIR = path.join(HOME, '.agents-system');
+const USER_DIR = path.join(HOME, '.agents');
+/**
+ * Move ~/.agents-system/agents.yaml -> ~/.agents/agents.yaml.
+ * No-op if user file already exists or system file absent.
+ * (This is also handled inline in state.ts readMeta, but is exposed here
+ *  for explicit migration calls from postinstall / CLI entry points.)
+ */
+function migrateAgentsYaml() {
+    const src = path.join(SYSTEM_DIR, 'agents.yaml');
+    const dest = path.join(USER_DIR, 'agents.yaml');
+    if (fs.existsSync(dest) || !fs.existsSync(src))
+        return;
+    try {
+        fs.mkdirSync(USER_DIR, { recursive: true, mode: 0o700 });
+        fs.renameSync(src, dest);
+        console.log('Migrated agents.yaml to ~/.agents/');
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Delete ~/.agents-system/prompts.json (dead file — zero refs in src/).
+ */
+function deleteSystemPromptsJson() {
+    const f = path.join(SYSTEM_DIR, 'prompts.json');
+    if (!fs.existsSync(f))
+        return;
+    try {
+        fs.unlinkSync(f);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move ~/.agents-system/config.json -> ~/.agents/teams/config.json.
+ * The teams persistence layer already reads the legacy path as a fallback;
+ * moving it here keeps the canonical location consistent.
+ */
+function migrateSystemConfigJson() {
+    const src = path.join(SYSTEM_DIR, 'config.json');
+    const dest = path.join(USER_DIR, 'teams', 'config.json');
+    if (!fs.existsSync(src) || fs.existsSync(dest))
+        return;
+    try {
+        fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+        fs.copyFileSync(src, dest);
+        fs.unlinkSync(src);
+    }
+    catch { /* best-effort */ }
+}
+/**
+ * Move promptcuts.yaml from each repo root into hooks/ subdir.
+ *   ~/.agents-system/promptcuts.yaml -> ~/.agents-system/hooks/promptcuts.yaml
+ *   ~/.agents/promptcuts.yaml        -> ~/.agents/hooks/promptcuts.yaml
+ * Idempotent: skips if dest already exists or src absent.
+ */
+function migratePromptcutsIntoHooks() {
+    for (const root of [SYSTEM_DIR, USER_DIR]) {
+        const src = path.join(root, 'promptcuts.yaml');
+        const dest = path.join(root, 'hooks', 'promptcuts.yaml');
+        if (fs.existsSync(dest) || !fs.existsSync(src))
+            continue;
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+            fs.renameSync(src, dest);
+        }
+        catch { /* best-effort */ }
+    }
+}
+/** Run all idempotent migrations. Safe to call multiple times. */
+export function runMigration() {
+    migrateAgentsYaml();
+    deleteSystemPromptsJson();
+    migrateSystemConfigJson();
+    migratePromptcutsIntoHooks();
+}