@phnx-labs/agents-cli 1.14.1 → 1.14.3

package/dist/commands/doctor.js

@@ -1,12 +1,16 @@
 import chalk from 'chalk';
 import { checkAllClis } from '../lib/teams/agents.js';
-import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
-import { getAvailableResources, getGlobalDefault, } from '../lib/versions.js';
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../lib/agents.js';
+import { getAvailableResources, getGlobalDefault, getVersionHomePath, isVersionInstalled, listInstalledVersions, parseAgentSpec, } from '../lib/versions.js';
 import { loadSyncManifest, isSyncStale } from '../lib/sync-manifest.js';
 import { diffVersionCommands, iterCommandsCapableVersions } from '../lib/commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions } from '../lib/skills.js';
 import { diffVersionHooks, iterHooksCapableVersions } from '../lib/hooks.js';
+import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
+import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
+import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
+// ─── overview mode (no target) ────────────────────────────────────────────────
 function checkSyncStatus(cwd) {
     const rows = [];
     for (const agent of ALL_AGENT_IDS) {
@@ -58,7 +62,7 @@ function countOrphans() {
     }
     return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
 }
-function renderText(clis, syncRows, orphanRows) {
+function renderOverviewText(clis, syncRows, orphanRows) {
     console.log(chalk.bold('Agent CLIs'));
     if (Object.keys(clis).length === 0) {
         console.log(chalk.gray('  (no agents reported)'));
@@ -113,20 +117,252 @@ function renderText(clis, syncRows, orphanRows) {
         console.log(chalk.gray('  Run `agents prune` to remove.'));
     }
 }
+function parseTargetArg(arg) {
+    const at = arg.indexOf('@');
+    const agentPart = at === -1 ? arg : arg.slice(0, at);
+    const versionPart = at === -1 ? '' : arg.slice(at + 1);
+    const agent = resolveAgentName(agentPart);
+    if (!agent)
+        return { error: formatAgentError(agentPart) };
+    if (!versionPart) {
+        const versions = listInstalledVersions(agent);
+        if (versions.length === 0)
+            return { error: `${AGENTS[agent].name} has no installed versions. Run \`agents add ${agent}@<version>\` first.` };
+        return { agent, versions };
+    }
+    if (versionPart === 'default') {
+        const def = getGlobalDefault(agent);
+        if (!def)
+            return { error: `${AGENTS[agent].name} has no default version pinned. Run \`agents use ${agent}@<version>\`.` };
+        return { agent, versions: [def] };
+    }
+    const spec = parseAgentSpec(`${agent}@${versionPart}`);
+    if (!spec)
+        return { error: `Invalid version: ${versionPart}` };
+    if (!isVersionInstalled(agent, versionPart)) {
+        return { error: `${AGENTS[agent].name}@${versionPart} is not installed. Installed: ${listInstalledVersions(agent).join(', ') || '(none)'}` };
+    }
+    return { agent, versions: [versionPart] };
+}
+function parseKindFilter(arg) {
+    if (!arg)
+        return DOCTOR_ALL_KINDS;
+    const requested = arg.split(',').map((s) => s.trim()).filter(Boolean);
+    const valid = new Set(DOCTOR_ALL_KINDS);
+    const out = [];
+    for (const k of requested) {
+        if (!valid.has(k)) {
+            return { error: `Unknown kind: ${k}. Valid: ${DOCTOR_ALL_KINDS.join(', ')}` };
+        }
+        out.push(k);
+    }
+    return out;
+}
+function statusLabel(status) {
+    switch (status) {
+        case 'ok': return chalk.green('ok   ');
+        case 'diff': return chalk.yellow('DIFF ');
+        case 'missing': return chalk.red('MISS ');
+        case 'extra': return chalk.magenta('EXTRA');
+    }
+}
+function sourceLabel(diff, layers) {
+    if (!diff.source)
+        return '';
+    if (diff.source === 'extra') {
+        // Find which extra repo this came from.
+        const sourcePath = diff.sourcePath;
+        if (sourcePath) {
+            for (const e of layers.extras) {
+                if (sourcePath.startsWith(e.dir + '/') || sourcePath === e.dir) {
+                    return chalk.gray(`source=extra:${e.alias}`);
+                }
+            }
+        }
+        return chalk.gray('source=extra');
+    }
+    return chalk.gray(`source=${diff.source}`);
+}
+function countByStatus(rows) {
+    let ok = 0, diff = 0, missing = 0, extra = 0;
+    for (const r of rows) {
+        if (r.status === 'ok')
+            ok++;
+        else if (r.status === 'diff')
+            diff++;
+        else if (r.status === 'missing')
+            missing++;
+        else if (r.status === 'extra')
+            extra++;
+    }
+    return { ok, diff, missing, extra };
+}
+function renderKindSection(kind, rows, layers, options) {
+    const counts = countByStatus(rows);
+    const total = rows.length;
+    const summaryParts = [];
+    if (counts.ok)
+        summaryParts.push(`${counts.ok} ok`);
+    if (counts.diff)
+        summaryParts.push(chalk.yellow(`${counts.diff} diff`));
+    if (counts.missing)
+        summaryParts.push(chalk.red(`${counts.missing} missing`));
+    if (counts.extra)
+        summaryParts.push(chalk.magenta(`${counts.extra} extra`));
+    const summary = total === 0 ? chalk.gray('(none)') : summaryParts.join(', ');
+    console.log(`  ${chalk.bold(kind.padEnd(11))} ${chalk.gray(`${total} item${total === 1 ? '' : 's'}`)}  ${summary}`);
+    if (total === 0)
+        return;
+    // Hide ok rows by default for big lists; show them only with --diff so the
+    // operator can verify presence; otherwise keep output focused on problems.
+    const visible = options.showDiff ? rows : rows.filter((r) => r.status !== 'ok');
+    if (visible.length === 0) {
+        console.log(`    ${chalk.gray('all ok')}`);
+        return;
+    }
+    for (const r of visible) {
+        const src = sourceLabel(r, layers);
+        console.log(`    ${statusLabel(r.status)}  ${r.name.padEnd(28)} ${src}`);
+        if (options.showDiff && r.status === 'diff' && r.sourcePath && r.homePath) {
+            const expected = readExpectedForDiff(kind, r);
+            const actual = safeRead(r.homePath);
+            if (expected != null && actual != null) {
+                const patch = unifiedDiff(expected, actual, {
+                    fromLabel: r.sourcePath,
+                    toLabel: r.homePath,
+                    context: 2,
+                });
+                if (patch)
+                    console.log(colorizeUnifiedDiff(patch, '      '));
+            }
+        }
+    }
+}
+function safeRead(p) {
+    try {
+        return fs.readFileSync(p, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function readExpectedForDiff(kind, row) {
+    // Skills are directories; per-file diffs would need recursive walking.
+    // Keep the v1 behaviour minimal: the row already says DIFF, the user can
+    // open the source path to inspect.
+    if (kind === 'skills')
+        return null;
+    if (!row.sourcePath)
+        return null;
+    return safeRead(row.sourcePath);
+}
+function renderTargetText(report, options) {
+    const label = `${AGENT_NAMES[report.agent] || report.agent}@${report.version}`;
+    console.log(chalk.bold(label));
+    console.log(chalk.gray(`  home: ${report.home}`));
+    console.log(chalk.gray(`  cwd:  ${report.cwd}`));
+    const layerStr = [
+        report.layers.project ? `project=${report.layers.project}` : null,
+        `user=${report.layers.user}`,
+        `system=${report.layers.system}`,
+        report.layers.extras.length > 0
+            ? `extras=[${report.layers.extras.map((e) => e.alias).join(',')}]`
+            : null,
+    ].filter(Boolean).join(' ');
+    console.log(chalk.gray(`  layers: ${layerStr}`));
+    console.log();
+    for (const kind of DOCTOR_ALL_KINDS) {
+        const rows = report.kinds[kind];
+        // Skip kinds that weren't requested (kind filter narrowed the report).
+        // We detect this by checking whether the kind has any rows AND was in
+        // scope; absent kinds with empty arrays still render so the operator
+        // sees what was checked. options.requestedKinds drives this.
+        if (options.requestedKinds && !options.requestedKinds.has(kind))
+            continue;
+        renderKindSection(kind, rows, report.layers, options);
+    }
+    console.log();
+    const { ok, diff, missing, extra } = report.summary;
+    const verdictParts = [];
+    if (diff)
+        verdictParts.push(chalk.yellow(`${diff} divergent`));
+    if (missing)
+        verdictParts.push(chalk.red(`${missing} missing`));
+    if (extra)
+        verdictParts.push(chalk.magenta(`${extra} extra`));
+    if (verdictParts.length === 0) {
+        console.log(chalk.green(`  Verdict: ${ok} resource${ok === 1 ? '' : 's'} reconciled. Version home matches resolved sources.`));
+    }
+    else {
+        console.log(`  Verdict: ${verdictParts.join(', ')}.`);
+        console.log(chalk.gray(`  Run \`agents sync --agent ${report.agent} --agent-version ${report.version}\` to reconcile, or \`agents prune\` to drop extras.`));
+    }
+}
+// ─── command registration ────────────────────────────────────────────────────
 export function registerDoctorCommand(program) {
     program
-        .command('doctor')
-        .description('Diagnose CLI availability, sync status, and orphan resources')
+        .command('doctor [target]')
+        .description('Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version])')
         .option('--json', 'Output machine-readable JSON')
-        .action((opts) => {
-        const cwd = process.cwd();
-        const clis = checkAllClis();
-        const syncRows = checkSyncStatus(cwd);
-        const orphanRows = countOrphans();
+        .option('--diff', 'In target mode, include unified diffs for divergent files')
+        .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
+        .addHelpText('after', `
+Examples:
+  # Overview across default versions (CLI availability + sync + orphans)
+  agents doctor
+
+  # Full per-resource report for the active default
+  agents doctor claude@default
+
+  # Pin to a specific installed version
+  agents doctor codex@0.117.0
+
+  # All installed versions for one agent
+  agents doctor gemini
+
+  # Only inspect rules and hooks, with full diffs
+  agents doctor claude@default --kind rules,hooks --diff
+`)
+        .action((target, opts) => {
+        const cwd = opts.cwd ? opts.cwd : process.cwd();
+        if (!target) {
+            const clis = checkAllClis();
+            const syncRows = checkSyncStatus(cwd);
+            const orphanRows = countOrphans();
+            if (opts.json) {
+                console.log(JSON.stringify({ clis, sync: syncRows, orphans: orphanRows }, null, 2));
+                return;
+            }
+            renderOverviewText(clis, syncRows, orphanRows);
+            return;
+        }
+        const parsed = parseTargetArg(target);
+        if ('error' in parsed) {
+            console.error(chalk.red(parsed.error));
+            process.exit(1);
+        }
+        const kinds = parseKindFilter(opts.kind);
+        if (!Array.isArray(kinds)) {
+            console.error(chalk.red(kinds.error));
+            process.exit(1);
+        }
+        const reports = parsed.versions.map((v) => diffVersionResources(parsed.agent, v, { cwd, kinds }));
         if (opts.json) {
-            console.log(JSON.stringify({ clis, sync: syncRows, orphans: orphanRows }, null, 2));
+            console.log(JSON.stringify(reports.length === 1 ? reports[0] : reports, null, 2));
             return;
         }
-        renderText(clis, syncRows, orphanRows);
+        const showDiff = !!opts.diff;
+        const requestedKinds = opts.kind ? new Set(kinds) : undefined;
+        reports.forEach((r, i) => {
+            if (i > 0)
+                console.log();
+            const home = getVersionHomePath(r.agent, r.version);
+            if (!fs.existsSync(home)) {
+                console.log(chalk.red(`${AGENT_NAMES[r.agent] || r.agent}@${r.version}: version home not found at ${home}`));
+                return;
+            }
+            renderTargetText(r, { showDiff, requestedKinds });
+        });
     });
 }

package/dist/commands/exec.js

@@ -16,12 +16,12 @@ const VALID_AGENTS = Object.keys(AGENT_COMMANDS);
 function isValidAgent(agent) {
     return VALID_AGENTS.includes(agent);
 }
-/** Build a one-line banner describing which version the rotation picked. */
-function formatRotationBanner(result) {
+/** Build a one-line banner describing which version the strategy picked. */
+function formatRotationBanner(result, verb = 'balanced') {
     const { picked, healthy, excluded } = result;
     const label = picked.email ? `${picked.email} · ${picked.agent}@${picked.version}` : `${picked.agent}@${picked.version}`;
     const ratio = `${healthy.length} of ${healthy.length + excluded.length} healthy`;
-    return `[agents] rotation picked ${label} (${ratio})`;
+    return `[agents] ${verb} picked ${label} (${ratio})`;
 }
 /** Register the `agents run <agent> [prompt]` command. */
 export function registerRunCommand(program) {
@@ -42,8 +42,8 @@ export function registerRunCommand(program) {
         .option('--verbose', 'Show detailed execution logs')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
-        .option('-r, --rotate', 'Shortcut for --strategy rotate. Ignored when @version is pinned.')
-        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | rotate. Defaults to run.<agent>.strategy, then pinned.')
+        .option('-b, --balanced', 'Shortcut for --strategy balanced. Ignored when @version is pinned.')
+        .option('--strategy <strategy>', 'Version/account selection strategy: pinned | available | balanced. Defaults to run.<agent>.strategy, then pinned. (Legacy `rotate` accepted as alias for `balanced`.)')
         .option('--acp', 'Route through the Agent Client Protocol instead of direct exec. Supported for gemini, claude (via @zed-industries/claude-code-acp adapter). Unified event stream; emits ndjson when --json.')
         .addHelpText('after', `
 Modes:
@@ -54,18 +54,20 @@ Run strategy:
   pinned     Use the workspace/global pinned version from agents.yaml.
   available  Use the pinned version if it has usage available; otherwise switch
              to another signed-in version with usage available.
-  rotate     Pick the signed-in account with usage available and the most
-             headroom; last-active breaks ties.
+  balanced   Distribute traffic across healthy accounts using weighted random
+             by remaining capacity — fresher accounts get more, near-exhausted
+             ones get less. Avoids bursting any single account.
   Configure with run.<agent>.strategy in agents.yaml, or override with
-  --strategy. --rotate is kept as a shortcut for --strategy rotate.
+  --strategy. --balanced is kept as a shortcut for --strategy balanced.
+  Legacy "rotate" is accepted as an alias for "balanced".
   Ignored when @version is pinned, when a profile is used, or with --fallback.
 
 Examples:
   # Interactive with the pinned default version
   agents run claude
 
-  # Interactive, rotate to the least-used healthy account
-  agents run claude --strategy rotate
+  # Interactive, distribute load across healthy accounts
+  agents run claude --strategy balanced
 
   # Headless, switch away from the pinned version when usage is unavailable
   agents run claude "summarize recent git commits" --mode plan --strategy available
@@ -134,14 +136,14 @@ Examples:
             console.error(chalk.red(`Invalid strategy: ${options.strategy}. Use ${RUN_STRATEGIES.join(', ')}.`));
             process.exit(1);
         }
-        if (options.rotate && explicitStrategy && explicitStrategy !== 'rotate') {
-            console.error(chalk.red('--rotate conflicts with --strategy. Use one strategy override.'));
+        if (options.balanced && explicitStrategy && explicitStrategy !== 'balanced') {
+            console.error(chalk.red('--balanced conflicts with --strategy. Use one strategy override.'));
             process.exit(1);
         }
-        const strategy = options.rotate ? 'rotate' : explicitStrategy ?? configuredStrategy;
+        const strategy = options.balanced ? 'balanced' : explicitStrategy ?? configuredStrategy;
         // Strategy only applies to bare agent invocations. Explicit @version,
         // profiles, and fallback chains already define their execution target.
-        if (strategy !== 'pinned' || options.rotate || explicitStrategy) {
+        if (strategy !== 'pinned' || options.balanced || explicitStrategy) {
             if (version) {
                 process.stderr.write(chalk.yellow(`[agents] strategy ${strategy} ignored: version ${version} is pinned\n`));
             }
@@ -157,9 +159,7 @@ Examples:
                     if (resolved.version) {
                         version = resolved.version;
                         if (resolved.rotation) {
-                            const banner = strategy === 'available'
-                                ? formatRotationBanner(resolved.rotation).replace('rotation picked', 'available picked')
-                                : formatRotationBanner(resolved.rotation);
+                            const banner = formatRotationBanner(resolved.rotation, strategy);
                             process.stderr.write(chalk.gray(banner + '\n'));
                         }
                     }

package/dist/commands/prune.js

@@ -133,7 +133,7 @@ async function runOrphanPrune(resourceTypes, options) {
 export function registerPruneCommand(program) {
     program
         .command('prune [target]')
-        .description('Remove orphan resources (commands/skills/hooks) and/or older duplicate version installs')
+        .description('Remove orphan resources (commands/skills/hooks) and/or older duplicate version installs (versions soft-deleted to ~/.agents-system/trash/)')
         .option('--all', 'For orphan cleanup: sweep every installed version (default: current default version per agent)')
         .option('--dry-run', 'Show what would be removed without deleting')
         .option('-y, --yes', 'Skip confirmation prompt')
@@ -172,8 +172,14 @@ What's an orphan?
   reconciled into the version install.
 
 What this does NOT do:
-  This is destructive cleanup only. Adds and updates flow through the auto-sync
-  that runs when you launch the agent — there is no manual sync verb.
+  Adds and updates flow through the auto-sync that runs when you launch the
+  agent — there is no manual sync verb.
+
+Soft-delete:
+  Version directories are NEVER hard-deleted. \`prune\` moves them to
+  ~/.agents-system/trash/versions/<agent>/<version>/<timestamp>/. Recover
+  with \`agents trash list\` and \`agents trash restore <agent>@<version>\`.
+  The trash never auto-expires; \`rm -rf\` it manually when you're sure.
 `)
         .action(async (target, options) => {
         const parsed = parseTarget(target);

package/dist/commands/refresh-rules.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Internal rules refresh command.
+ *
+ * Registers the hidden `agents refresh-rules` command invoked by shims for
+ * agents that do not natively resolve @-imports in their rules file.
+ * Recompiles only when source files have changed.
+ */
+import { Command } from 'commander';
+/**
+ * Hidden command invoked by shims for agents that don't natively resolve
+ * @-imports in their rules file. Fast-path check first (sha256 of tracked
+ * source files); only recompiles if a source has changed since the last
+ * sync. Typical cost: 10-20ms when rules are fresh.
+ */
+export declare function registerRefreshRulesCommand(program: Command): void;

package/dist/commands/{refresh-memory.js → refresh-rules.js}

@@ -1,26 +1,26 @@
 /**
- * Internal memory refresh command.
+ * Internal rules refresh command.
  *
- * Registers the hidden `agents refresh-memory` command invoked by
- * shims for agents that do not natively resolve @-imports in their
- * memory file. Recompiles memory only when source files have changed.
+ * Registers the hidden `agents refresh-rules` command invoked by shims for
+ * agents that do not natively resolve @-imports in their rules file.
+ * Recompiles only when source files have changed.
  */
 import chalk from 'chalk';
 import { AGENTS } from '../lib/agents.js';
 import { isVersionInstalled } from '../lib/versions.js';
-import { ensureMemoryFresh, supportsMemoryImports } from '../lib/memory-compile.js';
+import { ensureRulesFresh, supportsRulesImports } from '../lib/rules/compile.js';
 /**
  * Hidden command invoked by shims for agents that don't natively resolve
- * @-imports in their memory file. Fast-path check first (sha256 of tracked
+ * @-imports in their rules file. Fast-path check first (sha256 of tracked
  * source files); only recompiles if a source has changed since the last
- * sync. Typical cost: 10-20ms when memory is fresh.
+ * sync. Typical cost: 10-20ms when rules are fresh.
  */
-export function registerRefreshMemoryCommand(program) {
+export function registerRefreshRulesCommand(program) {
     program
-        .command('refresh-memory', { hidden: true })
-        .description('Internal: recompile memory for an agent if sources have changed. Called by shims.')
+        .command('refresh-rules', { hidden: true })
+        .description('Internal: recompile rules for an agent if sources have changed. Called by shims.')
         .requiredOption('--agent <agent>', 'Agent identifier (codex, opencode, cursor, etc.)')
-        .requiredOption('--agent-version <version>', 'Installed version whose memory file should be refreshed')
+        .requiredOption('--agent-version <version>', 'Installed version whose rules file should be refreshed')
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
         .action((opts) => {
         const agentId = opts.agent;
@@ -32,7 +32,7 @@ export function registerRefreshMemoryCommand(program) {
             process.exitCode = 1;
             return;
         }
-        if (supportsMemoryImports(agentId)) {
+        if (supportsRulesImports(agentId)) {
             // Nothing to do — agent resolves @-imports natively.
             return;
         }
@@ -43,9 +43,9 @@ export function registerRefreshMemoryCommand(program) {
             process.exitCode = 1;
             return;
         }
-        const recompiled = ensureMemoryFresh(agentId, version);
+        const recompiled = ensureRulesFresh(agentId, version);
         if (!quiet && recompiled) {
-            console.log(chalk.gray(`Refreshed memory for ${agentId}@${version}`));
+            console.log(chalk.gray(`Refreshed rules for ${agentId}@${version}`));
         }
     });
 }

package/dist/commands/routines.js

@@ -572,7 +572,7 @@ Examples:
         if (options.follow) {
             const { exec: execCb } = await import('child_process');
             const { getAgentsDir } = await import('../lib/state.js');
-            const logPath = path.join(getAgentsDir(), 'daemon.log');
+            const logPath = path.join(getAgentsDir(), 'helpers/daemon/logs.jsonl');
             const child = execCb(`tail -f "${logPath}"`);
             child.stdout?.pipe(process.stdout);
             child.stderr?.pipe(process.stderr);

package/dist/commands/rules.js

@@ -6,9 +6,11 @@ import * as path from 'path';
 import { select, checkbox } from '@inquirer/prompts';
 import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverInstructionsFromRepo, discoverMemoryFilesFromRepo, installInstructionsCentrally, uninstallInstructions, listInstalledInstructionsWithScope, instructionsExists, getInstructionsContent, listCentralMemory, } from '../lib/memory.js';
+import { discoverInstructionsFromRepo, discoverRuleFilesFromRepo, installInstructionsCentrally, uninstallInstructions, listInstalledInstructionsWithScope, instructionsExists, getInstructionsContent, listCentralRules, } from '../lib/rules/rules.js';
 import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, } from '../lib/versions.js';
-import { recordVersionResources } from '../lib/state.js';
+import { recordVersionResources, getActiveRulesPreset, setActiveRulesPreset } from '../lib/state.js';
+import { discoverRulesLayers } from '../lib/rules/compose.js';
+import * as yaml from 'yaml';
 import { isPromptCancelled, formatPath, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, requireDestructiveArg, } from './utils.js';
 /** Register the `agents rules` command tree (list, add, view, remove). */
 export function registerRulesCommands(program) {
@@ -205,7 +207,7 @@ Examples:
         try {
             let ruleNames;
             if (!source) {
-                const centralRules = listCentralMemory();
+                const centralRules = listCentralRules();
                 if (centralRules.length === 0) {
                     console.log(chalk.yellow('No rule files in ~/.agents/rules/'));
                     console.log(chalk.gray('\nTo add rule files from a repo:'));
@@ -271,7 +273,7 @@ Examples:
                     spinner.succeed('Using local path');
                 }
                 const agentInstructions = discoverInstructionsFromRepo(localPath);
-                const ruleFiles = discoverMemoryFilesFromRepo(localPath);
+                const ruleFiles = discoverRuleFilesFromRepo(localPath);
                 const totalFiles = agentInstructions.length + ruleFiles.length;
                 console.log(chalk.bold(`\nFound ${totalFiles} rule file(s):`));
                 if (totalFiles === 0) {
@@ -484,6 +486,100 @@ Examples:
             console.log(chalk.yellow(`No rule file found for ${agentLabel(agentId)}`));
         }
     });
+    rulesCmd
+        .command('switch <target>')
+        .description('Choose the active rule preset for an agent version (persists in agents.yaml)')
+        .option('-p, --preset <name>', 'Preset to activate; omit for an interactive picker')
+        .addHelpText('after', `
+Targets are <agent>@<version>. Use 'default' for the alias of the global default version.
+
+Examples:
+  # Persist the cautious preset for claude 2.1.111
+  agents rules switch claude@2.1.111 --preset cautious
+
+  # Reset back to the literal default preset
+  agents rules switch claude@default --preset default
+
+  # Pick interactively
+  agents rules switch codex@0.116.0
+`)
+        .action(async (target, options) => {
+        try {
+            const [rawAgent, rawVersion] = target.split('@');
+            const agentId = resolveAgentName(rawAgent);
+            if (!agentId) {
+                console.log(chalk.red(formatAgentError(rawAgent)));
+                process.exit(1);
+            }
+            const version = resolveVersionAlias(agentId, rawVersion);
+            if (!version) {
+                console.log(chalk.red(`Pass a version: ${agentId}@<version>. Try 'default' or 'agents list ${agentId}'.`));
+                process.exit(1);
+            }
+            const installed = listInstalledVersions(agentId);
+            if (!installed.includes(version)) {
+                console.log(chalk.red(`Version ${version} not installed for ${agentLabel(agentId)}.`));
+                console.log(chalk.gray(`Installed: ${installed.join(', ') || 'none'}`));
+                process.exit(1);
+            }
+            // Discover available presets across layers (highest-priority defines, lowers union in).
+            const layers = discoverRulesLayers();
+            const presetSet = new Set();
+            for (const layer of layers) {
+                const yamlPath = path.join(layer.rulesDir, 'rules.yaml');
+                if (!fs.existsSync(yamlPath))
+                    continue;
+                try {
+                    const parsed = yaml.parse(fs.readFileSync(yamlPath, 'utf-8'));
+                    for (const name of Object.keys(parsed?.presets || {}))
+                        presetSet.add(name);
+                }
+                catch { /* malformed yaml — skip */ }
+            }
+            const presets = Array.from(presetSet).sort();
+            if (presets.length === 0) {
+                console.log(chalk.red('No presets found. Define presets in ~/.agents-system/rules/rules.yaml or ~/.agents/rules/rules.yaml.'));
+                process.exit(1);
+            }
+            let chosen = options.preset;
+            if (chosen) {
+                if (!presets.includes(chosen)) {
+                    console.log(chalk.red(`Unknown preset: ${chosen}`));
+                    console.log(chalk.gray(`Available: ${presets.join(', ')}`));
+                    process.exit(1);
+                }
+            }
+            else {
+                if (!isInteractiveTerminal()) {
+                    requireInteractiveSelection('Selecting a rule preset', [
+                        `agents rules switch ${agentId}@${version} --preset default`,
+                        `agents rules switch ${agentId}@${version} --preset cautious`,
+                    ]);
+                }
+                const current = getActiveRulesPreset(agentId, version);
+                chosen = await select({
+                    message: `Active rule preset for ${agentLabel(agentId)}@${version}`,
+                    default: current,
+                    choices: presets.map((p) => ({ name: p === current ? `${p} (current)` : p, value: p })),
+                });
+            }
+            setActiveRulesPreset(agentId, version, chosen);
+            const spinner = ora(`Re-syncing ${agentLabel(agentId)}@${version} with preset '${chosen}'`).start();
+            const result = syncResourcesToVersion(agentId, version);
+            spinner.succeed(`Switched ${agentLabel(agentId)}@${version} to '${chosen}'`);
+            if (result.memory.length > 0) {
+                console.log(chalk.gray(`  Wrote ${result.memory[0]} from preset '${chosen}'.`));
+            }
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.gray('\nCancelled'));
+                return;
+            }
+            console.error(chalk.red(`Failed to switch preset: ${err.message}`));
+            process.exit(1);
+        }
+    });
     rulesCmd
         .command('show [agent]', { hidden: true })
         .action(async (agentArg) => {