@phnx-labs/agents-cli 1.12.0 → 1.14.1

package/dist/commands/prune.js

@@ -0,0 +1,191 @@
+import chalk from 'chalk';
+import { confirm } from '@inquirer/prompts';
+import { diffVersionCommands, iterCommandsCapableVersions, removeCommandFromVersion, } from '../lib/commands.js';
+import { diffVersionSkills, iterSkillsCapableVersions, removeSkillFromVersion, } from '../lib/skills.js';
+import { diffVersionHooks, iterHooksCapableVersions, removeHookFromVersion, } from '../lib/hooks.js';
+import { getGlobalDefault } from '../lib/versions.js';
+import { resolveAgentName, formatAgentError } from '../lib/agents.js';
+import { pruneDuplicates } from './view.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+const RESOURCE_TYPES = ['commands', 'skills', 'hooks'];
+const ALL_TYPES = [...RESOURCE_TYPES, 'versions'];
+function scopePairs(pairs, all) {
+    if (all)
+        return pairs;
+    return pairs.filter((p) => p.version === getGlobalDefault(p.agent));
+}
+function collectOrphans(types, all) {
+    const groups = [];
+    if (types.includes('commands')) {
+        for (const { agent, version } of scopePairs(iterCommandsCapableVersions(), all)) {
+            const diff = diffVersionCommands(agent, version);
+            if (diff.orphans.length > 0) {
+                groups.push({ type: 'commands', agent, version, orphans: diff.orphans });
+            }
+        }
+    }
+    if (types.includes('skills')) {
+        for (const { agent, version } of scopePairs(iterSkillsCapableVersions(), all)) {
+            const diff = diffVersionSkills(agent, version);
+            if (diff.orphans.length > 0) {
+                groups.push({ type: 'skills', agent, version, orphans: diff.orphans });
+            }
+        }
+    }
+    if (types.includes('hooks')) {
+        for (const { agent, version } of scopePairs(iterHooksCapableVersions(), all)) {
+            const diff = diffVersionHooks(agent, version);
+            if (diff.orphans.length > 0) {
+                groups.push({ type: 'hooks', agent, version, orphans: diff.orphans });
+            }
+        }
+    }
+    return groups;
+}
+function removeOne(group, name) {
+    switch (group.type) {
+        case 'commands':
+            return removeCommandFromVersion(group.agent, group.version, name);
+        case 'skills':
+            return removeSkillFromVersion(group.agent, group.version, name);
+        case 'hooks':
+            return removeHookFromVersion(group.agent, group.version, name);
+    }
+}
+function parseTarget(arg) {
+    if (!arg) {
+        return { resourceTypes: RESOURCE_TYPES, includeVersions: true };
+    }
+    if (RESOURCE_TYPES.includes(arg)) {
+        return { resourceTypes: [arg], includeVersions: false };
+    }
+    if (arg === 'versions') {
+        return { resourceTypes: [], includeVersions: true };
+    }
+    // Try treating as an agent name — shortcut for `prune versions <agent>`.
+    const agentId = resolveAgentName(arg);
+    if (agentId) {
+        return { resourceTypes: [], includeVersions: true, versionAgent: agentId };
+    }
+    console.log(chalk.red(`Unknown prune target: ${arg}`));
+    console.log(chalk.gray(`Available types: ${ALL_TYPES.join(', ')}`));
+    console.log(chalk.gray(formatAgentError(arg)));
+    process.exit(1);
+}
+async function runOrphanPrune(resourceTypes, options) {
+    const groups = collectOrphans(resourceTypes, options.all === true);
+    if (groups.length === 0) {
+        console.log(chalk.green('No orphans.'));
+        return;
+    }
+    const total = groups.reduce((n, g) => n + g.orphans.length, 0);
+    console.log(chalk.bold('Orphans (in version home, not in any source)\n'));
+    for (const g of groups) {
+        const label = `${g.type} · ${g.agent}@${g.version}`;
+        console.log(`  ${chalk.cyan(label)}  ${g.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${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;
+    let failures = 0;
+    for (const g of groups) {
+        for (const name of g.orphans) {
+            const r = removeOne(g, name);
+            if (r.success) {
+                removed++;
+            }
+            else {
+                failures++;
+                console.log(chalk.red(`  ! ${g.type} ${g.agent}@${g.version} ${name}: ${r.error}`));
+            }
+        }
+    }
+    const summary = `Pruned ${removed} orphan${removed === 1 ? '' : 's'}`;
+    console.log(chalk.green(summary) + (failures > 0 ? chalk.red(`, ${failures} failed`) : '') + '.');
+}
+export function registerPruneCommand(program) {
+    program
+        .command('prune [target]')
+        .description('Remove orphan resources (commands/skills/hooks) and/or older duplicate version installs')
+        .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')
+        .addHelpText('after', `
+Targets:
+  (none)     Orphans across commands, skills, hooks + duplicate versions
+  commands   Orphan command files only
+  skills     Orphan skill directories only
+  hooks      Orphan hook scripts only
+  versions   Older duplicate version installs only
+  <agent>    Older duplicate versions for one agent (e.g. 'claude')
+
+Examples:
+  # Full sweep: orphan resources + duplicate versions for current defaults
+  agents prune
+
+  # Just orphan skills
+  agents prune skills
+
+  # Just version dedup
+  agents prune versions
+
+  # Just version dedup for one agent
+  agents prune claude
+
+  # Sweep every installed version's orphans, not only the defaults
+  agents prune --all
+
+  # Preview without deleting
+  agents prune --dry-run
+
+What's an orphan?
+  A command, skill, or hook present inside a version home but missing from every
+  configured source (project .agents/, central ~/.agents/, and any enabled extra
+  repos). Usually leftovers from a resource that was deleted or moved but never
+  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.
+`)
+        .action(async (target, options) => {
+        const parsed = parseTarget(target);
+        if (parsed.resourceTypes.length > 0) {
+            await runOrphanPrune(parsed.resourceTypes, options);
+            if (parsed.includeVersions)
+                console.log();
+        }
+        if (parsed.includeVersions) {
+            const versionLabel = parsed.versionAgent ? ` for ${parsed.versionAgent}` : '';
+            console.log(chalk.bold(`Duplicate versions${versionLabel}`));
+            await pruneDuplicates(parsed.versionAgent, options.yes === true, options.dryRun === true);
+        }
+    });
+}

package/dist/commands/pty.d.ts

@@ -16,5 +16,5 @@
  *   agents pty server [start|stop|status]
  */
 import type { Command } from 'commander';
+/** Register the `agents pty` command tree. */
 export declare function registerPtyCommands(program: Command): void;
-//# sourceMappingURL=pty.d.ts.map

package/dist/commands/pty.js

@@ -19,6 +19,7 @@ import chalk from 'chalk';
 import { ptyRequest, unescapeInput } from '../lib/pty-client.js';
 import { isPtyServerRunning, runPtyServer, getPtyPidPath, getPtyLogPath } from '../lib/pty-server.js';
 import * as fs from 'fs';
+/** Register the `agents pty` command tree. */
 export function registerPtyCommands(program) {
     const pty = program
         .command('pty')
@@ -376,6 +377,7 @@ Example:
         await runPtyServer();
     });
 }
+/** Format a millisecond duration as a compact human-readable string (e.g. "5m", "2h 30m"). */
 function formatAge(ms) {
     const secs = Math.floor(ms / 1000);
     if (secs < 60)
@@ -386,4 +388,3 @@ function formatAge(ms) {
     const hours = Math.floor(mins / 60);
     return `${hours}h ${mins % 60}m`;
 }
-//# sourceMappingURL=pty.js.map

package/dist/commands/pull.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Config pull command.
+ *
+ * Registers the `agents pull` command which clones or updates the
+ * system ~/.agents-system/ git repo and syncs CLI versions, MCP servers,
+ * resources, and hooks to installed agent versions.
+ */
 import type { Command } from 'commander';
+/** Register the `agents pull` command. */
 export declare function registerPullCommand(program: Command): void;
-//# sourceMappingURL=pull.d.ts.map

package/dist/commands/pull.js

@@ -1,10 +1,16 @@
+/**
+ * Config pull command.
+ *
+ * Registers the `agents pull` command which clones or updates the
+ * system ~/.agents-system/ git repo and syncs CLI versions, MCP servers,
+ * resources, and hooks to installed agent versions.
+ */
 import chalk from 'chalk';
 import ora from 'ora';
-import { AGENTS, ALL_AGENT_IDS, MCP_CAPABLE_AGENTS, getAllCliStates, registerMcpToTargets, isAgentName, resolveAgentName, agentLabel, } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, HOOKS_CAPABLE_AGENTS, MCP_CAPABLE_AGENTS, getAllCliStates, registerMcpToTargets, isAgentName, resolveAgentName, agentLabel, } from '../lib/agents.js';
 import { readManifest, MANIFEST_FILENAME, } from '../lib/manifest.js';
-import { getAgentsDir, ensureAgentsDir, readMeta, updateMeta, } from '../lib/state.js';
-import { DEFAULT_SYSTEM_REPO, LEGACY_SYSTEM_REPO, systemRepoSlug } from '../lib/types.js';
-import { isGitRepo, cloneIntoExisting, pullRepo, pullFromUpstream, parseSource, getGitHubUsername, checkGitHubRepoExists, hasUpstreamRemote, getUpstreamUrl, } from '../lib/git.js';
+import { getUserAgentsDir, ensureAgentsDir, getEnabledExtraRepos, } from '../lib/state.js';
+import { isGitRepo, pullRepo, isSystemRepoOrigin, } from '../lib/git.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { installVersion, listInstalledVersions, getGlobalDefault, setGlobalDefault, getVersionHomePath, syncResourcesToVersion, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, promptResourceSelection, resolveConfiguredAgentTargets, } from '../lib/versions.js';
@@ -12,24 +18,43 @@ import { ensureShimCurrent, isShimsInPath, addShimsToPath, getPathSetupInstructi
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks.js';
 import { select } from '@inquirer/prompts';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/**
+ * Old repo layout stored promptcuts under claude/promptcuts.yaml (agent-scoped).
+ * The new layout is ~/.agents-system/promptcuts.yaml at the repo root — the hook
+ * reads from a fixed path so it survives version upgrades. If the root file
+ * doesn't exist yet but an agent-scoped one does, hoist the first one found.
+ */
+function migratePromptcutsToRoot(agentsDir) {
+    const rootPath = path.join(agentsDir, 'promptcuts.yaml');
+    if (fs.existsSync(rootPath))
+        return;
+    const agentDirs = ['claude', 'codex', 'cursor', 'gemini', 'opencode'];
+    for (const dir of agentDirs) {
+        const legacyPath = path.join(agentsDir, dir, 'promptcuts.yaml');
+        if (fs.existsSync(legacyPath)) {
+            try {
+                fs.renameSync(legacyPath, rootPath);
+                console.log(chalk.gray(`Moved ${dir}/promptcuts.yaml → promptcuts.yaml (repo root)`));
+                return;
+            }
+            catch {
+                // Best-effort migration; hook still works if the user moves it manually.
+            }
+        }
+    }
+}
+/** Register the `agents pull` command. */
 export function registerPullCommand(program) {
     program
-        .command('pull [source] [agent]')
-        .description('Sync your config from a git repo. Clones on first run, pulls updates thereafter.')
+        .command('pull [agent]')
+        .description('Pull your user repo at ~/.agents/ and refresh installed agent versions.')
         .option('-y, --yes', 'Auto-sync all resources without prompting')
         .option('--skip-clis', 'Pull config changes but do not install or upgrade agent CLIs')
-        .option('--upstream', 'Pull from the upstream remote instead of origin (for forked repos)')
         .addHelpText('after', `
 Examples:
-  # First time: clone from your repo (also works if ~/.agents/ is empty)
-  agents pull gh:yourname/.agents
-
-  # Update your config from origin (GitHub)
+  # First time: clone the system repo into ~/.agents-system/
   agents pull
 
-  # Pull updates from the upstream default repo (after you've forked)
-  agents pull --upstream
-
   # Sync only one agent's config
   agents pull claude
 
@@ -37,9 +62,8 @@ Examples:
   agents pull -y
 
 When to use:
-  - Initial setup: clone your config repo to a new machine
-  - Daily sync: pull changes you or teammates pushed to the repo
-  - Upstream updates: get new skills, commands, or MCP servers from the default repo
+  - Initial setup: clone the system repo to a new machine
+  - Daily sync: pull the latest system skills, commands, or MCP servers
   - Per-agent: sync just one agent's config without touching others
 
 What it syncs:
@@ -51,102 +75,44 @@ What it syncs:
 
 Skip CLI installs with --skip-clis when you only want config updates, not version changes.
 `)
-        .action(async (arg1, arg2, options) => {
+        .action(async (arg1, options) => {
+        // Deprecation banner — `agents pull` is on its way out. agents-cli now
+        // auto-syncs the system repo in the background and surfaces upstream
+        // changes for user/extra repos as one-line notices. Repo lifecycle is
+        // managed under `agents repo`. We keep this command functional today
+        // because `agents init` still invokes it for first-time setup; once
+        // init is refactored to call the bootstrap helpers directly, this
+        // command will hard-error like `agents memory` does.
+        if (!options.yes && process.argv[2] === 'pull') {
+            process.stderr.write('agents-cli: "agents pull" is deprecated.\n' +
+                '            First-time setup:  agents init\n' +
+                '            Force a sync now:  agents repo pull\n' +
+                '            Push your repo:    agents repo push\n\n');
+        }
         const skipPrompts = options.yes || !isInteractiveTerminal();
-        // Parse source and agent filter from positional args
-        let targetSource;
         let agentFilter;
         if (arg1) {
             if (isAgentName(arg1)) {
-                // agents pull claude
                 agentFilter = resolveAgentName(arg1);
             }
             else {
-                // agents pull gh:user/repo [agent]
-                targetSource = arg1;
-                if (arg2 && isAgentName(arg2)) {
-                    agentFilter = resolveAgentName(arg2);
-                }
-            }
-        }
-        const agentsDir = getAgentsDir();
-        ensureAgentsDir();
-        // Handle --upstream: pull from upstream remote
-        if (options.upstream) {
-            if (!isGitRepo(agentsDir)) {
-                console.log(chalk.red('~/.agents/ is not a git repository.'));
-                console.log(chalk.gray('\nInitialize first: agents pull'));
-                return;
-            }
-            if (!await hasUpstreamRemote(agentsDir)) {
-                console.log(chalk.red('No upstream remote configured.'));
-                console.log(chalk.gray('\nIf you forked from the system repo, run: agents fork'));
-                console.log(chalk.gray('This will set up the upstream remote automatically.'));
-                return;
-            }
-            // Migration nudge: one-time notice if upstream still points at the legacy personal repo.
-            const legacySlug = systemRepoSlug(LEGACY_SYSTEM_REPO).toLowerCase();
-            const currentSlug = systemRepoSlug(DEFAULT_SYSTEM_REPO);
-            const nudgeMarker = path.join(agentsDir, '.migration-nudge-shown');
-            const upstreamUrl = await getUpstreamUrl(agentsDir);
-            if (upstreamUrl && upstreamUrl.toLowerCase().includes(legacySlug) && !fs.existsSync(nudgeMarker)) {
-                console.log(chalk.yellow(`\nYour upstream points at a personal repo (${legacySlug}).`));
-                console.log(chalk.yellow(`The curated upstream is now ${currentSlug}.`));
-                console.log(chalk.gray('To switch:'));
-                console.log(chalk.cyan(`  cd ~/.agents && git remote set-url upstream git@github.com:${currentSlug}.git\n`));
-                try {
-                    fs.writeFileSync(nudgeMarker, new Date().toISOString() + '\n');
-                }
-                catch { /* best-effort */ }
-            }
-            const spinner = ora('Pulling from upstream...').start();
-            const result = await pullFromUpstream(agentsDir);
-            if (!result.success) {
-                spinner.fail(`Failed: ${result.error}`);
+                console.log(chalk.red(`Invalid agent: ${arg1}`));
+                console.log(chalk.gray(`Available: ${ALL_AGENT_IDS.join(', ')}`));
                 return;
             }
-            spinner.succeed(`Merged upstream changes (${result.commit})`);
-            // Continue with the rest of the sync (CLI versions, MCP, resources)
-            // Skip the source determination since we already pulled
-            targetSource = 'existing';
-        }
-        // Determine source
-        const meta = readMeta();
-        if (!targetSource) {
-            // Check if ~/.agents/ is already a git repo
-            if (isGitRepo(agentsDir)) {
-                targetSource = 'existing';
-            }
-            else {
-                // Try to infer from GitHub username
-                const spinner = ora('Checking GitHub...').start();
-                const username = await getGitHubUsername();
-                if (username) {
-                    const repoExists = await checkGitHubRepoExists(username, '.agents');
-                    if (repoExists) {
-                        targetSource = `gh:${username}/.agents`;
-                        spinner.succeed(`Found ${username}/.agents`);
-                    }
-                    else {
-                        spinner.info(`No .agents repo found for ${username}`);
-                        console.log(chalk.gray('\nTo create one:'));
-                        console.log(chalk.cyan('  gh repo create .agents --public'));
-                        console.log(chalk.gray('\nThen run: agents pull'));
-                        return;
-                    }
-                }
-                else {
-                    // Fall back to system default repo
-                    targetSource = DEFAULT_SYSTEM_REPO;
-                    spinner.info(`Using default: ${DEFAULT_SYSTEM_REPO}`);
-                }
-            }
         }
+        const agentsDir = getUserAgentsDir();
+        ensureAgentsDir();
         const spinner = ora('Syncing...').start();
         try {
-            let commit;
-            if (targetSource === 'existing') {
-                // Just pull updates
+            let commit = '';
+            if (isGitRepo(agentsDir)) {
+                // Don't pull if the remote is the system repo — that's a misconfiguration
+                if (await isSystemRepoOrigin(agentsDir)) {
+                    spinner.fail('~/.agents/ is pointing at the system repo. Use a personal repo instead.');
+                    console.log(chalk.gray('\nCreate your own repo: agents repo init'));
+                    return;
+                }
                 spinner.text = 'Pulling updates...';
                 const result = await pullRepo(agentsDir);
                 if (!result.success) {
@@ -157,35 +123,29 @@ Skip CLI installs with --skip-clis when you only want config updates, not versio
                 spinner.succeed(`Updated to ${commit}`);
             }
             else {
-                // Clone or update
-                const parsed = parseSource(targetSource);
-                if (isGitRepo(agentsDir)) {
-                    // Already a repo, just pull
-                    spinner.text = 'Pulling updates...';
-                    const result = await pullRepo(agentsDir);
-                    if (!result.success) {
-                        spinner.fail(`Pull failed: ${result.error}`);
-                        return;
+                // ~/.agents/ is not a git repo yet — skip git pull, proceed with local resource sync
+                spinner.succeed('Using local ~/.agents/ (no remote configured)');
+            }
+            // Pull extra DotAgent repos before resource sync so any new skills /
+            // commands they ship land in the version homes on this same run.
+            const extraRepos = getEnabledExtraRepos();
+            if (extraRepos.length > 0) {
+                console.log(chalk.bold(`\nExtra repos (${extraRepos.length}):\n`));
+                for (const { alias, dir } of extraRepos) {
+                    const extraSpinner = ora(`Pulling ${alias}...`).start();
+                    const result = await pullRepo(dir);
+                    if (result.success) {
+                        extraSpinner.succeed(`${alias} -> ${result.commit}`);
                     }
-                    commit = result.commit;
-                    spinner.succeed(`Updated to ${commit}`);
-                }
-                else {
-                    // Clone into existing ~/.agents/
-                    spinner.text = `Cloning ${targetSource}...`;
-                    const result = await cloneIntoExisting(targetSource, agentsDir);
-                    if (!result.success) {
-                        spinner.fail(`Clone failed: ${result.error}`);
-                        return;
+                    else {
+                        extraSpinner.warn(`${alias}: ${result.error}`);
                     }
-                    commit = result.commit;
-                    spinner.succeed(`Initialized from ${targetSource}`);
                 }
-                // Save source to meta
-                updateMeta({
-                    source: parsed.url,
-                });
             }
+            // One-time migration: promptcuts.yaml moved from agent-scoped
+            // (e.g. claude/promptcuts.yaml) to repo root. We move it so the
+            // hook at ~/.agents-system/hooks/ can always find it at a fixed path.
+            migratePromptcutsToRoot(agentsDir);
             // Read manifest for CLI versions and MCP config
             const manifest = readManifest(agentsDir);
             if (!manifest) {
@@ -318,12 +278,17 @@ Skip CLI installs with --skip-clis when you only want config updates, not versio
                     }
                 }
             }
-            // Register hooks as lifecycle events in settings.json
+            // Register hooks as lifecycle events in each agent's config file.
+            // Claude/codex/gemini all support prompt-time hooks, though only
+            // claude can replace the prompt — codex/gemini append via
+            // additionalContext. The hook script detects the caller and emits
+            // the correct protocol.
             const hookManifest = parseHookManifest();
             if (Object.keys(hookManifest).length > 0) {
                 let hookRegistered = 0;
+                const hookAgents = new Set(HOOKS_CAPABLE_AGENTS);
                 for (const agentId of agentsToSync) {
-                    if (agentId !== 'claude')
+                    if (!hookAgents.has(agentId))
                         continue;
                     const versions = listInstalledVersions(agentId);
                     const defaultVer = getGlobalDefault(agentId);
@@ -411,4 +376,3 @@ Skip CLI installs with --skip-clis when you only want config updates, not versio
         }
     });
 }
-//# sourceMappingURL=pull.js.map

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

@@ -1,3 +1,10 @@
+/**
+ * Internal memory 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.
+ */
 import { Command } from 'commander';
 /**
  * Hidden command invoked by shims for agents that don't natively resolve
@@ -6,4 +13,3 @@ import { Command } from 'commander';
  * sync. Typical cost: 10-20ms when memory is fresh.
  */
 export declare function registerRefreshMemoryCommand(program: Command): void;
-//# sourceMappingURL=refresh-memory.d.ts.map

package/dist/commands/refresh-memory.js

@@ -1,3 +1,10 @@
+/**
+ * Internal memory 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.
+ */
 import chalk from 'chalk';
 import { AGENTS } from '../lib/agents.js';
 import { isVersionInstalled } from '../lib/versions.js';
@@ -42,4 +49,3 @@ export function registerRefreshMemoryCommand(program) {
         }
     });
 }
-//# sourceMappingURL=refresh-memory.js.map

package/dist/commands/repo.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Extra DotAgent repo management.
+ *
+ * Registers `agents repo add|init|list|remove|enable|disable` which manage
+ * additional DotAgent repos alongside the primary ~/.agents-system/ repo so
+ * private, work, or team skills can ship separately from public ones.
+ *
+ * Extras are user-level config: managed clones live at ~/.agents-<alias>/ as
+ * peer dirs to ~/.agents/, and user-owned repos may live anywhere. All extras
+ * are registered in meta.extraRepos. Sync functions merge their resources into
+ * agent version homes after the user repo's (user-wins on name collisions).
+ */
+import type { Command } from 'commander';
+/** Register the `agents repo` command tree. */
+export declare function registerRepoCommands(program: Command): void;