@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/setup-term.d.ts

@@ -1,25 +1,4 @@
-/**
- * `agents setup term` — install the standalone `term` CLI if missing (PHNX-4092).
- *
- * The PTY engine lives in `@phnx-labs/term-cli` (extracted PHNX-4091);
- * agents-cli never rebundles it. The setup-token mint behind `agents accounts
- * add` / `agents accounts login` (auth-mint.ts → term-driver.ts) spawns `term`
- * on demand and fails loud when it is absent, so onboarding installs it here
- * like every other standalone tool.
- *
- * Unlike browser/computer/secrets there is nothing to configure — no profile,
- * no OS permission, no migrate step. A missing binary is a routine install
- * (`agents clis install term` via the system `clis/term.yaml`, then a pinned
- * `npm i -g`, both handled by installSetupTool), and once it is on PATH the
- * tool is ready.
- */
 import type { Command } from 'commander';
-/** True when the standalone `term` executable resolves ($TERM_BIN or PATH). */
 export declare function isTermCliInstalled(): boolean;
-/**
- * Install the standalone `term` CLI if missing. Returns whether `term` is on
- * PATH afterwards. There is no further onboarding — presence is readiness.
- */
 export declare function runTermWizard(): Promise<boolean>;
-/** Register `agents setup term` under the parent `setup` command. */
 export declare function registerSetupTermCommand(setupCmd: Command): void;

package/dist/commands/setup-term.js

@@ -1,18 +1,3 @@
-/**
- * `agents setup term` — install the standalone `term` CLI if missing (PHNX-4092).
- *
- * The PTY engine lives in `@phnx-labs/term-cli` (extracted PHNX-4091);
- * agents-cli never rebundles it. The setup-token mint behind `agents accounts
- * add` / `agents accounts login` (auth-mint.ts → term-driver.ts) spawns `term`
- * on demand and fails loud when it is absent, so onboarding installs it here
- * like every other standalone tool.
- *
- * Unlike browser/computer/secrets there is nothing to configure — no profile,
- * no OS permission, no migrate step. A missing binary is a routine install
- * (`agents clis install term` via the system `clis/term.yaml`, then a pinned
- * `npm i -g`, both handled by installSetupTool), and once it is on PATH the
- * tool is ready.
- */
 import chalk from 'chalk';
 import { isPromptCancelled } from './utils.js';
 import { openSetupTerminal } from './setup-terminal.js';
@@ -20,14 +5,9 @@ import { resolveTermBin } from '../lib/term-client.js';
 import { installSetupTool } from '../lib/setup-tool-install.js';
 import { refreshToolSetup } from '../lib/setup-tool-status.js';
 const INSTALL_HINT = 'agents clis install term   # or: npm i -g @phnx-labs/term-cli';
-/** True when the standalone `term` executable resolves ($TERM_BIN or PATH). */
 export function isTermCliInstalled() {
     return resolveTermBin() !== null;
 }
-/**
- * Install the standalone `term` CLI if missing. Returns whether `term` is on
- * PATH afterwards. There is no further onboarding — presence is readiness.
- */
 export async function runTermWizard() {
     if (isTermCliInstalled()) {
         console.log(chalk.green('The standalone `term` CLI is installed.'));
@@ -42,7 +22,6 @@ export async function runTermWizard() {
     console.log(chalk.cyan(`  ${INSTALL_HINT}`));
     return false;
 }
-/** Register `agents setup term` under the parent `setup` command. */
 export function registerSetupTermCommand(setupCmd) {
     setupCmd
         .command('term')

package/dist/commands/setup-terminal.d.ts

@@ -1,3 +1,2 @@
 import type { SetupTool } from '../lib/setup-tool-status.js';
-/** The GUI starts a terminal; the terminal child owns wizard completion. */
 export declare function openSetupTerminal(tool: SetupTool, terminal: boolean | string, installOnly?: boolean): Promise<void>;

package/dist/commands/setup-terminal.js

@@ -1,6 +1,5 @@
 import os from 'node:os';
 import { currentContext, openRunInTerminal, parseTerminalFlag } from '../lib/terminal/index.js';
-/** The GUI starts a terminal; the terminal child owns wizard completion. */
 export async function openSetupTerminal(tool, terminal, installOnly = false) {
     if (installOnly)
         throw new Error('--terminal and --install-only are separate setup modes.');

package/dist/commands/setup-tools.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerSetupToolsCommand(setupCmd: Command): void;

package/dist/commands/setup-tools.js

@@ -0,0 +1,73 @@
+import chalk from 'chalk';
+import { setHelpSections } from '../lib/help.js';
+import { ensureToolPins, STANDALONE_TOOLS } from '../lib/standalone-tools.js';
+function parseTools(values) {
+    if (!values?.length)
+        return undefined;
+    const tools = values.flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean);
+    for (const tool of tools) {
+        if (!STANDALONE_TOOLS.includes(tool)) {
+            throw new Error(`Unknown tool "${tool}". Choose from: ${STANDALONE_TOOLS.join(', ')}.`);
+        }
+    }
+    return tools;
+}
+function renderRow(row) {
+    const have = row.installed ?? 'not installed';
+    const label = row.tool.padEnd(9);
+    if (row.state === 'ok')
+        return `  ${chalk.green('[x]')} ${label} ${have} ${chalk.gray(`(>= ${row.floor})`)}`;
+    if (row.state === 'installed' || row.state === 'upgraded') {
+        return `  ${chalk.green('[x]')} ${label} ${have} ${chalk.gray(`(${row.state}, >= ${row.floor})`)}`;
+    }
+    if (row.state === 'failed')
+        return `  ${chalk.red('[!]')} ${label} ${have} ${chalk.red(row.error ?? 'install failed')}`;
+    return `  ${chalk.yellow('[ ]')} ${label} ${have} ${chalk.yellow(`needs ${row.pkg}@${row.floor}`)}`;
+}
+export function registerSetupToolsCommand(setupCmd) {
+    const cmd = setupCmd
+        .command('tools')
+        .description('Install or upgrade the standalone sessions, browser, secrets, computer, and term CLIs to the versions this release pins')
+        .option('--tool <name...>', `Only these tools: ${STANDALONE_TOOLS.join(', ')} (repeatable or comma-separated)`)
+        .option('--dry-run', 'Report what is below its pin without installing anything')
+        .option('--json', 'Print one row per tool as JSON (installer output goes to stderr)')
+        .action(async (opts) => {
+        let tools;
+        try {
+            tools = parseTools(opts.tool);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exitCode = 2;
+            return;
+        }
+        const rows = await ensureToolPins({ tools, dryRun: opts.dryRun, logToStderr: opts.json });
+        if (opts.json)
+            console.log(JSON.stringify(rows, null, 2));
+        else
+            for (const row of rows)
+                console.log(renderRow(row));
+        if (rows.some((row) => row.state !== 'ok' && row.state !== 'installed' && row.state !== 'upgraded'))
+            process.exitCode = 1;
+    });
+    setHelpSections(cmd, {
+        examples: `
+      # See which tools are below the pinned release, without installing
+      agents setup tools --dry-run
+
+      # Bring every tool up to its pin (npm install -g <pkg>@<pin>)
+      agents setup tools
+
+      # Just one tool, machine-readable
+      agents setup tools --tool sessions --json
+
+      # Every reachable device, one at a time
+      agents ssh yosemite-s1 'agents setup tools'
+    `,
+        notes: `
+      - A tool already at or above its pin is never downgraded or reinstalled.
+      - Exit 1 when any tool is still below its pin (dry run, failed install, or an
+        older copy earlier on PATH shadowing the new one).
+    `,
+    });
+}

package/dist/commands/setup.d.ts

@@ -1,9 +1,3 @@
-/**
- * First-run setup command.
- *
- * Registers the `agents setup` command which clones the system repo into
- * ~/.agents/.system/ and installs agent CLIs with resource syncing.
- */
 import type { Command } from 'commander';
 interface RunSetupOptions {
     force?: boolean;
@@ -16,21 +10,8 @@ interface RunSetupOptions {
     };
     isDaemonEnabledFn?: () => boolean;
 }
-/** First-run setup. Clones ~/.agents/.system/ from the system repo if needed. */
 export declare function runSetup(program: Command, options?: RunSetupOptions): 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 setup now. In non-interactive mode, print a clear
- * error and exit.
- */
 export declare function ensureInitialized(program: Command): Promise<void>;
-/**
- * Interactive "what else do you want to set up?" menu shown after the bare
- * `agents setup` finishes on a TTY. Each pick runs that capability's guided
- * wizard. Never throws — a cancel or an optional wizard's error just skips the
- * rest and lets core setup complete.
- */
 type SetupPhase = 'browser' | 'computer' | 'secrets' | 'term' | 'accounts' | 'fleet' | 'watchdog' | 'preferences';
 type SetupStatusState = 'ready' | 'missing' | 'n/a';
 interface SetupStatusRow {
@@ -44,6 +25,5 @@ export declare function runSetupHub(deps?: {
     selectPhase?: (rows: SetupStatusRow[]) => Promise<SetupPhase | 'exit'>;
     runPhase?: (phase: SetupPhase) => Promise<void>;
 }): Promise<void>;
-/** Register the `agents setup` command and its capability subcommands. */
 export declare function registerSetupCommand(program: Command): void;
 export {};

package/dist/commands/setup.js

@@ -1,9 +1,3 @@
-/**
- * First-run setup command.
- *
- * Registers the `agents setup` 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';
@@ -22,6 +16,7 @@ import { registerSetupBrowserCommand, runBrowserWizard } from './setup-browser.j
 import { registerSetupComputerCommand, runComputerWizard } from './setup-computer.js';
 import { registerSetupMineCommand } from './setup-mine.js';
 import { registerSetupSecretsCommand } from './setup-secrets.js';
+import { registerSetupToolsCommand } from './setup-tools.js';
 import { registerSetupTermCommand, runTermWizard, isTermCliInstalled } from './setup-term.js';
 import { registerSetupFleetCommand } from './setup-fleet.js';
 import { registerSetupAccountsCommand, runAccountsSetupWizard } from './setup-accounts.js';
@@ -38,37 +33,22 @@ import { getConfigValue } from '../lib/device-config.js';
 import { setupSecretsPrefsPath } from './setup-secrets.js';
 import { SETUP_TOOLS, getCachedToolSetup, refreshToolSetup } from '../lib/setup-tool-status.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];
-    // setup has its own hand-rolled adoption (rename + symlink inline, rather than
-    // calling switchConfigSymlink), so the primitive gates never see it. Check the
-    // boundary here, before the first mkdirSync — which would otherwise create the
-    // scaffolding this very check reads.
     assertIsolationBoundary(agentId, 'adopt your existing install');
     const configDir = agent.configDir;
     const versionsDir = getVersionsDir();
     const versionHome = path.join(versionsDir, agentId, version, 'home');
     const versionConfigDir = path.join(versionHome, agentConfigDirName(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 };
     }
@@ -76,7 +56,6 @@ async function importAgent(agentId, version) {
         return { success: false, error: err.message };
     }
 }
-/** First-run setup. Clones ~/.agents/.system/ from the system repo if needed. */
 export async function runSetup(program, options = {}) {
     const agentsDir = getAgentsDir();
     const alreadyConfigured = isGitRepo(agentsDir);
@@ -86,7 +65,6 @@ export async function runSetup(program, options = {}) {
         await (options.runHub ?? runSetupHub)();
         return;
     }
-    // Detect existing installations BEFORE cloning (they won't exist after if we import)
     const unmanaged = await getUnmanagedAgentInstalls();
     const sessionCounts = {};
     for (const install of unmanaged) {
@@ -106,7 +84,6 @@ export async function runSetup(program, options = {}) {
         ensureAgentsDir();
         const spinner = ora(alreadyConfigured ? 'Updating system repo...' : '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}`);
@@ -116,7 +93,6 @@ export async function runSetup(program, options = {}) {
             spinner.succeed(`Updated to ${result.commit}`);
         }
         else {
-            // Check git is available
             try {
                 const { execSync } = await import('child_process');
                 execSync('git --version', { stdio: 'ignore' });
@@ -148,10 +124,7 @@ export async function runSetup(program, options = {}) {
             }
         }
     }
-    catch { /* best effort */ }
-    // Populate the device registry from the tailnet on first setup. Soft mode is
-    // guaranteed non-throwing (no tailscale / corrupt file / lock contention all
-    // resolve to ok:false), so this can never block setup.
+    catch { }
     const { runDeviceSync } = await import('../lib/devices/sync.js');
     const dev = await runDeviceSync({ soft: true });
     if (dev.ok) {
@@ -162,7 +135,6 @@ export async function runSetup(program, options = {}) {
     if (dev.ok && dev.synced > 0) {
         console.log(chalk.gray(`Discovered ${dev.synced} device${dev.synced === 1 ? '' : 's'} on your tailnet (agents devices list).`));
     }
-    // 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));
@@ -194,7 +166,6 @@ export async function runSetup(program, options = {}) {
                     spinner.fail(`${agentLabel(install.agentId)}: ${result.error}`);
                 }
             }
-            // Ensure shims are in PATH
             if (!isShimsInPath()) {
                 const pathResult = addShimsToPath();
                 if (pathResult.success && !pathResult.alreadyPresent) {
@@ -206,7 +177,6 @@ export async function runSetup(program, options = {}) {
                     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
@@ -218,9 +188,6 @@ export async function runSetup(program, options = {}) {
             }
         }
     }
-    // Register the agents:// URL scheme so deep links in rendered artifacts can
-    // resume a session (RUSH — session deep links). Best-effort and idempotent:
-    // never fails setup, only registers when missing.
     try {
         const { registerAgentsUrlScheme } = await import('../lib/deeplink/register.js');
         const scheme = registerAgentsUrlScheme({ ifMissing: true });
@@ -228,13 +195,9 @@ export async function runSetup(program, options = {}) {
             console.log(chalk.gray('Registered the agents:// URL scheme (artifact session deep links).'));
     }
     catch {
-        // non-fatal — the user can run `agents setup url-scheme register` later.
     }
     if (options.suppressFooter)
         return;
-    // Fresh-machine hub: offer to set up the optional capabilities that need their
-    // own guided flow. TTY-only and fully opt-in — a non-interactive `agents setup`
-    // stops at the system-repo bootstrap above, unchanged.
     await (options.runHub ?? runSetupHub)();
     console.log(chalk.bold('\nSetup complete. Try:'));
     console.log(chalk.cyan('  agents view                 ') + chalk.gray(' # see what\'s installed'));
@@ -242,12 +205,6 @@ export async function runSetup(program, options = {}) {
     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 setup now. In non-interactive mode, print a clear
- * error and exit.
- */
 export async function ensureInitialized(program) {
     const agentsDir = getAgentsDir();
     if (isGitRepo(agentsDir))
@@ -268,10 +225,6 @@ export async function ensureInitialized(program) {
     await runSetup(program, { suppressFooter: true });
 }
 export async function getSetupStatus() {
-    // Browser readiness is now config + standalone presence (PHNX-4101): the engine
-    // (@phnx-labs/browser-cli) owns profile declarations and launchability, so
-    // agents-cli reads the shared default-profile key it and browser-cli both write
-    // rather than resolving a profile through a deleted in-repo engine.
     const browserCliInstalled = browserInstalled();
     const configuredBrowserProfile = getConfigValue('browser.profile').value;
     const browserReady = browserCliInstalled && !!configuredBrowserProfile;
@@ -364,19 +317,16 @@ export async function runSetupHub(deps = {}) {
         console.log(chalk.yellow(`Optional setup skipped: ${err.message}`));
     }
 }
-/** Register the `agents setup` command and its capability subcommands. */
 export function registerSetupCommand(program) {
     const setupCmd = program
         .command('setup')
         .description('Set up agents-cli, or re-open the capability onboarding hub.')
         .option('-f, --force', 'Re-run setup even if ~/.agents/.system/ already exists (use with caution)')
         .option('--no-system-repo', 'Skip cloning the system repo (you must populate ~/.agents/.system/ yourself)');
-    // Capability subcommands: `agents setup browser|computer|term|mine|secrets|accounts|fleet|alias|beta`.
-    // Artifact publishing is no longer set up here — it lives in the standalone
-    // `artifacts` CLI (`artifacts share setup`/`join`, PHNX-3992).
     registerSetupBrowserCommand(setupCmd);
     registerSetupComputerCommand(setupCmd);
     registerSetupTermCommand(setupCmd);
+    registerSetupToolsCommand(setupCmd);
     registerSetupMineCommand(setupCmd);
     registerSetupSecretsCommand(setupCmd);
     registerSetupAccountsCommand(setupCmd);
@@ -384,10 +334,6 @@ export function registerSetupCommand(program) {
     registerSetupWatchdogCommand(setupCmd);
     registerAliasCommand(setupCmd);
     registerBetaCommands(setupCmd);
-    // `agents setup url-scheme register|unregister|status` — the canonical, visible
-    // home for the agents:// OS handler that routes artifact deep links to the
-    // machine-only `agents _callback` verb. Reuses the same builder the hidden
-    // `agents open` back-compat subcommands mount.
     const urlScheme = setupCmd
         .command('url-scheme')
         .description('Register/unregister/status the agents:// OS URL-scheme handler for artifact session deep links.');
@@ -445,6 +391,7 @@ export function registerSetupCommand(program) {
       agents setup computer
       agents setup secrets
       agents setup term
+      agents setup tools
       agents setup accounts
       agents setup fleet
       agents setup watchdog

package/dist/commands/skills.d.ts

@@ -1,11 +1,2 @@
-/**
- * Skill management commands for adding domain-specific capabilities to agents.
- *
- * Implements `agents skills` -- list, add, remove, sync, prune, and view
- * packaged SKILL.md bundles (with optional rules/ directories). Central
- * storage lives in ~/.agents/skills/ and skills are synced to individual
- * version homes via copy or symlink.
- */
 import type { Command } from 'commander';
-/** Register the `agents skills` command tree (list, add, remove, sync, prune, view). */
 export declare function registerSkillsCommands(program: Command): void;

package/dist/commands/skills.js

@@ -13,7 +13,6 @@ import { getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection,
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, promptRemovalTargets, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-/** Register the `agents skills` command tree (list, add, remove, sync, prune, view). */
 export function registerSkillsCommands(program) {
     const skillsCmd = program
         .command('skills')
@@ -103,7 +102,6 @@ Examples:
         try {
             let skills;
             if (!source) {
-                // Interactive mode: pick from central storage
                 const installedSkills = listInstalledSkills();
                 if (installedSkills.size === 0) {
                     console.log(chalk.yellow('No skills in ~/.agents/skills/'));
@@ -157,7 +155,6 @@ Examples:
                 });
             }
             else {
-                // Source provided: fetch from repo or local path
                 const spinner = ora('Fetching skills...').start();
                 const isGitRepo = source.startsWith('gh:') || source.startsWith('git:') ||
                     source.startsWith('ssh:') || source.startsWith('https://') ||
@@ -184,7 +181,6 @@ Examples:
                         const { validateSkillMetadata, countSkillRules } = await import('../lib/plugins/skills.js');
                         const parseResult = tryParseSkillMetadata(localPath);
                         const validation = validateSkillMetadata(parseResult.metadata, skillName);
-                        // Warn if YAML is invalid
                         if (parseResult.error) {
                             spinner.warn(`Skill '${skillName}' has invalid SKILL.md`);
                             console.log(chalk.yellow(`  ${parseResult.error}`));
@@ -210,8 +206,6 @@ Examples:
                     console.log(chalk.yellow('No skills found (looking for SKILL.md files)'));
                     return;
                 }
-                // Filter by --names if provided. Mirrors the no-source path's behavior
-                // so users can pluck specific skills from a multi-skill repo.
                 const requestedNames = parseCommaSeparatedList(options.names);
                 if (requestedNames.length > 0) {
                     const discoveredNames = new Set(discoveredSkills.map((s) => s.name));
@@ -234,7 +228,6 @@ Examples:
                         console.log(`    ${chalk.yellow('Warning:')} ${chalk.gray(skill.parseError)}`);
                     }
                 }
-                // Install to central storage first
                 const installSpinner = ora('Installing skills to central storage...').start();
                 let installed = 0;
                 for (const skill of discoveredSkills) {
@@ -251,7 +244,6 @@ Examples:
                 installSpinner.succeed(`Installed ${installed} skills to ~/.agents/skills/`);
                 skills = discoveredSkills;
             }
-            // Get agent and version selection
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
@@ -274,7 +266,6 @@ Examples:
                 console.log(chalk.yellow('\nNo agents selected.'));
                 return;
             }
-            // Sync to selected versions
             const syncSpinner = ora('Syncing to agent versions...').start();
             let synced = 0;
             const skillNames = skills.map((s) => s.name);
@@ -407,7 +398,6 @@ Examples:
             console.log(chalk.gray("Central source unchanged. Restore any target with 'agents sync <agent>@<version> --yes'."));
         }
     });
-    // `skills prune` moved to the top-level `agents prune cleanup` command.
     skillsCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
@@ -429,7 +419,6 @@ Examples:
   agents skills view
 `)
         .action(async (name) => {
-        // If no name provided, show interactive select
         if (!name) {
             const cwd = process.cwd();
             const allSkills = [];
@@ -483,7 +472,6 @@ Examples:
             console.log(chalk.yellow(`Skill '${name}' not found`));
             return;
         }
-        // Build output
         const lines = [];
         lines.push(chalk.bold(`\n${skill.metadata.name}\n`));
         if (skill.metadata.description) {
@@ -512,20 +500,14 @@ Examples:
         printWithPager(output, lines.length);
     });
 }
-/**
- * Build the row data for `agents skills list`. Each row = one central skill
- * with a sync-status target per (agent, version) in scope.
- */
 async function buildSkillRows(opts) {
-    const central = listInstalledSkills(); // Map<name, DiscoveredSkill>
+    const central = listInstalledSkills();
     if (central.size === 0)
         return [];
     const targetPairs = iterSkillsCapableVersions({
         agent: opts.filterAgent,
         version: opts.filterVersion,
     });
-    // Precompute per-(agent, version) diffs so we can look up each skill's
-    // status without re-diffing 16 times per skill.
     const diffByTarget = new Map();
     const defaultByAgent = new Map();
     for (const { agent, version } of targetPairs) {
@@ -553,8 +535,6 @@ async function buildSkillRows(opts) {
             });
         }
         const fileCount = countSkillFiles(skill.path);
-        // Append repo source when a skill comes from a registered extra so users
-        // can see which DotAgent repo owns it at a glance.
         const description = skill.source
             ? `${skill.metadata.description || ''}${skill.metadata.description ? ' ' : ''}${chalk.gray(`[${skill.source}]`)}`
             : skill.metadata.description;
@@ -566,7 +546,6 @@ async function buildSkillRows(opts) {
             buildDetail: () => formatSkillDetail(name, skill, targets, fileCount),
         });
     }
-    // Sort: fully-synced first, then partial, then missing — stable by name within each tier.
     rows.sort((a, b) => {
         const aSynced = a.targets.filter((t) => t.status === 'synced').length;
         const bSynced = b.targets.filter((t) => t.status === 'synced').length;

package/dist/commands/snapshot.d.ts

@@ -1,11 +1,2 @@
-/**
- * `agents devices snapshot` — one-process consumer snapshot for pollers.
- *
- * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
- * fork storm with a single command. Does NOT replace `agents sync status`, which
- * remains the UnifiedSyncStatus sync contract for menubar / Agency drift.
- *
- * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
- */
 import type { Command } from 'commander';
 export declare function registerSnapshotCommand(devicesCmd: Command): void;

package/dist/commands/snapshot.js

@@ -1,12 +1,3 @@
-/**
- * `agents devices snapshot` — one-process consumer snapshot for pollers.
- *
- * Replaces the N× `view --json` + `sessions --active --json` (+ optional feed)
- * fork storm with a single command. Does NOT replace `agents sync status`, which
- * remains the UnifiedSyncStatus sync contract for menubar / Agency drift.
- *
- * JSON shape: {@link FleetSnapshot} in `lib/snapshot.ts` (version: 1).
- */
 import chalk from 'chalk';
 import { addHostOption } from '../lib/hosts/option.js';
 import { setHelpSections } from '../lib/help.js';
@@ -23,7 +14,6 @@ function resolveAgentFilter(raw) {
     }
     return name;
 }
-/** Compact human summary — the JSON path is the real contract. */
 function renderHuman(snap) {
     console.log(chalk.bold('Fleet snapshot') + chalk.gray(`  ·  ${snap.host}  ·  ${snap.capturedAt}`));
     const invParts = [];