@bugb-technologies/bravos 0.0.0-stage → 1.0.0

package/dist/cli.js

@@ -0,0 +1,963 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { DOCTOR_HELP, INIT_HELP, PROGRAM_HELP, SYNC_HELP } from './help.js';
+import { Command, CommanderError, InvalidArgumentError, Option } from 'commander';
+import { writeWorkflows } from './ci.js';
+import { writeCursorPointer } from './cursor.js';
+import { writeOmpExtension } from './omp.js';
+import { homeOf, installGlobal } from './global.js';
+import { uninstall } from './uninstall.js';
+import { checkKind, newToken, readAllAnswers, readDraft, renderReview, summarize, writePage } from './review.js';
+import { spawn as spawnChild } from 'node:child_process';
+import { createServer as netServer } from 'node:net';
+import { dirname as pathDirname, join as pathJoin } from 'node:path';
+import { OPENCODE_CONFIG, writeOpencode } from './opencode.js';
+import { GUIDE_TOPIC_IDS, renderGuide, renderGuideMarkdown } from './guide.js';
+import { detectHarnesses } from './detect.js';
+import { formatDoctor, runDoctor, withLicence } from './doctor.js';
+import { ensureGuardlink, registerPrePr, whichBin, writeScope } from './guardlink.js';
+import { installHook } from './hooks.js';
+import { activate, importLicence } from './account.js';
+import * as graph from './codegraph.js';
+import { askGraph } from './watch.js';
+import { plan as setupPlan, runSast, runSetup } from './setup.js';
+import { licenceDocument, licenceLib, licenceLines, requireFeature } from './licence.js';
+import { migrateFromOldName, reportMigration } from './migrate.js';
+import { listBundledSkills } from './skills.js';
+import { installSkills, linkSkillRoots, mirrorGuardlinkSkills, skillRootsLinked } from './install.js';
+import { readLock, sha256, writeLock } from './lock.js';
+import { mergeCodexConfig, mergeMcpJson, selectServers } from './mcp.js';
+import { hooksDir, skillsDir as bundledSkillsDir, version } from './paths.js';
+import { BravosError } from './types.js';
+const GUARDLINK_HINT = 'guardlink: not found on PATH — npm install -g guardlink';
+// Antigravity reads the shared .agents/ root; opencode and omp get their own files on top of a skills root.
+const AGENT_MAP = { claude: 'claude', codex: 'agents', agy: 'agents', opencode: 'opencode', omp: 'omp' };
+// @comment -- "Parses --agent <claude,codex>; codex maps to the .agents harness and anything else is a usage error."
+function parseAgents(value) {
+    const out = [];
+    // 'all' is every harness bravos knows: both skill roots plus the opencode and omp files.
+    const raws = value.split(',').map((s) => s.trim()).flatMap((r) => (r === 'all' ? ['claude', 'codex', 'opencode', 'omp'] : [r]));
+    for (const raw of raws) {
+        const h = AGENT_MAP[raw];
+        if (!h)
+            throw new InvalidArgumentError(`unknown agent '${raw}' (expected claude, codex, agy, opencode, omp or all)`);
+        if (!out.includes(h))
+            out.push(h);
+    }
+    return out;
+}
+const names = (list) => (list.length ? list.join(', ') : 'none');
+// @comment -- "Asks git (one `git check-ignore --stdin`, argv array, cwd root) which of the repo-relative paths bravos wrote are ignored and returns one warning per ignored top-level directory; silent when git is absent, the dir is not a repo, or nothing is ignored."
+function gitignoreWarnings(root, paths, env) {
+    if (paths.length === 0)
+        return [];
+    let out;
+    try {
+        out = execFileSync('git', ['check-ignore', '--stdin'], {
+            cwd: root,
+            env,
+            input: paths.join('\n') + '\n',
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+            timeout: 10000,
+        });
+    }
+    catch {
+        // Exit 1 (nothing ignored), 128 (not a repo) and ENOENT (no git) all mean: say nothing.
+        return [];
+    }
+    const dirs = [...new Set(out.split('\n').filter(Boolean).map((p) => p.split('/')[0]))];
+    return dirs.map((d) => `warning: ${d}/ is gitignored in this repo; files under it will not reach teammates via git`);
+}
+// @comment -- "Runs the install pipeline (detect, guardlink init unless sync, skills, hook, lock, MCP) and pushes summary lines as it goes, so a mid-way BravosError still leaves the summary so far in `lines`."
+function pipeline(root, io, opts, withGuardlink, lines) {
+    const dryRun = !!opts.dryRun;
+    if (dryRun)
+        lines.push('dry-run: nothing written');
+    reportMigration(migrateFromOldName(root, { dryRun, ownSkills: listBundledSkills(io.skillsDir).map((s) => s.name) }), lines);
+    const detected = detectHarnesses(root);
+    const chosen = opts.agent?.filter((a) => a === 'claude' || a === 'agents');
+    const harnesses = chosen && chosen.length > 0 ? chosen : detected.harnesses;
+    const defaulted = !(chosen && chosen.length > 0) && detected.defaulted;
+    const forceOpencode = !!opts.agent?.includes('opencode');
+    const forceOmp = !!opts.agent?.includes('omp');
+    lines.push(`Harnesses: ${harnesses.join(', ')}${defaulted ? ' (default: no evidence found)' : ''}`);
+    let guardlinkPending = false;
+    if (withGuardlink) {
+        const g = ensureGuardlink(root, harnesses, {
+            mode: opts.guardlinkMode,
+            skip: opts.guardlinkInit === false,
+            dryRun,
+            env: io.env,
+        });
+        switch (g.status) {
+            case 'present':
+                lines.push('guardlink: present');
+                break;
+            case 'initialised':
+                lines.push(`guardlink: initialised (${g.command.join(' ')})`);
+                break;
+            case 'skipped':
+                lines.push('guardlink: skipped');
+                break;
+            case 'guardlink-missing':
+                lines.push(GUARDLINK_HINT);
+                break;
+            case 'dry-run':
+                guardlinkPending = true;
+                lines.push(`guardlink: dry-run — would run ${g.command.join(' ')}`);
+                if (!whichBin('guardlink', io.env))
+                    lines.push(GUARDLINK_HINT);
+                break;
+            default: {
+                const unreachable = g;
+                throw new Error(`unknown guardlink status ${JSON.stringify(unreachable)}`);
+            }
+        }
+    }
+    // One folder behind both roots: render once (for Claude Code) instead of twice into the same files.
+    let linkedNow = false;
+    if (opts.linkSkills) {
+        if (!(harnesses.includes('claude') && harnesses.includes('agents'))) {
+            lines.push('link-skills: only one skills root is installed here, so there is nothing to link');
+        }
+        else {
+            const l = linkSkillRoots(root, { dryRun });
+            if (l.status === 'linked')
+                linkedNow = true;
+            if (l.status === 'linked')
+                lines.push(`link-skills: .agents/skills is now a link to .claude/skills (${l.removed.length} duplicate files removed)`);
+            else if (l.status === 'already-linked')
+                lines.push('link-skills: .agents/skills already links to .claude/skills');
+            else {
+                lines.push(`link-skills: not linked — ${l.reason}`);
+                for (const u of l.unknown.slice(0, 10))
+                    lines.push(`  ${u}`);
+                if (l.unknown.length > 10)
+                    lines.push(`  … and ${l.unknown.length - 10} more`);
+            }
+        }
+    }
+    const linked = harnesses.includes('claude') && harnesses.includes('agents') && (skillRootsLinked(root) || linkedNow);
+    if (linked)
+        lines.push('skills: .agents/skills is a link to .claude/skills — installed once');
+    const skillHarnesses = linked ? harnesses.filter((h) => h !== 'agents') : harnesses;
+    const skills = installSkills(root, skillHarnesses, { skillsDir: io.skillsDir, force: opts.force, dryRun });
+    lines.push(`Skills: ${skills.written.length} written, ${skills.updated.length} updated, ${skills.unchanged.length} unchanged, ${skills.skipped.length} skipped`);
+    for (const s of skills.skipped) {
+        lines.push(`  skipped ${s.path} — ${s.reason}`);
+        if (s.source)
+            lines.push(`  see: git diff --no-index ${s.path} ${s.source}`);
+    }
+    // guardlink writes its playbook skills under .claude/skills only; Codex reads .agents/skills.
+    const mirror = harnesses.includes('agents') && !linked
+        ? mirrorGuardlinkSkills(root, { force: opts.force, dryRun })
+        : { written: [], updated: [], unchanged: [], skipped: [] };
+    if (mirror.written.length + mirror.updated.length + mirror.unchanged.length + mirror.skipped.length > 0) {
+        lines.push(`Guardlink skills mirrored to .agents/skills: ${mirror.written.length} written, ${mirror.updated.length} updated, ${mirror.unchanged.length} unchanged, ${mirror.skipped.length} skipped`);
+        for (const s of mirror.skipped)
+            lines.push(`  skipped ${s.path} — ${s.reason}`);
+    }
+    const cursor = writeCursorPointer(root, harnesses, { force: opts.force, dryRun });
+    if (cursor.status === 'skipped')
+        lines.push(`Cursor: skipped ${cursor.path} — ${cursor.reason}`);
+    else if (cursor.status === 'no-skills')
+        lines.push(`Cursor: ${cursor.path} not written — no skills root was installed for it to point at`);
+    else if (cursor.status !== 'absent')
+        lines.push(`Cursor: ${cursor.path} ${cursor.status}`);
+    const omp = writeOmpExtension(root, io.env, { force: opts.force, dryRun, always: forceOmp });
+    if (omp.status === 'skipped')
+        lines.push(`omp: skipped ${omp.path} — ${omp.reason}`);
+    else if (omp.status !== 'absent')
+        lines.push(`omp: ${omp.path} ${omp.status} (banner and briefing at session start)`);
+    // Autopilot is the pre-PR gate plus the end-of-turn check.
+    if (opts.autopilot)
+        opts.prePrHook = true;
+    const hook = installHook(root, harnesses, { hooksDir: io.hooksDir, dryRun, prePr: !!opts.prePrHook, autopilot: !!opts.autopilot });
+    if (!dryRun) {
+        const lock = readLock(root);
+        for (const rel of hook.copied)
+            lock.files[rel] = sha256(readFileSync(join(root, rel)));
+        writeLock(root, lock);
+    }
+    for (const r of hook.registered)
+        lines.push(`Hooks: ${r.file} ${r.changed ? 'registered' : 'already registered'}`);
+    const guardlinkWritten = [];
+    if (opts.prePrHook) {
+        const p = registerPrePr(root, { dryRun });
+        if (p.status === 'no-config')
+            lines.push(`pre_pr: ${p.path} absent, bravos's gate not listed in guardlink's agent block (run guardlink init, then bravos sync --pre-pr-hook)`);
+        else if (p.status === 'already-registered')
+            lines.push(`pre_pr: ${p.path} already lists bravos's gate`);
+        else {
+            lines.push(`pre_pr: ${p.path} lists bravos's gate; run guardlink sync to render it into the agent instruction files`);
+            guardlinkWritten.push(p.path);
+        }
+    }
+    if (opts.scope) {
+        const s = writeScope(root, io.skillsDir ?? bundledSkillsDir(), { dryRun, guardlinkPending });
+        if (s.status === 'present')
+            lines.push('scope: present');
+        else if (s.status === 'written') {
+            lines.push(`scope: written ${s.path}`);
+            guardlinkWritten.push(s.path);
+        }
+        else if (s.status === 'no-guardlink')
+            lines.push(`scope: not written — .guardlink/ is absent (run guardlink init first)`);
+        else
+            lines.push('scope: not written — the bravos package has no bravos-env/scope.example.yaml');
+    }
+    const { selected, deferred } = selectServers(io.env);
+    // opencode lists skills only through its skill tool and runs no hooks: commands, a plugin and MCP.
+    const oc = writeOpencode(root, io.env, selected, { force: opts.force, dryRun, skillsDir: io.skillsDir, always: forceOpencode });
+    if (oc.status === 'done') {
+        lines.push(`opencode: ${oc.written.length} written, ${oc.unchanged.length} unchanged, ${oc.skipped.length} skipped (plugin, /bravos commands)${oc.mcpAdded.length ? `; ${OPENCODE_CONFIG} mcp added ${oc.mcpAdded.join(', ')}` : ''}${oc.mcpUpdated?.length ? `; ${OPENCODE_CONFIG} mcp refreshed ${oc.mcpUpdated.join(', ')}` : ''}`);
+        for (const s of oc.skipped)
+            lines.push(`  skipped ${s.path} — ${s.reason}`);
+    }
+    const mcpLine = (m) => lines.push(`MCP: ${m.path} added ${names(m.added)}; kept ${names(m.kept)}${m.updated?.length ? `; refreshed ${names(m.updated)} (it pointed at another bravos install or graph store)` : ''}`);
+    mcpLine(mergeMcpJson(root, selected, { dryRun }));
+    if (harnesses.includes('agents'))
+        mcpLine(mergeCodexConfig(root, selected, { dryRun }));
+    if (deferred.length) {
+        const tools = runDoctor(root, io.env).tools;
+        const bin = { cxg: 'cxg', codegraph: 'codegraph-mcp' };
+        for (const d of deferred)
+            lines.push(`MCP deferred: ${d} — ${tools.find((t) => t.name === bin[d])?.hint ?? ''}`);
+    }
+    let workflowWritten = [];
+    if (opts.ci) {
+        const wf = writeWorkflows(root, { force: opts.force, dryRun });
+        lines.push(`Workflows: ${wf.written.length} written, ${wf.updated.length} updated, ${wf.unchanged.length} unchanged, ${wf.skipped.length} skipped`);
+        for (const s of wf.skipped)
+            lines.push(`  skipped ${s.path} — ${s.reason}`);
+        workflowWritten = [...wf.written, ...wf.updated];
+    }
+    const cursorWritten = cursor.status === 'written' || cursor.status === 'updated' ? [cursor.path] : [];
+    const ompWritten = omp.status === 'written' || omp.status === 'updated' ? [omp.path] : [];
+    const ocWritten = oc.status === 'done' ? [...oc.written, ...(oc.mcpAdded.length ? [OPENCODE_CONFIG] : [])] : [];
+    const written = [...skills.written, ...skills.updated, ...mirror.written, ...mirror.updated, ...cursorWritten, ...ompWritten, ...ocWritten, ...workflowWritten, ...hook.copied, ...hook.registered.map((r) => r.file), ...guardlinkWritten];
+    lines.push(...gitignoreWarnings(root, written, io.env));
+    if (opts.autopilot) {
+        lines.push('autopilot on: an end-of-turn check (Stop hook) sends the agent back once when changed code lacks annotations, sits under a confirmed or stale claim, or adds exposures; the pre-PR gate checks every gh pr create / gh pr ready.');
+        lines.push('autopilot: the first time proving comes up, the agent asks you once how you want it handled and records your answer in .guardlink/proving.md. BRAVOS_AUTOPILOT=off pauses the check.');
+    }
+    if (harnesses.includes('agents'))
+        lines.push('In Codex run /hooks once to trust .codex/hooks.json');
+    // A user-level install of another version silently replaces these skills in Claude Code, so a
+    // repo sync brings an existing one up to date too (never creates one; a dry run only reports;
+    // BRAVOS_SYNC_GLOBAL=off keeps the two separate).
+    // @comment -- "When the person already has a user-level install (bravos init --global) of another version, a repo sync re-applies it through installGlobal, so an older ~/.claude/skills copy never shadows the repo's; it never creates a user-level install, and BRAVOS_SYNC_GLOBAL=off opts out."
+    let userVersion = null;
+    try {
+        userVersion = JSON.parse(readFileSync(pathJoin(homeOf(io.env), '.bravos', 'skills.lock'), 'utf8'))?.bravos_version ?? null;
+    }
+    catch {
+        userVersion = null;
+    }
+    if (userVersion && userVersion !== version() && resolve(homeOf(io.env)) !== resolve(root)) {
+        if (dryRun)
+            lines.push(`user-level bravos is ${userVersion}: a real sync would bring it to ${version()} too`);
+        else if (io.env.BRAVOS_SYNC_GLOBAL === 'off') {
+            lines.push(`warning: your user-level bravos (~/.claude/skills) is ${userVersion}; Claude Code prefers it over this repo's ${version()}. Run: bravos sync --global`);
+        }
+        else if (io.env.CLAUDECODE) {
+            // Inside a Claude Code session, writes under ~/.claude can be held back by its sandbox while the
+            // lock in ~/.bravos still lands, which would mark a stale copy current. Leave the user install alone.
+            lines.push(`warning: your user-level bravos is ${userVersion}, older than ${version()}; this runs inside a Claude Code session, which may not write ~/.claude, so it was left alone. In your own terminal run: bravos sync --global`);
+        }
+        else {
+            try {
+                const sub = [];
+                installGlobal(io.env, sub, { skillsDir: io.skillsDir, hooksDir: io.hooksDir });
+                const skipped = sub.filter((l) => l.startsWith('  skipped'));
+                if (skipped.length) {
+                    lines.push(`warning: user-level bravos only partly updated; ${skipped.length} file(s) were not written. Run: bravos sync --global`);
+                    lines.push(...skipped);
+                }
+                else
+                    lines.push(`user-level bravos updated ${userVersion} → ${version()} (~/.claude/skills, ~/.bravos/hooks), so Claude Code does not use an older copy. BRAVOS_SYNC_GLOBAL=off keeps them separate.`);
+            }
+            catch (e) {
+                lines.push(`warning: could not update your user-level bravos (${e instanceof Error ? e.message : String(e)}). Run: bravos sync --global`);
+            }
+        }
+    }
+    lines.push('Next: open a session. The banner and briefing load by themselves; /bravos is only for the next step.');
+}
+// @comment -- "Builds the commander program (init, sync, doctor); exit-code mapping lives in run()."
+export function buildProgram(io, result) {
+    const program = new Command('bravos')
+        .description('Makes Claude Code and Codex power users of guardlink, cxg, the code graph and SAST: installs skills, a session-start briefing, MCP wiring and optional CI into a repository.')
+        .addHelpText('after', PROGRAM_HELP)
+        .version(version())
+        .exitOverride()
+        .configureOutput({ writeOut: (s) => io.stdout(s.replace(/\n$/, '')), writeErr: (s) => io.stderr(s.replace(/\n$/, '')) });
+    const guarded = (fn) => {
+        const lines = [];
+        try {
+            fn(lines);
+        }
+        catch (err) {
+            if (!(err instanceof BravosError))
+                throw err;
+            result.code = err.exitCode;
+            for (const l of lines)
+                io.stdout(l);
+            io.stderr(err.message);
+            return;
+        }
+        for (const l of lines)
+            io.stdout(l);
+    };
+    const dirArg = (dir) => resolve(dir ?? process.cwd());
+    // @comment -- "The paid install flags (--pre-pr-hook, --autopilot, --ci) are checked against the licence before the pipeline writes anything, so a refusal leaves the repo untouched and names the flag."
+    const gateInstallFlags = async (opts, cmd) => {
+        const flags = [
+            [opts.autopilot, 'pre-pr', `bravos ${cmd} --autopilot`],
+            [opts.prePrHook, 'pre-pr', `bravos ${cmd} --pre-pr-hook`],
+            [opts.ci, 'ci', `bravos ${cmd} --ci`],
+        ];
+        for (const [on, feature, what] of flags)
+            if (on)
+                await requireFeature(io.env, feature, what);
+    };
+    const guardedAsync = async (fn) => {
+        const lines = [];
+        try {
+            await fn(lines);
+        }
+        catch (err) {
+            if (!(err instanceof BravosError))
+                throw err;
+            result.code = err.exitCode;
+            for (const l of lines)
+                io.stdout(l);
+            io.stderr(err.message);
+            return;
+        }
+        for (const l of lines)
+            io.stdout(l);
+    };
+    program
+        .command('init [dir]')
+        .description('First install: detect agents, run guardlink init if needed, install skills, hooks and MCP wiring.')
+        .addHelpText('after', INIT_HELP)
+        .option('--agent <list>', 'comma-separated agents: claude,codex,agy,opencode,omp, or all', parseAgents)
+        .addOption(new Option('--guardlink-mode <mode>', 'guardlink annotation mode').choices(['inline', 'external']).default('inline'))
+        .option('--no-guardlink-init', 'do not run guardlink init')
+        .option('--force', 'overwrite edited or authored skill files')
+        .option('--pre-pr-hook', 'also register the PreToolUse gate that checks gh pr create / gh pr ready')
+        .option('--ci', 'also write the PR gate and nightly GitHub Actions workflows into .github/workflows/')
+        .option('--scope', 'also write the loopback-only cxg scope starter to .guardlink/scope.yaml when absent')
+        .option('--link-skills', 'make .agents/skills a link to .claude/skills so each skill exists once')
+        .option('--global', 'install for your user (home folder) instead of a repository')
+        .option('--autopilot', 'end-of-turn check plus the pre-PR gate, so upkeep happens without being asked')
+        .option('--dry-run', 'report what would change without writing')
+        .action((dir, opts) => guardedAsync(async (lines) => {
+        await gateInstallFlags(opts, 'init');
+        if (opts.global)
+            installGlobal(io.env, lines, { force: opts.force, dryRun: opts.dryRun, skillsDir: io.skillsDir, hooksDir: io.hooksDir });
+        else
+            pipeline(dirArg(dir), io, opts, true, lines);
+    }));
+    program
+        .command('sync [dir]')
+        .description('Re-apply the installed bravos version to a repository (never runs guardlink init).')
+        .addHelpText('after', SYNC_HELP)
+        .option('--agent <list>', 'comma-separated agents: claude,codex,agy,opencode,omp, or all', parseAgents)
+        .option('--force', 'overwrite edited or authored skill files')
+        .option('--pre-pr-hook', 'also register the PreToolUse gate that checks gh pr create / gh pr ready')
+        .option('--ci', 'also write the PR gate and nightly GitHub Actions workflows into .github/workflows/')
+        .option('--scope', 'also write the loopback-only cxg scope starter to .guardlink/scope.yaml when absent')
+        .option('--link-skills', 'make .agents/skills a link to .claude/skills so each skill exists once')
+        .option('--global', 'install for your user (home folder) instead of a repository')
+        .option('--autopilot', 'end-of-turn check plus the pre-PR gate, so upkeep happens without being asked')
+        .option('--dry-run', 'report what would change without writing')
+        .action((dir, opts) => guardedAsync(async (lines) => {
+        await gateInstallFlags(opts, 'sync');
+        if (opts.global)
+            installGlobal(io.env, lines, { force: opts.force, dryRun: opts.dryRun, skillsDir: io.skillsDir, hooksDir: io.hooksDir });
+        else
+            pipeline(dirArg(dir), io, opts, false, lines);
+    }));
+    program
+        .command('licence')
+        .alias('license')
+        .description('Which plan this machine is on, where the licence is, and what it unlocks.')
+        .option('--json', 'print the status as JSON (bravos.licence/v1)')
+        .action((opts) => guardedAsync(async (lines) => {
+        const L = await licenceLib();
+        const v = L.status(io.env);
+        if (opts.json)
+            lines.push(JSON.stringify(licenceDocument(v), null, 2));
+        else
+            lines.push(...licenceLines(L, v));
+    }));
+    program
+        .command('account <action> [file]')
+        .description('activate: sign in once in the browser and get this machine its licence (a 30-day Team trial when the account has no plan); import FILE: install a downloaded licence; status: same as bravos licence.')
+        .action((action, file) => guardedAsync(async (lines) => {
+        if (action === 'activate')
+            lines.push(...(await activate({ env: io.env, stdout: io.stdout })));
+        else if (action === 'import') {
+            if (!file)
+                throw new BravosError('usage: bravos account import <licence file>');
+            lines.push(...(await importLicence(resolve(file), { env: io.env, stdout: io.stdout })));
+        }
+        else if (action === 'status') {
+            const L = await licenceLib();
+            lines.push(...licenceLines(L, L.status(io.env)));
+        }
+        else
+            throw new BravosError(`unknown account action ${JSON.stringify(action)}: activate, import <file> or status`);
+    }));
+    program
+        .command('setup')
+        .description('Put the binaries bravos drives on this machine: the analyzer (bravos-cli, SAST) and the code graph (codegraph-build, codegraph-mcp) are licensed bundles fetched through the account portal, verified and staged under $BRAVOS_HOME; --tools adds guardlink and cxg through npm and cargo.')
+        .option('--analyzer', 'only the analyzer bundle')
+        .option('--codegraph', 'only the code graph bundle')
+        .option('--tools', 'also guardlink (npm) and cxg (cargo); needs -y')
+        .option('--check', 'report what is here and what setup would do; changes nothing')
+        .option('--dry-run', 'say what would be fetched or run; changes nothing')
+        .option('-y, --yes', 'run the package-manager installs, and refetch a bundle that is already staged')
+        .option('--json', 'with --check: print the plan as JSON (bravos.setup-plan/v1)')
+        .action((opts) => guardedAsync(async (lines) => {
+        if (opts.check && opts.json) {
+            const p = await setupPlan(io.env);
+            lines.push(JSON.stringify({ schema: 'bravos.setup-plan/v1', plan: p.licence.licensed ? 'licensed' : p.licence.state, items: p.items }, null, 2));
+            return;
+        }
+        lines.push(...(await runSetup(io.env, opts, { echo: io.stdout })));
+    }));
+    program
+        .command('graph [question] [args...]')
+        .description('Ask the code graph (Team plan): `graph build [DIR] [--scip MODE]` indexes a repository; `graph <question> [args] --json` asks it (attack-surface, entry-points, callers <file::symbol>, reachable-sinks, call-chain, …; the same answers as the codegraph_ MCP tools); `graph --json` lists every question this machine\'s binary answers.')
+        .option('-C, --dir <dir>', 'the repository (default: the current directory)')
+        .option('--json', 'print the answer as JSON')
+        .option('--scip <mode>', 'build: how the type checkers run — no-exec (default), auto, trusted, isolate, off')
+        .option('--mode <mode>', 'build: auto (default), build, reuse')
+        .allowUnknownOption()
+        .action((question, args, opts) => guardedAsync(async (lines) => {
+        const L = await licenceLib();
+        const lic = L.status(io.env);
+        if (!L.entitled(lic, 'codegraph')) {
+            // In --json the refusal is a document too, so a probe (the briefing, watch) reads 'locked' rather than 'broken'.
+            if (opts.json) {
+                lines.push(JSON.stringify({ error: 'licence_required', message: L.refusal(lic, 'codegraph', `bravos graph ${question ?? ''}`.trim()), remedy: 'bravos account activate' }));
+                result.code = 1;
+                return;
+            }
+            throw new BravosError(L.refusal(lic, 'codegraph', `bravos graph ${question ?? ''}`.trim()));
+        }
+        const root = dirArg(opts.dir ?? (question === 'build' && args[0] && !args[0].startsWith('--') ? args.shift() : undefined));
+        if (question === 'build') {
+            const r = graph.build(root, io.env, { scip: opts.scip, mode: opts.mode, json: opts.json });
+            lines.push((r.stdout || r.stderr).trim());
+            if (r.status !== 0)
+                result.code = 1;
+            return;
+        }
+        if (!question) {
+            const tools = await graph.listTools(root, io.env);
+            if (opts.json)
+                lines.push(JSON.stringify({ tools }, null, 2));
+            else
+                for (const t of tools)
+                    lines.push(`${t.name.replace(/^codegraph_/, '').replace(/_/g, '-').padEnd(26)} ${(t.description ?? '').split('\n')[0].slice(0, 100)}`);
+            return;
+        }
+        const extra = args.filter((a) => a !== '--json');
+        // The same document the Python CLI printed: {result} on an answer, {error, message, remedy} on a refusal, exit 2 when the graph is not built.
+        const a = await askGraph(root, io.env, question, extra);
+        if (!a)
+            throw new BravosError('codegraph-mcp is not installed: bravos setup --codegraph fetches it');
+        if (a.error) {
+            if (opts.json)
+                lines.push(JSON.stringify(a, null, 2));
+            else
+                lines.push(`no answer: ${a.message}${a.remedy ? `\nfix: ${a.remedy}` : ''}`);
+            result.code = a.error === 'codegraph_unavailable' ? 2 : 1;
+            return;
+        }
+        lines.push(JSON.stringify(opts.json ? a : a.result, null, 2));
+    }));
+    program
+        .command('doctor [dir]')
+        .description('Read-only check of the tools, licence, skills and hooks bravos relies on.')
+        .addHelpText('after', DOCTOR_HELP)
+        .action((dir) => guardedAsync(async (lines) => {
+        const L = await licenceLib();
+        const v = L.status(io.env);
+        lines.push(formatDoctor(withLicence(runDoctor(dirArg(dir), io.env), L.planLine(v), v.licensed)));
+    }));
+    program
+        .command('uninstall [dir]')
+        .description('Remove what bravos installed in a repository (or, with --global, for your user): its unchanged files, hook entries and .bravos/.')
+        .option('--global', 'remove the user-level install from your home folder instead')
+        .option('--force', 'also remove bravos files you edited')
+        .option('--dry-run', 'list what would be removed without removing it')
+        .action((dir, opts) => guarded((lines) => {
+        const root = opts.global ? homeOf(io.env) : dirArg(dir);
+        const r = uninstall(root, { force: opts.force, dryRun: opts.dryRun, home: opts.global });
+        if (opts.dryRun)
+            lines.push('dry-run: nothing removed');
+        lines.push(`${opts.global ? 'User-level install' : 'Repository'}: ${root}`);
+        lines.push(`Removed: ${r.removed.length} file(s)${opts.dryRun ? ' (would be)' : ''}`);
+        for (const p of r.removed)
+            lines.push(`  ${p}`);
+        for (const u of r.unregistered)
+            lines.push(`Unregistered bravos's hooks from ${u}`);
+        for (const k of r.kept)
+            lines.push(`Kept ${k.path} — ${k.reason}`);
+        for (const n of r.notes)
+            lines.push(`Note: ${n}`);
+        if (r.unregistered.some((u) => u.includes('.codex')))
+            lines.push('Codex keeps its own trust record for removed hooks; nothing to do there.');
+    }));
+    program
+        .command('review <kind> [dir]')
+        .description("Open bravos's questions (.guardlink/<kind>-draft.json, e.g. kind 'intent') as a branded page people answer in; answers are saved to .guardlink/<kind>-answers/<name>.json. Runs no model.")
+        .option('--summary', 'print everyone\'s answers, agreements and disagreements, as plain text')
+        .option('--no-serve', 'write the page as a file instead of serving it; Save then downloads the answers')
+        .option('--no-open', 'do not open a browser, only print the URL')
+        .option('--share', 'render the page for a shared claude.ai artifact (Claude Code only; the agent publishes it)')
+        .action((kind, dir, opts) => guardedAsync(async (lines) => {
+        const root = dirArg(dir);
+        checkKind(kind);
+        const draft = readDraft(root, kind);
+        if (opts.summary) {
+            const { files, skipped } = readAllAnswers(root, draft);
+            lines.push(summarize(draft, files, skipped));
+            return;
+        }
+        if (opts.share) {
+            const rel = writePage(root, `${kind}-share`, await renderReview(draft, { kind: 'artifact' }));
+            lines.push(`Share page: ${rel}`);
+            lines.push('Sharing publishes your security intent to claude.ai, private until you share the link; teammates need access there.');
+            lines.push('In Claude Code: publish that file with the Artifact tool and capabilities {db: {}}; share the link with the team.');
+            lines.push(`Each person's answers land as a document in the "answers" collection; read them with ArtifactData list "answers" and write each one to .guardlink/${kind}-answers/<name>.json, then run bravos review ${kind} --summary.`);
+            lines.push(`Other harnesses cannot publish artifacts: use bravos review ${kind} and git instead.`);
+            return;
+        }
+        if (opts.serve === false) {
+            const rel = writePage(root, kind, await renderReview(draft, { kind: 'file' }));
+            lines.push(`Review page: ${rel} (Save downloads your answers; put them in .guardlink/${kind}-answers/ and commit)`);
+            if (opts.open !== false)
+                openInBrowser(pathJoin(root, rel));
+            return;
+        }
+        const port = await freePort();
+        const token = newToken();
+        const child = spawnChild(process.execPath, [pathJoin(pathDirname(fileURLToPath(import.meta.url)), 'review-server.js'), root, kind, token, String(port)], { detached: true, stdio: 'ignore' });
+        child.unref();
+        const url = `http://127.0.0.1:${port}/?t=${token}`;
+        if (!(await waitUp(url)))
+            throw new BravosError('the review server did not start; try bravos review --no-serve');
+        lines.push(`Review page: ${url}`);
+        lines.push(`Answers save to .guardlink/${kind}-answers/<name>.json. Teammates run bravos review ${kind} after pulling. The page stops on Done or after 30 minutes idle.`);
+        lines.push(`When everyone is done: bravos review ${kind} --summary`);
+        if (opts.open !== false)
+            openInBrowser(url);
+    }));
+    program
+        .command('next [dir]')
+        .description("bravos's setup score for a repository: what is switched on, what each step unlocks, the exact command for the next one. Read-only; runs guardlink ci and git, no model.")
+        .addOption(new Option('--harness <name>', 'show skills in this harness syntax').choices(['claude', 'codex', 'omp', 'opencode', 'other']).default('claude'))
+        .option('--json', 'print the setup as JSON (bravos.setup/v1)')
+        .action((dir, opts) => guardedAsync(async (lines) => {
+        const root = dirArg(dir);
+        const briefing = await import(pathToFileURL(pathJoin(hooksDir(), 'lib', 'briefing.mjs')).href);
+        const setupLib = await import(pathToFileURL(pathJoin(hooksDir(), 'lib', 'setup.mjs')).href);
+        const inputs = await briefing.collect(root, io.env);
+        const s = setupLib.readSetup(root, inputs, opts.harness);
+        if (opts.json) {
+            lines.push(JSON.stringify(s, null, 2));
+            return;
+        }
+        lines.push(`bravos setup ${s.done}/${s.total} for ${inputs.repo}`, '');
+        for (const item of s.items) {
+            const mark = item.on ? '✔' : item.unavailable ? '·' : item === s.next ? '→' : '✘';
+            lines.push(`${mark} ${item.label}${item.on ? '' : item.unavailable ? '  (not available here)' : ''}`);
+            if (!item.on)
+                lines.push(`    unlocks: ${item.unlocks}`, `    how:     ${item.how}`);
+        }
+        lines.push('', s.next ? `Next: ${s.next.label} — ${s.next.how}` : 'Everything bravos can use here is on.', 'More: bravos guide · bravos guide roles · bravos guide tasks', 'Live view: bravos watch (in a second terminal pane)');
+    }));
+    program
+        .command('watch [dir]')
+        .description('A live, read-only view of the repository\'s security work for a second terminal pane beside any agent: setup, open and confirmed exposures, what to test next, stale claims, the code graph, SAST, teammates\' PRs and autopilot nudges. Redraws when files change. Runs no model.')
+        .option('--interval <seconds>', 'how often to re-read PRs, boundaries and the model\'s size', seconds(10), 60)
+        .option('--graph-interval <seconds>', 'how often to ask the code graph again (each ask takes a few seconds)', seconds(30), 300)
+        .option('--once', 'print one frame and exit (also what happens when stdout is not a terminal)')
+        .option('--json', 'print one snapshot as JSON (bravos.watch/v1) and exit')
+        .option('--compact', 'use the narrow layout whatever the width')
+        .action((dir, opts) => guardedAsync(async (lines) => {
+        const root = dirArg(dir);
+        const watch = await import('./watch.js');
+        const color = !io.env.NO_COLOR && io.env.BRAVOS_WATCH_COLOR !== 'off';
+        const live = !opts.once && !opts.json && process.stdout.isTTY && process.stdin.isTTY;
+        if (live) {
+            await watch.runWatch(root, io.env, { intervalSec: opts.interval, graphIntervalSec: opts.graphInterval, color, compact: !!opts.compact });
+            return;
+        }
+        const sn = await watch.snapshot(root, io.env, { refreshGraph: true, refreshSlow: true });
+        if (opts.json) {
+            lines.push(JSON.stringify(sn, null, 2));
+            return;
+        }
+        const width = Number(io.env.COLUMNS) || process.stdout.columns || 100;
+        const events = watch.readAutopilotEvents(root).slice(-8);
+        lines.push(watch.buildFrame(sn, events, { width, color: color && !!process.stdout.isTTY, status: 'once', compact: !!opts.compact }));
+    }));
+    program
+        .command('workspace <action> [args...]')
+        .description("One application made of several repositories. create NAME --member PATH[=service[@url]]... makes a bravos workspace, links the members with guardlink link-project, installs bravos in each member and in the app folder (the parent they share, or --folder), and keeps a snapshot bravos's hooks, watch and reports read; add NAME PATH[=service[@url]], remove NAME MEMBER, target NAME SERVICE=URL, show [NAME], sync [NAME]. Runs no model; nothing is pushed.")
+        .option('--member <spec>', 'create: a member, PATH[=service[@url]]; repeatable', (v, acc) => [...acc, v], [])
+        .option('--folder <dir>', 'create: the app folder (default: the parent every member sits under, if they share one)')
+        .option('--json', 'show: print the snapshot and export as JSON')
+        .action((action, args, opts) => guardedAsync(async (lines) => {
+        // show only reads the snapshot; every verb that changes membership is on the Team plan.
+        if (action !== 'show')
+            await requireFeature(io.env, 'workspace', `bravos workspace ${action}`);
+        const ws = await import('./workspace.js');
+        const env = io.env;
+        const cwd = process.cwd();
+        // bravos init (no bravos yet) or sync in one folder, in-process, summarised to one line.
+        const install = async (path, appFolder = false) => {
+            const out = [];
+            const fresh = !appFolder && !existsSync(pathJoin(path, '.bravos', 'skills.lock'));
+            const code = await run([fresh ? 'init' : 'sync', path], { ...io, stdout: (s) => out.push(s), stderr: (s) => out.push(s) });
+            return `${code === 0 ? '✔' : '✘'} bravos ${fresh ? 'init' : 'sync'} ${path}${code === 0 ? '' : `: ${out.filter(Boolean).slice(-1)[0] ?? `exit ${code}`}`}`;
+        };
+        const known = (name) => {
+            const members = ws.getWorkspace(env, name).members.map((m) => m.path);
+            const prior = members.map((m) => ws.readSnapshot(m)).find(Boolean) ?? null;
+            return { members, appFolder: prior?.appFolder ?? ws.appFolderFor(members) };
+        };
+        const finish = (name, appFolder) => {
+            const { snap, exp, exportError } = ws.refresh(name, env, appFolder);
+            lines.push('', ...ws.describe(snap, exp));
+            if (exportError)
+                lines.push(`(export: ${exportError})`);
+        };
+        if (action === 'create') {
+            const name = args[0];
+            if (!name)
+                throw new BravosError('usage: bravos workspace create NAME --member PATH[=service[@url]] ...');
+            if (!opts.member.length)
+                throw new BravosError('give each repository with --member PATH[=service[@url]]');
+            const specs = opts.member.map((m) => ws.parseMemberSpec(m, cwd));
+            for (const s of specs)
+                ws.checkMemberPath(s.path);
+            const appFolder = ws.appFolderFor(specs.map((s) => s.path), opts.folder ?? null);
+            ws.createWorkspace(env, name, specs);
+            lines.push(`bravos workspace ${name}: ${specs.length} member${specs.length === 1 ? '' : 's'} (registry: ${ws.registryFile(env)})`);
+            lines.push(specs.length > 1 ? `guardlink: ${ws.linkProject([...specs.map((s) => s.path), '-w', name], env, cwd)}` : 'guardlink: one member, nothing to link yet');
+            for (const s of specs)
+                lines.push(await install(s.path));
+            if (appFolder) {
+                mkdirSync(appFolder, { recursive: true });
+                lines.push(await install(appFolder, true));
+            }
+            finish(name, appFolder);
+            lines.push('', appFolder ? `Open your agent in ${appFolder} for questions across services, or in a service for changes to it.` : 'No app folder: the members do not share a parent. Pass --folder DIR to make one.');
+            lines.push(`For the graph to link services, build it over the app folder: bravos graph build ${appFolder ?? '<app folder>'} --scip no-exec`);
+            return;
+        }
+        if (action === 'add') {
+            const [name, spec] = args;
+            if (!name || !spec)
+                throw new BravosError('usage: bravos workspace add NAME PATH[=service[@url]]');
+            const s = ws.parseMemberSpec(spec, cwd);
+            ws.checkMemberPath(s.path);
+            const { members, appFolder } = known(name);
+            ws.addMember(env, name, s);
+            lines.push(members.length ? `guardlink: ${ws.linkProject(['--add', s.path, '--from', members[0]], env, cwd)}` : 'guardlink: first member, nothing to link yet');
+            lines.push(await install(s.path));
+            finish(name, appFolder);
+            return;
+        }
+        if (action === 'remove') {
+            const [name, member] = args;
+            if (!name || !member)
+                throw new BravosError('usage: bravos workspace remove NAME MEMBER');
+            const { members, appFolder } = known(name);
+            const gone = ws.removeMember(env, name, member, cwd);
+            const leaving = gone.path;
+            const from = members.find((m) => m !== leaving);
+            if (from && members.length > 2)
+                lines.push(`guardlink: ${ws.linkProject(['--remove', member, '--from', from], env, cwd)}`);
+            if (leaving)
+                rmSync(pathJoin(leaving, ws.WORKSPACE_DIR), { recursive: true, force: true });
+            finish(name, appFolder);
+            return;
+        }
+        if (action === 'target') {
+            const [name, pair] = args;
+            if (!name || !pair || !/^[^=]+=https?:\/\//.test(pair))
+                throw new BravosError('usage: bravos workspace target NAME SERVICE=http://host:port');
+            const [service, url] = [pair.slice(0, pair.indexOf('=')), pair.slice(pair.indexOf('=') + 1)];
+            ws.setTarget(env, name, service, url);
+            finish(name, known(name).appFolder);
+            return;
+        }
+        if (action === 'show' || action === 'sync') {
+            const here = ws.readSnapshot(dirArg(undefined));
+            const name = args[0] ?? here?.name;
+            if (!name)
+                throw new BravosError('no workspace here: give its name, or create one with bravos workspace create');
+            const { members, appFolder } = known(name);
+            if (action === 'sync') {
+                for (const m of members)
+                    lines.push(await install(m));
+                if (appFolder)
+                    lines.push(await install(appFolder, true));
+            }
+            const { snap, exp, exportError } = ws.refresh(name, env, appFolder);
+            if (opts.json) {
+                lines.push(JSON.stringify({ workspace: snap, export: exp }, null, 2));
+                return;
+            }
+            lines.push(...ws.describe(snap, exp));
+            if (exportError)
+                lines.push(`(export: ${exportError})`);
+            return;
+        }
+        throw new BravosError(`unknown workspace action '${action}'; use create, add, remove, target, show or sync`);
+    }));
+    program
+        .command('report <action> [id]')
+        .description("Evidence-bound security write-ups (the bravos-report skill writes the prose). 'data' gathers the facts into .bravos/reports/<id>/evidence.json; 'check' gates the report.md written from them; 'export' renders it to md, txt, html and pdf; 'list' shows the reports. Runs no model; nothing under .bravos/reports is committed.")
+        .option('-C, --dir <dir>', 'repository root (default: the current directory)')
+        .addOption(new Option('--kind <kind>', "data: assessment, finding, retest or brief").choices(['assessment', 'finding', 'retest', 'brief']).default('assessment'))
+        .option('--finding <ref>', 'data, kind finding: the claim key prefix, file:line or EXP id of the one finding')
+        .option('--no-graph', 'data: skip asking the code graph')
+        .option('--workspace <name>', 'data: one report across every service of a bravos workspace (the default at an app folder)')
+        .option('--format <list>', "export: comma-separated md, txt, html, pdf", 'md,html')
+        .option('--open', 'export: open the pdf (or html) when done')
+        .option('--force', 'export: export even when the check fails')
+        .option('--json', 'print JSON (data: the bundle; check: the verdict; list: the reports)')
+        .action((action, id, opts) => guardedAsync(async (lines) => {
+        const root = dirArg(opts.dir);
+        const data = await import('./report/data.js');
+        if (action === 'data') {
+            // A workspace report: named with --workspace, or implied at an app folder.
+            const wsLib = await import(pathToFileURL(pathJoin(hooksDir(), 'lib', 'workspace.mjs')).href);
+            const here = wsLib.readWorkspace(root);
+            const wsName = opts.workspace ?? (here?.isAppFolder && opts.kind !== 'finding' ? here.name : null);
+            if (opts.workspace && here && here.name !== opts.workspace)
+                throw new BravosError(`this folder belongs to workspace ${here.name}, not ${opts.workspace}`);
+            if (wsName && !here)
+                throw new BravosError(`no snapshot of workspace ${wsName} here: run bravos workspace show ${wsName} in this folder's app folder or a member`);
+            const bundle = wsName
+                ? await data.gatherWorkspaceEvidence(here.appFolder ?? root, io.env, { name: here.name, members: here.members, edges: here.export?.edges ?? null, unresolved: here.export?.unresolved ?? [] }, { kind: opts.kind, graph: opts.graph })
+                : await data.gatherEvidence(root, io.env, { kind: opts.kind, finding: opts.finding ?? id ?? null, graph: opts.graph });
+            const { evidence } = data.writeEvidence(wsName && here?.appFolder ? here.appFolder : root, bundle);
+            if (opts.json) {
+                lines.push(JSON.stringify(bundle, null, 2));
+                return;
+            }
+            const count = (l) => bundle.candidates.filter((c) => c.level === l).length;
+            const rel = (p) => p.replace(root + '/', '');
+            lines.push(`Report ${bundle.id} (${bundle.kind}) for ${bundle.repo} @ ${bundle.git.short ?? '?'}`, `Evidence: ${rel(evidence)}`, `${bundle.candidates.length} exposure${bundle.candidates.length === 1 ? '' : 's'}: ${count('reproduced')} reproduced at runtime, ${count('held')} control held, ${count('code-review')} code review, ${count('suspected')} suspected`, `${bundle.runs.length} cxg run${bundle.runs.length === 1 ? '' : 's'}, ${bundle.items.length} citable facts`, ...(bundle.gaps.length ? ['Not available:', ...bundle.gaps.map((g) => `  - ${g}`)] : []), `Next: write ${rel(join(data.reportDir(root, bundle.id), 'report.md'))} from the bravos-report template, then bravos report check ${bundle.id}`);
+            return;
+        }
+        if (action === 'list') {
+            const ids = data.listReports(root);
+            const rows = ids.map((r) => ({ id: r, meta: data.readMeta(root, r) }));
+            if (opts.json) {
+                lines.push(JSON.stringify(rows.map((r) => ({ id: r.id, ...r.meta })), null, 2));
+                return;
+            }
+            if (!rows.length)
+                lines.push('No reports yet: bravos report data, then /bravos-report writes report.md');
+            for (const r of rows) {
+                const m = r.meta;
+                const check = m?.check ? (m.check.ok ? `check passes, ${m.check.findings} findings` : `check: ${m.check.errors} problems`) : 'not checked';
+                lines.push(`${r.id}  ${m?.kind ?? '?'}  ${m?.title ?? '(no report.md yet)'}  · ${check}${m && Object.keys(m.exports).length ? ` · ${Object.keys(m.exports).join(', ')}` : ''}`);
+            }
+            return;
+        }
+        const ref = data.resolveReport(root, id);
+        const exp = await import('./report/export.js');
+        if (action === 'check') {
+            const { result } = exp.checkAndRecord(root, ref);
+            if (opts.json) {
+                lines.push(JSON.stringify(result, null, 2));
+                if (!result.ok)
+                    throw new BravosError(`bravos report check ${ref}: ${result.errors.length} problems`);
+                return;
+            }
+            lines.push(`bravos report check ${ref}: ${result.ok ? 'passes' : `${result.errors.length} problem${result.errors.length === 1 ? '' : 's'}`}${result.warnings.length ? `, ${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'}` : ''}; ${result.findings.length} finding${result.findings.length === 1 ? '' : 's'}`);
+            for (const e of result.errors)
+                lines.push(`  error ${e.line ? `line ${e.line} ` : ''}[${e.rule}] ${e.message}`);
+            for (const w of result.warnings)
+                lines.push(`  warn  ${w.line ? `line ${w.line} ` : ''}[${w.rule}] ${w.message}`);
+            if (!result.ok)
+                throw new BravosError(`fix the problems above in .bravos/reports/${ref}/report.md and run bravos report check ${ref} again`);
+            return;
+        }
+        if (action === 'export') {
+            const formats = opts.format.split(',').map((f) => f.trim().toLowerCase()).filter(Boolean);
+            const bad = formats.filter((f) => !exp.FORMATS.includes(f));
+            if (bad.length || !formats.length)
+                throw new BravosError(`unknown format ${bad.join(', ') || '(none)'}; use md, txt, html, pdf`);
+            const r = await exp.exportReport(root, ref, formats, { env: io.env, force: opts.force });
+            if (!r.check.ok)
+                lines.push(`Exported with --force: bravos report check found ${r.check.errors.length} problems.`);
+            for (const w of r.written)
+                lines.push(`${w.format.padEnd(4)} ${w.path}`);
+            for (const s of r.skipped)
+                lines.push(`${s.format.padEnd(4)} not written: ${s.reason}`);
+            if (opts.open) {
+                const target = r.written.find((w) => w.format === 'pdf') ?? r.written.find((w) => w.format === 'html');
+                if (target)
+                    openInBrowser(target.path);
+            }
+            lines.push('These files quote assessment evidence and are not committed; share them deliberately.');
+            return;
+        }
+        throw new BravosError(`unknown report action '${action}'; use data, check, export or list`);
+    }));
+    program
+        .command('sast <action> [dir]')
+        .description("SAST (Team plan): 'run' analyzes the repository with the staged bravos-cli into .bravos/sast/<run>/ (not committed); 'status' prints one line about the newest run; 'candidates' lists its reachable findings joined to a claim, not yet in the threat model, dependencies and secrets. Runs no model.")
+        .option('--json', 'print candidates as JSON (bravos.sast-candidates/v1)')
+        .option('--all', 'include findings whose reach is unknown or false')
+        .option('--scope <paths>', 'run: comma-separated paths to analyze (default: the whole repository)')
+        .option('--exclude <paths>', 'run: comma-separated paths to skip')
+        .option('--min-severity <level>', 'run: lowest severity to report')
+        .option('--timeout <seconds>', 'run: ceiling for the analysis', (v) => Number(v))
+        .action((action, dir, opts) => guardedAsync(async (lines) => {
+        const root = dirArg(dir);
+        const lib = await import(pathToFileURL(pathJoin(hooksDir(), 'lib', 'sast.mjs')).href);
+        if (action === 'run') {
+            const r = await runSast(root, io.env, { scope: opts.scope?.split(',').filter(Boolean), exclude: opts.exclude?.split(',').filter(Boolean), minSeverity: opts.minSeverity, timeoutS: opts.timeout });
+            lines.push(...r.lines);
+            if (r.exit !== 0 && r.exit !== 1)
+                result.code = 1;
+            return;
+        }
+        if (action === 'status') {
+            lines.push(lib.sastLine(lib.readSast(root, io.env), lib.sastAvailable(io.env)));
+            return;
+        }
+        if (action !== 'candidates')
+            throw new BravosError(`unknown sast action '${action}'; use run, status or candidates`);
+        const c = lib.sastCandidates(root, { all: !!opts.all });
+        if (!c) {
+            lines.push(`no SAST report in .bravos/sast/ — ${lib.sastAvailable(io.env).ok ? 'run bravos-sast first' : 'SAST unavailable here (bravos doctor)'}`);
+            return;
+        }
+        if (opts.json) {
+            lines.push(JSON.stringify(c, null, 2));
+            return;
+        }
+        const row = (f) => `  ${(f.severity ?? '').toLowerCase().padEnd(8)} ${f.rule ?? '?'}  ${f.file ?? '?'}:${f.line ?? '?'}${f.route ? `  ${f.route}` : f.entryPoint ? `  via ${f.entryPoint}` : ''}`;
+        lines.push(`SAST run ${c.run}${c.sha ? ` at ${String(c.sha).slice(0, 9)}` : ''}${opts.all ? '' : ' (reachable only; --all for the rest)'}`);
+        lines.push('', `Joined to a claim (${c.joined.length}) — taint evidence for bravos-templatize and bravos-prove:`, ...c.joined.map((f) => `${row(f)}  [${f.claimState}]`));
+        lines.push('', `Not in the threat model yet (${c.unjoined.length}) — leads for bravos-annotate:`, ...c.unjoined.map(row));
+        lines.push('', `Dependencies (${c.dependencies.length}):`, ...c.dependencies.map((f) => `${row(f)}  vulnerable function reached: ${String(f.vulnerableFunctionReached ?? 'unknown')}`));
+        lines.push('', `Secrets (${c.secrets.length}) — rotate; never pentest candidates:`, ...c.secrets.map((f) => `  ${f.rule ?? '?'}  ${f.file ?? '?'}:${f.line ?? '?'}${f.inHistory ? '  (in git history)' : ''}`));
+    }));
+    program
+        .command('guide [topic]')
+        .description(`How to use bravos by role and by task, every skill, the safety rules (topics: ${GUIDE_TOPIC_IDS.join(', ')}, all). Free: runs no model.`)
+        .addOption(new Option('--harness <name>', 'show skills in this harness syntax').choices(['claude', 'codex', 'omp']).default('claude'))
+        .option('--markdown', 'print the whole guide as Markdown (docs/GUIDE.md)')
+        .action((topic, opts) => {
+        if (opts.markdown)
+            return io.stdout(renderGuideMarkdown().replace(/\n$/, ''));
+        if (topic !== undefined && topic !== 'all' && !GUIDE_TOPIC_IDS.includes(topic)) {
+            result.code = 2;
+            io.stderr(`unknown topic '${topic}'; topics: ${GUIDE_TOPIC_IDS.join(', ')}, all`);
+            return;
+        }
+        io.stdout(renderGuide(topic, { sigil: { claude: '/', codex: '$', omp: '/skill:' }[opts.harness] }));
+    });
+    return program;
+}
+/** A free loopback port: listen on 0, read it, close. */
+function freePort() {
+    return new Promise((res, rej) => {
+        const s = netServer();
+        s.once('error', rej);
+        s.listen(0, '127.0.0.1', () => {
+            const a = s.address();
+            const p = typeof a === 'object' && a ? a.port : 0;
+            s.close(() => res(p));
+        });
+    });
+}
+/** Polls the review page until it answers (about 5 s at most). */
+async function waitUp(url) {
+    for (let i = 0; i < 50; i++) {
+        try {
+            const r = await fetch(url);
+            if (r.ok)
+                return true;
+        }
+        catch {
+            /* not up yet */
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    return false;
+}
+// @comment -- "A commander parser for a whole number of seconds no smaller than min; anything else is a usage error."
+function seconds(min) {
+    return (v) => {
+        const n = Number(v);
+        if (!Number.isFinite(n) || n < min)
+            throw new InvalidArgumentError(`give a number of seconds, ${min} or more`);
+        return n;
+    };
+}
+// @comment -- "Opens a URL or file in the person's browser with the OS opener (argv, no shell); failure is silent because the URL is printed anyway."
+function openInBrowser(target) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [target]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', target]] : ['xdg-open', [target]];
+    try {
+        spawnChild(cmd, args, { detached: true, stdio: 'ignore' }).on('error', () => { }).unref();
+    }
+    catch {
+        /* printed URL is enough */
+    }
+}
+// @comment -- "Runs the CLI in-process and returns the exit code: 0 ok, 1 BravosError, 2 commander usage error."
+export async function run(argv, io = {}) {
+    const full = {
+        stdout: (s) => process.stdout.write(s + '\n'),
+        stderr: (s) => process.stderr.write(s + '\n'),
+        env: process.env,
+        ...io,
+    };
+    const result = { code: 0 };
+    try {
+        await buildProgram(full, result).parseAsync(argv, { from: 'user' });
+    }
+    catch (err) {
+        if (err instanceof CommanderError)
+            return err.exitCode === 0 ? 0 : 2;
+        full.stderr(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    return result.code;
+}
+// @comment -- "Entry guard compares real paths so a bin symlink (npm i -g, npx, node_modules/.bin) still runs the CLI."
+function isEntry() {
+    try {
+        return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isEntry()) {
+    run(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}