@phnx-labs/agents-cli 1.18.5 → 1.19.0

package/dist/commands/secrets.js

@@ -10,7 +10,7 @@ import * as fs from 'fs';
 import { bundleExists, deleteBundle, describeBundle, keychainItemsForBundle, keychainRef, listBundles, migrateLegacyBundles, parseDotenv, readBundle, renameBundle, rotateBundleSecret, validateBundleName, validateEnvKey, validateExpiresFutureDated, validateSecretType, writeBundle, } from '../lib/secrets/bundles.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
-import { registerCommandGroups } from '../lib/help.js';
+import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
@@ -314,86 +314,45 @@ function countExpiringSoon(meta) {
 export function registerSecretsCommands(program) {
     const cmd = program
         .command('secrets')
-        .description('Named bundles of env variables backed by macOS Keychain (iCloud-synced by default). Inject into agents via `agents run --secrets <name>`.')
-        .hook('preAction', () => { migrateLegacyBundles(); })
-        .addHelpText('after', `
-Workflow:
-  Bundles are containers; secrets are the variables inside them. Create a
-  bundle once, add secrets to it, then inject the whole bundle into any agent
-  run with --secrets <name>. Keychain-backed values never touch disk in
-  plaintext.
-
-  New bundles store values in the iCloud-synced keychain by default so they
-  appear automatically on your other Macs (same iCloud account, iCloud
-  Keychain enabled). Pass --no-icloud-sync at create time to keep values
-  device-local instead.
-
-Examples:
-  # Create a bundle for production credentials (iCloud-synced by default)
-  agents secrets create prod --description "Production keys for the api stack"
-
-  # Create a bundle that never leaves this Mac
-  agents secrets create local-only --no-icloud-sync
-
-  # Rename a bundle (moves metadata + every keychain value)
-  agents secrets rename prod production
-
-  # Edit the description of an existing bundle
-  agents secrets describe prod "Production keys for the api stack"
-  agents secrets describe prod --clear
-
-  # Add a keychain-backed secret (prompts for the value)
-  agents secrets add prod STRIPE_API_KEY
-
-  # Add a literal (non-sensitive) value
-  agents secrets add prod LOG_LEVEL --value info
+        .description('Named bundles of env variables backed by macOS Keychain (iCloud-synced by default). Inject into agents via `agents run --secrets <name>`.');
+    setHelpSections(cmd, {
+        examples: `
+      # Create a bundle
+      agents secrets create prod --description "Production keys for the api stack"
 
-  # Add with metadata
-  agents secrets add prod STRIPE_API_KEY --type api-key --expires 2027-01-15 --note "Live key, owner: payments-team"
+      # Add a keychain-backed secret (prompts for the value)
+      agents secrets add prod STRIPE_API_KEY
 
-  # Rotate a key (replaces the value, preserves metadata unless overridden)
-  agents secrets rotate prod STRIPE_API_KEY
-
-  # Import an entire .env file straight into keychain
-  agents secrets import prod --from .env.prod
-
-  # Import secrets from a 1Password vault
-  agents secrets import prod --from-1password --vault "Rush Prod"
-
-  # Push a bundle back to 1Password (vault migration, backup)
-  agents secrets export prod --to-1password --vault "Rush Prod"
-  agents secrets export prod --to-1password --vault "Rush Prod" --force
-
-  # See what's in a bundle (values masked)
-  agents secrets view prod
+      # Add a non-sensitive literal
+      agents secrets add prod LOG_LEVEL --value info
 
-  # Reveal the real values in an interactive shell
-  agents secrets view prod --reveal
+      # Inject the bundle into an agent run
+      agents run claude "deploy the worker" --secrets prod
 
-  # Inject the bundle into an agent run
-  agents run claude "deploy the worker" --secrets prod
+      # See what's in the bundle (values masked)
+      agents secrets view prod
 
-  # Eval the bundle into your current shell
-  eval "$(agents secrets export prod --plaintext)"
+      # Eval the bundle into your current shell
+      eval "$(agents secrets export prod --plaintext)"
 
-  # Run a command with secrets injected
-  agents secrets exec prod -- ./deploy.sh
-  agents secrets exec hetzner.com -- crabbox list
+      # Run a one-off command with secrets injected
+      agents secrets exec prod -- ./deploy.sh
+    `,
+        notes: `
+      Bundles are containers; secrets are the variables inside them. Keychain values
+      never touch disk in plaintext.
 
-  # Remove one key (purges the keychain item by default)
-  agents secrets remove prod STRIPE_API_KEY
+      iCloud sync: new bundles use the iCloud-synced keychain by default so they
+      appear on other Macs (same iCloud account, iCloud Keychain enabled). Pass
+      --no-icloud-sync at create time to keep values device-local instead.
 
-  # Delete the whole bundle and purge every keychain item it owned
-  agents secrets delete prod
-
-  # Generate a random password (32 chars, all character classes)
-  agents secrets generate
-
-  # Generate a 16-char password, or a PIN, or hex
-  agents secrets generate 16
-  agents secrets generate 8 --pin
-  agents secrets generate 32 --hex
-`);
+      See also:
+        agents secrets rotate <bundle> <key>           rotate value, preserve metadata
+        agents secrets import <bundle> --from .env     bulk import from .env
+        agents secrets import <bundle> --from-1password --vault <name>
+        agents secrets generate [length]               generate a random password / PIN / hex
+    `,
+    });
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'rename', 'describe', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
@@ -796,6 +755,40 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('migrate')
+        .description('Interactively migrate legacy YAML bundles into Keychain')
+        .action(async () => {
+        try {
+            if (!isInteractiveTerminal()) {
+                console.error(chalk.red('Refusing to migrate legacy secrets without an interactive confirmation prompt.'));
+                process.exit(1);
+            }
+            const { confirm } = await import('@inquirer/prompts');
+            const migrated = await migrateLegacyBundles(async (candidate) => {
+                console.log(chalk.bold(`Legacy bundle '${candidate.name}'`));
+                console.log(chalk.gray(candidate.file));
+                for (const key of candidate.keys) {
+                    console.log(`  ${key}`);
+                }
+                return await confirm({
+                    message: `Migrate legacy bundle '${candidate.name}' into Keychain?`,
+                    default: false,
+                });
+            });
+            if (migrated === 0) {
+                console.log(chalk.gray('No legacy bundles migrated.'));
+                return;
+            }
+            console.log(chalk.green(`Migrated ${migrated} legacy bundle${migrated === 1 ? '' : 's'} into keychain.`));
+        }
+        catch (err) {
+            if (isPromptCancelled(err))
+                return;
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
     cmd
         .command('import [bundle]')
         .description('Import keys from a .env file or a 1Password vault into a bundle. By default every key is stored in keychain.')

package/dist/commands/sessions-tail.js

@@ -10,6 +10,7 @@ import * as fsp from 'fs/promises';
 import * as path from 'path';
 import chalk from 'chalk';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
+import { setHelpSections } from '../lib/help.js';
 const TAIL_SUPPORTED = ['claude', 'codex'];
 /**
  * Tail a file: emit each newline-terminated line via onLine as it's written.
@@ -202,34 +203,32 @@ async function runTail(sessionId, options) {
 }
 /** Attach the `tail` subcommand to an existing `sessions` command. */
 export function registerSessionsTailCommand(sessionsCmd) {
-    sessionsCmd
+    const tailCmd = sessionsCmd
         .command('tail [sessionId]')
-        .description('Live-tail a session file, streaming new JSONL events as they are written. Long-running: press Ctrl+C to stop. Claude and Codex only.')
+        .description('Stream JSONL events from a session file as they are written, one event per line. Long-running: Ctrl+C to stop. Claude and Codex only.')
         .option('--latest', 'Tail the most recent tailable session (claude or codex)')
         .option('--from-start', 'Emit the full file first, then follow (default: start at EOF)')
-        .option('--json', 'Raw JSONL passthrough (default)')
-        .addHelpText('after', `
-This command runs until interrupted (Ctrl+C). Each line printed to stdout
-is a raw JSONL event from the session file — parse with jq or similar.
+        .option('--json', 'Raw JSONL passthrough (default)');
+    setHelpSections(tailCmd, {
+        examples: `
+      # Follow the most recent active Claude or Codex session
+      agents sessions tail --latest
 
-Examples:
-  # Follow the most recent active Claude or Codex session
-  agents sessions tail --latest
+      # Follow a specific session by short or full ID
+      agents sessions tail a1b2c3d4
 
-  # Follow a specific session by short or full ID
-  agents sessions tail a1b2c3d4
+      # Replay from the beginning, then follow
+      agents sessions tail a1b2c3d4 --from-start
 
-  # Replay from the beginning, then follow
-  agents sessions tail a1b2c3d4 --from-start
-
-  # Pipe through jq to extract just user messages
-  agents sessions tail --latest | jq 'select(.type == "user")'
-
-Only Claude and Codex sessions are supported — they append JSONL one event
-per line, which makes live-tailing safe. Gemini, OpenCode, and OpenClaw
-use formats that rewrite the file or store state elsewhere.
-`)
-        .action(async (sessionId, options) => {
+      # Pipe through jq to extract just user messages
+      agents sessions tail --latest | jq 'select(.type == "user")'
+    `,
+        notes: `
+      - Only Claude and Codex sessions are tailable — they append JSONL one event per line.
+      - Gemini, OpenCode, and OpenClaw use formats that rewrite the file or store state elsewhere.
+    `,
+    });
+    tailCmd.action(async (sessionId, options) => {
         await runTail(sessionId, options);
     });
 }

package/dist/commands/sessions.js

@@ -25,6 +25,7 @@ import { colorAgent, resolveAgentName } from '../lib/agents.js';
 import { resolveVersion, resolveVersionAliasLoose } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { sessionPicker } from './sessions-picker.js';
+import { setHelpSections } from '../lib/help.js';
 import { registerSessionsTailCommand } from './sessions-tail.js';
 const SESSION_AGENT_FILTER_HELP = `Filter by agent, e.g. claude, codex, claude@2.0.65`;
 const CLAUDE_RESUME_MATCH_WINDOW_MS = 10 * 60_000;
@@ -297,7 +298,7 @@ async function sessionsAction(query, options) {
     // When the user explicitly asks to render (via mode flag), resolve the
     // query globally so sessions outside the default cwd/30d window are found.
     if (wantsRender && searchQuery) {
-        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts });
+        await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, noRedact: options.noRedact });
         return;
     }
     // Interactive picker loads a deep pool but shows only recent sessions
@@ -347,11 +348,11 @@ async function sessionsAction(query, options) {
         if (searchQuery) {
             const idMatches = resolveSessionById(sessions, searchQuery);
             if (idMatches.length === 1) {
-                await renderSession(idMatches[0], mode, filterOpts);
+                await renderSession(idMatches[0], mode, filterOpts, options);
                 return;
             }
             if (idMatches.length === 0 && looksLikeSessionId(searchQuery)) {
-                await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts });
+                await renderOneSession(searchQuery, mode, { agent: options.agent, project: options.project, filter: filterOpts, noRedact: options.noRedact });
                 return;
             }
         }
@@ -472,7 +473,7 @@ function resolveViewMode(options, filters) {
         return 'markdown';
     return 'summary';
 }
-async function renderSession(session, mode, filters) {
+async function renderSession(session, mode, filters, options = {}) {
     // OpenCode stores sessions in SQLite; filePath is "db_path#session_id"
     const realPath = session.filePath.split('#')[0];
     if (!fs.existsSync(realPath)) {
@@ -518,7 +519,7 @@ async function renderSession(session, mode, filters) {
             chalk.gray(` ${formatRelativeTime(session.timestamp)}`) +
             (session.account ? chalk.gray(` (${session.account})`) : ''));
         console.log(chalk.gray('─'.repeat(60)));
-        process.stdout.write(renderMarkdown(renderConversationMarkdown(events)));
+        process.stdout.write(renderMarkdown(renderConversationMarkdown(events, { redact: options.noRedact !== true })));
         return;
     }
     // json — no header, raw events only (pipeable)
@@ -731,7 +732,7 @@ async function runCloudSessions(query, options) {
     const cachedSpinner = options.json ? null : ora('Fetching session...').start();
     let cachedPath;
     try {
-        cachedPath = await ensureCloudSessionCached(meta.id, meta.filePath);
+        cachedPath = await ensureCloudSessionCached(meta.id);
     }
     catch (err) {
         cachedSpinner?.stop();
@@ -740,7 +741,7 @@ async function runCloudSessions(query, options) {
     }
     cachedSpinner?.stop();
     // Ensure the SessionMeta points at the local cache path for renderSession.
-    await renderSession({ ...meta, filePath: cachedPath }, mode, filterOpts);
+    await renderSession({ ...meta, filePath: cachedPath }, mode, filterOpts, options);
 }
 function parseAgentFilter(agentName) {
     if (!agentName)
@@ -986,7 +987,7 @@ async function renderOneSession(query, mode, scope) {
             throw new Error('Session resolution failed');
         }
         spinner.stop();
-        await renderSession(session, mode, scope.filter);
+        await renderSession(session, mode, scope.filter, { noRedact: scope.noRedact });
     }
     catch (err) {
         if (isPromptCancelled(err))
@@ -1011,6 +1012,7 @@ export function registerSessionsCommands(program) {
         .option('--until <time>', 'Only sessions older than this (ISO timestamp)')
         .option('-n, --limit <n>', 'Maximum number of sessions to return', '50')
         .option('--markdown', 'Render the session as markdown (user, assistant, thinking, tool calls)')
+        .option('--no-redact', 'Disable default secret redaction in markdown session output')
         .option('--json', 'Output JSON (session list when browsing, event array when rendering one session)')
         .option('--include <roles>', 'Only include these roles (comma-separated): user, assistant, thinking, tools')
         .option('--exclude <roles>', 'Exclude these roles (comma-separated): user, assistant, thinking, tools')
@@ -1019,70 +1021,36 @@ export function registerSessionsCommands(program) {
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
-        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
-        .addHelpText('after', `
-Examples:
-  # Interactive picker: browse and search recent sessions (TTY only)
-  agents sessions
+        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk');
+    setHelpSections(sessionsCmd, {
+        examples: `
+      # Search prior sessions in this project by topic, file path, or command
+      agents sessions "add auth middleware"
 
-  # List sessions from current project (last 30 days, piped output shows table)
-  agents sessions | head -20
+      # Read a session as markdown (user + assistant + thinking + tools)
+      agents sessions a1b2c3d4 --markdown
 
-  # Search sessions by text (topic, file paths, commands)
-  agents sessions "add auth middleware"
+      # Just the user turns — useful for recalling intent
+      agents sessions a1b2c3d4 --include user
 
-  # Filter by project across all directories
-  agents sessions --project agents-cli --all
+      # Show only what's running right now (terminals, teams, cloud, headless)
+      agents sessions --active
 
-  # Filter by agent and time window
-  agents sessions --agent claude --since 7d
+      # Search across every directory, not just this project
+      agents sessions "topic" --all
 
-  # Filter sessions in a specific directory
-  agents sessions ~/src/my-project
-
-  # Default summary view for one session
-  agents sessions a1b2c3d4
-
-  # Full conversation (user + assistant + thinking + tools) as markdown
-  agents sessions a1b2c3d4 --markdown
-
-  # Same conversation as structured JSON events
-  agents sessions a1b2c3d4 --json
-
-  # Only user messages (filter flags auto-select markdown)
-  agents sessions a1b2c3d4 --include user
-
-  # Everything except thinking, as markdown
-  agents sessions a1b2c3d4 --exclude thinking --markdown
-
-  # Last 3 turns as markdown
-  agents sessions a1b2c3d4 --last 3
-
-  # First 10 turns, user messages only, as JSON
-  agents sessions a1b2c3d4 --first 10 --include user --json
-
-  # Export all recent sessions as JSON for analysis
-  agents sessions --since 30d --limit 200 --json > sessions.json
-
-  # Include team-spawned sessions in results
-  agents sessions --teams
-
-  # Show only live sessions across terminals, teams, cloud, and headless agents
-  agents sessions --active
-  agents sessions --active --json
-
-  # List captured cloud-run sessions (claude/codex/rush) via Rush Cloud
-  agents sessions --cloud
-  agents sessions --cloud <execution_id>
-  agents sessions --cloud <execution_id> --markdown
-  agents sessions --cloud <execution_id> --include user,assistant --last 3
-
-Notes:
-  - --include and --exclude are mutually exclusive.
-  - --first and --last are mutually exclusive.
-  - A filter flag without --markdown/--json defaults to --markdown output.
-`)
-        .action(async (query, options) => {
+      # Export for analysis
+      agents sessions --since 30d --limit 200 --json > sessions.json
+    `,
+        notes: `
+      - --include and --exclude are mutually exclusive.
+      - --first and --last are mutually exclusive.
+      - A filter flag (--include/--exclude/--first/--last) without --markdown/--json defaults to --markdown output.
+      - --cloud sources from Rush Cloud captured runs instead of local disk.
+      - Without --teams, team-spawned sessions are hidden by default.
+    `,
+    });
+    sessionsCmd.action(async (query, options) => {
         await sessionsAction(query, options);
     });
     registerSessionsTailCommand(sessionsCmd);
@@ -1272,7 +1240,7 @@ function formatAbsoluteTime(isoTimestamp) {
     return `${months[d.getMonth()]} ${d.getDate()} ${hh}:${mm}`;
 }
 function padRight(s, width) {
-    return s.length >= width ? s + ' ' : s + ' '.repeat(width - s.length);
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
 }
 function truncate(s, max) {
     return s.length > max ? s.slice(0, max - 1) + '.' : s;

package/dist/commands/setup.js

@@ -17,6 +17,7 @@ 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';
+import { setHelpSections } from '../lib/help.js';
 const HOME = os.homedir();
 /**
  * Import an existing unmanaged agent installation into agents-cli.
@@ -191,33 +192,28 @@ export async function ensureInitialized(program) {
 }
 /** Register the `agents setup` command. */
 export function registerSetupCommand(program) {
-    program
+    const setupCmd = program
         .command('setup')
-        .description('Set up agents-cli for the first time. Clones a config repo and installs agent CLIs.')
-        .option('-f, --force', 'Re-run setup even if ~/.agents-system/ already exists (use with caution)')
-        .addHelpText('after', `
-Examples:
-  # First-time setup (clones the system repo into ~/.agents-system/)
-  agents setup
+        .description('First-time setup. Clones a config repo and installs agent CLIs.')
+        .option('-f, --force', 'Re-run setup even if ~/.agents-system/ already exists (use with caution)');
+    setHelpSections(setupCmd, {
+        examples: `
+      # First-time setup (clones the system repo into ~/.agents-system/)
+      agents setup
 
-  # Re-run setup after corruption
-  agents setup --force
+      # Re-run after corruption or to repair ~/.agents-system/
+      agents setup --force
+    `,
+        notes: `
+      What it does:
+        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
 
-When to use:
-  - First time running agents-cli: this is your starting point
-  - Onboarding a new machine: restore the system repo and installed CLIs
-  - Repairing ~/.agents-system/ after accidental deletion or corruption
-
-What it does:
-  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:
-  Skip 'setup' and run:
-    agents pull
-`)
-        .action(async (options) => {
+      Non-interactive alternative: agents pull
+    `,
+    });
+    setupCmd.action(async (options) => {
         try {
             await runSetup(program, options);
         }

package/dist/commands/teams.js

@@ -6,6 +6,7 @@ import { resolveProvider } from '../lib/cloud/registry.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
 import { handleSpawn, handleStatus, handleStop, handleTasks, } from '../lib/teams/api.js';
 import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
+import { setHelpSections } from '../lib/help.js';
 import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
 import { isVersionInstalled, resolveVersionAlias, resolveVersionAliasLoose } from '../lib/versions.js';
 import { discoverSessions, parseTimeFilter, resolveSessionById } from '../lib/session/discover.js';
@@ -513,53 +514,43 @@ async function pickTeamOr(mgr, command) {
 export function registerTeamsCommands(program) {
     const teams = program
         .command('teams')
-        .description('Organize AI coding agents into teams that collaborate on a shared task')
-        .addHelpText('after', `
-A team is a named group of agents working together on a shared task. Each teammate
-runs in the background; you use 'status' to check in on progress. Use --after to
-create DAG-style dependencies (one teammate waits for another to finish first).
+        .description('Organize AI coding agents into teams that work in parallel on a shared task.');
+    setHelpSections(teams, {
+        examples: `
+      # Create a team for a coordinated task
+      agents teams create pricing-page
 
-Teammate sessions appear in 'agents sessions --teams' with a [team/name · mode] tag.
+      # Add a teammate — name them so you can refer to them later
+      agents teams add pricing-page claude "Rewrite /v2/pricing endpoint" --name backend
 
-Examples:
-  # Spin up a team to ship the new pricing page end-to-end
-  agents teams create pricing-page
+      # Parallel work — frontend stubs API while backend lands
+      agents teams add pricing-page codex "Build /pricing route with three-tier layout" --name frontend
 
-  # Backend first: Claude rewrites the billing endpoint
-  agents teams add pricing-page claude "Rewrite /v2/pricing to return tiered plans from billing.plans table" --name backend
+      # DAG dependency — QA waits for backend AND frontend to finish
+      agents teams add pricing-page claude "Run Playwright suite, fix flakes" --name qa --after backend,frontend
 
-  # Frontend can start in parallel — it stubs the API while backend lands
-  agents teams add pricing-page codex "Build the new /pricing route in apps/web with the three-tier layout" --name frontend
+      # Start everyone (respects --after dependencies) and watch live
+      agents teams start pricing-page --watch
 
-  # QA waits for both to finish before running e2e
-  agents teams add pricing-page claude "Run the full Playwright suite, fix any flakes, paste failing screenshots" --name qa --after backend,frontend
+      # Delta-poll status without rereading everything
+      agents teams status pricing-page --since 2026-04-24T09:00:00-07:00
 
-  # Drain the DAG: backend + frontend launch now, qa picks up when they're done
-  agents teams start pricing-page --watch
+      # Wind everyone down when shipped
+      agents teams disband pricing-page
+    `,
+        notes: `
+      A team is a named group of agents working in the background on a shared task.
+      Teammate sessions show in 'agents sessions --teams' tagged [team/name · mode].
 
-  # Check in without re-reading everything (delta poll)
-  agents teams status pricing-page --since 2026-04-24T09:00:00-07:00
+      Teammate syntax:
+        'claude'           the default Claude version on this machine
+        'claude@2.1.112'   a specific installed version (see 'agents view')
 
-  # Pull the live log of one teammate
-  agents teams logs frontend
-
-  # A teammate is stuck — stop them, then remove if needed
-  agents teams stop pricing-page frontend
-  agents teams remove pricing-page frontend
-
-  # Ship done — wind everyone down
-  agents teams disband pricing-page
-
-Short aliases:
-  teams c  = create    teams a  = add       teams s  = status
-  teams rm = remove    teams d  = disband   teams ls = list
-
-Teammate syntax (same as the rest of agents-cli):
-  'claude'              -> the default Claude version on this machine
-  'claude@2.1.112'      -> a specific installed version (see 'agents view')
-
-Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
-`);
+      Short aliases:
+        teams c  = create    teams a  = add       teams s  = status
+        teams rm = remove    teams d  = disband   teams ls = list
+    `,
+    });
     // list
     teams
         .command('list [query]')