@productbrain/cli 0.1.0-beta.14 → 0.1.0-beta.1400

package/dist/index.js

@@ -7,17 +7,23 @@
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Command } from 'commander';
+import { Command, CommanderError } from 'commander';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const cliPackageVersion = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-import { setOutputMode } from './lib/runner.js';
+import { setOutputMode, setQuietMode, isJsonMode } from './lib/runner.js';
+import { CLIError, ErrorCode } from './lib/errors.js';
 import { runContext } from './commands/context.js';
 import { runGet, runGetMany } from './commands/get.js';
+import { runConnect } from './commands/connect.js';
 import { runLogin } from './commands/login.js';
+import { runSetup } from './commands/setup.js';
+import { runSetupDetectSurfaces, formatDetectSurfacesSummary } from './commands/setup-detect-surfaces.js';
+import { runSetupState } from './commands/setup-state.js';
+import { runSetupAudit } from './commands/setup-audit.js';
 import { runOrient } from './commands/orient.js';
 import { runSearch } from './commands/search.js';
 import { runHandshake, runHandshakeInit } from './commands/handshake.js';
-import { runSessionStart, runSessionClose, runSessionId } from './commands/session.js';
+import { runSessionStart, runSessionClose, runSessionId, runSessionReset } from './commands/session.js';
 import { runCapture } from './commands/capture.js';
 import { runUpdate } from './commands/update.js';
 import { runRelate, runUnrelate } from './commands/relate.js';
@@ -35,16 +41,133 @@ import { runChainWalk } from './commands/chain-walk.js';
 import { runCrossCut } from './commands/cross-cut.js';
 import { runBrief, runCompoundBrief, isCompoundType } from './commands/brief.js';
 import { runVerify } from './commands/verify.js';
+import { runCodexPrep } from './commands/codex-prep.js';
+import { runCollectionsList, runCollectionsGet, runCollectionsAudit, runCollectionsExport } from './commands/collections.js';
+import { runWorkspaceVerify, runWorkspaceRepair, runDefinitionsDiff } from './commands/workspace.js';
+import { runAuthorityDomainsActivateCutover, runAuthorityDomainsAdd, runAuthorityDomainsDeactivateCutover, runAuthorityDomainsBenchmark, runAuthorityDomainsDiscardPending, runAuthorityDomainsPropose, runAuthorityDomainsQueueTag, runAuthorityDomainsRatify, runAuthorityDomainsReadiness, runAuthorityDomainsRecordSample, runAuthorityDomainsReject, runAuthorityDomainsReview, runAuthorityDomainsPrincipleDistribution, } from './commands/authority-domains.js';
+import { runDoctor } from './commands/doctor.js';
+import { runWhoami } from './commands/whoami.js';
+import { runUpgrade } from './commands/upgrade.js';
+import { runProfileList, runProfileCreate, runProfileUse, runProfileDelete } from './commands/profile.js';
+import { runInit } from './commands/init.js';
+import { runMethodList, runMethodShow, runMethodDiff, runMethodPublish } from './commands/method.js';
+import { createAdminCommand } from './commands/admin/index.js';
+import { runUsage } from './commands/usage.js';
+import { runProofRun } from './commands/proof-run.js';
+import { GLOSSARY, formatGlossary } from './lib/glossary.js';
+import { API_KEY_PREFIX } from './lib/tokenConstants.js';
+import { hint, heading, bold, dim, green, icons, yellow } from './lib/style.js';
+import { getPreviewBinding } from './lib/config.js';
+import { checkForUpdate } from './lib/update-check.js';
+import { UPGRADE_COMMAND } from './lib/constants.js';
+import { resolveSetupState, detectRenderTier } from './lib/state.js';
 const program = new Command();
+/**
+ * Top-level Chain-write commands that receive the throwaway-writes advisory in
+ * addition to the PREVIEW banner. Each is registered directly on `program`, so
+ * `actionCommand.name()` matches verbatim. We gate on top-level (parent === program)
+ * to avoid false positives from nested commands whose leaf name collides
+ * (e.g. `pb workspace verify`, which is a health check, not a Chain write).
+ */
+const PREVIEW_WRITE_COMMANDS = new Set([
+    'capture',
+    'update',
+    'verify',
+    'promote',
+    'relate',
+    'unrelate',
+    'ingest',
+    'accept',
+    'reject',
+]);
+/**
+ * Print a loud PREVIEW banner to stderr when pb is bound to a throwaway preview.
+ *
+ * Writes to stderr (NOT stdout) so stdout stays clean JSON for agents — and so the
+ * banner appears even when --json or --quiet are set, which is the whole point: the
+ * agent must see it every time. Cheap + synchronous (one file read). Never throws.
+ *
+ * For every Chain-write command (see PREVIEW_WRITE_COMMANDS), also writes an
+ * advisory reminding the user that real learnings belong in the real Chain.
+ */
+function printPreviewBanner(actionCommand) {
+    try {
+        const binding = getPreviewBinding();
+        if (!binding)
+            return;
+        const name = binding.workspaceName ?? 'preview';
+        process.stderr.write(yellow(bold(`⚠ PREVIEW ${name} — writes are throwaway. npm run pb:real to return to the real Chain`)) + '\n');
+        const isTopLevel = actionCommand.parent?.name() === 'pb';
+        if (isTopLevel && PREVIEW_WRITE_COMMANDS.has(actionCommand.name())) {
+            process.stderr.write(`  → real learnings belong in the real Chain. Switch back with: npm run pb:real\n`);
+        }
+    }
+    catch {
+        // Never let the banner crash the CLI
+    }
+}
+/**
+ * Global error handler — single exit point for all CLI errors.
+ * CLIError: format with code + category + guidance.
+ * CommanderError: re-throw for --help / --version (exitCode 0), format others.
+ * Regular Error: wrap as INTERNAL.
+ */
+function handleError(err) {
+    // Commander help/version exits with code 0 — let them through
+    if (err instanceof CommanderError && err.exitCode === 0) {
+        process.exit(0);
+    }
+    const json = isJsonMode();
+    if (err instanceof CLIError) {
+        if (json) {
+            process.stderr.write(JSON.stringify(err.toJSON()) + '\n');
+        }
+        else {
+            process.stderr.write(err.message + '\n');
+            if (err.guidance) {
+                process.stderr.write(err.guidance + '\n');
+            }
+        }
+        process.exit(1);
+    }
+    // CommanderError (bad usage, missing args, etc.)
+    if (err instanceof CommanderError) {
+        const cliErr = new CLIError(err.message, {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+        });
+        if (json) {
+            process.stderr.write(JSON.stringify(cliErr.toJSON()) + '\n');
+        }
+        else {
+            process.stderr.write(err.message + '\n');
+        }
+        process.exit(err.exitCode);
+    }
+    // Unknown / unstructured errors
+    const message = err instanceof Error ? err.message : String(err);
+    if (json) {
+        process.stderr.write(JSON.stringify({ error: message, code: 'INTERNAL', category: 'internal' }) + '\n');
+    }
+    else {
+        process.stderr.write(message + '\n');
+    }
+    process.exit(1);
+}
 program
     .name('pb')
     .description('Product Brain — Chain knowledge + write-back CLI')
     .version(cliPackageVersion.version)
     // Global output mode flags (DEC-299, BET-181)
     .option('--json', 'Output machine-readable JSON (overrides TTY auto-detection)')
-    .option('--pretty', 'Force human-readable output even when piped');
+    .option('--pretty', 'Force human-readable output even when piped')
+    .option('-q, --quiet', 'Suppress non-essential output (banners, hints, progress)')
+    .exitOverride(); // Throw CommanderError instead of calling process.exit directly
 // Apply global output mode BEFORE subcommand actions run
-program.hook('preAction', (thisCommand) => {
+// Commander preAction hook signature: (hookedCommand, actionCommand)
+// hookedCommand = the command where hook was registered (root program)
+// actionCommand = the subcommand actually being invoked
+program.hook('preAction', (_hookedCommand, actionCommand) => {
     const globalOpts = program.opts();
     if (globalOpts.json) {
         setOutputMode('json');
@@ -53,7 +176,128 @@ program.hook('preAction', (thisCommand) => {
         setOutputMode('pretty');
     }
     // else: 'auto' (default) — TTY detection handles it
-    void thisCommand;
+    if (globalOpts.quiet) {
+        setQuietMode(true);
+    }
+    // Ambient update notification — non-blocking, suppressed in JSON mode (WP-322 S1)
+    checkForUpdate(cliPackageVersion.version);
+    // PREVIEW banner — writes to stderr so it's always visible even in --json/--quiet mode.
+    // Advisory line added for top-level Chain-write commands: real learnings belong in the real Chain.
+    printPreviewBanner(actionCommand);
+});
+// Default action — status dashboard when `pb` is invoked with no command.
+// `pb --help` still works because Commander intercepts --help before the action runs.
+program.action(async () => {
+    // Alias handling — forward common shorthands before showing the welcome screen
+    if (program.args.length > 0) {
+        const args = program.args;
+        // `pb start` / `pb start session` → `pb session start`
+        if (args[0] === 'start') {
+            await runSessionStart();
+            return;
+        }
+        // `pb close` / `pb close session` → `pb session close`
+        if (args[0] === 'close') {
+            await runSessionClose({});
+            return;
+        }
+        // Unknown command — show a helpful error instead of the welcome screen
+        const unknown = args[0];
+        process.stderr.write(`error: unknown command '${unknown}'\n`);
+        process.stderr.write(`Run 'pb --help' to see available commands.\n`);
+        process.exit(1);
+    }
+    const tier = detectRenderTier();
+    // JSON tier — structured status output
+    if (tier === 'json') {
+        // Check for API key first (sync, no network)
+        let hasKey = false;
+        try {
+            const { getConfig: gc } = await import('./lib/config.js');
+            gc();
+            hasKey = true;
+        }
+        catch {
+            // No valid key
+        }
+        if (!hasKey) {
+            process.stdout.write(JSON.stringify({
+                configured: false,
+                hint: 'Run pb login to configure your API key.',
+            }) + '\n');
+            return;
+        }
+        const { readSession } = await import('./lib/session.js');
+        const { probeWorkspace } = await import('./lib/workspace-probe.js');
+        const session = readSession();
+        const wsInfo = await probeWorkspace();
+        process.stdout.write(JSON.stringify({
+            configured: true,
+            workspace: wsInfo?.name ?? null,
+            session: session ? { id: session.sessionId, startedAt: session.startedAt } : null,
+            entryCount: wsInfo?.entryCount ?? null,
+            hint: 'Run pb --help for available commands.',
+        }) + '\n');
+        return;
+    }
+    // Ink tier: suppress withSpinner output before Ink mounts — spinner writes pollute the TUI canvas
+    if (tier === 'ink')
+        setQuietMode(true);
+    // Resolve state (plain and ink both need it)
+    const state = await resolveSetupState();
+    // Plain tier — console output driven by state
+    if (tier === 'plain') {
+        process.stdout.write('\n');
+        if (state.stage === 'unconfigured') {
+            process.stdout.write(`${bold('Product Brain')} ${dim('— not connected')}\n\n`);
+            process.stdout.write(`${heading('Get started')}\n\n`);
+            hint('1. pb login      Save your API key');
+            hint('2. pb connect    Connect a workspace');
+            hint('3. pb orient -b  See what\'s happening');
+            process.stdout.write('\n');
+            hint('pb --help        Show all commands');
+            process.stdout.write('\n');
+        }
+        else if (state.stage === 'authenticated') {
+            process.stdout.write(`${bold('Product Brain')} ${dim('— server unreachable')}\n\n`);
+            process.stdout.write(`  ${green(icons.pass)} Key: configured\n`);
+            process.stdout.write(`  ! Server: unreachable — run pb doctor to diagnose\n\n`);
+            hint('pb session start    Start a write session');
+            hint('pb doctor           Diagnose connection issues');
+            hint('pb --help           Show all commands');
+            process.stdout.write('\n');
+        }
+        else {
+            // workspace-bound or active
+            const workspaceName = state.workspaceName ?? 'unknown';
+            const entryCount = state.entryCount ?? 0;
+            const title = `${bold('Product Brain')} ${dim('—')} ${bold(workspaceName)}`;
+            process.stdout.write(`${title}\n\n`);
+            process.stdout.write(`  ${green(icons.pass)} Key: configured\n`);
+            process.stdout.write(`  ${green(icons.pass)} Workspace: ${workspaceName}  (${entryCount} entries)\n`);
+            if (state.sessionActive) {
+                process.stdout.write(`  ${green(icons.pass)} Session: active\n`);
+            }
+            else {
+                process.stdout.write(`  ${dim('- Session: none')}\n`);
+            }
+            process.stdout.write('\n');
+            if (!state.sessionActive) {
+                hint('pb session start    Start a write session');
+            }
+            hint('pb orient -b        Workspace overview');
+            hint('pb --help           Show all commands');
+            process.stdout.write('\n');
+        }
+        return;
+    }
+    // Ink tier — interactive TUI
+    const version = cliPackageVersion.version;
+    const { render } = await import('ink');
+    const { WelcomeCockpit } = await import('./commands/welcome.js');
+    const React = await import('react');
+    const { waitUntilExit, unmount } = render(React.default.createElement(WelcomeCockpit, { state, version, onExit: () => unmount() }));
+    await waitUntilExit();
 });
 program
     .command('get <entry-id>')
@@ -63,25 +307,13 @@ program
         program.commands.find((c) => c.name() === 'get')?.help();
         return;
     }
-    try {
-        await runGet({ entryId: entryId.trim() });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runGet({ entryId: entryId.trim() });
 });
 program
     .command('get-many <entry-ids...>')
     .description('Fetch multiple entries in parallel (space-separated IDs)')
     .action(async (entryIds) => {
-    try {
-        await runGetMany({ entryIds: entryIds.map((id) => id.trim()).filter(Boolean) });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runGetMany({ entryIds: entryIds.map((id) => id.trim()).filter(Boolean) });
 });
 program
     .command('context <entry-id>')
@@ -91,26 +323,14 @@ program
         program.commands.find((c) => c.name() === 'context')?.help();
         return;
     }
-    try {
-        await runContext({ entryId: entryId.trim() });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runContext({ entryId: entryId.trim() });
 });
 program
     .command('changes')
     .description('Detect entries modified and relations created since a given time (BET-239)')
     .requiredOption('--since <duration>', 'Time window: 1h, 6h, 1d, 7d, 30d')
     .action(async (opts) => {
-    try {
-        await runChanges({ since: opts.since });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runChanges({ since: opts.since });
 });
 program
     .command('walk <entry-id>')
@@ -119,36 +339,26 @@ program
     .option('--direction <dir>', 'Traversal direction: outgoing or incoming (default outgoing)', 'outgoing')
     .option('-t, --type <relation-type>', 'Filter by relation type (e.g. depends_on, informs, governs)')
     .action(async (entryId, opts) => {
-    try {
-        const depth = parseInt(opts.depth, 10);
-        if (isNaN(depth) || depth < 1 || depth > 4) {
-            console.error('--depth must be between 1 and 4.');
-            process.exit(1);
-        }
-        await runChainWalk({
-            entryId: entryId.trim(),
-            depth,
-            direction: opts.direction,
-            type: opts.type,
+    const depth = parseInt(opts.depth, 10);
+    if (isNaN(depth) || depth < 1 || depth > 4) {
+        throw new CLIError('--depth must be between 1 and 4.', {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
         });
     }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runChainWalk({
+        entryId: entryId.trim(),
+        depth,
+        direction: opts.direction,
+        type: opts.type,
+    });
 });
 program
     .command('cross-cut')
     .description('Structural aggregation — all relations of a given type grouped by source collection (BET-239)')
     .requiredOption('--type <relation-type>', 'Relation type to scan (e.g. part_of, informs, governs)')
     .action(async (opts) => {
-    try {
-        await runCrossCut({ type: opts.type });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runCrossCut({ type: opts.type });
 });
 program
     .command('brief [type]')
@@ -161,27 +371,20 @@ program
     .option('--since-last', 'Compare against last brief run (incremental mode)')
     .option('--since <timestamp>', 'ISO 8601 timestamp for delta type (e.g. 2026-03-24T00:00:00Z)')
     .action(async (type, opts) => {
-    try {
-        // If positional arg is a compound type, route to compound brief
-        if (type && isCompoundType(type)) {
-            await runCompoundBrief({ type, since: opts.since });
-            return;
-        }
-        // Otherwise, require --skill for incremental brief
-        if (!opts.skill) {
-            console.error('Usage:\n' +
-                '  pb brief --skill <name>    Incremental delta\n' +
-                '  pb brief steering          Compound steering brief\n' +
-                '  pb brief confidence        Compound confidence pass\n' +
-                '  pb brief delta             Compound delta sync');
-            process.exit(1);
-        }
-        await runBrief({ skill: opts.skill, sinceLast: opts.sinceLast });
+    // If positional arg is a compound type, route to compound brief
+    if (type && isCompoundType(type)) {
+        await runCompoundBrief({ type, since: opts.since });
+        return;
     }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    // Otherwise, require --skill for incremental brief
+    if (!opts.skill) {
+        throw new CLIError('Usage:\n' +
+            '  pb brief --skill <name>    Incremental delta\n' +
+            '  pb brief steering          Compound steering brief\n' +
+            '  pb brief confidence        Compound confidence pass\n' +
+            '  pb brief delta             Compound delta sync', { code: ErrorCode.VALIDATION_FAILED, category: 'validation' });
     }
+    await runBrief({ skill: opts.skill, sinceLast: opts.sinceLast });
 });
 program
     .command('search [query...]')
@@ -192,59 +395,132 @@ program
         program.commands.find((c) => c.name() === 'search')?.help();
         return;
     }
-    try {
-        await runSearch({ query });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runSearch({ query });
 });
 program
     .command('orient')
     .description('Print workspace stage and all orient sections (strategic context, bets, governance, tensions, etc.)')
     .option('-b, --brief', 'Compact view: stage, counts, top bets, tensions, planned work')
+    .option('-t, --task <task>', 'Task description for task-shaped governance and context')
+    .option('-s, --scope <domain>', 'Domain scope for governance filtering. Forwarded to the workspace model for validation and custom domain resolution.')
+    .option('--full', 'Full depth orient (tier=full). Use for thorough context loading.')
     .action(async (opts) => {
-    try {
-        await runOrient({ brief: opts.brief });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runOrient({ brief: opts.brief, task: opts.task?.trim() || undefined, scope: opts.scope?.trim() || undefined, full: opts.full });
 });
 program
     .command('handshake')
-    .description('Generate context files for AI developer tools (CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md)')
+    .description('Generate context files for AI developer tools (AGENTS.md, .codex/skills/, CLAUDE.md, .cursor/rules/, .github/copilot-instructions.md)')
     .option('--force', 'Overwrite adapter files even if they exist without auto-generated marker')
-    .option('--dry-run', 'Show what would be generated without writing files')
+    .option('--apply', 'Write files (default: preview only)')
+    .option('--dry-run', 'Show what would be generated without writing files (alias for preview)')
     .option('--init', 'Set up Claude Code integration: team hooks + personal trust level')
     .option('--level <level>', 'With --init: trust level (guide|work|silent|full-trust). Without --init: content tier (beginner|intermediate|expert)')
+    .option('--generate', 'Fetch governance entries from the Chain and merge generated rules (BET-286)')
+    .option('--surfaces <list>', 'Comma-separated surfaces to write (cursor,claude,copilot,codex)')
+    .option('--no-prompt', 'Headless mode: refuse on tampered projection files (WP-421 S3, doneWhen #17). Always implied when stdout is not a TTY.')
+    .option('--lenient', 'WP-439 S4: continue past setup-asset body fetch failures with a warning (legacy behaviour). By default, body fetch failures are hard errors; run `pb setup-audit --repair` to fix orphaned rows.')
     .action(async (opts) => {
-    try {
-        if (opts.init) {
-            await runHandshakeInit({ level: opts.level, dryRun: opts.dryRun });
-            return;
-        }
-        await runHandshake({ force: opts.force, dryRun: opts.dryRun, level: opts.level });
+    if (opts.init) {
+        await runHandshakeInit({ level: opts.level, dryRun: opts.dryRun });
+        return;
     }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    // Commander turns `--no-prompt` into `prompt: false`. We invert so HandshakeOptions sees noPrompt=true.
+    const noPrompt = opts.prompt === false;
+    // Attribute the bare-handshake invocation so its context.served row is separable from
+    // session-start ('session-start') / session-close ('session-close') / manual orient rows.
+    // Without this, the kernel used to coerce the absent path to 'manual-orient', polluting the
+    // proof slice that isolates manual `pb orient --task` rows (the 'handshake' union member was
+    // otherwise never emitted).
+    await runHandshake({ force: opts.force, apply: opts.apply, dryRun: opts.dryRun, level: opts.level, generate: opts.generate, surfaces: opts.surfaces?.split(','), noPrompt, lenient: opts.lenient, invocationPath: 'handshake' });
+});
+program
+    .command('codex-prep <task...>')
+    .description('Generate task-specific governance context for Codex (.codex/task-context.md)')
+    .option('--dry-run', 'Print to stdout instead of writing file')
+    .option('--full', 'Full depth orient (tier=full). Use for thorough context loading.')
+    .action(async (taskParts, opts) => {
+    const task = taskParts.join(' ').trim();
+    if (!task) {
+        program.commands.find((c) => c.name() === 'codex-prep')?.help();
+        return;
+    }
+    await runCodexPrep({ task, dryRun: opts.dryRun, full: opts.full });
+});
+program
+    .command('init')
+    .description('Detect setup state and guide you through configuration (WP-303)')
+    .action(async () => {
+    await runInit();
+});
+program
+    .command('connect <token>')
+    .description('Redeem an onboarding token and save your API key locally (FEAT-958). Uses CONVEX_SITE_URL if set, otherwise the production gateway. Override with --gateway or PB_CONNECT_GATEWAY_URL. Optional --name sets the key label in workspace settings (useful in non-interactive shells).')
+    .option('--gateway <url>', 'Override redeem gateway (default: CONVEX_SITE_URL or production). Use when token came from a different Convex deployment.')
+    .option('--name <label>', 'Optional label for this API key in workspace settings. In non-interactive terminals, use this instead of a prompt.')
+    .action(async (token, opts) => {
+    if (!token?.trim()) {
+        program.commands.find((c) => c.name() === 'connect')?.help();
+        return;
     }
+    await runConnect(token.trim(), { gateway: opts.gateway, name: opts.name });
 });
 program
     .command('login')
     .description('Save your API key to ~/.config/productbrain/.env (works from any directory)')
     .action(async () => {
-    try {
-        await runLogin();
+    await runLogin();
+});
+program
+    .command('doctor')
+    .description('Check CLI configuration and connectivity')
+    .option('--fix', 'Auto-repair common configuration issues')
+    .option('--dry-run', 'Preview what --fix would do without changing anything')
+    .action(async (opts) => {
+    await runDoctor({ fix: opts.fix, dryRun: opts.dryRun });
+});
+program
+    .command('whoami')
+    .alias('status')
+    .description('Show the active profile + workspace (fast; no session required).')
+    .action(async () => {
+    await runWhoami();
+});
+program
+    .command('setup')
+    .description('Canonical pb-setup entry (DEC-995): detect surfaces, read state, emit JSON for the skill body.')
+    .action(async () => {
+    await runSetup();
+});
+program
+    .command('setup-detect-surfaces')
+    .description('Detect local surface markers and union-merge into manifest.surfaces (STD-235 forward-only)')
+    .action(async () => {
+    const result = await runSetupDetectSurfaces();
+    if (process.stdout.isTTY) {
+        process.stdout.write(formatDetectSurfacesSummary(result) + '\n');
     }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    else {
+        process.stderr.write(formatDetectSurfacesSummary(result) + '\n');
     }
 });
+program
+    .command('setup-state')
+    .description('Emit compact JSON of getPbSetupState (machine-readable, used by the pb-setup skill body)')
+    .action(async () => {
+    await runSetupState();
+});
+// WP-439 S2: setup-asset orphan audit. Read-only diagnostic; exits 1 if any
+// setup_asset row has a broken body wiring (will fail at handshake).
+// WP-439 S3: --repair attempts to restore class III/II orphans from STARTER_*
+// constants. Class I (inline-only) and IV (hash drift) are NOT touched.
+program
+    .command('setup-audit')
+    .description('Audit setup_asset rows for orphaned bodies (WP-439 S2/S3). Exits 1 if any orphan or repair-failure.')
+    .option('--json', 'Emit machine-readable JSON (overrides pretty output for this command)')
+    .option('--repair', 'Attempt to restore class III/II orphans from STARTER_* constants (WP-439 S3)')
+    .action(async (opts) => {
+    await runSetupAudit({ json: opts.json, repair: opts.repair });
+});
 // --- Write commands (require active session) ---
 const sessionCmd = program
     .command('session')
@@ -254,38 +530,30 @@ sessionCmd
     .description('Start a tracked write session (opens session, refreshes context)')
     .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
     .action(async (opts) => {
-    try {
-        await runSessionStart({ json: opts.json });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runSessionStart({ json: opts.json });
 });
 sessionCmd
     .command('id')
     .description('Print current session ID to stdout (machine-readable, TEN-707)')
     .action(() => {
-    try {
-        runSessionId();
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    runSessionId();
 });
 sessionCmd
     .command('close')
     .description('Close the active session (wrapup, refresh context)')
     .option('--force', 'Clear local session state even if server close fails')
     .action(async (opts) => {
-    try {
-        await runSessionClose({ force: opts.force });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runSessionClose({ force: opts.force });
+});
+// TEN-2189 / WP-456 E2: hard-reset worktree-local session state (no resume marker)
+// + clear the PREVIEW_MODE marker. Recovery path for a session stranded on the wrong
+// workspace after a pb:preview/pb:real binding flip.
+sessionCmd
+    .command('reset')
+    .description('Hard-reset local session state (discard session.json + clear PREVIEW_MODE)')
+    .option('--force', 'Skip the confirmation prompt when an active session is present')
+    .action(async (opts) => {
+    await runSessionReset({ force: opts.force });
 });
 program
     .command('capture [text...]')
@@ -295,28 +563,33 @@ program
     .option('-c, --collection <slug>', 'Explicit collection (skip auto-classification)')
     .option('-l, --link <entry-id>', 'Link new entry to an existing entry (TEN-705)')
     .option('-t, --type <relation-type>', 'Relation type for --link (default: surfaces_tension_in)')
+    .option('--source-ref <ref>', 'Source reference URI (BET-240 E2: e.g. "meeting-2026-03-28.md")')
+    .option('--source-excerpt <text>', 'Verbatim source excerpt (BET-240 E2)')
+    // TEN-2226 / WP-456 E1: opt-in override — keeps the entry a draft even in Open governance mode.
+    .option('--draft', 'Force the entry to draft regardless of workspace governance mode (TEN-2226)')
     .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+    .option('--suggest-only', 'Show grounding preview (possible duplicates, related entries) without creating entry (WP-319)')
+    .option('--strict', 'Prompt y/N before capturing when a possible duplicate is detected (WP-319)')
     .action(async (textParts = [], opts) => {
     const text = textParts.join(' ').trim();
     if (!text && !opts.name) {
         program.commands.find((c) => c.name() === 'capture')?.help();
         return;
     }
-    try {
-        await runCapture({
-            text: text || opts.name || '',
-            name: opts.name,
-            description: opts.description,
-            collection: opts.collection,
-            link: opts.link,
-            type: opts.type,
-            json: opts.json,
-        });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runCapture({
+        text: text || opts.name || '',
+        name: opts.name,
+        description: opts.description,
+        collection: opts.collection,
+        link: opts.link,
+        type: opts.type,
+        sourceRef: opts.sourceRef,
+        sourceExcerpt: opts.sourceExcerpt,
+        draft: opts.draft,
+        json: opts.json,
+        suggestOnly: opts.suggestOnly,
+        strict: opts.strict,
+    });
 });
 // --- Update command (TEN-703) ---
 program
@@ -325,21 +598,17 @@ program
     .option('-f, --field <key=value>', 'Set a data field (repeatable)', (val, prev) => [...prev, val], [])
     .option('--name <name>', 'Update entry name')
     .option('--status <status>', 'Update entry status (draft | active | deprecated | archived)')
+    .option('--workflow-status <status>', 'Set workflow status (server-validated)')
     .option('--note <text>', 'Change note for history')
     .action(async (entryId, opts) => {
-    try {
-        await runUpdate({
-            entryId,
-            field: opts.field,
-            name: opts.name,
-            status: opts.status,
-            note: opts.note,
-        });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runUpdate({
+        entryId,
+        field: opts.field,
+        name: opts.name,
+        status: opts.status,
+        workflowStatus: opts.workflowStatus,
+        note: opts.note,
+    });
 });
 // --- Promote command (Wave 2 CLI Polish) ---
 program
@@ -350,26 +619,14 @@ program
         program.commands.find((c) => c.name() === 'verify')?.help();
         return;
     }
-    try {
-        await runVerify({ entryId: entryId.trim() });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runVerify({ entryId: entryId.trim() });
 });
 program
-    .command('promote <entry-id>')
-    .description('Promote entry from draft to active (commit to SSOT)')
-    .option('-m, --message <text>', 'Commit message')
-    .action(async (entryId, opts) => {
-    try {
-        await runPromote({ entryId, message: opts.message });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    .command('promote <entry-ids...>')
+    .description('Promote one or more entries from draft to active (commit to SSOT). Batch: a single failure does not abort the rest (INS-1813).')
+    .option('-m, --message <text>', 'Commit message (applied to every entry in the batch)')
+    .action(async (entryIds, opts) => {
+    await runPromote({ entryIds, message: opts.message });
 });
 // --- Relate / Unrelate commands (TEN-704) ---
 program
@@ -377,25 +634,13 @@ program
     .description('Add a typed relation between two entries (requires active session)')
     .option('--if-missing', 'Only create relation if it does not already exist')
     .action(async (fromId, type, toId, opts) => {
-    try {
-        await runRelate({ fromId, type, toId, ifMissing: opts.ifMissing });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runRelate({ fromId, type, toId, ifMissing: opts.ifMissing });
 });
 program
     .command('unrelate <from-id> <type> <to-id>')
     .description('Remove a typed relation between two entries (requires active session)')
     .action(async (fromId, type, toId) => {
-    try {
-        await runUnrelate({ fromId, type, toId });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runUnrelate({ fromId, type, toId });
 });
 // --- Ingest command (BET-81) ---
 program
@@ -405,23 +650,43 @@ program
     .option('--resume', 'Skip files whose sourceRef is already committed in staging.')
     .option('--concurrency <n>', 'Process up to N files in parallel (default 1, max 5).', '1')
     .action(async (pattern, opts) => {
-    try {
-        const concurrency = parseInt(opts.concurrency ?? '1', 10);
-        if (Number.isNaN(concurrency) || concurrency < 1) {
-            console.error('--concurrency must be a positive integer.');
-            process.exit(1);
-        }
-        await runIngest({
-            pattern,
-            dryRun: opts.dryRun,
-            resume: opts.resume,
-            concurrency,
+    const concurrency = parseInt(opts.concurrency ?? '1', 10);
+    if (Number.isNaN(concurrency) || concurrency < 1) {
+        throw new CLIError('--concurrency must be a positive integer.', {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
         });
     }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    await runIngest({
+        pattern,
+        dryRun: opts.dryRun,
+        resume: opts.resume,
+        concurrency,
+    });
+});
+// --- migrate:setup command (WP-345 S0b) ---
+program
+    .command('migrate:setup')
+    .description('Migrate .productbrain/skills|rules|hooks/*.md into the DB setup-assets collection (WP-345)')
+    .option('--dry-run', 'Show what would be migrated without writing to DB.')
+    .option('--cwd <path>', 'Override working directory (default: process.cwd())')
+    .action(async (opts) => {
+    const { runMigrateSetup } = await import('./commands/migrate-setup.js');
+    await runMigrateSetup({ dryRun: opts.dryRun, cwd: opts.cwd });
+});
+// --- setup:ingest command (WP-345 S3) ---
+program
+    .command('setup:ingest <path>')
+    .description('Push a single .productbrain skill/rule/hook file to the DB setup-assets SSOT (WP-345)')
+    .option('--dry-run', 'Show what would be ingested without writing to DB.')
+    .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+    .action(async (filePath, opts) => {
+    if (!filePath?.trim()) {
+        program.commands.find((c) => c.name() === 'setup:ingest')?.help();
+        return;
     }
+    const { runSetupIngest } = await import('./commands/setup-ingest.js');
+    await runSetupIngest(filePath.trim(), { dryRun: opts.dryRun });
 });
 // --- Fields command (BET-181 Slice 2) ---
 program
@@ -432,13 +697,7 @@ program
         program.commands.find((c) => c.name() === 'fields')?.help();
         return;
     }
-    try {
-        await runFields({ collectionSlug: collection.trim() });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runFields({ collectionSlug: collection.trim() });
 });
 // --- Constellation command (BET-181 Slice 3) ---
 program
@@ -449,36 +708,24 @@ program
         program.commands.find((c) => c.name() === 'constellation')?.help();
         return;
     }
-    try {
-        await runConstellation({ entryId: entryId.trim() });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runConstellation({ entryId: entryId.trim() });
 });
 // --- Audit command (BET-182 Slice 2) ---
 program
     .command('audit <entry-ids...>')
-    .description('Run STD-113 hygiene audit on bet(s) — 13 gates, exit code reflects verdict')
+    .description('Run hygiene audit on bet(s) — 13 gates (shaping) / 18 gates (handoff), exit code reflects verdict')
     .option('--phase <phase>', 'Override phase detection (shaping | handoff)')
     .option('--gate <name>', 'Run only specified gate(s) (repeatable)', (val, prev) => [...prev, val], [])
     .option('--fix', 'Auto-execute exact fixes via pb update, rerun once')
     .option('--verbose', 'Show all gates including PASS detail')
     .action(async (entryIds, opts) => {
-    try {
-        await runAudit({
-            entryIds: entryIds.map((id) => id.trim()).filter(Boolean),
-            phase: opts.phase,
-            gate: opts.gate,
-            fix: opts.fix,
-            verbose: opts.verbose,
-        });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runAudit({
+        entryIds: entryIds.map((id) => id.trim()).filter(Boolean),
+        phase: opts.phase,
+        gate: opts.gate,
+        fix: opts.fix,
+        verbose: opts.verbose,
+    });
 });
 program
     .command('brand-pack')
@@ -493,13 +740,7 @@ program
     .command('proposals')
     .description('List open consent proposals with expiry countdown (BET-221)')
     .action(async () => {
-    try {
-        await runProposals();
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    await runProposals();
 });
 program
     .command('accept [proposal-id]')
@@ -507,29 +748,313 @@ program
     .option('-a, --auto', 'Auto-approve all open proposals (skip contradictions)')
     .action(async (proposalId, opts) => {
     if (!proposalId && !opts.auto) {
-        process.stderr.write('Usage: pb accept <proposal-id> or pb accept --auto\n');
-        process.exit(1);
-    }
-    try {
-        await runAccept({ proposalId, auto: opts.auto });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+        throw new CLIError('Usage: pb accept <proposal-id> or pb accept --auto', {
+            code: ErrorCode.VALIDATION_FAILED,
+            category: 'validation',
+        });
     }
+    await runAccept({ proposalId, auto: opts.auto });
 });
 program
     .command('reject <proposal-id>')
     .description('Reject a consent proposal with a required reason (BR-7)')
     .requiredOption('-r, --reason <text>', 'Reason for rejection (required)')
     .action(async (proposalId, opts) => {
-    try {
-        await runReject({ proposalId, reason: opts.reason });
+    await runReject({ proposalId, reason: opts.reason });
+});
+// --- Collections command (BET-280 Slice 1) ---
+const collectionsCmd = program
+    .command('collections')
+    .description('Inspect and audit workspace collection registry (BET-280)');
+collectionsCmd
+    .command('list')
+    .description('List all collections — slug, name, field count, icon')
+    .action(async () => {
+    await runCollectionsList();
+});
+collectionsCmd
+    .command('get <slug>')
+    .description('Show full detail for a collection by slug')
+    .action(async (slug) => {
+    if (!slug?.trim()) {
+        program.commands.find((c) => c.name() === 'collections')?.help();
+        return;
     }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    await runCollectionsGet({ slug: slug.trim() });
+});
+collectionsCmd
+    .command('audit')
+    .description('Collection health report — classification, icon, displayHint coverage, schema gaps')
+    .action(async () => {
+    await runCollectionsAudit();
+});
+collectionsCmd
+    .command('export')
+    .description('Export all system_collection_definitions with full classification metadata (admin only)')
+    .action(async () => {
+    await runCollectionsExport();
+});
+// --- Workspace operator commands (WP-305 Slice 4) ---
+const workspaceCmd = program
+    .command('workspace')
+    .description('Operator commands for workspace health and repair (WP-305)');
+workspaceCmd
+    .command('verify')
+    .description('Check workspace health — seeds, collections, glossary (admin only)')
+    .action(async () => {
+    await runWorkspaceVerify();
+});
+workspaceCmd
+    .command('repair')
+    .description('Backfill missing seeds for the active workspace (admin only)')
+    .action(async () => {
+    await runWorkspaceRepair();
+});
+const authorityDomainsCmd = program
+    .command('authority-domains')
+    .description('Operator commands for WP-354 authority-domain readiness and evidence');
+function collectRepeatableOption(value, previous) {
+    return [...(previous ?? []), value];
+}
+authorityDomainsCmd
+    .command('add <slug>')
+    .description('Create an authority domain for this workspace')
+    .option('--description <description>', 'Authority-domain description')
+    .option('--alias <alias>', 'Alias/keyword for this domain (repeatable)', collectRepeatableOption)
+    .option('--path-glob <glob>', 'Changed-path glob for this domain (repeatable)', collectRepeatableOption)
+    .action(async (slug, opts) => {
+    await runAuthorityDomainsAdd(slug, opts);
+});
+authorityDomainsCmd
+    .command('propose')
+    .description('Generate authority-domain tag proposals')
+    .option('--dry-run', 'Preview without writing staging proposals')
+    .option('--limit <n>', 'Maximum governance entries to classify')
+    .option('--mock', 'Use deterministic mock classifier')
+    .action(async (opts) => {
+    await runAuthorityDomainsPropose(opts);
+});
+authorityDomainsCmd
+    .command('review')
+    .description('List authority-domain tag proposals')
+    .option('--status <status>', 'pending, committed, rejected, or skipped', 'pending')
+    .option('--limit <n>', 'Maximum proposals to list')
+    .option('--sample <n>', 'Return a stable proposal sample')
+    .option('--stratified', 'Stratify sample across proposed domain and source collection')
+    .action(async (opts) => {
+    await runAuthorityDomainsReview(opts);
+});
+const authorityDomainsSampleCmd = authorityDomainsCmd
+    .command('sample')
+    .description('Manage human-reviewed authority-domain proposal samples');
+authorityDomainsSampleCmd
+    .command('record')
+    .description('Record human-reviewed sample accuracy for authority-domain proposals')
+    .requiredOption('--sample-id <id>', 'Stable sample identifier from the review packet')
+    .option('--run-id <id>', 'Proposal run identifier')
+    .requiredOption('--approved <n>', 'Count of sampled proposals approved as-is')
+    .requiredOption('--rejected <n>', 'Count of sampled proposals rejected')
+    .requiredOption('--corrected <n>', 'Count of sampled proposals corrected to another domain')
+    .action(async (opts) => {
+    await runAuthorityDomainsRecordSample(opts);
+});
+authorityDomainsCmd
+    .command('ratify <proposal-id>')
+    .description('Ratify an authority-domain tag proposal')
+    .option('--note <note>', 'Review note')
+    .action(async (proposalId, opts) => {
+    await runAuthorityDomainsRatify(proposalId, opts);
+});
+authorityDomainsCmd
+    .command('queue-tag')
+    .description('Queue a known-correct authority-domain tag proposal')
+    .requiredOption('--entry <entryId>', 'Entry ID to tag, e.g. DEC-1244')
+    .requiredOption('--domain <domainSlug>', 'Authority-domain slug, e.g. product-design/ux')
+    .option('--note <note>', 'Known-correct evidence note')
+    .option('--ratify', 'Immediately ratify using the generated confirmation string')
+    .action(async (opts) => {
+    await runAuthorityDomainsQueueTag(opts);
+});
+authorityDomainsCmd
+    .command('reject <proposal-id>')
+    .description('Reject an authority-domain tag proposal')
+    .option('--reason <reason>', 'Rejection reason')
+    .action(async (proposalId, opts) => {
+    await runAuthorityDomainsReject(proposalId, opts);
+});
+authorityDomainsCmd
+    .command('discard-pending')
+    .description('Reject all pending authority-domain tag proposals after a failed batch diagnosis')
+    .option('--reason <reason>', 'Discard reason')
+    .action(async (opts) => {
+    await runAuthorityDomainsDiscardPending(opts);
+});
+authorityDomainsCmd
+    .command('readiness')
+    .description('Show WP-354 authority-domain readiness, evidence gap, and next action')
+    .action(async () => {
+    await runAuthorityDomainsReadiness();
+});
+authorityDomainsCmd
+    .command('benchmark')
+    .description('Run and persist the WP-354 authority-domain benchmark')
+    .action(async () => {
+    await runAuthorityDomainsBenchmark();
+});
+authorityDomainsCmd
+    .command('activate-cutover')
+    .description('Activate graph retrieval after WP-354 evidence gates pass')
+    .option('--force-pre-production', 'Bypass the permanently-locked valueProof gate (requires --dec-id, DEC-864)')
+    .option('--dec-id <decId>', 'Chain DEC ID authorizing the bypass')
+    .action(async (opts) => {
+    await runAuthorityDomainsActivateCutover({ forcePreProduction: opts.forcePreProduction, decId: opts.decId });
+});
+authorityDomainsCmd
+    .command('deactivate-cutover')
+    .description('Deactivate the active WP-354 authorityDomain cutover for this workspace (DEC-864 rollback).')
+    .option('--clerk-user-id <clerkUserId>', 'Override the Clerk user ID for audit trail')
+    .action(async (opts) => {
+    await runAuthorityDomainsDeactivateCutover({ clerkUserId: opts.clerkUserId });
+});
+authorityDomainsCmd
+    .command('principle-distribution')
+    .description('Pre-merge gate: check governance category match rate for principles entries')
+    .action(async () => {
+    await runAuthorityDomainsPrincipleDistribution();
+});
+// --- Definitions diff command (WP-305 Slice 4) ---
+const definitionsCmd = program
+    .command('definitions')
+    .description('Inspect and compare workspace definitions (WP-305)');
+definitionsCmd
+    .command('diff [file]')
+    .description('Compare local dev-system-collections.json against server definitions (admin only)')
+    .action(async (file) => {
+    await runDefinitionsDiff({ file });
+});
+// --- Method commands (WP-329 S1: method visibility) ---
+const methodCmd = program
+    .command('method')
+    .description('Inspect published methods (skills + rules) and their per-surface adapter status (WP-329)');
+methodCmd
+    .command('ls')
+    .description('List all methods with version, published status, and adapter presence')
+    .action(async () => {
+    await runMethodList();
+});
+methodCmd
+    .command('show <name>')
+    .description('Show details for one method: frontmatter, Chain entry, and per-adapter fork status')
+    .action(async (name) => {
+    if (!name?.trim()) {
+        program.commands.find((c) => c.name() === 'method')?.help();
+        return;
+    }
+    await runMethodShow({ name: name.trim() });
+});
+methodCmd
+    .command('diff <name>')
+    .description('Show diff between local .productbrain/ source and last-published Chain version (WP-329 S2)')
+    .action(async (name) => {
+    if (!name?.trim()) {
+        program.commands.find((c) => c.name() === 'method')?.help();
+        return;
+    }
+    await runMethodDiff({ name: name.trim() });
+});
+methodCmd
+    .command('publish <name>')
+    .description('Publish a local .productbrain/ method (skill or rule) to the Chain methods collection (WP-329 S3)')
+    .option('--force', 'Publish even when local body matches the last-published version (override D4 no-op guard)')
+    .action(async (name, opts) => {
+    if (!name?.trim()) {
+        program.commands.find((c) => c.name() === 'method')?.help();
+        return;
+    }
+    await runMethodPublish({ name: name.trim(), force: opts.force });
+});
+// --- Profile commands (WP-302 Slice 2) ---
+const profileCmd = program
+    .command('profile')
+    .description('Manage workspace profiles (WP-302: multi-workspace support)');
+profileCmd
+    .command('list')
+    .description('List all profiles, mark active one')
+    .action(async () => {
+    await runProfileList();
+});
+profileCmd
+    .command('create <name>')
+    .description('Create a new profile with an API key')
+    .requiredOption('--api-key <key>', `API key (${API_KEY_PREFIX}...)`)
+    .option('--url <url>', 'Convex site URL (defaults to production)')
+    .action(async (name, opts) => {
+    await runProfileCreate({ name, apiKey: opts.apiKey, url: opts.url });
+});
+profileCmd
+    .command('use <name>')
+    .description('Switch profile: reconciles the repo pin + global by default. --local = repo pin only; --global = global only.')
+    .option('--local', 'Write the profile pin only to .productbrain/config.local.json (repo-local, gitignored)')
+    .option('--global', 'Switch only the global active profile (does not change a locally-pinned repo)')
+    .action(async (name, opts) => {
+    await runProfileUse({ name, local: opts.local, global: opts.global });
+});
+profileCmd
+    .command('delete <name>')
+    .description('Delete a profile (cannot delete active or last profile)')
+    .action(async (name) => {
+    await runProfileDelete({ name });
+});
+program
+    .command('use <name>')
+    .description('Switch the active workspace profile (alias for `pb profile use`).')
+    .option('--local', 'Write the profile pin only to .productbrain/config.local.json (repo-local, gitignored)')
+    .option('--global', 'Switch only the global active profile (does not change a locally-pinned repo)')
+    .action(async (name, opts) => {
+    await runProfileUse({ name, local: opts.local, global: opts.global });
+});
+// --- Glossary command (WP-302 Slice 4) ---
+program
+    .command('glossary')
+    .description('Show key Product Brain CLI terms and definitions')
+    .action(() => {
+    if (isJsonMode()) {
+        process.stdout.write(JSON.stringify(GLOSSARY) + '\n');
+        return;
     }
+    const lines = [
+        '',
+        heading('Glossary'),
+        '',
+        formatGlossary(),
+        '',
+    ];
+    process.stdout.write(lines.join('\n') + '\n');
+});
+// --- Usage command (WP-322 S4, FEAT-1011) ---
+program
+    .command('usage')
+    .description('Session and activity dashboard — 4-tab Ink TUI (WP-322)')
+    .option('--json', 'Output machine-readable JSON (sessions, entries30d, activity array)')
+    .action(async (opts) => {
+    await runUsage({ json: opts.json });
+});
+// --- Proof-run command (WP-459: admin-proof bridge dogfood) ---
+program
+    .command('proof-run <proof-name>')
+    .description('Run an admin-only proof against the seeded preview via the proof bridge (WP-459)')
+    .action(async (proofName) => {
+    await runProofRun({ proofName: proofName.trim() });
+});
+// --- Admin command group (WP-312 S2, FEAT-969) ---
+program.addCommand(createAdminCommand());
+// --- Upgrade command (WP-322 S1: ambient update notification) ---
+program
+    .command('upgrade')
+    .description(`Upgrade pb CLI to the latest beta (${UPGRADE_COMMAND})`)
+    .action(async () => {
+    await runUpgrade({ currentVersion: cliPackageVersion.version });
 });
-program.parse();
+// Parse with global error handler — all uncaught errors route through handleError
+program.parseAsync(process.argv).catch(handleError);
 //# sourceMappingURL=index.js.map