@phnx-labs/agents-cli 0.1.0 → 1.14.1

package/dist/commands/hooks.js

@@ -3,13 +3,15 @@ import ora from 'ora';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { checkbox, confirm } from '@inquirer/prompts';
-import { AGENTS, HOOKS_CAPABLE_AGENTS, CODEX_HOOKS_MIN_VERSION, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { checkbox } from '@inquirer/prompts';
+import { AGENTS, HOOKS_CAPABLE_AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
+import { supports } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
-import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, removeHook, getHookInfo, parseHookManifest, diffVersionHooks, installHookToVersion, removeHookFromVersion, iterHooksCapableVersions, } from '../lib/hooks.js';
-import { listInstalledVersions, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, compareVersions, } from '../lib/versions.js';
+import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listInstalledHooksWithScope, removeHook, getHookInfo, parseHookManifest, } from '../lib/hooks.js';
+import { listInstalledVersions, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveAgentVersionTargets, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
+/** Register the `agents hooks` command tree (list, add, remove, sync, prune, view). */
 export function registerHooksCommands(program) {
     const hooksCmd = program.command('hooks')
         .description('Automate workflows by running shell scripts in response to agent events')
@@ -53,13 +55,13 @@ When to use:
         if (agentInput) {
             const parts = agentInput.split('@');
             const agentName = parts[0];
-            requestedVersion = parts[1] || null;
             agentId = resolveAgentName(agentName);
             if (!agentId) {
                 spinner.stop();
                 console.log(chalk.red(formatAgentError(agentName, [...HOOKS_CAPABLE_AGENTS])));
                 process.exit(1);
             }
+            requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
         }
         // Load hook manifest for event display
         const hookManifest = parseHookManifest();
@@ -79,14 +81,12 @@ When to use:
             const agent = AGENTS[agentId];
             const defaultLabel = isDefault ? ' default' : '';
             const versionStr = chalk.gray(` (${version}${defaultLabel})`);
-            if (!agent.supportsHooks) {
-                console.log(`  ${chalk.bold(agentLabel(agent.id))} (${version}${defaultLabel}): ${chalk.gray('hooks not supported')}`);
-                console.log();
-                return;
-            }
-            // Version gate for Codex hooks
-            if (agentId === 'codex' && compareVersions(version, CODEX_HOOKS_MIN_VERSION) < 0) {
-                console.log(`  ${chalk.bold(agentLabel(agentId))}${versionStr}: ${chalk.gray(`unsupported (codex@${version} < ${CODEX_HOOKS_MIN_VERSION})`)}`);
+            const gate = supports(agentId, 'hooks', version);
+            if (!gate.ok) {
+                const detail = gate.reason === 'unsupported'
+                    ? 'hooks not supported'
+                    : `unsupported (${agentId}@${version} requires ${gate.need})`;
+                console.log(`  ${chalk.bold(agentLabel(agent.id))}${versionStr}: ${chalk.gray(detail)}`);
                 console.log();
                 return;
             }
@@ -455,177 +455,26 @@ Examples:
             }
         }
     });
+    // `hooks sync` is gone — sync runs automatically when the agent launches.
     hooksCmd
-        .command('sync')
-        .description('Reconcile version-home hook scripts against central ~/.agents/hooks/ (add + update, never delete)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .addHelpText('after', `
-Examples:
-  # Sync every installed hooks-capable version
-  agents hooks sync
-
-  # Scope to one agent or version
-  agents hooks sync --agent claude
-  agents hooks sync --agent claude@2.1.113
-
-Sync reconciles the hook script files in each version home against the central
-source of truth in ~/.agents/hooks/. It does NOT touch settings.json
-registrations — those point at central paths and are managed on install.
-
-Sync is additive: to remove orphan scripts, use 'agents hooks prune'.
-`)
-        .action(async (options) => {
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, HOOKS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterHooksCapableVersions(filter);
-        if (pairs.length === 0) {
-            console.log(chalk.gray('No matching installed versions.'));
-            return;
-        }
-        const diffs = pairs.map(({ agent, version }) => diffVersionHooks(agent, version));
-        const plan = diffs.filter((d) => d.toAdd.length > 0 || d.toUpdate.length > 0);
-        if (plan.length === 0) {
-            console.log(chalk.green('All version homes are up to date with central.'));
-            if (diffs.some((d) => d.orphans.length > 0)) {
-                console.log(chalk.gray('Orphan hooks present. Run \'agents hooks prune --dry-run\' to review.'));
-            }
-            return;
-        }
-        console.log(chalk.bold('Syncing hooks\n'));
-        let adds = 0, updates = 0, failures = 0;
-        for (const diff of plan) {
-            const label = `${diff.agent}@${diff.version}`;
-            if (diff.toAdd.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('add:')} ${diff.toAdd.join(', ')}`);
-                for (const name of diff.toAdd) {
-                    const r = installHookToVersion(diff.agent, diff.version, name);
-                    if (r.success)
-                        adds++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-            if (diff.toUpdate.length > 0) {
-                console.log(`  ${chalk.cyan(label)} ${chalk.gray('update:')} ${diff.toUpdate.join(', ')}`);
-                for (const name of diff.toUpdate) {
-                    const r = installHookToVersion(diff.agent, diff.version, name);
-                    if (r.success)
-                        updates++;
-                    else {
-                        failures++;
-                        console.log(chalk.red(`    ! ${name}: ${r.error}`));
-                    }
-                }
-            }
-        }
-        console.log();
-        console.log(chalk.green(`Synced: ${adds} added, ${updates} updated${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
-        const totalOrphans = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        if (totalOrphans > 0) {
-            console.log(chalk.gray(`${totalOrphans} orphan(s) remain. Run 'agents hooks prune --dry-run' to review.`));
-        }
+        .command('sync', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents hooks sync" is gone.'));
+        console.error(chalk.gray('Sync runs automatically when you launch the agent.'));
+        console.error(chalk.gray('To remove orphans, use:  agents prune hooks'));
+        process.exit(1);
     });
+    // `hooks prune` moved to the top-level `agents prune` command.
     hooksCmd
-        .command('prune')
-        .description('Remove orphan hook scripts from version homes (scripts present locally but not in central)')
-        .option('-a, --agent <agent>', 'Scope to a specific agent or agent@version')
-        .option('--dry-run', 'Show orphans without deleting')
-        .option('-y, --yes', 'Skip confirmation prompt')
-        .addHelpText('after', `
-Examples:
-  # See what would be pruned
-  agents hooks prune --dry-run
-
-  # Prune across every installed version (prompts for confirmation)
-  agents hooks prune
-
-  # Scope to one agent or version
-  agents hooks prune --agent claude@2.1.80
-
-  # Skip confirmation (for scripts)
-  agents hooks prune -y
-
-Prune removes hook SCRIPT FILES from version homes. It does not edit
-settings.json registrations — those are keyed off central paths and remain
-consistent as long as central ~/.agents/hooks/ and ~/.agents/hooks.yaml are
-the source of truth.
-`)
-        .action(async (options) => {
-        let filter;
-        if (options.agent) {
-            const [name, version] = String(options.agent).split('@');
-            const agentId = resolveAgentName(name);
-            if (!agentId) {
-                console.log(chalk.red(formatAgentError(name, HOOKS_CAPABLE_AGENTS)));
-                process.exit(1);
-            }
-            filter = { agent: agentId, version: version || undefined };
-        }
-        const pairs = iterHooksCapableVersions(filter);
-        const diffs = pairs
-            .map(({ agent, version }) => diffVersionHooks(agent, version))
-            .filter((d) => d.orphans.length > 0);
-        if (diffs.length === 0) {
-            console.log(chalk.green('No orphan hooks.'));
-            return;
-        }
-        const total = diffs.reduce((n, d) => n + d.orphans.length, 0);
-        console.log(chalk.bold(`Orphans (in version home, not in central)\n`));
-        for (const d of diffs) {
-            console.log(`  ${chalk.cyan(`${d.agent}@${d.version}`)}  ${d.orphans.join(', ')}`);
-        }
-        console.log();
-        if (options.dryRun) {
-            console.log(chalk.gray(`${total} orphan(s). Run without --dry-run to delete.`));
-            return;
-        }
-        if (!options.yes) {
-            if (!isInteractiveTerminal()) {
-                console.log(chalk.yellow('Non-interactive shell: pass -y to confirm, or --dry-run to preview.'));
-                process.exit(1);
-            }
-            let ok = false;
-            try {
-                ok = await confirm({
-                    message: `Delete ${total} orphan hook${total === 1 ? '' : 's'}?`,
-                    default: false,
-                });
-            }
-            catch (err) {
-                if (isPromptCancelled(err)) {
-                    console.log(chalk.gray('Cancelled'));
-                    return;
-                }
-                throw err;
-            }
-            if (!ok) {
-                console.log(chalk.gray('Cancelled'));
-                return;
-            }
-        }
-        let removed = 0, failures = 0;
-        for (const d of diffs) {
-            for (const name of d.orphans) {
-                const r = removeHookFromVersion(d.agent, d.version, name);
-                if (r.success)
-                    removed++;
-                else {
-                    failures++;
-                    console.log(chalk.red(`  ! ${d.agent}@${d.version} ${name}: ${r.error}`));
-                }
-            }
-        }
-        console.log(chalk.green(`Pruned ${removed} orphan(s)${failures > 0 ? chalk.red(`, ${failures} failed`) : ''}.`));
+        .command('prune', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(chalk.red('"agents hooks prune" moved.'));
+        console.error(chalk.gray('Use:  agents prune hooks   (or `agents prune` for everything)'));
+        process.exit(1);
     });
     hooksCmd
         .command('view [name]')
@@ -686,4 +535,3 @@ Examples:
         }
     });
 }
-//# sourceMappingURL=hooks.js.map

package/dist/commands/init.d.ts

@@ -1,6 +1,20 @@
+/**
+ * First-run initialization command.
+ *
+ * Registers the `agents init` command which clones the system repo into
+ * ~/.agents-system/ and installs agent CLIs with resource syncing.
+ */
 import type { Command } from 'commander';
+/** First-run setup. Clones ~/.agents-system/ from the system repo if needed. */
 export declare function runInit(program: Command, options?: {
     force?: boolean;
 }): Promise<void>;
+/**
+ * Ensure the system repo exists before running a command that needs it.
+ * If ~/.agents-system/ is not a git repo AND we're in an interactive TTY,
+ * prompt the user to run init now. In non-interactive mode, print a clear
+ * error and exit.
+ */
+export declare function ensureInitialized(program: Command): Promise<void>;
+/** Register the `agents init` command. */
 export declare function registerInitCommand(program: Command): void;
-//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -1,115 +1,210 @@
+/**
+ * First-run initialization command.
+ *
+ * Registers the `agents init` command which clones the system repo into
+ * ~/.agents-system/ and installs agent CLIs with resource syncing.
+ */
 import chalk from 'chalk';
+import ora from 'ora';
 import * as fs from 'fs';
 import * as path from 'path';
-import { select, input } from '@inquirer/prompts';
+import * as os from 'os';
+import { confirm } from '@inquirer/prompts';
 import { DEFAULT_SYSTEM_REPO, systemRepoSlug } from '../lib/types.js';
-import { getAgentsDir } from '../lib/state.js';
-import { isGitRepo } from '../lib/git.js';
-import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-function isValidSourceInput(value) {
-    const trimmed = value.trim();
-    if (!trimmed)
-        return 'Repo is required';
-    // Accept gh:owner/repo, owner/repo, github.com/..., https://github.com/...
-    if (trimmed.startsWith('gh:') ||
-        trimmed.startsWith('github.com') ||
-        trimmed.startsWith('https://github.com/') ||
-        trimmed.startsWith('git@github.com:') ||
-        /^[a-zA-Z0-9_-]+\/[a-zA-Z0-9_.-]+$/.test(trimmed)) {
-        return true;
+import { getAgentsDir, getVersionsDir, ensureAgentsDir } from '../lib/state.js';
+import { isGitRepo, cloneIntoExisting, pullRepo } from '../lib/git.js';
+import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
+import { AGENTS, getUnmanagedAgentInstalls, countSessionFiles, agentLabel } from '../lib/agents.js';
+import { setGlobalDefault } from '../lib/versions.js';
+import { ensureShimCurrent, switchHomeFileSymlinks, isShimsInPath, addShimsToPath, getPathSetupInstructions } from '../lib/shims.js';
+const HOME = os.homedir();
+/**
+ * Import an existing unmanaged agent installation into agents-cli.
+ * Moves the config dir into the versions structure and creates a symlink.
+ */
+async function importAgent(agentId, version) {
+    const agent = AGENTS[agentId];
+    const configDir = agent.configDir;
+    const versionsDir = getVersionsDir();
+    const versionHome = path.join(versionsDir, agentId, version, 'home');
+    const versionConfigDir = path.join(versionHome, `.${agentId}`);
+    // Skip if version dir already exists (collision)
+    if (fs.existsSync(versionConfigDir)) {
+        return { success: false, skipped: true, error: `${version} already installed` };
+    }
+    try {
+        // Create version home directory
+        fs.mkdirSync(versionHome, { recursive: true });
+        // Move existing config dir into version home
+        fs.renameSync(configDir, versionConfigDir);
+        // Create symlink from original location to version config
+        fs.symlinkSync(versionConfigDir, configDir);
+        // Set as global default
+        setGlobalDefault(agentId, version);
+        // Handle home-level files (e.g. ~/.claude.json)
+        switchHomeFileSymlinks(agentId, version);
+        // Ensure shim exists
+        ensureShimCurrent(agentId);
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
     }
-    return 'Format: gh:owner/repo';
 }
+/** First-run setup. Clones ~/.agents-system/ from the system repo if needed. */
 export async function runInit(program, options = {}) {
     const agentsDir = getAgentsDir();
-    const metaFile = path.join(agentsDir, 'agents.yaml');
-    const alreadyConfigured = fs.existsSync(metaFile) || isGitRepo(agentsDir);
+    const alreadyConfigured = isGitRepo(agentsDir);
     if (alreadyConfigured && !options.force) {
-        console.log(chalk.yellow('~/.agents/ is already set up.'));
-        console.log(chalk.gray('\nTo sync updates:      agents pull'));
+        console.log(chalk.gray('~/.agents-system/ is already set up.'));
+        console.log(chalk.gray('\nTo sync updates:      agents repo pull system'));
         console.log(chalk.gray('To re-initialize:     agents init --force'));
         return;
     }
-    if (!isInteractiveTerminal()) {
-        console.error(chalk.red('agents init requires an interactive terminal.'));
-        console.error(chalk.gray('\nNon-interactive setup:'));
-        console.error(chalk.cyan(`  agents pull ${DEFAULT_SYSTEM_REPO}   # use the default config`));
-        console.error(chalk.cyan(`  agents pull gh:you/.agents           # use your own repo`));
-        process.exit(1);
+    // Detect existing installations BEFORE cloning (they won't exist after if we import)
+    const unmanaged = await getUnmanagedAgentInstalls();
+    const sessionCounts = {};
+    for (const install of unmanaged) {
+        sessionCounts[install.agentId] = countSessionFiles(install.agentId);
     }
     console.log(chalk.bold('\nWelcome to agents-cli.'));
-    console.log(chalk.gray('Let\'s pick where your agent config comes from.\n'));
-    const choice = await select({
-        message: "Where's your config?",
-        choices: [
-            {
-                name: `Use default  (${systemRepoSlug(DEFAULT_SYSTEM_REPO)})`,
-                value: 'default',
-                description: 'Clones the curated config. Push later with `agents fork`.',
-            },
-            {
-                name: 'Pull mine    (from GitHub)',
-                value: 'mine',
-                description: 'Use an existing .agents repo you own.',
-            },
-        ],
-    });
-    let source;
-    if (choice === 'default') {
-        source = DEFAULT_SYSTEM_REPO;
+    console.log(chalk.gray(`Cloning the system repo from ${systemRepoSlug(DEFAULT_SYSTEM_REPO)} into ~/.agents-system/.\n`));
+    ensureAgentsDir();
+    const spinner = ora('Cloning system repo...').start();
+    if (isGitRepo(agentsDir)) {
+        // --force on an existing repo: pull instead of re-clone
+        const result = await pullRepo(agentsDir);
+        if (!result.success) {
+            spinner.fail(`Pull failed: ${result.error}`);
+            console.log(chalk.gray('Fix the issue and re-run: agents init --force'));
+            process.exit(1);
+        }
+        spinner.succeed(`Updated to ${result.commit}`);
     }
     else {
-        const answer = await input({
-            message: 'Your repo (e.g. gh:you/.agents):',
-            validate: isValidSourceInput,
-        });
-        source = answer.trim();
+        const result = await cloneIntoExisting(DEFAULT_SYSTEM_REPO, agentsDir);
+        if (!result.success) {
+            spinner.fail(`Clone failed: ${result.error}`);
+            console.log(chalk.gray('Fix the issue and re-run: agents init --force'));
+            process.exit(1);
+        }
+        spinner.succeed(`Cloned ${systemRepoSlug(DEFAULT_SYSTEM_REPO)} (${result.commit})`);
     }
-    console.log();
-    await program.parseAsync(['node', 'agents', 'pull', source]);
-    // `agents pull` prints its own error but doesn't throw — verify the clone actually
-    // landed before claiming success. Without this check the wizard would celebrate even
-    // when pull failed (e.g. empty repo, bad ref, network error).
-    if (!isGitRepo(agentsDir)) {
-        console.log(chalk.red('\nSetup did not complete — see errors above.'));
-        console.log(chalk.gray('Fix the issue and re-run: agents init --force'));
-        process.exit(1);
+    // Offer to import existing unmanaged installations
+    if (unmanaged.length > 0 && isInteractiveTerminal()) {
+        console.log(chalk.bold('\nFound existing installations:\n'));
+        const maxAgentLen = Math.max(...unmanaged.map(i => agentLabel(i.agentId).length));
+        for (const install of unmanaged) {
+            const label = agentLabel(install.agentId).padEnd(maxAgentLen);
+            const sessions = sessionCounts[install.agentId] || 0;
+            const sessionStr = sessions > 0 ? `${sessions} sessions` : 'no sessions';
+            const versionStr = install.version ? `v${install.version}` : '';
+            console.log(`  ${chalk.cyan(label)}  ${install.configDir}  ${chalk.gray(sessionStr)}  ${chalk.gray(versionStr)}`);
+        }
+        console.log();
+        const shouldImport = await confirm({
+            message: 'Import these under agents-cli management?',
+            default: true,
+        });
+        if (shouldImport) {
+            console.log();
+            for (const install of unmanaged) {
+                const version = install.version || 'unknown';
+                const spinner = ora(`Importing ${agentLabel(install.agentId)} v${version}...`).start();
+                const result = await importAgent(install.agentId, version);
+                if (result.success) {
+                    spinner.succeed(`${agentLabel(install.agentId)} imported`);
+                }
+                else if (result.skipped) {
+                    spinner.warn(`${agentLabel(install.agentId)}: ${result.error} (skipped)`);
+                }
+                else {
+                    spinner.fail(`${agentLabel(install.agentId)}: ${result.error}`);
+                }
+            }
+            // Ensure shims are in PATH
+            if (!isShimsInPath()) {
+                const pathResult = addShimsToPath();
+                if (pathResult.success && !pathResult.alreadyPresent) {
+                    console.log(chalk.green(`\nAdded shims to ~/${pathResult.rcFile}`));
+                    console.log(chalk.gray('Restart your shell or run: source ~/' + pathResult.rcFile));
+                }
+                else if (!pathResult.success) {
+                    console.log(chalk.yellow('\nTo enable version switching, add shims to PATH:'));
+                    console.log(chalk.gray(getPathSetupInstructions()));
+                }
+            }
+            // Show total session count
+            const totalSessions = Object.values(sessionCounts).reduce((a, b) => a + (b || 0), 0);
+            if (totalSessions > 0) {
+                const breakdown = unmanaged
+                    .filter(i => (sessionCounts[i.agentId] || 0) > 0)
+                    .map(i => `${agentLabel(i.agentId)} (${sessionCounts[i.agentId] || 0})`)
+                    .join(', ');
+                console.log(chalk.gray(`\n${totalSessions} sessions available across ${breakdown}`));
+                console.log(chalk.cyan('  agents sessions') + chalk.gray('  # browse them'));
+            }
+        }
     }
     console.log(chalk.bold('\nSetup complete. Try:'));
     console.log(chalk.cyan('  agents view                 ') + chalk.gray(' # see what\'s installed'));
     console.log(chalk.cyan('  agents run <agent> "hello"  ') + chalk.gray(' # run an agent'));
-    if (choice === 'default') {
-        console.log(chalk.gray('\nWhen you want to save your own changes, run:'));
-        console.log(chalk.cyan('  agents fork'));
+    console.log(chalk.gray('\nWhen you want your own editable repo, scaffold one with:'));
+    console.log(chalk.cyan('  agents repo init'));
+}
+/**
+ * Ensure the system repo exists before running a command that needs it.
+ * If ~/.agents-system/ is not a git repo AND we're in an interactive TTY,
+ * prompt the user to run init now. In non-interactive mode, print a clear
+ * error and exit.
+ */
+export async function ensureInitialized(program) {
+    const agentsDir = getAgentsDir();
+    if (isGitRepo(agentsDir))
+        return;
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('agents-cli is not initialized. Run: agents init'));
+        process.exit(1);
+    }
+    console.log(chalk.yellow('\nagents-cli has not been set up yet.'));
+    const proceed = await confirm({
+        message: 'Run `agents init` now?',
+        default: true,
+    }).catch(() => false);
+    if (!proceed) {
+        console.log(chalk.gray('Skipped. Run `agents init` when ready.'));
+        process.exit(0);
     }
+    await runInit(program);
+    process.exit(0);
 }
+/** Register the `agents init` command. */
 export function registerInitCommand(program) {
     program
         .command('init')
         .description('Set up agents-cli for the first time. Clones a config repo and installs agent CLIs.')
-        .option('-f, --force', 'Reinitialize even if ~/.agents/ already exists (use with caution)')
+        .option('-f, --force', 'Reinitialize even if ~/.agents-system/ already exists (use with caution)')
         .addHelpText('after', `
 Examples:
-  # Interactive setup (asks where to pull config from)
+  # First-time setup (clones the system repo into ~/.agents-system/)
   agents init
 
-  # Re-initialize after corruption or to switch config sources
+  # Re-initialize after corruption
   agents init --force
 
 When to use:
   - First time running agents-cli: this is your starting point
-  - Onboarding a new machine: sync your existing setup from GitHub
-  - Switching to a different config repo
+  - Onboarding a new machine: restore the system repo and installed CLIs
+  - Repairing ~/.agents-system/ after accidental deletion or corruption
 
 What it does:
-  1. Asks if you want the default config or your own GitHub repo
-  2. Clones the chosen repo into ~/.agents/
-  3. Installs agent CLIs based on agents.yaml in the repo
-  4. Syncs commands, skills, hooks, and MCP servers to each version
+  1. Clones the system repo into ~/.agents-system/
+  2. Installs agent CLIs based on agents.yaml in that repo
+  3. Syncs commands, skills, hooks, and MCP servers to each version
 
 Non-interactive alternative:
-  If you're scripting or know your repo already, skip 'init' and use 'agents pull' directly:
-    agents pull gh:yourname/.agents
+  Skip 'init' and run:
+    agents pull
 `)
         .action(async (options) => {
         try {
@@ -124,4 +219,3 @@ Non-interactive alternative:
         }
     });
 }
-//# sourceMappingURL=init.js.map

package/dist/commands/mcp.d.ts

@@ -1,3 +1,11 @@
+/**
+ * MCP (Model Context Protocol) server management commands.
+ *
+ * Implements `agents mcp` -- list, add, remove, view, and register MCP
+ * servers that give agents runtime access to databases, APIs, and external
+ * services. Servers are declared in ~/.agents/mcp/ YAML files or the
+ * agents.yaml manifest, then registered into each agent version's config.
+ */
 import type { Command } from 'commander';
+/** Register the `agents mcp` command tree (list, add, remove, view, register). */
 export declare function registerMcpCommands(program: Command): void;
-//# sourceMappingURL=mcp.d.ts.map

package/dist/commands/mcp.js

@@ -5,10 +5,11 @@ import { AGENTS, MCP_CAPABLE_AGENTS, getAllCliStates, resolveAgentName, formatAg
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
 import { listMcpServerConfigs } from '../lib/mcp.js';
 import { getMcpDir } from '../lib/state.js';
-import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, } from '../lib/versions.js';
+import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHomePath, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, resolveVersionAlias, } from '../lib/versions.js';
 import { getAgentsDir } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
+/** Parse a comma-separated --agents string into validated agent IDs and optional version targets. */
 function parseMcpAgentTargets(value) {
     const agents = [];
     const agentVersions = {};
@@ -49,12 +50,15 @@ function parseMcpAgentTargets(value) {
         if (installedVersions.length === 0) {
             throw new Error(`No managed versions are installed for ${AGENTS[agentId].name}. Run: agents add ${agentId}@latest`);
         }
-        if (!installedVersions.includes(versionToken)) {
-            throw new Error(`Version ${versionToken} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installedVersions.join(', ')}`);
+        const resolvedVersion = versionToken === 'latest'
+            ? installedVersions[installedVersions.length - 1]
+            : versionToken;
+        if (!installedVersions.includes(resolvedVersion)) {
+            throw new Error(`Version ${resolvedVersion} is not installed for ${AGENTS[agentId].name}. Installed versions: ${installedVersions.join(', ')}`);
         }
         const versions = agentVersions[agentId] || [];
-        if (!versions.includes(versionToken)) {
-            versions.push(versionToken);
+        if (!versions.includes(resolvedVersion)) {
+            versions.push(resolvedVersion);
             agentVersions[agentId] = versions;
         }
     }
@@ -66,6 +70,7 @@ function parseMcpAgentTargets(value) {
 function formatTargetLabel(agentId, version) {
     return version ? `${agentLabel(agentId)}@${version}` : agentLabel(agentId);
 }
+/** Register the `agents mcp` command tree (list, add, remove, view, register). */
 export function registerMcpCommands(program) {
     const mcpCmd = program
         .command('mcp')
@@ -112,7 +117,7 @@ When to use:
                 process.exit(1);
             }
             filterAgent = resolved;
-            filterVersion = parts[1] || undefined;
+            filterVersion = resolveVersionAlias(resolved, parts[1]);
         }
         const rows = buildMcpRows({ filterAgent, filterVersion });
         spinner.stop();
@@ -578,4 +583,3 @@ function truncateString(s, max) {
         return s;
     return s.slice(0, max - 1) + '…';
 }
-//# sourceMappingURL=mcp.js.map

package/dist/commands/models.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Model catalog inspection command.
+ *
+ * Registers the hidden `agents models` command for listing models
+ * supported by installed agent versions. Extracts model catalogs from
+ * each agent's CLI bundle and displays IDs, aliases, and metadata.
+ */
 import type { Command } from 'commander';
+/** Register the hidden `agents models` command. */
 export declare function registerModelsCommand(program: Command): void;
-//# sourceMappingURL=models.d.ts.map