switchman-dev 0.1.4 → 0.1.6

package/src/cli/index.js

@@ -19,6 +19,7 @@
 import { program } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
+import { existsSync } from 'fs';
 import { join } from 'path';
 import { execSync, spawn } from 'child_process';
 
@@ -43,6 +44,16 @@ import { installGitHubActionsWorkflow, resolveGitHubOutputTargets, writeGitHubCi
 import { importCodeObjectsToStore, listCodeObjects, materializeCodeObjects, materializeSemanticIndex, updateCodeObjectSource } from '../core/semantic.js';
 import { buildQueueStatusSummary, runMergeQueue } from '../core/queue.js';
 import { DEFAULT_LEASE_POLICY, loadLeasePolicy, writeLeasePolicy } from '../core/policy.js';
+import {
+  captureTelemetryEvent,
+  disableTelemetry,
+  enableTelemetry,
+  getTelemetryConfigPath,
+  getTelemetryRuntimeConfig,
+  loadTelemetryConfig,
+  maybePromptForTelemetry,
+  sendTelemetryEvent,
+} from '../core/telemetry.js';
 
 function installMcpConfig(targetDirs) {
   return targetDirs.flatMap((targetDir) => upsertAllProjectMcpConfigs(targetDir));
@@ -170,6 +181,40 @@ function renderMiniBar(items) {
   return items.map(({ label, value, color = chalk.white }) => `${color('■')} ${label}:${value}`).join(chalk.dim('  '));
 }
 
+function renderChip(label, value, color = chalk.white) {
+  return color(`[${label}:${value}]`);
+}
+
+function renderSignalStrip(signals) {
+  return signals.join(chalk.dim('  '));
+}
+
+function formatClockTime(isoString) {
+  if (!isoString) return null;
+  const date = new Date(isoString);
+  if (Number.isNaN(date.getTime())) return null;
+  return date.toLocaleTimeString('en-GB', {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  });
+}
+
+function buildWatchSignature(report) {
+  return JSON.stringify({
+    health: report.health,
+    summary: report.summary,
+    counts: report.counts,
+    active_work: report.active_work,
+    attention: report.attention,
+    queue_summary: report.queue?.summary || null,
+    next_up: report.next_up || null,
+    next_steps: report.next_steps,
+    suggested_commands: report.suggested_commands,
+  });
+}
+
 function formatRelativePolicy(policy) {
   return `stale ${policy.stale_after_minutes}m • heartbeat ${policy.heartbeat_interval_seconds}s • auto-reap ${policy.reap_on_status_check ? 'on' : 'off'}`;
 }
@@ -178,6 +223,169 @@ function sleepSync(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
+function boolBadge(ok) {
+  return ok ? chalk.green('OK   ') : chalk.yellow('CHECK');
+}
+
+function printErrorWithNext(message, nextCommand = null) {
+  console.error(chalk.red(message));
+  if (nextCommand) {
+    console.error(`${chalk.yellow('next:')} ${nextCommand}`);
+  }
+}
+
+async function maybeCaptureTelemetry(event, properties = {}, { homeDir = null } = {}) {
+  try {
+    await maybePromptForTelemetry({ homeDir: homeDir || undefined });
+    await captureTelemetryEvent(event, {
+      app_version: program.version(),
+      os: process.platform,
+      node_version: process.version,
+      ...properties,
+    }, { homeDir: homeDir || undefined });
+  } catch {
+    // Telemetry must never block CLI usage.
+  }
+}
+
+function collectSetupVerification(repoRoot, { homeDir = null } = {}) {
+  const dbPath = join(repoRoot, '.switchman', 'switchman.db');
+  const rootMcpPath = join(repoRoot, '.mcp.json');
+  const cursorMcpPath = join(repoRoot, '.cursor', 'mcp.json');
+  const claudeGuidePath = join(repoRoot, 'CLAUDE.md');
+  const checks = [];
+  const nextSteps = [];
+  let workspaces = [];
+  let db = null;
+
+  const dbExists = existsSync(dbPath);
+  checks.push({
+    key: 'database',
+    ok: dbExists,
+    label: 'Project database',
+    detail: dbExists ? '.switchman/switchman.db is ready' : 'Switchman database is missing',
+  });
+  if (!dbExists) {
+    nextSteps.push('Run `switchman init` or `switchman setup --agents 3` in this repo.');
+  }
+
+  if (dbExists) {
+    try {
+      db = getDb(repoRoot);
+      workspaces = listWorktrees(db);
+    } catch {
+      checks.push({
+        key: 'database_open',
+        ok: false,
+        label: 'Database access',
+        detail: 'Switchman could not open the project database',
+      });
+      nextSteps.push('Re-run `switchman init` if the project database looks corrupted.');
+    } finally {
+      try { db?.close(); } catch { /* no-op */ }
+    }
+  }
+
+  const agentWorkspaces = workspaces.filter((entry) => entry.name !== 'main');
+  const workspaceReady = agentWorkspaces.length > 0;
+  checks.push({
+    key: 'workspaces',
+    ok: workspaceReady,
+    label: 'Agent workspaces',
+    detail: workspaceReady
+      ? `${agentWorkspaces.length} agent workspace(s) registered`
+      : 'No agent workspaces are registered yet',
+  });
+  if (!workspaceReady) {
+    nextSteps.push('Run `switchman setup --agents 3` to create agent workspaces.');
+  }
+
+  const rootMcpExists = existsSync(rootMcpPath);
+  checks.push({
+    key: 'claude_mcp',
+    ok: rootMcpExists,
+    label: 'Claude Code MCP',
+    detail: rootMcpExists ? '.mcp.json is present in the repo root' : '.mcp.json is missing from the repo root',
+  });
+  if (!rootMcpExists) {
+    nextSteps.push('Re-run `switchman setup --agents 3` to restore the repo-local MCP config.');
+  }
+
+  const cursorMcpExists = existsSync(cursorMcpPath);
+  checks.push({
+    key: 'cursor_mcp',
+    ok: cursorMcpExists,
+    label: 'Cursor MCP',
+    detail: cursorMcpExists ? '.cursor/mcp.json is present in the repo root' : '.cursor/mcp.json is missing from the repo root',
+  });
+  if (!cursorMcpExists) {
+    nextSteps.push('Re-run `switchman setup --agents 3` if you want Cursor to attach automatically.');
+  }
+
+  const claudeGuideExists = existsSync(claudeGuidePath);
+  checks.push({
+    key: 'claude_md',
+    ok: claudeGuideExists,
+    label: 'Claude guide',
+    detail: claudeGuideExists ? 'CLAUDE.md is present' : 'CLAUDE.md is optional but recommended for Claude Code',
+  });
+  if (!claudeGuideExists) {
+    nextSteps.push('If you use Claude Code, add `CLAUDE.md` from the repo root setup guide.');
+  }
+
+  const windsurfConfigExists = existsSync(getWindsurfMcpConfigPath(homeDir || undefined));
+  checks.push({
+    key: 'windsurf_mcp',
+    ok: windsurfConfigExists,
+    label: 'Windsurf MCP',
+    detail: windsurfConfigExists
+      ? 'Windsurf shared MCP config is installed'
+      : 'Windsurf shared MCP config is optional and not installed',
+  });
+  if (!windsurfConfigExists) {
+    nextSteps.push('If you use Windsurf, run `switchman mcp install --windsurf` once.');
+  }
+
+  const ok = checks.every((item) => item.ok || ['claude_md', 'windsurf_mcp'].includes(item.key));
+  return {
+    ok,
+    repo_root: repoRoot,
+    checks,
+    workspaces: workspaces.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      branch: entry.branch,
+    })),
+    suggested_commands: [
+      'switchman status --watch',
+      'switchman task add "Your first task" --priority 8',
+      'switchman gate ci',
+      ...nextSteps.some((step) => step.includes('Windsurf')) ? ['switchman mcp install --windsurf'] : [],
+    ],
+    next_steps: [...new Set(nextSteps)].slice(0, 6),
+  };
+}
+
+function renderSetupVerification(report, { compact = false } = {}) {
+  console.log(chalk.bold(compact ? 'First-run check:' : 'Setup verification:'));
+  for (const check of report.checks) {
+    const badge = boolBadge(check.ok);
+    console.log(`  ${badge} ${check.label} ${chalk.dim(`— ${check.detail}`)}`);
+  }
+  if (report.next_steps.length > 0) {
+    console.log('');
+    console.log(chalk.bold('Fix next:'));
+    for (const step of report.next_steps) {
+      console.log(`  - ${step}`);
+    }
+  }
+  console.log('');
+  console.log(chalk.bold('Try next:'));
+  for (const command of report.suggested_commands.slice(0, 4)) {
+    console.log(`  ${chalk.cyan(command)}`);
+  }
+}
+
 function summarizeLeaseScope(db, lease) {
   const reservations = listScopeReservations(db, { leaseId: lease.id });
   const pathScopes = reservations
@@ -665,13 +873,34 @@ function renderUnifiedStatusReport(report) {
   const badge = healthColor(healthLabel(report.health));
   const mergeColor = report.merge_readiness.ci_gate_ok ? chalk.green : chalk.red;
   const queueCounts = report.counts.queue;
+  const blockedCount = report.attention.filter((item) => item.severity === 'block').length;
+  const warningCount = report.attention.filter((item) => item.severity !== 'block').length;
+  const focusItem = blockedCount > 0
+    ? report.attention.find((item) => item.severity === 'block')
+    : warningCount > 0
+      ? report.attention.find((item) => item.severity !== 'block')
+      : report.next_up[0];
+  const focusLine = focusItem
+    ? ('title' in focusItem
+      ? `${focusItem.title}${focusItem.detail ? ` ${chalk.dim(`• ${focusItem.detail}`)}` : ''}`
+      : `${focusItem.title} ${chalk.dim(focusItem.id)}`)
+    : 'Nothing urgent. Safe to keep parallel work moving.';
+  const queueLoad = queueCounts.queued + queueCounts.retrying + queueCounts.merging + queueCounts.blocked;
+  const landingLabel = report.merge_readiness.ci_gate_ok ? 'ready' : 'hold';
 
   console.log('');
-  console.log(healthColor('='.repeat(64)));
-  console.log(`${badge} ${chalk.bold('switchman status')} ${chalk.dim('• user-centred repo overview')}`);
+  console.log(healthColor('='.repeat(72)));
+  console.log(`${badge} ${chalk.bold('switchman status')} ${chalk.dim('• mission control for parallel agents')}`);
   console.log(`${chalk.dim(report.repo_root)}`);
   console.log(`${chalk.dim(report.summary)}`);
-  console.log(healthColor('='.repeat(64)));
+  console.log(healthColor('='.repeat(72)));
+  console.log(renderSignalStrip([
+    renderChip('health', healthLabel(report.health), healthColor),
+    renderChip('blocked', blockedCount, blockedCount > 0 ? chalk.red : chalk.green),
+    renderChip('watch', warningCount, warningCount > 0 ? chalk.yellow : chalk.green),
+    renderChip('landing', landingLabel, mergeColor),
+    renderChip('queue', queueLoad, queueLoad > 0 ? chalk.blue : chalk.green),
+  ]));
   console.log(renderMetricRow([
     { label: 'tasks', value: `${report.counts.pending}/${report.counts.in_progress}/${report.counts.done}/${report.counts.failed}`, color: chalk.white },
     { label: 'leases', value: `${report.counts.active_leases} active`, color: chalk.blue },
@@ -685,13 +914,18 @@ function renderUnifiedStatusReport(report) {
     { label: 'merging', value: queueCounts.merging, color: chalk.blue },
     { label: 'merged', value: queueCounts.merged, color: chalk.green },
   ]));
+  console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
   console.log(chalk.dim(`policy: ${formatRelativePolicy(report.lease_policy)} • requeue on reap ${report.lease_policy.requeue_task_on_reap ? 'on' : 'off'}`));
 
   const runningLines = report.active_work.length > 0
     ? report.active_work.slice(0, 5).map((item) => {
-      const boundary = item.boundary_validation ? ` validation:${item.boundary_validation.status}` : '';
-      const stale = (item.dependency_invalidations?.length || 0) > 0 ? ` stale:${item.dependency_invalidations.length}` : '';
-      return `${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${chalk.dim(boundary)}${chalk.dim(stale)}`;
+      const boundary = item.boundary_validation
+        ? ` ${renderChip('validation', item.boundary_validation.status, item.boundary_validation.status === 'accepted' ? chalk.green : chalk.yellow)}`
+        : '';
+      const stale = (item.dependency_invalidations?.length || 0) > 0
+        ? ` ${renderChip('stale', item.dependency_invalidations.length, chalk.yellow)}`
+        : '';
+      return `${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${boundary}${stale}`;
     })
     : [chalk.dim('Nothing active right now.')];
 
@@ -700,7 +934,7 @@ function renderUnifiedStatusReport(report) {
 
   const blockedLines = blockedItems.length > 0
     ? blockedItems.slice(0, 4).flatMap((item) => {
-      const lines = [`${chalk.red('BLOCK')} ${item.title}`];
+      const lines = [`${renderChip('BLOCKED', item.kind || 'item', chalk.red)} ${item.title}`];
       if (item.detail) lines.push(`  ${chalk.dim(item.detail)}`);
       lines.push(`  ${chalk.yellow('next:')} ${item.next_step}`);
       if (item.command) lines.push(`  ${chalk.cyan('run:')} ${item.command}`);
@@ -710,8 +944,7 @@ function renderUnifiedStatusReport(report) {
 
   const warningLines = warningItems.length > 0
     ? warningItems.slice(0, 4).flatMap((item) => {
-      const tone = chalk.yellow('WARN ');
-      const lines = [`${tone} ${item.title}`];
+      const lines = [`${renderChip('WATCH', item.kind || 'item', chalk.yellow)} ${item.title}`];
       if (item.detail) lines.push(`  ${chalk.dim(item.detail)}`);
       lines.push(`  ${chalk.yellow('next:')} ${item.next_step}`);
       if (item.command) lines.push(`  ${chalk.cyan('run:')} ${item.command}`);
@@ -728,7 +961,7 @@ function renderUnifiedStatusReport(report) {
         .filter((entry) => ['blocked', 'retrying', 'merging'].includes(entry.status))
         .slice(0, 4)
         .flatMap((item) => {
-          const lines = [`${statusBadge(item.status)} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`];
+          const lines = [`${renderChip(item.status.toUpperCase(), item.id, item.status === 'blocked' ? chalk.red : item.status === 'retrying' ? chalk.yellow : chalk.blue)} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`];
           if (item.last_error_summary) lines.push(`  ${chalk.red('why:')} ${item.last_error_summary}`);
           if (item.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.next_action}`);
           return lines;
@@ -738,7 +971,7 @@ function renderUnifiedStatusReport(report) {
 
   const nextActionLines = [
     ...(report.next_up.length > 0
-      ? report.next_up.map((task) => `[p${task.priority}] ${task.title} ${chalk.dim(task.id)}`)
+      ? report.next_up.map((task) => `${renderChip('NEXT', `p${task.priority}`, chalk.green)} ${task.title} ${chalk.dim(task.id)}`)
       : [chalk.dim('No pending tasks waiting right now.')]),
     '',
     ...report.suggested_commands.slice(0, 4).map((command) => `${chalk.cyan('$')} ${command}`),
@@ -859,6 +1092,23 @@ program
   .description('Conflict-aware task coordinator for parallel AI coding agents')
   .version('0.1.0');
 
+program.showHelpAfterError('(run with --help for usage examples)');
+program.addHelpText('after', `
+Start here:
+  switchman setup --agents 5
+  switchman status --watch
+  switchman gate ci
+
+Most useful commands:
+  switchman task add "Implement auth helper" --priority 9
+  switchman lease next --json
+  switchman queue run --watch
+
+Docs:
+  README.md
+  docs/setup-cursor.md
+`);
+
 // ── init ──────────────────────────────────────────────────────────────────────
 
 program
@@ -902,7 +1152,12 @@ program
   .description('One-command setup: create agent workspaces and initialise Switchman')
   .option('-a, --agents <n>', 'Number of agent workspaces to create (default: 3)', '3')
   .option('--prefix <prefix>', 'Branch prefix (default: switchman)', 'switchman')
-  .action((opts) => {
+  .addHelpText('after', `
+Examples:
+  switchman setup --agents 5
+  switchman setup --agents 3 --prefix team
+`)
+  .action(async (opts) => {
     const agentCount = parseInt(opts.agents);
 
     if (isNaN(agentCount) || agentCount < 1 || agentCount > 10) {
@@ -984,16 +1239,148 @@ program
       console.log(`     ${chalk.cyan('switchman status')}`);
       console.log('');
 
+      const verification = collectSetupVerification(repoRoot);
+      renderSetupVerification(verification, { compact: true });
+      await maybeCaptureTelemetry('setup_completed', {
+        agent_count: agentCount,
+        verification_ok: verification.ok,
+      });
+
     } catch (err) {
       spinner.fail(err.message);
       process.exit(1);
     }
   });
 
+program
+  .command('verify-setup')
+  .description('Check whether this repo is ready for a smooth first Switchman run')
+  .option('--json', 'Output raw JSON')
+  .option('--home <path>', 'Override the home directory for editor config checks')
+  .addHelpText('after', `
+Examples:
+  switchman verify-setup
+  switchman verify-setup --json
+
+Use this after setup or whenever editor/config wiring feels off.
+`)
+  .action(async (opts) => {
+    const repoRoot = getRepo();
+    const report = collectSetupVerification(repoRoot, { homeDir: opts.home || null });
+
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+      if (!report.ok) process.exitCode = 1;
+      return;
+    }
+
+    renderSetupVerification(report);
+    await maybeCaptureTelemetry(report.ok ? 'verify_setup_passed' : 'verify_setup_failed', {
+      check_count: report.checks.length,
+      next_step_count: report.next_steps.length,
+    }, { homeDir: opts.home || null });
+    if (!report.ok) process.exitCode = 1;
+  });
+
 
 // ── mcp ───────────────────────────────────────────────────────────────────────
 
 const mcpCmd = program.command('mcp').description('Manage editor connections for Switchman');
+const telemetryCmd = program.command('telemetry').description('Control anonymous opt-in telemetry for Switchman');
+
+telemetryCmd
+  .command('status')
+  .description('Show whether telemetry is enabled and where events would be sent')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .option('--json', 'Output raw JSON')
+  .action((opts) => {
+    const config = loadTelemetryConfig(opts.home || undefined);
+    const runtime = getTelemetryRuntimeConfig();
+    const payload = {
+      enabled: config.telemetry_enabled === true,
+      configured: Boolean(runtime.apiKey) && !runtime.disabled,
+      install_id: config.telemetry_install_id,
+      destination: runtime.apiKey && !runtime.disabled ? runtime.host : null,
+      config_path: getTelemetryConfigPath(opts.home || undefined),
+    };
+
+    if (opts.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+
+    console.log(`Telemetry: ${payload.enabled ? chalk.green('enabled') : chalk.yellow('disabled')}`);
+    console.log(`Configured destination: ${payload.configured ? chalk.cyan(payload.destination) : chalk.dim('not configured')}`);
+    console.log(`Config file: ${chalk.dim(payload.config_path)}`);
+    if (payload.install_id) {
+      console.log(`Install ID: ${chalk.dim(payload.install_id)}`);
+    }
+  });
+
+telemetryCmd
+  .command('enable')
+  .description('Enable anonymous telemetry for setup and operator workflows')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .action((opts) => {
+    const runtime = getTelemetryRuntimeConfig();
+    if (!runtime.apiKey || runtime.disabled) {
+      printErrorWithNext('Telemetry destination is not configured. Set SWITCHMAN_TELEMETRY_API_KEY first.', 'switchman telemetry status');
+      process.exitCode = 1;
+      return;
+    }
+    const result = enableTelemetry(opts.home || undefined);
+    console.log(`${chalk.green('✓')} Telemetry enabled`);
+    console.log(`  ${chalk.dim(result.path)}`);
+  });
+
+telemetryCmd
+  .command('disable')
+  .description('Disable anonymous telemetry')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .action((opts) => {
+    const result = disableTelemetry(opts.home || undefined);
+    console.log(`${chalk.green('✓')} Telemetry disabled`);
+    console.log(`  ${chalk.dim(result.path)}`);
+  });
+
+telemetryCmd
+  .command('test')
+  .description('Send one test telemetry event and report whether delivery succeeded')
+  .option('--home <path>', 'Override the home directory for telemetry config')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const result = await sendTelemetryEvent('telemetry_test', {
+      app_version: program.version(),
+      os: process.platform,
+      node_version: process.version,
+      source: 'switchman-cli-test',
+    }, { homeDir: opts.home || undefined });
+
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+
+    if (result.ok) {
+      console.log(`${chalk.green('✓')} Telemetry test event delivered`);
+      console.log(`  ${chalk.dim('destination:')} ${chalk.cyan(result.destination)}`);
+      if (result.status) {
+        console.log(`  ${chalk.dim('status:')} ${result.status}`);
+      }
+      return;
+    }
+
+    printErrorWithNext(`Telemetry test failed (${result.reason || 'unknown_error'}).`, 'switchman telemetry status');
+    console.log(`  ${chalk.dim('destination:')} ${result.destination || 'unknown'}`);
+    if (result.status) {
+      console.log(`  ${chalk.dim('status:')} ${result.status}`);
+    }
+    if (result.error) {
+      console.log(`  ${chalk.dim('error:')} ${result.error}`);
+    }
+    process.exitCode = 1;
+  });
 
 mcpCmd
   .command('install')
@@ -1001,6 +1388,11 @@ mcpCmd
   .option('--windsurf', 'Write Windsurf MCP config to ~/.codeium/mcp_config.json')
   .option('--home <path>', 'Override the home directory for config writes (useful for testing)')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman mcp install --windsurf
+  switchman mcp install --windsurf --json
+`)
   .action((opts) => {
     if (!opts.windsurf) {
       console.error(chalk.red('Choose an editor install target, for example `switchman mcp install --windsurf`.'));
@@ -1030,6 +1422,12 @@ mcpCmd
 // ── task ──────────────────────────────────────────────────────────────────────
 
 const taskCmd = program.command('task').description('Manage the task list');
+taskCmd.addHelpText('after', `
+Examples:
+  switchman task add "Fix login bug" --priority 8
+  switchman task list --status pending
+  switchman task done task-123
+`);
 
 taskCmd
   .command('add <title>')
@@ -1127,10 +1525,15 @@ taskCmd
 
 taskCmd
   .command('next')
-  .description('Get and assign the next pending task (compatibility shim for lease next)')
+  .description('Get the next pending task quickly (use `lease next` for the full workflow)')
   .option('--json', 'Output as JSON')
   .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
   .option('--agent <name>', 'Agent identifier for logging (e.g. claude-code)')
+  .addHelpText('after', `
+Examples:
+  switchman task next
+  switchman task next --json
+`)
   .action((opts) => {
     const repoRoot = getRepo();
     const worktreeName = getCurrentWorktreeName(opts.worktree);
@@ -1159,7 +1562,13 @@ taskCmd
 
 // ── queue ─────────────────────────────────────────────────────────────────────
 
-const queueCmd = program.command('queue').description('Land finished work safely back onto main, one item at a time');
+const queueCmd = program.command('queue').alias('land').description('Land finished work safely back onto main, one item at a time');
+queueCmd.addHelpText('after', `
+Examples:
+  switchman queue add --worktree agent1
+  switchman queue status
+  switchman queue run --watch
+`);
 
 queueCmd
   .command('add [branch]')
@@ -1170,6 +1579,12 @@ queueCmd
   .option('--max-retries <n>', 'Maximum automatic retries', '1')
   .option('--submitted-by <name>', 'Operator or automation name')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman queue add feature/auth-hardening
+  switchman queue add --worktree agent2
+  switchman queue add --pipeline pipe-123
+`)
   .action((branch, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1179,7 +1594,7 @@ queueCmd
       if (opts.worktree) {
         const worktree = listWorktrees(db).find((entry) => entry.name === opts.worktree);
         if (!worktree) {
-          throw new Error(`Worktree ${opts.worktree} is not registered.`);
+          throw new Error(`Workspace ${opts.worktree} is not registered.`);
         }
         payload = {
           sourceType: 'worktree',
@@ -1207,7 +1622,7 @@ queueCmd
           submittedBy: opts.submittedBy || null,
         };
       } else {
-        throw new Error('Provide a branch, --worktree, or --pipeline.');
+        throw new Error('Choose one source to land: a branch name, `--worktree`, or `--pipeline`.');
       }
 
       const result = enqueueMergeItem(db, payload);
@@ -1223,7 +1638,7 @@ queueCmd
       if (result.source_worktree) console.log(`  ${chalk.dim('worktree:')} ${result.source_worktree}`);
     } catch (err) {
       db.close();
-      console.error(chalk.red(err.message));
+      printErrorWithNext(err.message, 'switchman queue add --help');
       process.exitCode = 1;
     }
   });
@@ -1266,6 +1681,19 @@ queueCmd
   .command('status')
   .description('Show an operator-friendly merge queue summary')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  Use this when finished branches are waiting to land and you want one safe queue view.
+
+Examples:
+  switchman queue status
+  switchman queue status --json
+
+What it helps you answer:
+  - what lands next
+  - what is blocked
+  - what command should I run now
+`)
   .action((opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1281,18 +1709,77 @@ queueCmd
       return;
     }
 
-    console.log(`Queue: ${items.length} item(s)`);
-    console.log(`  ${chalk.dim('queued')} ${summary.counts.queued}  ${chalk.dim('validating')} ${summary.counts.validating}  ${chalk.dim('rebasing')} ${summary.counts.rebasing}  ${chalk.dim('merging')} ${summary.counts.merging}  ${chalk.dim('retrying')} ${summary.counts.retrying}  ${chalk.dim('blocked')} ${summary.counts.blocked}  ${chalk.dim('merged')} ${summary.counts.merged}`);
-    if (summary.next) {
-      console.log(`  ${chalk.dim('next:')} ${summary.next.id} ${summary.next.source_type}:${summary.next.source_ref} ${chalk.dim(`retries:${summary.next.retry_count}/${summary.next.max_retries}`)}`);
-    }
-    for (const item of summary.blocked) {
-      console.log(`  ${statusBadge(item.status)} ${item.id} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`);
-      if (item.last_error_summary) console.log(`    ${chalk.red('why:')} ${item.last_error_summary}`);
-      if (item.next_action) console.log(`    ${chalk.yellow('next:')} ${item.next_action}`);
+    const queueHealth = summary.counts.blocked > 0 ? 'block' : summary.counts.retrying > 0 ? 'warn' : 'healthy';
+    const queueHealthColor = colorForHealth(queueHealth);
+    const focus = summary.blocked[0] || summary.retrying[0] || summary.next || null;
+    const focusLine = focus
+      ? `${focus.id} ${focus.source_type}:${focus.source_ref}${focus.last_error_summary ? ` ${chalk.dim(`• ${focus.last_error_summary}`)}` : ''}`
+      : 'Nothing waiting. Landing queue is clear.';
+
+    console.log('');
+    console.log(queueHealthColor('='.repeat(72)));
+    console.log(`${queueHealthColor(healthLabel(queueHealth))} ${chalk.bold('switchman queue status')} ${chalk.dim('• landing mission control')}`);
+    console.log(queueHealthColor('='.repeat(72)));
+    console.log(renderSignalStrip([
+      renderChip('queued', summary.counts.queued, summary.counts.queued > 0 ? chalk.yellow : chalk.green),
+      renderChip('retrying', summary.counts.retrying, summary.counts.retrying > 0 ? chalk.yellow : chalk.green),
+      renderChip('blocked', summary.counts.blocked, summary.counts.blocked > 0 ? chalk.red : chalk.green),
+      renderChip('merging', summary.counts.merging, summary.counts.merging > 0 ? chalk.blue : chalk.green),
+      renderChip('merged', summary.counts.merged, summary.counts.merged > 0 ? chalk.green : chalk.white),
+    ]));
+    console.log(renderMetricRow([
+      { label: 'items', value: items.length, color: chalk.white },
+      { label: 'validating', value: summary.counts.validating, color: chalk.blue },
+      { label: 'rebasing', value: summary.counts.rebasing, color: chalk.blue },
+      { label: 'target', value: summary.next?.target_branch || 'main', color: chalk.cyan },
+    ]));
+    console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+
+    const queueFocusLines = summary.next
+      ? [
+        `${renderChip('NEXT', summary.next.id, chalk.green)} ${summary.next.source_type}:${summary.next.source_ref} ${chalk.dim(`retries:${summary.next.retry_count}/${summary.next.max_retries}`)}`,
+        `  ${chalk.yellow('run:')} switchman queue run`,
+      ]
+      : [chalk.dim('No queued landing work right now.')];
+
+    const queueBlockedLines = summary.blocked.length > 0
+      ? summary.blocked.slice(0, 4).flatMap((item) => {
+        const lines = [`${renderChip('BLOCKED', item.id, chalk.red)} ${item.source_type}:${item.source_ref} ${chalk.dim(`retries:${item.retry_count}/${item.max_retries}`)}`];
+        if (item.last_error_summary) lines.push(`  ${chalk.red('why:')} ${item.last_error_summary}`);
+        if (item.next_action) lines.push(`  ${chalk.yellow('next:')} ${item.next_action}`);
+        return lines;
+      })
+      : [chalk.green('Nothing blocked.')];
+
+    const queueWatchLines = items.filter((item) => ['retrying', 'merging', 'rebasing', 'validating'].includes(item.status)).length > 0
+      ? items
+        .filter((item) => ['retrying', 'merging', 'rebasing', 'validating'].includes(item.status))
+        .slice(0, 4)
+        .flatMap((item) => {
+          const lines = [`${renderChip(item.status.toUpperCase(), item.id, item.status === 'retrying' ? chalk.yellow : chalk.blue)} ${item.source_type}:${item.source_ref}`];
+          if (item.last_error_summary) lines.push(`  ${chalk.dim(item.last_error_summary)}`);
+          return lines;
+        })
+      : [chalk.green('No in-flight queue items right now.')];
+
+    const queueCommandLines = [
+      `${chalk.cyan('$')} switchman queue run`,
+      `${chalk.cyan('$')} switchman queue status --json`,
+      ...(summary.blocked[0] ? [`${chalk.cyan('$')} switchman queue retry ${summary.blocked[0].id}`] : []),
+    ];
+
+    console.log('');
+    for (const block of [
+      renderPanel('Landing focus', queueFocusLines, chalk.green),
+      renderPanel('Blocked', queueBlockedLines, summary.counts.blocked > 0 ? chalk.red : chalk.green),
+      renderPanel('In flight', queueWatchLines, queueWatchLines[0] === 'No in-flight queue items right now.' ? chalk.green : chalk.blue),
+      renderPanel('Next commands', queueCommandLines, chalk.cyan),
+    ]) {
+      for (const line of block) console.log(line);
+      console.log('');
     }
+
     if (recentEvents.length > 0) {
-      console.log('');
       console.log(chalk.bold('Recent Queue Events:'));
       for (const event of recentEvents) {
         console.log(`  ${chalk.cyan(event.queue_item_id)} ${chalk.dim(event.event_type)} ${chalk.dim(event.status || '')} ${chalk.dim(event.created_at)}`.trim());
@@ -1302,13 +1789,19 @@ queueCmd
 
 queueCmd
   .command('run')
-  .description('Process queued merge items serially')
+  .description('Process landing-queue items one at a time')
   .option('--max-items <n>', 'Maximum queue items to process', '1')
   .option('--target <branch>', 'Default target branch', 'main')
   .option('--watch', 'Keep polling for new queue items')
   .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '1000')
   .option('--max-cycles <n>', 'Maximum watch cycles before exiting (mainly for tests)')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Examples:
+  switchman queue run
+  switchman queue run --watch
+  switchman queue run --watch --watch-interval-ms 1000
+`)
   .action(async (opts) => {
     const repoRoot = getRepo();
 
@@ -1348,6 +1841,13 @@ queueCmd
 
       if (aggregate.processed.length === 0) {
         console.log(chalk.dim('No queued merge items.'));
+        await maybeCaptureTelemetry('queue_used', {
+          watch,
+          cycles: aggregate.cycles,
+          processed_count: 0,
+          merged_count: 0,
+          blocked_count: 0,
+        });
         return;
       }
 
@@ -1362,6 +1862,14 @@ queueCmd
           if (item.next_action) console.log(`  ${chalk.yellow('next:')} ${item.next_action}`);
         }
       }
+
+      await maybeCaptureTelemetry('queue_used', {
+        watch,
+        cycles: aggregate.cycles,
+        processed_count: aggregate.processed.length,
+        merged_count: aggregate.processed.filter((entry) => entry.status === 'merged').length,
+        blocked_count: aggregate.processed.filter((entry) => entry.status !== 'merged').length,
+      });
     } catch (err) {
       console.error(chalk.red(err.message));
       process.exitCode = 1;
@@ -1379,7 +1887,7 @@ queueCmd
     db.close();
 
     if (!item) {
-      console.error(chalk.red(`Queue item ${itemId} is not retryable.`));
+      printErrorWithNext(`Queue item ${itemId} is not retryable.`, 'switchman queue status');
       process.exitCode = 1;
       return;
     }
@@ -1402,7 +1910,7 @@ queueCmd
     db.close();
 
     if (!item) {
-      console.error(chalk.red(`Queue item ${itemId} does not exist.`));
+      printErrorWithNext(`Queue item ${itemId} does not exist.`, 'switchman queue status');
       process.exitCode = 1;
       return;
     }
@@ -1413,6 +1921,12 @@ queueCmd
 // ── pipeline ──────────────────────────────────────────────────────────────────
 
 const pipelineCmd = program.command('pipeline').description('Create and summarize issue-to-PR execution pipelines');
+pipelineCmd.addHelpText('after', `
+Examples:
+  switchman pipeline start "Harden auth API permissions"
+  switchman pipeline exec pipe-123 "/path/to/agent-command"
+  switchman pipeline status pipe-123
+`);
 
 pipelineCmd
   .command('start <title>')
@@ -1450,6 +1964,14 @@ pipelineCmd
   .command('status <pipelineId>')
   .description('Show task status for a pipeline')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  Use this when one goal has been split into several tasks and you want to see what is running, stuck, or next.
+
+Examples:
+  switchman pipeline status pipe-123
+  switchman pipeline status pipe-123 --json
+`)
   .action((pipelineId, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1463,20 +1985,74 @@ pipelineCmd
         return;
       }
 
+      const pipelineHealth = result.status === 'blocked'
+        ? 'block'
+        : result.counts.failed > 0
+          ? 'warn'
+          : result.counts.in_progress > 0
+            ? 'warn'
+            : 'healthy';
+      const pipelineHealthColor = colorForHealth(pipelineHealth);
+      const failedTask = result.tasks.find((task) => task.status === 'failed');
+      const runningTask = result.tasks.find((task) => task.status === 'in_progress');
+      const nextPendingTask = result.tasks.find((task) => task.status === 'pending');
+      const focusTask = failedTask || runningTask || nextPendingTask || result.tasks[0] || null;
+      const focusLine = focusTask
+        ? `${focusTask.title} ${chalk.dim(focusTask.id)}`
+        : 'No pipeline tasks found.';
+
+      console.log('');
+      console.log(pipelineHealthColor('='.repeat(72)));
+      console.log(`${pipelineHealthColor(healthLabel(pipelineHealth))} ${chalk.bold('switchman pipeline status')} ${chalk.dim('• pipeline mission control')}`);
       console.log(`${chalk.bold(result.title)} ${chalk.dim(result.pipeline_id)}`);
-      console.log(`  ${chalk.dim('done')} ${result.counts.done}  ${chalk.dim('in_progress')} ${result.counts.in_progress}  ${chalk.dim('pending')} ${result.counts.pending}  ${chalk.dim('failed')} ${result.counts.failed}`);
-      for (const task of result.tasks) {
+      console.log(pipelineHealthColor('='.repeat(72)));
+      console.log(renderSignalStrip([
+        renderChip('done', result.counts.done, result.counts.done > 0 ? chalk.green : chalk.white),
+        renderChip('running', result.counts.in_progress, result.counts.in_progress > 0 ? chalk.blue : chalk.green),
+        renderChip('pending', result.counts.pending, result.counts.pending > 0 ? chalk.yellow : chalk.green),
+        renderChip('failed', result.counts.failed, result.counts.failed > 0 ? chalk.red : chalk.green),
+      ]));
+      console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+
+      const runningLines = result.tasks.filter((task) => task.status === 'in_progress').slice(0, 4).map((task) => {
         const worktree = task.worktree || task.suggested_worktree || 'unassigned';
         const blocked = task.blocked_by?.length ? ` ${chalk.dim(`blocked by ${task.blocked_by.join(', ')}`)}` : '';
         const type = task.task_spec?.task_type ? ` ${chalk.dim(`[${task.task_spec.task_type}]`)}` : '';
-        console.log(`  ${statusBadge(task.status)} ${task.id} ${task.title}${type} ${chalk.dim(worktree)}${blocked}`);
+        return `${chalk.cyan(worktree)} -> ${task.title}${type} ${chalk.dim(task.id)}${blocked}`;
+      });
+
+      const blockedLines = result.tasks.filter((task) => task.status === 'failed').slice(0, 4).flatMap((task) => {
+        const type = task.task_spec?.task_type ? ` ${chalk.dim(`[${task.task_spec.task_type}]`)}` : '';
+        const lines = [`${renderChip('BLOCKED', task.id, chalk.red)} ${task.title}${type}`];
         if (task.failure?.summary) {
           const reasonLabel = humanizeReasonCode(task.failure.reason_code);
-          console.log(`    ${chalk.red('why:')} ${task.failure.summary} ${chalk.dim(`(${reasonLabel})`)}`);
-        }
-        if (task.next_action) {
-          console.log(`    ${chalk.yellow('next:')} ${task.next_action}`);
+          lines.push(`  ${chalk.red('why:')} ${task.failure.summary} ${chalk.dim(`(${reasonLabel})`)}`);
         }
+        if (task.next_action) lines.push(`  ${chalk.yellow('next:')} ${task.next_action}`);
+        return lines;
+      });
+
+      const nextLines = result.tasks.filter((task) => task.status === 'pending').slice(0, 4).map((task) => {
+        const worktree = task.suggested_worktree || task.worktree || 'unassigned';
+        const blocked = task.blocked_by?.length ? ` ${chalk.dim(`blocked by ${task.blocked_by.join(', ')}`)}` : '';
+        return `${renderChip('NEXT', task.id, chalk.green)} ${task.title} ${chalk.dim(worktree)}${blocked}`;
+      });
+
+      const commandLines = [
+        `${chalk.cyan('$')} switchman pipeline exec ${result.pipeline_id} "/path/to/agent-command"`,
+        `${chalk.cyan('$')} switchman pipeline pr ${result.pipeline_id}`,
+        ...(result.counts.failed > 0 ? [`${chalk.cyan('$')} switchman pipeline status ${result.pipeline_id}`] : []),
+      ];
+
+      console.log('');
+      for (const block of [
+        renderPanel('Running now', runningLines.length > 0 ? runningLines : [chalk.dim('No tasks are actively running.')], runningLines.length > 0 ? chalk.cyan : chalk.green),
+        renderPanel('Blocked', blockedLines.length > 0 ? blockedLines : [chalk.green('Nothing blocked.')], blockedLines.length > 0 ? chalk.red : chalk.green),
+        renderPanel('Next up', nextLines.length > 0 ? nextLines : [chalk.dim('No pending tasks left.')], chalk.green),
+        renderPanel('Next commands', commandLines, chalk.cyan),
+      ]) {
+        for (const line of block) console.log(line);
+        console.log('');
       }
     } catch (err) {
       db.close();
@@ -1666,6 +2242,14 @@ pipelineCmd
   .option('--retry-backoff-ms <ms>', 'Base backoff in milliseconds between retry attempts', '0')
   .option('--timeout-ms <ms>', 'Default command timeout in milliseconds when a task spec does not provide one', '0')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  pipeline = one goal, broken into smaller safe tasks
+
+Examples:
+  switchman pipeline exec pipe-123 "/path/to/agent-command"
+  switchman pipeline exec pipe-123 "npm test"
+`)
   .action(async (pipelineId, agentCommand, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1699,20 +2283,34 @@ pipelineCmd
       console.log(chalk.dim(result.pr.markdown.split('\n')[0]));
     } catch (err) {
       db.close();
-      console.error(chalk.red(err.message));
+      printErrorWithNext(err.message, `switchman pipeline status ${pipelineId}`);
       process.exitCode = 1;
     }
   });
 
 // ── lease ────────────────────────────────────────────────────────────────────
 
-const leaseCmd = program.command('lease').description('Manage active work leases');
+const leaseCmd = program.command('lease').alias('session').description('Manage active work sessions and keep long-running tasks alive');
+leaseCmd.addHelpText('after', `
+Plain English:
+  lease = a task currently checked out by an agent
+
+Examples:
+  switchman lease next --json
+  switchman lease heartbeat lease-123
+  switchman lease reap
+`);
 
 leaseCmd
   .command('acquire <taskId> <worktree>')
-  .description('Acquire a lease for a pending task')
+  .description('Start a tracked work session for a specific pending task')
   .option('--agent <name>', 'Agent identifier for logging')
   .option('--json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  switchman lease acquire task-123 agent2
+  switchman lease acquire task-123 agent2 --agent cursor
+`)
   .action((taskId, worktree, opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1722,7 +2320,7 @@ leaseCmd
 
     if (!lease || !task) {
       if (opts.json) console.log(JSON.stringify({ lease: null, task: null }));
-      else console.log(chalk.red(`Could not acquire lease. The task may not exist or is not pending.`));
+      else printErrorWithNext('Could not start a work session. The task may not exist or may already be in progress.', 'switchman task list --status pending');
       process.exitCode = 1;
       return;
     }
@@ -1742,10 +2340,16 @@ leaseCmd
 
 leaseCmd
   .command('next')
-  .description('Claim the next pending task and acquire its lease')
+  .description('Start the next pending task and open a tracked work session for it')
   .option('--json', 'Output as JSON')
-  .option('--worktree <name>', 'Worktree to assign the task to (defaults to current worktree name)')
+  .option('--worktree <name>', 'Workspace to assign the task to (defaults to the current folder name)')
   .option('--agent <name>', 'Agent identifier for logging')
+  .addHelpText('after', `
+Examples:
+  switchman lease next
+  switchman lease next --json
+  switchman lease next --worktree agent2 --agent cursor
+`)
   .action((opts) => {
     const repoRoot = getRepo();
     const worktreeName = getCurrentWorktreeName(opts.worktree);
@@ -1753,7 +2357,7 @@ leaseCmd
 
     if (!task) {
       if (opts.json) console.log(JSON.stringify({ task: null, lease: null }));
-      else if (exhausted) console.log(chalk.dim('No pending tasks.'));
+      else if (exhausted) console.log(chalk.dim('No pending tasks. Add one with `switchman task add "Your task"`.'));
       else console.log(chalk.yellow('Tasks were claimed by other agents during assignment. Run again to get the next one.'));
       return;
     }
@@ -1816,7 +2420,7 @@ leaseCmd
 
     if (!lease) {
       if (opts.json) console.log(JSON.stringify({ lease: null }));
-      else console.log(chalk.red(`No active lease found for ${leaseId}`));
+      else printErrorWithNext(`No active work session found for ${leaseId}.`, 'switchman lease list --status active');
       process.exitCode = 1;
       return;
     }
@@ -1832,9 +2436,14 @@ leaseCmd
 
 leaseCmd
   .command('reap')
-  .description('Expire stale leases, release their claims, and return their tasks to pending')
+  .description('Clean up abandoned work sessions and release their file locks')
   .option('--stale-after-minutes <minutes>', 'Age threshold for staleness')
   .option('--json', 'Output as JSON')
+  .addHelpText('after', `
+Examples:
+  switchman lease reap
+  switchman lease reap --stale-after-minutes 20
+`)
   .action((opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1919,11 +2528,20 @@ leasePolicyCmd
 
 // ── worktree ───────────────────────────────────────────────────────────────────
 
-const wtCmd = program.command('worktree').description('Manage worktrees');
+const wtCmd = program.command('worktree').alias('workspace').description('Manage registered workspaces (Git worktrees)');
+wtCmd.addHelpText('after', `
+Plain English:
+  worktree = the Git feature behind each agent workspace
+
+Examples:
+  switchman worktree list
+  switchman workspace list
+  switchman worktree sync
+`);
 
 wtCmd
   .command('add <name> <path> <branch>')
-  .description('Register a worktree with switchman')
+  .description('Register a workspace with Switchman')
   .option('--agent <name>', 'Agent assigned to this worktree')
   .action((name, path, branch, opts) => {
     const repoRoot = getRepo();
@@ -1935,7 +2553,7 @@ wtCmd
 
 wtCmd
   .command('list')
-  .description('List all registered worktrees')
+  .description('List all registered workspaces')
   .action(() => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1944,7 +2562,7 @@ wtCmd
     db.close();
 
     if (!worktrees.length && !gitWorktrees.length) {
-      console.log(chalk.dim('No worktrees found.'));
+      console.log(chalk.dim('No workspaces found. Run `switchman setup --agents 3` or `switchman worktree sync`.'));
       return;
     }
 
@@ -1964,7 +2582,7 @@ wtCmd
 
 wtCmd
   .command('sync')
-  .description('Sync git worktrees into the switchman database')
+  .description('Sync Git workspaces into the Switchman database')
   .action(() => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -1981,12 +2599,20 @@ wtCmd
 
 program
   .command('claim <taskId> <worktree> [files...]')
-  .description('Claim files for a task (warns if conflicts exist)')
+  .description('Lock files for a task before editing')
   .option('--agent <name>', 'Agent name')
   .option('--force', 'Claim even if conflicts exist')
+  .addHelpText('after', `
+Examples:
+  switchman claim task-123 agent2 src/auth.js src/server.js
+  switchman claim task-123 agent2 src/auth.js --agent cursor
+
+Use this before editing files in a shared repo.
+`)
   .action((taskId, worktree, files, opts) => {
     if (!files.length) {
-      console.log(chalk.yellow('No files specified. Use: switchman claim <taskId> <worktree> file1 file2 ...'));
+      console.log(chalk.yellow('No files specified.'));
+      console.log(`${chalk.yellow('next:')} switchman claim <taskId> <workspace> file1 file2`);
       return;
     }
     const repoRoot = getRepo();
@@ -2000,7 +2626,8 @@ program
         for (const c of conflicts) {
           console.log(`  ${chalk.yellow(c.file)} → already claimed by worktree ${chalk.cyan(c.claimedBy.worktree)} (task: ${c.claimedBy.task_title})`);
         }
-        console.log(chalk.dim('\nUse --force to claim anyway, or resolve conflicts first.'));
+        console.log(chalk.dim('\nUse --force to claim anyway, or pick different files first.'));
+        console.log(`${chalk.yellow('next:')} switchman status`);
         process.exitCode = 1;
         return;
       }
@@ -2009,7 +2636,7 @@ program
       console.log(`${chalk.green('✓')} Claimed ${files.length} file(s) for task ${chalk.cyan(taskId)} (${chalk.dim(lease.id)})`);
       files.forEach(f => console.log(`  ${chalk.dim(f)}`));
     } catch (err) {
-      console.error(chalk.red(err.message));
+      printErrorWithNext(err.message, 'switchman task list --status in_progress');
       process.exitCode = 1;
     } finally {
       db.close();
@@ -2181,6 +2808,12 @@ program
   .description('Scan all workspaces for conflicts')
   .option('--json', 'Output raw JSON')
   .option('--quiet', 'Only show conflicts')
+  .addHelpText('after', `
+Examples:
+  switchman scan
+  switchman scan --quiet
+  switchman scan --json
+`)
   .action(async (opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -2296,12 +2929,21 @@ program
   .option('--watch', 'Keep refreshing status in the terminal')
   .option('--watch-interval-ms <n>', 'Polling interval for --watch mode', '2000')
   .option('--max-cycles <n>', 'Maximum refresh cycles before exiting', '0')
+  .addHelpText('after', `
+Examples:
+  switchman status
+  switchman status --watch
+  switchman status --json
+
+Use this first when the repo feels stuck.
+`)
   .action(async (opts) => {
     const repoRoot = getRepo();
     const watch = Boolean(opts.watch);
     const watchIntervalMs = Math.max(100, Number.parseInt(opts.watchIntervalMs, 10) || 2000);
     const maxCycles = Math.max(0, Number.parseInt(opts.maxCycles, 10) || 0);
     let cycles = 0;
+    let lastSignature = null;
 
     while (true) {
       if (watch && process.stdout.isTTY && !opts.json) {
@@ -2316,8 +2958,16 @@ program
       } else {
         renderUnifiedStatusReport(report);
         if (watch) {
+          const signature = buildWatchSignature(report);
+          const watchState = lastSignature === null
+            ? chalk.cyan('baseline snapshot')
+            : signature === lastSignature
+              ? chalk.dim('no repo changes since last refresh')
+              : chalk.green('change detected');
+          const updatedAt = formatClockTime(report.generated_at);
+          lastSignature = signature;
           console.log('');
-          console.log(chalk.dim(`Watching every ${watchIntervalMs}ms${maxCycles > 0 ? ` • cycle ${cycles}/${maxCycles}` : ''}`));
+          console.log(chalk.dim(`Live watch • updated ${updatedAt || 'just now'} • ${watchState}${maxCycles > 0 ? ` • cycle ${cycles}/${maxCycles}` : ''} • refresh ${watchIntervalMs}ms`));
         }
       }
 
@@ -2326,12 +2976,27 @@ program
       if (opts.json) break;
       sleepSync(watchIntervalMs);
     }
+
+    if (watch) {
+      await maybeCaptureTelemetry('status_watch_used', {
+        cycles,
+        interval_ms: watchIntervalMs,
+      });
+    }
   });
 
 program
   .command('doctor')
   .description('Show one operator-focused health view: what is running, what is blocked, and what to do next')
   .option('--json', 'Output raw JSON')
+  .addHelpText('after', `
+Plain English:
+  Use this when the repo feels risky, noisy, or stuck and you want the health summary plus exact next moves.
+
+Examples:
+  switchman doctor
+  switchman doctor --json
+`)
   .action(async (opts) => {
     const repoRoot = getRepo();
     const db = getDb(repoRoot);
@@ -2356,66 +3021,83 @@ program
       return;
     }
 
-    const badge = report.health === 'healthy'
-      ? chalk.green('HEALTHY')
-      : report.health === 'warn'
-        ? chalk.yellow('ATTENTION')
-        : chalk.red('BLOCKED');
-    console.log(`${badge} ${report.summary}`);
-    console.log(chalk.dim(repoRoot));
-    console.log('');
-
-    console.log(chalk.bold('At a glance:'));
-    console.log(`  ${chalk.dim('tasks')} ${report.counts.pending} pending, ${report.counts.in_progress} in progress, ${report.counts.done} done, ${report.counts.failed} failed`);
-    console.log(`  ${chalk.dim('leases')} ${report.counts.active_leases} active, ${report.counts.stale_leases} stale`);
-    console.log(`  ${chalk.dim('merge')} CI ${report.merge_readiness.ci_gate_ok ? chalk.green('clear') : chalk.red('blocked')}  AI ${report.merge_readiness.ai_gate_status}`);
+    const doctorColor = colorForHealth(report.health);
+    const blockedCount = report.attention.filter((item) => item.severity === 'block').length;
+    const warningCount = report.attention.filter((item) => item.severity !== 'block').length;
+    const focusItem = report.attention[0] || report.active_work[0] || null;
+    const focusLine = focusItem
+      ? `${focusItem.title || focusItem.task_title}${focusItem.detail ? ` ${chalk.dim(`• ${focusItem.detail}`)}` : ''}`
+      : 'Nothing urgent. Repo health looks steady.';
 
-    if (report.active_work.length > 0) {
-      console.log('');
-      console.log(chalk.bold('Running now:'));
-      for (const item of report.active_work.slice(0, 5)) {
+    console.log('');
+    console.log(doctorColor('='.repeat(72)));
+    console.log(`${doctorColor(healthLabel(report.health))} ${chalk.bold('switchman doctor')} ${chalk.dim('• repo health mission control')}`);
+    console.log(chalk.dim(repoRoot));
+    console.log(chalk.dim(report.summary));
+    console.log(doctorColor('='.repeat(72)));
+    console.log(renderSignalStrip([
+      renderChip('blocked', blockedCount, blockedCount > 0 ? chalk.red : chalk.green),
+      renderChip('watch', warningCount, warningCount > 0 ? chalk.yellow : chalk.green),
+      renderChip('leases', report.counts.active_leases, report.counts.active_leases > 0 ? chalk.blue : chalk.green),
+      renderChip('stale', report.counts.stale_leases, report.counts.stale_leases > 0 ? chalk.red : chalk.green),
+      renderChip('merge', report.merge_readiness.ci_gate_ok ? 'clear' : 'hold', report.merge_readiness.ci_gate_ok ? chalk.green : chalk.red),
+    ]));
+    console.log(renderMetricRow([
+      { label: 'tasks', value: `${report.counts.pending}/${report.counts.in_progress}/${report.counts.done}/${report.counts.failed}`, color: chalk.white },
+      { label: 'AI gate', value: report.merge_readiness.ai_gate_status, color: report.merge_readiness.ai_gate_status === 'blocked' ? chalk.red : report.merge_readiness.ai_gate_status === 'warn' ? chalk.yellow : chalk.green },
+    ]));
+    console.log(`${chalk.bold('Focus now:')} ${focusLine}`);
+
+    const runningLines = report.active_work.length > 0
+      ? report.active_work.slice(0, 5).map((item) => {
         const leaseId = activeLeases.find((lease) => lease.task_id === item.task_id && lease.worktree === item.worktree)?.id || null;
         const boundary = item.boundary_validation
-          ? ` ${chalk.dim(`validation:${item.boundary_validation.status}`)}`
+          ? ` ${renderChip('validation', item.boundary_validation.status, item.boundary_validation.status === 'accepted' ? chalk.green : chalk.yellow)}`
           : '';
         const stale = (item.dependency_invalidations?.length || 0) > 0
-          ? ` ${chalk.dim(`stale:${item.dependency_invalidations.length}`)}`
+          ? ` ${renderChip('stale', item.dependency_invalidations.length, chalk.yellow)}`
           : '';
-        console.log(`  ${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${leaseId ? ` ${chalk.dim(`lease:${leaseId}`)}` : ''}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${boundary}${stale}`);
-      }
-    }
+        return `${chalk.cyan(item.worktree)} -> ${item.task_title} ${chalk.dim(item.task_id)}${leaseId ? ` ${chalk.dim(`lease:${leaseId}`)}` : ''}${item.scope_summary ? ` ${chalk.dim(item.scope_summary)}` : ''}${boundary}${stale}`;
+      })
+      : [chalk.dim('Nothing active right now.')];
+
+    const attentionLines = report.attention.length > 0
+      ? report.attention.slice(0, 6).flatMap((item) => {
+        const lines = [`${item.severity === 'block' ? renderChip('BLOCKED', item.kind || 'item', chalk.red) : renderChip('WATCH', item.kind || 'item', chalk.yellow)} ${item.title}`];
+        if (item.detail) lines.push(`  ${chalk.dim(item.detail)}`);
+        lines.push(`  ${chalk.yellow('next:')} ${item.next_step}`);
+        if (item.command) lines.push(`  ${chalk.cyan('run:')} ${item.command}`);
+        return lines;
+      })
+      : [chalk.green('Nothing urgent.')];
+
+    const nextStepLines = [
+      ...report.next_steps.slice(0, 4).map((step) => `- ${step}`),
+      '',
+      ...report.suggested_commands.slice(0, 4).map((command) => `${chalk.cyan('$')} ${command}`),
+    ];
 
     console.log('');
     console.log(chalk.bold('Attention now:'));
-    if (report.attention.length === 0) {
-      console.log(`  ${chalk.green('Nothing urgent.')}`);
-    } else {
-      for (const item of report.attention.slice(0, 6)) {
-        const itemBadge = item.severity === 'block' ? chalk.red('block') : chalk.yellow('warn ');
-        console.log(`  ${itemBadge} ${item.title}`);
-        if (item.detail) console.log(`        ${chalk.dim(item.detail)}`);
-        console.log(`        ${chalk.yellow('next:')} ${item.next_step}`);
-        if (item.command) console.log(`        ${chalk.cyan('run:')} ${item.command}`);
-      }
-    }
-
-    console.log('');
-    console.log(chalk.bold('Recommended next steps:'));
-    for (const step of report.next_steps) {
-      console.log(`  - ${step}`);
-    }
-    if (report.suggested_commands.length > 0) {
+    for (const block of [
+      renderPanel('Running now', runningLines, chalk.cyan),
+      renderPanel('Attention now', attentionLines, report.attention.some((item) => item.severity === 'block') ? chalk.red : report.attention.length > 0 ? chalk.yellow : chalk.green),
+      renderPanel('Recommended next steps', nextStepLines, chalk.green),
+    ]) {
+      for (const line of block) console.log(line);
       console.log('');
-      console.log(chalk.bold('Suggested commands:'));
-      for (const command of report.suggested_commands) {
-        console.log(`  ${chalk.cyan(command)}`);
-      }
     }
   });
 
 // ── gate ─────────────────────────────────────────────────────────────────────
 
 const gateCmd = program.command('gate').description('Safety checks for edits, merges, and CI');
+gateCmd.addHelpText('after', `
+Examples:
+  switchman gate ci
+  switchman gate ai
+  switchman gate install-ci
+`);
 
 const auditCmd = program.command('audit').description('Inspect and verify the tamper-evident audit trail');
 
@@ -2612,6 +3294,15 @@ gateCmd
       }
     }
 
+    await maybeCaptureTelemetry(ok ? 'gate_ci_passed' : 'gate_ci_failed', {
+      worktree_count: report.worktrees.length,
+      unclaimed_change_count: result.unclaimed_changes.length,
+      file_conflict_count: result.file_conflicts.length,
+      ownership_conflict_count: result.ownership_conflicts.length,
+      semantic_conflict_count: result.semantic_conflicts.length,
+      branch_conflict_count: result.branch_conflicts.length,
+    });
+
     if (!ok) process.exitCode = 1;
   });