@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/dist/graphbin.js

@@ -0,0 +1,136 @@
+import { accessSync, constants, existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { whichBin } from './guardlink.js';
+import { packageRoot } from './paths.js';
+/** The names the Python bravos launcher may have on PATH: its own, or `bravos-py` once it is renamed so `bravos` means this CLI. */
+export const PYTHON_BRAVOS_NAMES = ['bravos', 'bravos-py'];
+// @comment -- "The Python bravos CLI (siete) on PATH, under its own name or renamed to bravos-py, and never this package's own `bravos` bin: every candidate is resolved to its real file and skipped when it lives inside this package or is an npm shim onto dist/cli.js, so the fallbacks to the Python install's code graph and analyzer cannot spawn this CLI back into itself. `bravos setup` staging the bundles makes this lookup unnecessary."
+export function pythonBravos(env = process.env) {
+    const self = packageRoot();
+    for (const name of PYTHON_BRAVOS_NAMES) {
+        for (const dir of (env.PATH ?? '').split(':')) {
+            if (!dir)
+                continue;
+            const file = join(dir, name);
+            try {
+                if (!statSync(file).isFile())
+                    continue;
+                accessSync(file, constants.X_OK);
+                const real = realpathSync(file);
+                if (real.startsWith(self + '/'))
+                    continue;
+                // An npm shim (a shell script that execs node on this package's dist/cli.js) is not the Python CLI either.
+                if (readFileSync(real, 'utf8').includes('dist/cli.js'))
+                    continue;
+                return file;
+            }
+            catch {
+                // not here
+            }
+        }
+    }
+    return null;
+}
+// @comment -- "Finds a code-graph binary (codegraph-mcp, codegraph-build) the way bravos resolves it: on PATH first, else inside the bravos install's own wheel payload (<venv>/lib/python*/site-packages/bravos/_graph/bin/<name>), found from the real path of the bravos launcher. Read-only; null when neither has it."
+export function graphBin(name, env = process.env) {
+    const onPath = whichBin(name, env);
+    if (onPath)
+        return onPath;
+    const launcher = pythonBravos(env);
+    if (!launcher)
+        return null;
+    let real;
+    try {
+        real = realpathSync(launcher);
+    }
+    catch {
+        return null;
+    }
+    // <install>/bin/bravos → <install>, then the venv layouts siete's installer and pipx use.
+    const install = dirname(dirname(real));
+    for (const lib of [join(install, 'venv', 'lib'), join(install, 'lib')]) {
+        let pythons = [];
+        try {
+            pythons = readdirSync(lib).filter((d) => d.startsWith('python'));
+        }
+        catch {
+            continue;
+        }
+        for (const py of pythons.sort().reverse()) {
+            const file = join(lib, py, 'site-packages', 'bravos', '_graph', 'bin', name);
+            try {
+                if (existsSync(file) && statSync(file).isFile())
+                    return file;
+            }
+            catch {
+                /* keep looking */
+            }
+        }
+    }
+    return null;
+}
+// @comment -- "Finds bravos-cli the way the bravos launcher puts it on its own PATH: on PATH first, else <install>/analyzer/bravos-cli beside the real path of the bravos launcher (<install>/bin/bravos). Read-only; null when neither has it. hooks/lib/sast.mjs carries the same lookup, dependency-free, for the hooks."
+export function findAnalyzer(env = process.env) {
+    // The bundle bravos setup staged wins; then PATH; then the Python install's own copy.
+    const home = env.BRAVOS_HOME || (env.HOME ? join(env.HOME, '.bravos') : null);
+    if (home) {
+        const stagedBin = join(home, 'analyzer', 'current', 'bravos-cli');
+        try {
+            accessSync(stagedBin, constants.X_OK);
+            return realpathSync(stagedBin);
+        }
+        catch {
+            /* not staged */
+        }
+    }
+    const direct = whichBin('bravos-cli', env);
+    if (direct)
+        return direct;
+    const launcher = pythonBravos(env);
+    if (!launcher)
+        return null;
+    try {
+        const file = join(dirname(dirname(realpathSync(launcher))), 'analyzer', 'bravos-cli');
+        accessSync(file, constants.X_OK);
+        return file;
+    }
+    catch {
+        return null;
+    }
+}
+// @comment -- "Where a Bravos licence is, read-only: BRAVOS_LICENCE / BRAVOS_LICENSE, else licence.jwt or license.jwt in $BRAVOS_HOME, ~/.bravos, or ~/.bugb (where bravos still keeps its state until ~/.bravos holds some). Returns a short label for the source, or null. Same rule as hooks/lib/sast.mjs findLicence."
+export function findLicence(env = process.env) {
+    if (env.BRAVOS_LICENCE)
+        return 'BRAVOS_LICENCE';
+    if (env.BRAVOS_LICENSE)
+        return 'BRAVOS_LICENSE';
+    const home = env.HOME;
+    const homes = [env.BRAVOS_HOME, home && join(home, '.bravos'), home && join(home, '.bugb')].filter((h) => !!h);
+    for (const dir of homes) {
+        for (const name of ['licence.jwt', 'license.jwt']) {
+            if (existsSync(join(dir, name)))
+                return dir === env.BRAVOS_HOME ? `$BRAVOS_HOME/${name}` : `${home ? dir.replace(home, '~') : dir}/${name}`;
+        }
+    }
+    return null;
+}
+// @comment -- "The graph store bravos reads and writes, for the codegraph-mcp entry bravos registers: BRAVOS_CODEGRAPH_DIR when bravos's environment sets it, else the default a bravos launcher script assigns (`: \"${BRAVOS_CODEGRAPH_DIR:=<dir>}\"`, read from the launcher's real path, first 8 KiB, never executed). Null when neither says, which leaves codegraph-mcp on its own default."
+export function graphStoreDir(env = process.env) {
+    if (env.BRAVOS_CODEGRAPH_DIR)
+        return env.BRAVOS_CODEGRAPH_DIR;
+    const launcher = pythonBravos(env);
+    if (!launcher)
+        return null;
+    try {
+        const head = readFileSync(realpathSync(launcher)).subarray(0, 8192).toString('utf8');
+        if (!head.startsWith('#!'))
+            return null;
+        const m = /\$\{BRAVOS_CODEGRAPH_DIR:=([^}"'\n]+)\}/.exec(head);
+        return m ? m[1].trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True for a codegraph-mcp entry bravos registers by full path into a bravos install, which goes stale when that install is replaced. */
+export const isInstallGraphCommand = (command) => typeof command === 'string' && /[\\/]bravos[\\/]_graph[\\/]bin[\\/]codegraph-mcp$/.test(command);

package/dist/guardlink.js

@@ -0,0 +1,123 @@
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { readLock, sha256, writeLock } from './lock.js';
+import { BravosError } from './types.js';
+const AGENT_ID = { claude: 'claude', agents: 'codex' };
+/** Full path of the first executable regular file `name` on `env.PATH`, or null. */
+// @comment -- "Resolves a command name to the first executable regular file on env.PATH without spawning anything; null when absent."
+export function whichBin(name, env = process.env) {
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (!dir)
+            continue;
+        const file = join(dir, name);
+        try {
+            if (!statSync(file).isFile())
+                continue;
+            accessSync(file, constants.X_OK);
+            return file;
+        }
+        catch {
+            // not here
+        }
+    }
+    return null;
+}
+/** Runs `guardlink init` (argv array, no shell) only when `<root>/.guardlink` is absent. */
+// @comment -- "Runs guardlink init (argv array, no shell) only when <root>/.guardlink is absent, and reports what it did or would do with the argv it used."
+export function ensureGuardlink(root, harnesses, opts = {}) {
+    if (existsSync(join(root, '.guardlink')))
+        return { status: 'present' };
+    if (opts.skip)
+        return { status: 'skipped' };
+    const env = opts.env ?? process.env;
+    const command = [
+        'guardlink', 'init',
+        '--agent', harnesses.map((h) => AGENT_ID[h]).join(','),
+        '--mode', opts.mode ?? 'inline',
+    ];
+    if (opts.dryRun)
+        return { status: 'dry-run', command };
+    if (!whichBin('guardlink', env))
+        return { status: 'guardlink-missing', command };
+    try {
+        execFileSync(command[0], command.slice(1), { cwd: root, stdio: 'inherit', env });
+    }
+    catch (err) {
+        const code = err.status;
+        throw new BravosError(`\`${command.join(' ')}\` failed with exit code ${code ?? 'unknown'}`);
+    }
+    return { status: 'initialised', command };
+}
+/** Sorted guardlink-annotate-* / guardlink-report-* / guardlink-translate skill folders under `<root>/<skillsRoot>` that hold a SKILL.md. */
+// @comment -- "Lists the guardlink-annotate-*, guardlink-report-* and guardlink-translate skill folders (with a SKILL.md) under a skills root, sorted; read-only. guardlink-translate is included so Codex, which reads .agents/skills, gets the translate method bravos-templatize follows first."
+export function installedGuardlinkSkills(root, skillsRoot) {
+    const dir = join(root, skillsRoot);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && /^guardlink-(?:(?:annotate|report)-|translate$)/.test(e.name))
+        .filter((e) => existsSync(join(dir, e.name, 'SKILL.md')))
+        .map((e) => e.name)
+        .sort();
+}
+// @comment -- "Repo-relative path of the cxg scope file bravos's testing-loop skills read, and the bundled starter it is copied from."
+export const SCOPE_PATH = '.guardlink/scope.yaml';
+export const SCOPE_SOURCE = 'bravos-env/scope.example.yaml';
+/** Copies the bundled loopback-only scope starter to `.guardlink/scope.yaml` when that file is absent; never overwrites. */
+// @comment -- "Writes the cxg scope starter only when .guardlink/scope.yaml is absent and .guardlink/ exists (creating .guardlink/ here would make a later bravos init skip guardlink init); never overwrites a scope the team may have reviewed, and records the hash in the lock."
+export function writeScope(root, skillsDir, opts = {}) {
+    const abs = join(root, SCOPE_PATH);
+    if (existsSync(abs))
+        return { status: 'present', path: SCOPE_PATH };
+    if (!existsSync(join(root, '.guardlink')) && !(opts.dryRun && opts.guardlinkPending))
+        return { status: 'no-guardlink', path: SCOPE_PATH };
+    const src = join(skillsDir, SCOPE_SOURCE);
+    if (!existsSync(src))
+        return { status: 'no-source', path: SCOPE_PATH };
+    if (!opts.dryRun) {
+        const content = readFileSync(src);
+        writeFileSync(abs, content);
+        const lock = readLock(root);
+        writeLock(root, { ...lock, files: { ...lock.files, [SCOPE_PATH]: sha256(content) } });
+    }
+    return { status: 'written', path: SCOPE_PATH };
+}
+// @comment -- "The pre_pr entry bravos adds to .guardlink/config.json; guardlink renders up to five such entries into its stamped agent block and refuses backticks, line breaks and HTML comment delimiters, which these strings avoid."
+export const PRE_PR_ENTRY = Object.freeze({
+    command: 'node .bravos/hooks/pre-pr.mjs --check',
+    why: 'bravos pre-PR gate: blocks on lint errors and confirmed claims on changed files, lists new exposures to disclose in the PR body',
+});
+const CONFIG_PATH = '.guardlink/config.json';
+/** Adds bravos's gate to `pre_pr` in `.guardlink/config.json`, creating the array if absent and never duplicating it. */
+// @comment -- "Read-validate-write of .guardlink/config.json: an unparsable file, a non-object or a non-array pre_pr is refused with nothing written; an entry with the same command counts as registered, and the pre---check entry is replaced; a missing config is reported, not created, since guardlink init owns it."
+export function registerPrePr(root, opts = {}) {
+    const abs = join(root, CONFIG_PATH);
+    if (!existsSync(abs))
+        return { status: 'no-config', path: CONFIG_PATH };
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(abs, 'utf8'));
+    }
+    catch {
+        throw new BravosError(`${CONFIG_PATH} is not valid JSON; fix it or remove it, nothing was written`);
+    }
+    if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+        throw new BravosError(`${CONFIG_PATH} is not a JSON object; fix it or remove it, nothing was written`);
+    }
+    const config = doc;
+    if (config.pre_pr !== undefined && !Array.isArray(config.pre_pr)) {
+        throw new BravosError(`${CONFIG_PATH} has a pre_pr value that is not an array; fix it or remove it, nothing was written`);
+    }
+    const entries = (config.pre_pr ?? []);
+    // The entry bravos registered before --check existed ran the PreToolUse entry with no payload, a silent no-op: it is replaced.
+    const LEGACY = 'node .bravos/hooks/pre-pr.mjs';
+    const commandOf = (e) => (typeof e === 'object' && e !== null ? e.command : undefined);
+    const hasLegacy = entries.some((e) => commandOf(e) === LEGACY);
+    if (!hasLegacy && entries.some((e) => commandOf(e) === PRE_PR_ENTRY.command))
+        return { status: 'already-registered', path: CONFIG_PATH };
+    config.pre_pr = [...entries.filter((e) => commandOf(e) !== LEGACY && commandOf(e) !== PRE_PR_ENTRY.command), { ...PRE_PR_ENTRY }];
+    if (!opts.dryRun)
+        writeFileSync(abs, JSON.stringify(config, null, 2) + '\n');
+    return { status: 'registered', path: CONFIG_PATH };
+}

package/dist/guide.js

@@ -0,0 +1,255 @@
+// @comment -- "The bravos guide: what bravos does, what to do by role and by task, every skill, the three claim states, the safety rules, and how each harness starts it. One source rendered as terminal text (bravos guide) or Markdown (bravos guide --markdown, committed as docs/GUIDE.md). Pure data and string formatting; reads nothing."
+export const GUIDE_TOPICS = [
+    {
+        id: 'start',
+        title: 'What bravos is and how a session starts',
+        summary: 'what bravos does, what you see at start, how to run a skill in each harness',
+        intro: [
+            'bravos is a skills pack for coding agents. It makes the agent in your session a power user of guardlink (the threat model, written as annotations beside the code), cxg (pentests as code, against targets you own), the code graph and licensed SAST. There is no bravos server and no bravos database: the threat model lives in your repo, the evidence comes from the real tools, and your team shares it through git.',
+            'Every claim moves through one loop: an annotation says code is exposed (or mitigated) → it becomes a cxg template → an authorized run tests it against a target you own → the result is recorded in guardlink → it is rechecked when the code changes.',
+        ],
+        items: [
+            {
+                name: 'At session start',
+                body: [
+                    'A hook gathers the repo\'s security picture (open exposures, confirmed exploits, what to test next, stale claims, tickets, teammates\' open PRs, intent) and hands it to the model, so you never need a command to load it. On a fresh start you also see the banner; the model does not.',
+                    'Claude Code shows the banner above the first prompt. Codex lists a two-line summary as a hook warning (F2 to view). omp shows the banner above the editor until your first prompt. opencode gets the briefing for the model only. Antigravity (agy) gets the briefing for the model only. Anywhere else, the bravos skill loads the briefing when you run it.',
+                ],
+            },
+            {
+                name: 'Running a skill',
+                body: [
+                    'Claude Code and opencode: /bravos-ship. Codex: $bravos-ship. omp: /skill:bravos-ship. Elsewhere, ask for it by name ("use the bravos-ship skill"). You can also just say what you want ("is this PR safe to open?") and the agent picks the skill.',
+                ],
+            },
+            {
+                name: 'Plans',
+                body: [
+                    'Free (researcher) needs no licence: context, annotate, templatize, env, prove, recheck, report and watch, in one repository. Team, licensed per developer (Solo is one seat), adds the pre-PR gate and autopilot, the CI and nightly workflows, scheduled upkeep, multi-repository workspaces, campaigns, SAST and the code graph. The briefing opens every session with a Plan: line; bravos licence shows the same in a shell. bravos account activate signs you in once in the browser and writes the licence (a 30-day Team trial, no card, when the account has no plan); bravos account import <file> installs a downloaded one. Without a licence a paid command explains what it would do and how to start the trial, a paid hook stands down with one line and never blocks, and a paid skill stops at its first step and says so.',
+                ],
+            },
+            {
+                name: 'Effort',
+                body: [
+                    'Every skill reads one dial: low, medium (default), high or max. Say it ("annotate at high") or put a line `bravos effort: high` in AGENTS.md or CLAUDE.md. These are starting budgets, not limits: the agent goes further when the work needs it and says why. Only the safety rules are hard.',
+                ],
+            },
+            {
+                name: 'Installing',
+                body: [
+                    'npm install -g @bugb-technologies/bravos (Node 20 or newer). Then bravos account activate signs you in once in the browser and writes the licence — a 30-day Team trial when the account has no plan; skip it to stay on Free — bravos init in a repository writes the skills, hooks and MCP wiring, and bravos setup puts the analyzer and the code graph on the machine (Team plan). guardlink and cxg come from bravos setup --tools -y, or npm and cargo by hand. If you used the Python bravos, rename its command so bravos means this one: mv ~/.local/bin/bravos ~/.local/bin/bravos-py (this CLI still finds its code graph and analyzer), or remove it with pipx or uv.',
+                ],
+            },
+            {
+                name: 'Your first day',
+                body: [
+                    'Run bravos next in a shell (free): it shows which of the nine steps are done here, in the order they build on each other — the code graph first (a machine step every later skill reads), then what the app intends, annotation coverage, SAST (which reads the annotations), how findings are proven and a test target, then the gates (autopilot, the pre-PR gate, CI, cheap to switch on any time) — what each unlocks, and the exact command for the next one. The banner shows the next step too, and every harness gives it to the agent, which offers a few starts the first time and suggests the next step at natural moments.',
+                    'Or just ask the agent "help me get started" (or run /bravos, $bravos in Codex): it gives a short tour fitted to this repo. BRAVOS_COACH=off stops the coaching; the Setup line stays.',
+                    'Keep bravos watch running in a second terminal pane beside your agent (free, read-only, no model): the setup score, open and confirmed exposures, what to test next, stale claims and autopilot nudges, redrawn within seconds of a change. It also shows the hypothesis ledger, boundaries, the model\'s size, the code graph\'s call resolution and entry points, and the branch\'s commits. Keys: n copies the next command, r opens the intent review, d guardlink\'s dashboard, g asks the code graph, t shows test-next, i shows the recorded intent, u refreshes now, j and k scroll, q quits. Three columns from 150 wide, two from 110, one in an 80-column split.',
+                ],
+            },
+            {
+                name: 'Hands-off: autopilot',
+                body: [
+                    'bravos init --autopilot (or sync --autopilot) makes upkeep happen without anyone asking. At the end of each turn a check sends the agent back once if the changes left code with no annotation, touched code under a confirmed or stale claim, or put open exposures on changed files. The pre-PR gate runs on every gh pr create.',
+                    'Proving follows your choice, not a fixed rule: the first time it comes up the agent asks you once — prove automatically on your loopback target, ask each time, on a schedule, or not now — and records your words in .guardlink/proving.md. Say "ask me first" or "stop auto-proving" at any time to change it. Non-loopback targets still need a reviewed scope and your typed authorization every time.',
+                ],
+            },
+            {
+                name: 'Free views (no tokens)',
+                body: [
+                    'In a shell: `bravos guide` (this guide), `bravos doctor` (which tools are installed), `guardlink status .`, `guardlink ci -f json`, `guardlink hypothesis next`. None of these runs a model.',
+                ],
+            },
+        ],
+    },
+    {
+        id: 'roles',
+        title: 'What to do, by role',
+        summary: 'developer, security engineer, team lead, new to the repo, CI owner',
+        items: [
+            {
+                name: 'Developer',
+                skills: ['bravos', 'bravos-annotate', 'bravos-ship'],
+                body: [
+                    'Work as usual; the briefing tells the agent what is open around your code. When you write or change an endpoint, an auth check, a query, file or process handling, crypto or config parsing, ask the agent to annotate it (bravos-annotate) so the threat model keeps up. Before you open a pull request, run bravos-ship: it validates the model, lints your new claims, lists new exposure the PR must disclose, and refuses to ship a confirmed exploit on a changed path. After you fix a finding, run bravos-recheck.',
+                ],
+            },
+            {
+                name: 'Security engineer',
+                skills: ['bravos-context', 'bravos-templatize', 'bravos-env', 'bravos-prove', 'bravos-recheck'],
+                body: [
+                    'Start by recording what the product intends (bravos-context), so severities reflect impact on this product, not code patterns. Then turn the top untested exposures into cxg templates (bravos-templatize), bring up a target you own with a reviewed scope and your typed authorization (bravos-env), and run the test (bravos-prove). Outcomes go back into guardlink\'s hypothesis ledger as confirmed or refuted, with the evidence. After a fix, bravos-recheck replays the retest kit. bravos-sast adds licensed static analysis joined to the threat model.',
+                ],
+            },
+            {
+                name: 'Team lead or reviewer',
+                skills: ['bravos-campaign', 'bravos-schedule', 'bravos-cicd'],
+                body: [
+                    'Turn on bravos init --autopilot so the threat model keeps up as people work, with no commands to remember, and settle once with the team how findings should be proven (it is recorded in .guardlink/proving.md and shows in every briefing).',
+                    'Coverage and findings are visible to everyone from the repo itself. To raise coverage or clear the backlog, run bravos-campaign with a goal ("coverage 100%", "test every open exposure"): it plans disjoint batches, runs one subagent per batch, gates each, rests, and reports before-and-after numbers. Use bravos-schedule for recurring upkeep (an in-session loop or the nightly workflow) and bravos-cicd for the PR gate and code-scanning upload. Acceptances (@accepts) and entitlements are yours to write; agents never write them.',
+                ],
+            },
+            {
+                name: 'New to the repo',
+                skills: ['bravos', 'bravos-context', 'bravos-codegraph'],
+                body: [
+                    'Run bravos first: it reads the briefing, explains the loop in five lines and routes you. If the banner says "intent none", run bravos-context: a short interview about purpose, users and roles, the data that matters, what must never happen, and what looks dangerous but is intended. bravos-codegraph answers "where are the routes", "what does this handler reach", "is this code live" without reading the whole tree.',
+                ],
+            },
+            {
+                name: 'CI owner',
+                skills: ['bravos-cicd', 'bravos-schedule'],
+                body: [
+                    'bravos init --ci writes the PR gate and nightly workflows. bravos-cicd audits existing workflows: broken guardlink calls, script injection from pull-request text, missing SARIF upload. The nightly can replay retest kits only against a target the committed, reviewed scope authorizes.',
+                ],
+            },
+        ],
+    },
+    {
+        id: 'tasks',
+        title: 'What to do, by task',
+        summary: 'the skill (or skills, in order) for each common job',
+        items: [
+            { name: 'Where do I start? What is open?', skills: ['bravos'], body: ['Reads the briefing and names the one next step, with the reason.'] },
+            { name: 'Teach bravos what the app is for', skills: ['bravos-context'], body: ['Writes .guardlink/intent.md: invariants (INV-n) that become threats, and intended-by-design items (INT-n) that get an "intended?" audit instead of a high rating.'] },
+            { name: 'Threat-model someone else\'s project', skills: ['bravos-context', 'bravos-annotate'], body: ['bravos-context assumes you are researching software you do not own (an open-source project, a vendor\'s code): it drafts the intent from upstream\'s own docs with links and asks only the scope decisions — which configuration to rate against (shipped defaults or the hardened setup upstream recommends), single organisation or multi-tenant, which attackers are in scope, and the intended-looking behaviours upstream does not document. intent.md records them as Assumptions, and severities are rated against them. Say "this is our product" for the owner interview instead.'] },
+            { name: 'Answer bravos\'s questions as a team', skills: ['bravos-context'], body: ['bravos-context opens its questions as a bravos page (bravos review intent): pre-filled with bravos\'s suggestions and their sources; change what is wrong, make the calls marked \'needs your call\' (Confirm stays off until you do), and the facts bravos drafted stay folded unless you open one to object. Each person\'s answers save to .guardlink/intent-answers/<name>.json; teammates run bravos review intent after pulling and commit theirs. bravos review intent --summary shows where people agree and disagree; only what a named person agreed to is marked confirmed. On Claude Code, --share puts the same page on a private claude.ai link instead.'] },
+            { name: 'I wrote security-relevant code', skills: ['bravos-annotate'], body: ['Annotates what you changed to guardlink\'s evidence bar and runs the lint gate until clean.'] },
+            { name: 'Cover the whole repo', skills: ['bravos-campaign'], body: ['Rounds of batches with subagents and rests, until the coverage goal or until you stop it.'] },
+            { name: 'Is this exposure real?', skills: ['bravos-templatize', 'bravos-env', 'bravos-prove'], body: ['Template → authorized target → run. Only a reproduced run confirms; reading code never does.'] },
+            { name: 'I fixed a finding', skills: ['bravos-recheck'], body: ['Re-verifies stale claims, replays the retest kit, and checks the fix added no new exposure.'] },
+            { name: 'I am about to open a PR', skills: ['bravos-ship'], body: ['The no-mistakes gate: validate, lint since the merge base, disclose new exposure, block confirmed exploits on changed paths.'] },
+            { name: 'Find the routes, callers or blast radius', skills: ['bravos-codegraph'], body: ['One bounded question to the code graph instead of grepping. Needs codegraph-mcp (pip install bravos; licence-free). With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix\'s callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.'] },
+            { name: 'Scan for dependency CVEs, secrets, IaC', skills: ['bravos-sast'], body: ['Licensed bravos-cli: Semgrep rules, request-to-sink taint over the code graph, dependency CVEs with whether the vulnerable function is reached, secrets (git history too) and IaC. It reads the GuardLink threat model as input, so annotate first. Says plainly when it is unavailable.'] },
+            { name: 'What did SAST find, and what happens to it', skills: ['bravos-sast', 'bravos-annotate', 'bravos-templatize', 'bravos-prove', 'bravos-recheck'], body: ['bravos sast candidates (free, no model) reads the newest run in .bravos/sast/: reachable findings joined to a claim feed bravos-templatize and bravos-prove (the route and taint path to target, tested first); reachable findings not in the threat model are leads for bravos-annotate; bravos-recheck rescans the changed files after a fix. A static finding is a lead, never a confirmation; only a run confirms. The briefing\'s SAST line shows the latest run, or that SAST is unavailable.'] },
+            { name: 'Keep it fresh while I work, or nightly', skills: ['bravos-schedule'], body: ['An in-session /loop from .claude/loop.md, the nightly workflow, or a cloud task you create. Loops never send test traffic.'] },
+            { name: 'Add or fix security CI', skills: ['bravos-cicd'], body: ['PR gate, nightly annotation, SARIF to code scanning, script-injection fixes.'] },
+            { name: 'An app made of several repositories (microservices)', skills: ['bravos-annotate', 'bravos-codegraph', 'bravos-prove'], body: ['Clone the services side by side in one folder, then run bravos workspace create NAME --member ./gateway=gateway@http://127.0.0.1:8080 --member ./orders=orders@http://127.0.0.1:8081 (bravos workspace plus guardlink link-project plus bravos in each repo and in the shared folder). Work on a service from its own repo; ask questions that cross services from the shared folder, where the briefing and bravos watch show every service. Declare each call to another service as @flows #<this>-<x> -> #<other>-<y> via http (plain ids, not #repo.tag). Build the code graph over the shared folder so it links one service\'s client calls to another\'s handlers. bravos report data --workspace writes one report across the services.'] },
+            { name: 'Write up the assessment, a finding or a retest', skills: ['bravos-report'], body: ['Ask "write the assessment report" (or a finding, a retest, an executive brief). bravos report data gathers the evidence; the agent writes report.md in the eight-section reading order, with every proof claim citing its evidence; bravos report check refuses a finding labelled reproduced without a run or ledger record; bravos report export writes md, txt, html and pdf. bravos watch shows the newest report (p to read it, o to open the pdf or html).'] },
+        ],
+    },
+    {
+        id: 'skills',
+        title: 'Every skill',
+        summary: 'all fourteen skills, what each does and leaves for the next',
+        items: [
+            { name: 'bravos', body: ['Front door: reads the security picture, explains the evidence loop, routes to the right skill.'] },
+            { name: 'bravos-context', body: ['Learns what the product intends from the repo and a short interview; records invariants, intended behaviour, actors, assets and boundaries.'] },
+            { name: 'bravos-annotate', body: ['Picks a budgeted slice (entry points and trust code first), follows guardlink\'s own playbook, writes annotations to the evidence bar, lints until clean, reports the coverage delta.'] },
+            { name: 'bravos-codegraph', body: ['Bounded questions to codegraph-mcp: routes, attack surface, sinks a symbol reaches, liveness, blast radius, annotation gaps in a change.'] },
+            { name: 'bravos-ship', body: ['The pre-PR gate. Optional PreToolUse hook (bravos init --pre-pr-hook) runs it on every gh pr create / gh pr ready.'] },
+            { name: 'bravos-templatize', body: ['Turns open exposures into validated cxg templates following guardlink\'s translate method; keeps replay kits apart from scan templates; records classes with no oracle as gaps.'] },
+            { name: 'bravos-env', body: ['Brings up a target you own: loopback by default, a committed reviewed scope.yaml, your typed authorization, a real session captured or imported.'] },
+            { name: 'bravos-prove', body: ['Runs the authorized test, reads cxg\'s report and exit code, writes outcomes only through guardlink\'s hypothesis ledger.'] },
+            { name: 'bravos-recheck', body: ['After a fix: stale claims, retest-kit replay, no new exposure, what to test next.'] },
+            { name: 'bravos-sast', body: ['Licensed static analysis joined to guardlink claims and reachability; gates on findings new since the base.'] },
+            { name: 'bravos-campaign', body: ['A goal over many rounds: disjoint batches, one subagent each, a gate per batch, rests, a final before-and-after.'] },
+            { name: 'bravos-schedule', body: ['Recurring upkeep with each harness\'s own mechanism; never live tests from a loop.'] },
+            { name: 'bravos-cicd', body: ['Audits and writes the security workflows.'] },
+            { name: 'bravos-report', body: ['Writes the assessment, a single finding, a retest or an executive brief from the evidence bravos report data gathers; each finding\'s evidence level is computed from the ledger and runs, bravos report check gates the report, and bravos report export renders md, txt, html and pdf. Reports stay in .bravos/reports/, not committed.'] },
+        ],
+    },
+    {
+        id: 'states',
+        title: 'Reading a finding',
+        summary: 'the three separate states every claim has, and what each word means',
+        items: [
+            { name: 'open / mitigated / accepted', body: ['Does a control cover it? Open means no control is recorded; mitigated names the control; accepted is a human\'s written decision to live with it, never an agent\'s.'] },
+            { name: 'untested / confirmed / refuted', body: ['Has an authorized run tested it? Confirmed means a run reproduced it, with evidence; refuted means a run showed it does not hold. Untested is neither cleared nor proven.'] },
+            { name: 'verified / stale', body: ['Is the claim still true of today\'s code? Stale means the code under it changed since it was last checked; bravos-recheck clears it.'] },
+            { name: 'Severity', body: ['Rated by impact on this product × reach × ease, with the reason written down. Without .guardlink/intent.md, severities are defaults, not calibrated.'] },
+            { name: 'unknown is not zero', body: ['When a tool is unavailable the briefing says "unknown", never 0. Nothing is called clean unless a gate exited 0.'] },
+        ],
+    },
+    {
+        id: 'safety',
+        title: 'The hard rules',
+        summary: 'what bravos never does, whatever the effort level',
+        items: [
+            { name: 'Authorization', body: ['No request goes to a host other than loopback without a committed, reviewed scope.yaml and your own typed authorization naming the target.'] },
+            { name: 'Destructive tests', body: ['DoS and other destructive classes run only against a disposable loopback target.'] },
+            { name: 'Credentials', body: ['Never invented. Test users and sessions are seeded or captured for real, or the run waits for you.'] },
+            { name: 'No hidden agents', body: ['The agent in your session does the work; bravos never spawns another agent CLI. Model-API probe generation in cxg runs only after you agree to the spend.'] },
+            { name: 'Governance', body: ['Agents never write @accepts or @entitles (a human\'s decision) and never write @confirmed without reproduction evidence in hand.'] },
+        ],
+    },
+    {
+        id: 'harnesses',
+        title: 'Harnesses',
+        summary: 'what bravos installs for each agent and how it starts there',
+        items: [
+            { name: 'Claude Code', body: ['Skills in .claude/skills, SessionStart hook in .claude/settings.json (banner + briefing), MCP in .mcp.json, optional pre-PR PreToolUse hook. Also as a plugin.'] },
+            { name: 'Codex', body: ['Skills in .agents/skills, hook in .codex/hooks.json (trust it once in /hooks), MCP in .codex/config.toml. Also as a plugin.'] },
+            { name: 'omp', body: ['Reads the Claude Code skills and MCP; .omp/extensions/bravos.js shows the banner and hands over the briefing.'] },
+            { name: 'opencode', body: ['Finds the skills in .claude/skills and .agents/skills through its skill tool; bravos adds /bravos… commands in .opencode/commands that load them, a plugin in .opencode/plugins (opencode 2.x) that adds the briefing to the system prompt, and guardlink MCP in opencode.json.'] },
+            { name: 'Antigravity (agy)', body: ['Reads .agents/skills; .agents/hooks.json carries a bravos SessionStart group that injects the briefing.'] },
+            { name: 'Cursor', body: ['.cursor/rules/bravos.mdc points at the skills when the repo has a .cursor/ folder.'] },
+            { name: 'VS Code (Copilot agent)', body: ['Reads hooks from .claude/settings.json (preview), so the briefing can load there too.'] },
+            { name: 'Every repo, or one copy of each skill', body: ['bravos init --global installs for your user: skills in ~/.claude/skills (linked from ~/.agents/skills) and a user hook that briefs repos with a threat model but no bravos install. bravos sync --link-skills makes a repo\'s .agents/skills a link to .claude/skills, so tools that read both (Warp) list each skill once.'] },
+            { name: 'Banner switches', body: ['BRAVOS_BANNER=off hides it; BRAVOS_BANNER_COLOR=off or NO_COLOR prints it plain. The briefing for the model is unchanged either way.'] },
+        ],
+    },
+];
+const WIDTH = 80;
+function wrap(text, width, indent) {
+    const out = [];
+    let line = '';
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (line && (indent + line + ' ' + word).length > width) {
+            out.push(indent + line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        out.push(indent + line);
+    return out;
+}
+const skillList = (skills, sigil) => (skills?.length ? skills.map((s) => sigil + s).join(' · ') : '');
+// @comment -- "Renders one topic, or every topic, as wrapped terminal text with skills shown in the given harness syntax."
+export function renderGuide(topicId, opts = {}) {
+    const sigil = opts.sigil ?? '/';
+    const topics = topicId === 'all' ? GUIDE_TOPICS : GUIDE_TOPICS.filter((t) => t.id === (topicId ?? 'start'));
+    const out = [];
+    for (const t of topics) {
+        out.push(t.title.toUpperCase(), '');
+        for (const p of t.intro ?? [])
+            out.push(...wrap(p, WIDTH, '  '), '');
+        for (const it of t.items) {
+            const skills = skillList(it.skills, sigil);
+            out.push(`  ${it.name}`);
+            if (skills)
+                out.push(...wrap(`skills: ${skills}`, WIDTH, '      '));
+            for (const p of it.body)
+                out.push(...wrap(p, WIDTH, '      '));
+            out.push('');
+        }
+    }
+    if (topicId === undefined || topicId === 'start') {
+        out.push('MORE TOPICS  (bravos guide <topic>, or bravos guide all)', '');
+        for (const t of GUIDE_TOPICS.filter((x) => x.id !== 'start'))
+            out.push(`  ${t.id.padEnd(10)} ${t.summary}`);
+        out.push('', 'Skills are shown in Claude Code syntax; Codex uses $bravos-…, omp /skill:bravos-….');
+    }
+    return out.join('\n').replace(/\n+$/, '');
+}
+// @comment -- "Renders the whole guide as Markdown for docs/GUIDE.md; a test keeps the committed file in step."
+export function renderGuideMarkdown() {
+    const out = ['# bravos guide', '', '_Generated from `src/guide.ts` by `bravos guide --markdown`; edit the source, not this file._', ''];
+    out.push('Skills are written in Claude Code syntax (`/bravos-ship`); in Codex use `$bravos-ship`, in omp `/skill:bravos-ship`.', '');
+    for (const t of GUIDE_TOPICS) {
+        out.push(`## ${t.title}`, '');
+        for (const p of t.intro ?? [])
+            out.push(p, '');
+        for (const it of t.items) {
+            out.push(`### ${it.name}`, '');
+            if (it.skills?.length)
+                out.push(`Skills: ${it.skills.map((s) => `\`/${s}\``).join(' · ')}`, '');
+            out.push(...it.body.flatMap((p) => [p, '']));
+        }
+    }
+    return out.join('\n').replace(/\n+$/, '') + '\n';
+}
+export const GUIDE_TOPIC_IDS = GUIDE_TOPICS.map((t) => t.id);