@productbrain/cli 0.1.0-beta.9 → 0.1.0-beta.9000

package/dist/index.js

@@ -1,34 +1,88 @@
 #!/usr/bin/env node
 /**
- * Product Brain CLI — Chain knowledge + write-back in the terminal.
- * Read: BET-108. Write: pb session + pb capture (TEN-27, INS-80).
- * BET-181 Slice 0: global --json / --pretty flags for agent-native output (DEC-299).
+ * Product Brain CLI — Chain knowledge + write-back in the terminal. Read: BET-108.
+ * Write: pb session + pb capture (TEN-27, INS-80). BET-181 Slice 0: global --json / --pretty flags for agent-native output (DEC-299).
  */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
-import { setOutputMode } from './lib/runner.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPackageVersion = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+import { setOutputMode, setQuietMode, isJsonMode } from './lib/runner.js';
+import { CLIError, ErrorCode } from './lib/errors.js';
+import { handleCliError as handleError } from './handleCliError.js';
 import { runContext } from './commands/context.js';
 import { runGet, runGetMany } from './commands/get.js';
+import { runScoreboard } from './commands/scoreboard.js';
+import { registerHistoryCommand } from './registerHistoryCommand.js';
+import { runReworkReport } from './commands/rework.js';
+import { runConnect } from './commands/connect.js';
 import { runLogin } from './commands/login.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, runSessionList, runSessionShow } from './commands/session.js';
 import { runCapture } from './commands/capture.js';
 import { runUpdate } from './commands/update.js';
-import { runRelate, runUnrelate } from './commands/relate.js';
+import { runRestore } from './commands/restore.js';
 import { runIngest } from './commands/ingest.js';
 import { runFields } from './commands/fields.js';
 import { runConstellation } from './commands/constellation.js';
+import { registerEntryCommands, registerRelateCommands } from './registerEntryCommands.js';
+import { registerTensionsCommands } from './registerTensionsCommands.js'; // WP-768 L0: same-line combine
+import { runBrandPack } from './commands/brand-pack.js';
+import { runChanges } from './commands/changes.js';
+import { registerOutcomeCommands } from './registerOutcomeCommands.js';
+import { registerRoleCommands } from './registerRoleCommands.js';
+import { runChainWalk } from './commands/chain-walk.js';
+import { runCrossCut } from './commands/cross-cut.js';
+import { runBrief, runCompoundBrief, isCompoundType } from './commands/brief.js';
+import { runDigest } from './commands/digest.js'; // same-line combine
+import { runVerify } from './commands/verify.js';
+import { runCodexPrep } from './commands/codex-prep.js';
+import { runStillTrue } from './commands/stillTrue.js'; // same-line combine, TASK-384 S1
+import { runCollectionsList, runCollectionsGet, runCollectionsAudit, runCollectionsExport } from './commands/collections.js';
+import { runWorkspaceVerify, runWorkspaceRepair, runDefinitionsDiff } from './commands/workspace.js';
+import { runDoctor } from './commands/doctor.js';
+import { runWhoami } from './commands/whoami.js';
+import { runFiles } from './commands/files.js';
+import { runUpgrade } from './commands/upgrade.js';
+import { runProfileList, runProfileCreate, runProfileUse, runProfileDelete } from './commands/profile.js';
+import { runInit } from './commands/init.js';
+import { runStatus } from './commands/status.js';
+import { runMethodList, runMethodShow, runMethodDiff, runMethodPublish } from './commands/method.js';
+import { createAdminCommand } from './commands/admin/index.js';
+import { createFeedbackCommand } from './commands/feedback.js';
+import { createConflictsCommand } from './commands/conflicts.js';
+import { createShapeCommand } from './commands/shape.js';
+import { createQuestionCommand } from './commands/questions.js';
+import { createDirectionCommand } from './commands/direction.js';
+import { createOrganisationCommand } from './commands/organisation.js';
+import { createAcceptPolicyCommand } from './commands/accept-policy.js'; // WP-661 S3
+import { runUsage } from './commands/usage.js';
+import { runProofRun } from './commands/proof-run.js'; // same-line combine
+import { runQualitySpineCheck } from './commands/quality.js';
+import { GLOSSARY, formatGlossary } from './lib/glossary.js';
+import { API_KEY_PREFIX } from './lib/tokenConstants.js'; // same-line combine
+import { heading } from './lib/style.js';
+import { printPreviewBanner } from './lib/previewBanner.js';
+import { checkForUpdate } from './lib/update-check.js';
+import { UPGRADE_COMMAND } from './lib/constants.js';
 const program = new Command();
+// WP-753 V2 (TASK-203): the global error handler lives in ./handleCliError.ts (STD-2/DEC-1724 —
+// kept out of this grandfathered file); imported below as handleError for the call site's own name.
 program
     .name('pb')
     .description('Product Brain — Chain knowledge + write-back CLI')
-    .version('0.2.0')
+    .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');
-// Apply global output mode BEFORE subcommand actions run
-program.hook('preAction', (thisCommand) => {
+    .option('--json', 'Output machine-readable JSON (the card is the default even when piped)')
+    .option('--pretty', 'Force human-readable output even when PB_JSON=1 is set')
+    .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. Commander preAction hook signature: (hookedCommand = root program, actionCommand = the subcommand actually invoked).
+program.hook('preAction', (_hookedCommand, actionCommand) => {
     const globalOpts = program.opts();
     if (globalOpts.json) {
         setOutputMode('json');
@@ -36,8 +90,18 @@ program.hook('preAction', (thisCommand) => {
     else if (globalOpts.pretty) {
         setOutputMode('pretty');
     }
-    // else: 'auto' (default) — TTY detection handles it
-    void thisCommand;
+    // else: 'auto' (default) — isJsonMode() checks PB_JSON=1, never TTY (WP-744 / 1e-B)
+    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 () => {
+    await runStatus({ args: program.args, version: cliPackageVersion.version });
 });
 program
     .command('get <entry-id>')
@@ -47,42 +111,124 @@ 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() });
+});
+registerHistoryCommand(program); // WP-753 V2 (TASK-203): same-line combine, module-health shrink-only budget
+program
+    .command('scoreboard')
+    .description('Flywheel scoreboard — M3/M4/M5 metrics + diagnosis layer (agent-primary; --json for structured consumption)')
+    .action(async () => {
+    await runScoreboard();
+});
+const qualityCmd = program
+    .command('quality')
+    .description('Quality-check surfaces');
+qualityCmd
+    .command('spine-check')
+    .description('Check purpose+vision+strategy structural completeness + refusal heuristic; --story runs the on-demand one-story LLM judgment')
+    .option('--story', 'Also run the on-demand one-story judgment (never scheduled; result labelled [unvalidated])')
+    .action(async (opts) => { await runQualitySpineCheck({ story: opts.story }); });
+const reworkCmd = program
+    .command('rework')
+    .description('Report observed rework signals (WP-487 / FEAT-1373 — fills the M4 rework meter)');
+reworkCmd
+    .command('report <entry-id>')
+    .description('Report a rework event attributed to a previously served governance entry (agent-native checkpoint; requires an active session)')
+    .requiredOption('--classification <kind>', 'revision | ci_review_correction | user_override')
+    .option('--via <kind>', 'How this was observed: followup_commit | ci_rerun | manual', 'manual')
+    .option('--attributable', 'Flag: this ci_review_correction is attributed to a missing/violated served decision')
+    .option('--task <text>', 'Task context this rework relates to (truncated server-side, never raw diff/comment text)')
+    .option('--conversation <id>', 'Explicit conversation override, matching `pb session start --conversation <id>` — use when the shell has no PB_CONVERSATION_ID set')
+    .action(async (entryId, opts) => {
+    await runReworkReport({
+        entryId,
+        classification: opts.classification,
+        reportedVia: opts.via,
+        attributable: opts.attributable,
+        task: opts.task,
+        conversation: opts.conversation,
+    });
 });
 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>')
-    .description('Gather and display constellation context (pipe-friendly: JSON when piped, human text in terminal)')
+    .description('Gather and display constellation context (human-readable card by default, even when piped — pass --json for machine-readable output)')
     .action(async (entryId) => {
     if (!entryId?.trim()) {
         program.commands.find((c) => c.name() === 'context')?.help();
         return;
     }
-    try {
-        await runContext({ entryId: entryId.trim() });
+    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) => {
+    await runChanges({ since: opts.since });
+});
+program
+    .command('walk <entry-id>')
+    .description('Directed deep traversal along one relation type to depth 4 (BET-239)')
+    .option('-d, --depth <n>', 'Traversal depth 1-4 (default 2)', '2')
+    .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) => {
+    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',
+        });
+    }
+    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) => {
+    await runCrossCut({ type: opts.type });
+});
+program
+    .command('brief [type]')
+    .description('Brief intelligence queries (BET-239).\n' +
+    '  pb brief --skill <name>    Incremental delta for a skill (E4)\n' +
+    '  pb brief steering          Compound: changes + structure + delta + readiness (E6)\n' +
+    '  pb brief confidence        Compound: changes + active work packages (tensions: `pb tensions list`) (E6)\n' +
+    '  pb brief delta [--since]   Compound: changes + relations since timestamp (E6)')
+    .option('--skill <name>', 'Skill name for incremental brief (e.g. preflight, shaping, review)')
+    .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) => {
+    // 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('digest').description('Narrative brief over pending drafts: decisions vs fixes, read-only (TASK-130, WP-702)')
+    .requiredOption('--since <window>', 'ISO timestamp or duration (1h, 6h, 1d, 7d, 30d)').action(async (opts) => { await runDigest({ since: opts.since }); });
 program
     .command('search [query...]')
     .description('Full-text search across all collections')
@@ -92,58 +238,100 @@ 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')
+    .description('Print all orient sections (strategic context, work packages, governance, tensions, etc.)')
+    .option('-b, --brief', 'Compact view: counts, top work packages, tensions, planned work')
+    .option('-t, --task <task>', 'Task description for task-shaped governance and context')
+    .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, 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('--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.')
     .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;
+    }
+    // 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 manual
+    // orient rows — the kernel used to coerce the absent path to 'manual-orient', polluting the
+    // proof slice that isolates manual `pb orient --task` rows. session start/close no longer
+    // call runHandshake at all (WP-759/TASK-232, DEC-1736); 'handshake' now covers every other row.
+    await runHandshake({ force: opts.force, apply: opts.apply, dryRun: opts.dryRun, level: opts.level, surfaces: opts.surfaces?.split(','), noPrompt, 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;
     }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    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. In a non-interactive shell (e.g. CI), pass --yes to confirm the workspace, optionally with --name to label the key.')
+    .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. Skips the key-label prompt when set.')
+    .option('-y, --yes', 'Skip the interactive workspace confirmation. Required to connect in a non-interactive shell (e.g. CI).')
+    .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, assumeYes: opts.yes });
 });
 program
     .command('login')
     .description('Save your API key to ~/.config/productbrain/.env (works from any directory)')
     .action(async () => {
-    try {
-        await runLogin();
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
-    }
+    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('files')
+    .description('Show which .productbrain files are pb-owned vs committed, and what writes each.')
+    .option('--fix', 'Add any exposed pb-owned files to .gitignore (idempotent)')
+    .option('--dry-run', 'With --fix: preview the .gitignore lines without writing')
+    .action(async (opts) => {
+    await runFiles({ fix: opts.fix, dryRun: opts.dryRun });
 });
 // --- Write commands (require active session) ---
 const sessionCmd = program
@@ -151,41 +339,44 @@ const sessionCmd = program
     .description('Manage write sessions (DEC-9: sessions required before write access)');
 sessionCmd
     .command('start')
-    .description('Start a tracked write session (opens session, refreshes context)')
+    .description('Start a tracked write session')
     .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);
-    }
-});
+    .option('--conversation <id>', 'Explicit conversation identity override (WP-479 E2) — takes priority over env-detected channels. Pair with PB_CONVERSATION_ID=<id> so later bare pb commands (orient, capture) attribute to the same conversation — they resolve identity from env only')
+    .option('--role <entry-id>', 'Role to act as this session (DEC-1715) — only needed if you hold more than one; the error lists your roles if omitted') // WP-753 O1a same-line combine (STD-2 shrink-only)
+    .action(async (opts) => { await runSessionStart({ json: opts.json, conversation: opts.conversation, role: opts.role }); });
 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)')
+    .description('Close the active session (wrapup)')
     .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 });
+});
+// WP-479 E4: traceback + quota observability.
+sessionCmd
+    .command('list')
+    .description('List active sessions (with quota gauge) + recent non-active ones (WP-479 E4)')
+    .action(async () => {
+    await runSessionList();
+});
+sessionCmd
+    .command('show <id-or-conversation>')
+    .description('Show a conversation\'s full session lineage + governance serves (WP-479 E4)')
+    .action(async (idOrConversation) => {
+    await runSessionShow(idOrConversation);
+});
+// 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...]')
@@ -193,91 +384,100 @@ program
     .option('-n, --name <name>', 'Entry name (defaults to capture text)')
     .option('-d, --description <desc>', 'Entry description (defaults to capture text)')
     .option('-c, --collection <slug>', 'Explicit collection (skip auto-classification)')
+    .option('-f, --field <key=value>', 'Set a data field (repeatable; checklist: -f doneWhen="a" -f doneWhen="b", one item per flag)', (val, prev) => [...prev, val], [])
     .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('-t, --link-type <relation-type>', 'Relation type for --link — REQUIRED when --link is used (WP-688 S4): no default, the door refuses and lists the source entry\'s legal verbs if omitted')
+    .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)')
+    .option('--draft', 'Force the entry to draft regardless of workspace governance mode — opt-in override, keeps it draft even in Open mode (TEN-2226 / WP-456 E1)')
     .option('--json', 'Output machine-readable JSON (deprecated: use global --json flag)')
+    .option('--strict', 'Prompt y/N before capturing when a possible duplicate is detected (WP-319)')
+    .option('--owner-role <entry-id>', 'Existing Role entry ID to create AS OWNER of (WP-513 rung 2; you must hold it, and its team is the one you hold it in: root first, else the shallowest)') // WP-753 O1b: --owner-team deleted, default owner resolves from the session's acting role.
+    .option('--entry-type <canonical-key>', 'Explicit canonical type for the new entry (e.g. objective, key_result) — bypasses classification; -t/--link-type is the --link relation type (WP-684 TASK-77)')
     .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,
+        field: opts.field, link: opts.link, linkType: opts.linkType, sourceRef: opts.sourceRef, sourceExcerpt: opts.sourceExcerpt,
+        draft: opts.draft, json: opts.json, strict: opts.strict,
+        ownerRole: opts.ownerRole, entryType: opts.entryType,
+    });
 });
 // --- Update command (TEN-703) ---
 program
     .command('update <entry-id>')
     .description('Update fields on an existing Chain entry (requires active session)')
-    .option('-f, --field <key=value>', 'Set a data field (repeatable)', (val, prev) => [...prev, val], [])
+    .option('-f, --field <key=value>', 'Set a data field (repeatable; checklist: -f doneWhen="a" -f doneWhen="b", one item per flag)', (val, prev) => [...prev, val], [])
     .option('--name <name>', 'Update entry name')
-    .option('--status <status>', 'Update entry status (draft | active | deprecated | archived)')
-    .option('--note <text>', 'Change note for history')
+    .option('--status <status>', 'Update entry status (draft | archived) — accepted is set via `pb entry accept`; active/deprecated are legacy and refused')
+    .option('--workflow-status <status>', 'Set workflow status (server-validated)')
+    .option('--type <canonical-key>', 'Reclassify a DRAFT entry to another canonical type (immutable once committed — supersede instead)')
+    .option('--note <text>', 'Change note for history').option('--change-reason <text>', 'Why what the entry promises is changing (required for a promise-field change)')
+    .option('--override-reason <text>', 'Typed override (≥12 chars) clearing a steering coherency block — recorded with author attribution (WP-465)')
+    .option('--acknowledge <response>', 'Respond to a coherency challenge: linked | accepted-fix | diverged (WP-465)')
+    .option('--ack-entry <entry-id>', 'Authorizing entry for --acknowledge linked / accepted-fix')
+    .option('--ack-reason <text>', 'Divergence rationale (≥12 chars) for --acknowledge diverged')
+    // Commander camelCases every flag to exactly the UpdateOptions key it feeds, so the options
+    // object spreads straight through. The previous hand-written 1:1 mapping had to be edited twice
+    // per new flag (once here, once in the type) and silently dropped anything you forgot.
     .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, ...opts });
 });
-// --- Relate / Unrelate commands (TEN-704) ---
+// --- Restore command (WP-514 review round 2, P1) ---
 program
-    .command('relate <from-id> <type> <to-id>')
-    .description('Add a typed relation between two entries (requires active session)')
-    .action(async (fromId, type, toId) => {
-    try {
-        await runRelate({ fromId, type, toId });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    .command('restore <entry-id>')
+    .description('Restore an archived Chain entry to draft (requires active session + rung-3 authority coverage)')
+    .action(async (entryId) => { await runRestore(entryId); });
+// --- Entry noun-scoped commands (DEC-1574, WP-640 S4) — registerEntryCommands.ts ---
+registerEntryCommands(program);
+registerTensionsCommands(program); // WP-768 L0: same-line combine, module-health shrink-only budget
+// --- Promote command (Wave 2 CLI Polish) ---
+program.command('verify <entry-id>').description('Mark an entry as verified (BET-240: source fidelity trust signal)').action(async (entryId) => {
+    if (!entryId?.trim()) {
+        program.commands.find((c) => c.name() === 'verify')?.help();
+        return;
     }
+    await runVerify({ entryId: entryId.trim() });
 });
-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);
+// TASK-384 S1: distinct from verify (attestation) — the holder of the owning role (else the nearest seated Team Lead) confirms accuracy; no content/version change.
+program.command('still-true <entry-id>').description('Confirm an entry is still true (the holder of the owning role, else the nearest seated Team Lead)').action(async (entryId) => {
+    if (!entryId?.trim()) {
+        program.commands.find((c) => c.name() === 'still-true')?.help();
+        return;
     }
+    await runStillTrue({ entryId: entryId.trim() });
 });
+// registerProposalCommands(program) deleted (WP-776 S2a, DEC-1771) — `pb accept`/`pb reject`/`pb proposals` are gone.
+registerOutcomeCommands(program);
+registerRoleCommands(program); // WP-722 S2 outcome; WP-730 S2 role — registerOutcomeCommands.ts / registerRoleCommands.ts
+// --- Relate / Unrelate commands (TEN-704) — registerEntryCommands.ts (WP-688 S2a: moved off
+// this shrink-only file to fund the --dry-run flag) ---
+registerRelateCommands(program);
 // --- Ingest command (BET-81) ---
 program
     .command('ingest <pattern>')
     .description('Bulk ingest documents to Chain as drafts')
-    .action(async (pattern) => {
-    try {
-        await runIngest({ pattern });
-    }
-    catch (err) {
-        console.error(err instanceof Error ? err.message : String(err));
-        process.exit(1);
+    .option('--dry-run', 'Stage entries without auto-committing. Shows summary only.')
+    .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) => {
+    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',
+        });
     }
+    await runIngest({
+        pattern,
+        dryRun: opts.dryRun,
+        resume: opts.resume,
+        concurrency,
+    });
 });
 // --- Fields command (BET-181 Slice 2) ---
 program
@@ -288,13 +488,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
@@ -305,13 +499,207 @@ program
         program.commands.find((c) => c.name() === 'constellation')?.help();
         return;
     }
-    try {
-        await runConstellation({ entryId: entryId.trim() });
+    await runConstellation({ entryId: entryId.trim() });
+});
+program
+    .command('brand-pack')
+    .description('Internal marketing: structured community copy via OpenRouter (requires OPENROUTER_API_KEY). Forwards args to scripts/brand-pack.mjs')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action(() => {
+    runBrandPack(process.argv);
+});
+// --- 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();
+});
+// D3a (WP-754/TASK-213): the entire `authority-domains` CLI command tree deleted — its backing
+// HTTP gateway routes (convex/http.ts) and convex/authorityDomains.ts are deleted in this same
+// slice, so every one of these subcommands would call a route that no longer exists.
+// --- 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());
+program.addCommand(createFeedbackCommand());
+program.addCommand(createConflictsCommand());
+program.addCommand(createShapeCommand());
+program.addCommand(createQuestionCommand());
+program.addCommand(createDirectionCommand());
+program.addCommand(createOrganisationCommand());
+program.addCommand(createAcceptPolicyCommand());
+// --- 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