@bugb-technologies/bravos 0.0.0-stage → 1.0.0

package/dist/workspace.js

@@ -0,0 +1,316 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { whichBin } from './guardlink.js';
+import { BravosError } from './types.js';
+// @comment -- "bravos workspace: one application made of several repositories. Membership (name, path, service, URL per member) lives in $BRAVOS_HOME/workspaces.json, this CLI's own registry; guardlink link-project writes each member's .guardlink/workspace.yaml; the merged view (per-member counts, the calls that cross services, references nothing defines, ids two members define) is computed from each member's own guardlink parse, so no other CLI is needed. A machine-local snapshot under .bravos/workspace/ in each member and in the app folder is what hooks, watch and reports read. argv spawns only, no shell."
+export const WORKSPACE_SCHEMA = 'bravos.workspace/v1';
+export const EXPORT_SCHEMA = 'bravos.workspace-export/v1';
+export const WORKSPACE_DIR = join('.bravos', 'workspace');
+/** `PATH[=service[@url]]`, the form bravos takes: `PATH=@URL` gives a URL and no service, a bare `PATH` neither. */
+export function parseMemberSpec(spec, cwd = process.cwd()) {
+    const eq = spec.indexOf('=');
+    const rawPath = eq < 0 ? spec : spec.slice(0, eq);
+    const rest = eq < 0 ? '' : spec.slice(eq + 1);
+    const at = rest.indexOf('@');
+    const service = at < 0 ? rest : rest.slice(0, at);
+    const url = at < 0 ? '' : rest.slice(at + 1);
+    if (!rawPath)
+        throw new BravosError(`member "${spec}" has no path`);
+    if (url && !/^https?:\/\/[^\s/]+/.test(url))
+        throw new BravosError(`member "${spec}": the URL must start with http:// or https://`);
+    return { path: resolve(cwd, rawPath), service, url };
+}
+// @comment -- "Refuses a member path that does not exist, is not a directory, or is not a git repository (bravos requires .git; a worktree's .git file counts)."
+export function checkMemberPath(path) {
+    if (!existsSync(path) || !statSync(path).isDirectory())
+        throw new BravosError(`${path} is not a folder`);
+    if (!existsSync(join(path, '.git')))
+        throw new BravosError(`${path} is not a git repository (bravos workspaces need one per member)`);
+}
+/** The app folder: the one parent every member sits directly under, else null. An explicit folder wins. */
+export function appFolderFor(paths, explicit) {
+    if (explicit)
+        return resolve(explicit);
+    const parents = [...new Set(paths.map((p) => dirname(resolve(p))))];
+    return paths.length > 1 && parents.length === 1 ? parents[0] : null;
+}
+const run = (cmd, args, cwd, env, timeout = 120000) => spawnSync(cmd, args, { cwd, env, encoding: 'utf8', timeout, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+const firstLine = (s) => (s ?? '').split('\n').map((l) => l.trim()).find((l) => l && !l.startsWith('note:')) ?? '';
+// ---------------------------------------------------------------------------------------------
+// The registry: $BRAVOS_HOME/workspaces.json
+// ---------------------------------------------------------------------------------------------
+export const REGISTRY_SCHEMA = 'bravos.workspaces/v1';
+const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const registryFile = (env) => {
+    const home = env.BRAVOS_HOME || (env.HOME ? join(env.HOME, '.bravos') : null);
+    if (!home)
+        throw new BravosError('no home directory: set BRAVOS_HOME to where bravos keeps its workspaces');
+    return join(home, 'workspaces.json');
+};
+export function readRegistry(env) {
+    const file = registryFile(env);
+    if (!existsSync(file))
+        return { schema: REGISTRY_SCHEMA, workspaces: {} };
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new BravosError(`${file} is not valid JSON; fix it or delete it, nothing was written`);
+    }
+    if (doc?.schema !== REGISTRY_SCHEMA || typeof doc.workspaces !== 'object' || doc.workspaces === null)
+        throw new BravosError(`${file} is not a ${REGISTRY_SCHEMA} document; fix it or delete it`);
+    const workspaces = {};
+    for (const [k, v] of Object.entries(doc.workspaces))
+        workspaces[k] = { name: String(v?.name ?? k), createdAt: String(v?.createdAt ?? ''), members: membersOf(v) };
+    return { schema: REGISTRY_SCHEMA, workspaces };
+}
+// @comment -- "Writes the registry atomically (temp file, rename) with mode 0600: it holds machine-local paths and service URLs, nothing a teammate needs and nothing to share."
+export function writeRegistry(env, reg) {
+    const file = registryFile(env);
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(reg, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, file);
+}
+export function getWorkspace(env, name) {
+    const ws = readRegistry(env).workspaces[name];
+    if (!ws)
+        throw new BravosError(`no workspace ${JSON.stringify(name)}: bravos workspace create ${name} --member PATH ... makes one${Object.keys(readRegistry(env).workspaces).length ? ` (known: ${Object.keys(readRegistry(env).workspaces).join(', ')})` : ''}`);
+    return ws;
+}
+const uniqueName = (base, taken) => {
+    let n = base;
+    for (let i = 2; taken.has(n); i++)
+        n = `${base}-${i}`;
+    return n;
+};
+const toMember = (spec, taken) => {
+    const name = uniqueName(memberName(spec.path), taken);
+    taken.add(name);
+    return { name, path: resolve(spec.path), service: spec.service || name, url: spec.url };
+};
+export function createWorkspace(env, name, specs) {
+    if (!NAME_RE.test(name))
+        throw new BravosError(`a workspace name is lowercase letters, digits, dots, dashes and underscores, got ${JSON.stringify(name)}`);
+    const reg = readRegistry(env);
+    if (reg.workspaces[name])
+        throw new BravosError(`workspace ${name} already exists: bravos workspace add/remove change it, bravos workspace show ${name} lists it`);
+    const taken = new Set();
+    const members = specs.map((s) => toMember(s, taken));
+    const paths = new Set();
+    for (const m of members) {
+        if (paths.has(m.path))
+            throw new BravosError(`${m.path} is given twice`);
+        paths.add(m.path);
+    }
+    reg.workspaces[name] = { name, createdAt: new Date().toISOString(), members };
+    writeRegistry(env, reg);
+    return members;
+}
+export function addMember(env, name, spec) {
+    const reg = readRegistry(env);
+    const ws = reg.workspaces[name];
+    if (!ws)
+        throw new BravosError(`no workspace ${JSON.stringify(name)}`);
+    if (ws.members.some((m) => m.path === resolve(spec.path)))
+        throw new BravosError(`${spec.path} is already a member of ${name}`);
+    const m = toMember(spec, new Set(ws.members.map((x) => x.name)));
+    ws.members.push(m);
+    writeRegistry(env, reg);
+    return m;
+}
+export function removeMember(env, name, member, cwd = process.cwd()) {
+    const reg = readRegistry(env);
+    const ws = reg.workspaces[name];
+    if (!ws)
+        throw new BravosError(`no workspace ${JSON.stringify(name)}`);
+    const i = ws.members.findIndex((m) => m.name === member || m.service === member || m.path === resolve(cwd, member));
+    if (i < 0)
+        throw new BravosError(`${member} is not a member of ${name} (members: ${ws.members.map((m) => m.name).join(', ')})`);
+    const [gone] = ws.members.splice(i, 1);
+    writeRegistry(env, reg);
+    return gone;
+}
+export function setTarget(env, name, service, url) {
+    if (!/^https?:\/\//.test(url))
+        throw new BravosError(`a target URL starts with http:// or https://, got ${JSON.stringify(url)}`);
+    const reg = readRegistry(env);
+    const ws = reg.workspaces[name];
+    if (!ws)
+        throw new BravosError(`no workspace ${JSON.stringify(name)}`);
+    const m = ws.members.find((x) => x.service === service || x.name === service);
+    if (!m)
+        throw new BravosError(`${service} is not a service of ${name} (services: ${ws.members.map((x) => x.service).join(', ')})`);
+    m.url = url;
+    writeRegistry(env, reg);
+    return m;
+}
+// @comment -- "Runs guardlink link-project (fresh link, --add or --remove) so each member's .guardlink/workspace.yaml and agent files name the workspace and its siblings; returns guardlink's own output, or a note when guardlink is missing or there is only one member."
+export function linkProject(args, env, cwd = process.cwd()) {
+    if (!whichBin('guardlink', env))
+        return 'guardlink not on PATH: member workspace.yaml files not written';
+    const r = run('guardlink', ['link-project', ...args], cwd, env);
+    if (r.status !== 0)
+        throw new BravosError(`guardlink link-project failed: ${firstLine(r.stderr) || firstLine(r.stdout) || `exit ${r.status}`}`);
+    return firstLine(r.stdout) || 'guardlink link-project done';
+}
+const membersOf = (doc) => (Array.isArray(doc?.members) ? doc.members : []).map((m) => ({ name: String(m.name), path: String(m.path), service: String(m.service ?? m.service_name ?? ''), url: String(m.url ?? '') }));
+/** Ids the coding-agent configuration generates in every repo (guardlink's agent block); the same id in two members is expected, not a clash. */
+const SHARED_ACTOR = /^(claude-code|codex|cursor|copilot|gemini|opencode|omp|antigravity|coding-agent)(-|$)/;
+// @comment -- "One member's model as guardlink parse prints it: the ids it defines (assets, threats, controls, actors — by kind), its flows, its exposure counts, and HEAD. A member whose parse fails reads as an error, never as empty."
+export function readMemberModel(path, env) {
+    const out = { ids: new Map(), flows: [], exposures: 0, bySeverity: {}, head: null, error: null };
+    const head = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: path, env, encoding: 'utf8', timeout: 5000 });
+    out.head = head.status === 0 ? head.stdout.trim() : null;
+    if (!whichBin('guardlink', env)) {
+        out.error = 'guardlink not on PATH';
+        return out;
+    }
+    const r = run('guardlink', ['parse', '.', '--no-pretty'], path, env);
+    if (r.status !== 0) {
+        out.error = `guardlink parse failed: ${firstLine(r.stderr) || firstLine(r.stdout) || `exit ${r.status}`}`;
+        return out;
+    }
+    let doc;
+    try {
+        doc = JSON.parse(r.stdout);
+    }
+    catch {
+        out.error = 'guardlink parse printed no JSON';
+        return out;
+    }
+    for (const kind of ['assets', 'threats', 'controls', 'actors'])
+        for (const d of Array.isArray(doc?.[kind]) ? doc[kind] : [])
+            if (typeof d?.id === 'string')
+                out.ids.set(d.id, kind);
+    for (const f of Array.isArray(doc?.flows) ? doc.flows : [])
+        out.flows.push({ source: String(f?.source ?? ''), target: String(f?.target ?? ''), mechanism: String(f?.mechanism ?? ''), file: `${f?.location?.file ?? '?'}${f?.location?.line ? `:${f.location.line}` : ''}` });
+    for (const e of Array.isArray(doc?.exposures) ? doc.exposures : []) {
+        out.exposures++;
+        const sev = String(e?.severity ?? 'unset');
+        out.bySeverity[sev] = (out.bySeverity[sev] ?? 0) + 1;
+    }
+    return out;
+}
+// @comment -- "The merged view, from the members' own models: an edge is a flow whose #id end is defined in another member (de-duplicated by src, dst and mechanism); an unresolved reference is a #id no member defines; a clash is an id two members define, except the coding-agent actors every repo generates. Per member: exposure counts, HEAD, and any read error."
+export function computeExport(name, members, models, at = new Date().toISOString()) {
+    const owners = new Map();
+    for (const m of members)
+        for (const id of models[m.name]?.ids.keys() ?? [])
+            owners.set(id, [...(owners.get(id) ?? []), m.name]);
+    const edges = [];
+    const seen = new Set();
+    const unresolved = [];
+    const ref = (s) => (s.startsWith('#') ? s.slice(1) : null);
+    for (const m of members) {
+        for (const f of models[m.name]?.flows ?? []) {
+            const srcId = ref(f.source);
+            const dstId = ref(f.target);
+            const srcOwner = srcId ? (models[m.name]?.ids.has(srcId) ? m.name : owners.get(srcId)?.[0] ?? null) : m.name;
+            const dstOwner = dstId ? (models[m.name]?.ids.has(dstId) ? m.name : owners.get(dstId)?.[0] ?? null) : m.name;
+            if (srcId && !srcOwner)
+                unresolved.push({ member: m.name, reference: srcId, flow: 'src' });
+            if (dstId && !dstOwner)
+                unresolved.push({ member: m.name, reference: dstId, flow: 'dst' });
+            if (!srcOwner || !dstOwner || srcOwner === dstOwner)
+                continue;
+            const key = `${srcId ?? f.source}|${dstId ?? f.target}|${f.mechanism}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            edges.push({ src: srcId ?? f.source, dst: dstId ?? f.target, srcMember: srcOwner, dstMember: dstOwner, mechanism: f.mechanism, declaredIn: `${m.name}/${f.file}` });
+        }
+    }
+    const clashes = [];
+    for (const [id, ms] of owners) {
+        if (ms.length < 2)
+            continue;
+        const kind = models[ms[0]]?.ids.get(id) ?? '';
+        if (kind === 'actors' && SHARED_ACTOR.test(id))
+            continue;
+        clashes.push({ kind, id, members: ms });
+    }
+    const out = {};
+    for (const m of members) {
+        const md = models[m.name];
+        out[m.name] = { exposures: md?.exposures ?? 0, bySeverity: md?.bySeverity ?? {}, head: md?.head ?? null, ...(md?.error ? { error: md.error } : {}) };
+    }
+    return { schema: EXPORT_SCHEMA, name, at, members: out, edges, unresolved: unresolved.filter((u, i, a) => a.findIndex((x) => x.member === u.member && x.reference === u.reference) === i), clashes: clashes.sort((a, b) => a.id.localeCompare(b.id)) };
+}
+const dirFor = (root) => join(root, WORKSPACE_DIR);
+// @comment -- "Writes the snapshot (and the export cache when given) into root/.bravos/workspace/, creating its .gitignore (*) first: paths are machine-local and never committed."
+export function writeSnapshot(root, snap, exp) {
+    const dir = dirFor(root);
+    mkdirSync(dir, { recursive: true });
+    if (!existsSync(join(dir, '.gitignore')))
+        writeFileSync(join(dir, '.gitignore'), '*\n');
+    writeFileSync(join(dir, 'workspace.json'), JSON.stringify(snap, null, 2) + '\n');
+    if (exp)
+        writeFileSync(join(dir, 'export.json'), JSON.stringify(exp, null, 2) + '\n');
+}
+export function readSnapshot(root) {
+    try {
+        const s = JSON.parse(readFileSync(join(dirFor(root), 'workspace.json'), 'utf8'));
+        return s?.schema === WORKSPACE_SCHEMA && Array.isArray(s.members) ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readExport(root) {
+    try {
+        const s = JSON.parse(readFileSync(join(dirFor(root), 'export.json'), 'utf8'));
+        return s?.schema === EXPORT_SCHEMA ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Every place a snapshot belongs: each member, and the app folder when there is one. */
+export const snapshotRoots = (snap) => [...snap.members.map((m) => m.path), ...(snap.appFolder ? [snap.appFolder] : [])];
+// @comment -- "Reads the workspace from the registry, computes the merged export from each member's own model (a member that fails to parse is reported, not dropped), and writes the snapshot and cache to every member and the app folder. Returns both."
+export function refresh(name, env, appFolder) {
+    const ws = getWorkspace(env, name);
+    const members = ws.members;
+    const models = {};
+    for (const m of members)
+        models[m.name] = existsSync(m.path) ? readMemberModel(m.path, env) : { ids: new Map(), flows: [], exposures: 0, bySeverity: {}, head: null, error: 'path is gone' };
+    const exp = computeExport(name, members, models);
+    const errors = members.filter((m) => models[m.name].error).map((m) => `${m.name}: ${models[m.name].error}`);
+    const snap = { schema: WORKSPACE_SCHEMA, name, appFolder, members, at: new Date().toISOString() };
+    for (const root of snapshotRoots(snap))
+        if (existsSync(root))
+            writeSnapshot(root, snap, exp);
+    return { snap, exp, exportError: errors.length ? errors.join('; ') : null };
+}
+/** Lines describing a workspace for `bravos workspace show`. */
+export function describe(snap, exp) {
+    const lines = [`Workspace ${snap.name}: ${snap.members.length} service${snap.members.length === 1 ? '' : 's'}${snap.appFolder ? ` · app folder ${snap.appFolder}` : ' · no app folder'}`];
+    for (const m of snap.members) {
+        const e = exp?.members[m.name];
+        const sev = e ? Object.entries(e.bySeverity).filter(([, n]) => n).map(([k, n]) => `${n} ${k}`).join(', ') : '';
+        const state = [existsSync(join(m.path, '.guardlink', 'workspace.yaml')) ? 'linked' : 'not linked', existsSync(join(m.path, '.bravos')) ? 'bravos' : 'no bravos'].join(', ');
+        lines.push(`  ${m.name.padEnd(14)} ${(m.service || '-').padEnd(12)} ${(m.url || 'no URL').padEnd(26)} ${e ? `${e.exposures} exposures${sev ? ` (${sev})` : ''}` : 'exposures ?'}  [${state}]`);
+        lines.push(`  ${''.padEnd(14)} ${m.path}`);
+    }
+    if (!exp)
+        lines.push('Cross-service edges: unknown (bravos workspace export failed or not run)');
+    else {
+        lines.push(`Cross-service edges: ${exp.edges.length}`);
+        for (const e of exp.edges)
+            lines.push(`  ${e.srcMember}:${e.src} -> ${e.dstMember}:${e.dst}${e.mechanism ? ` via ${e.mechanism}` : ''}  (${e.declaredIn})`);
+        if (exp.unresolved.length)
+            lines.push(`Unresolved references: ${exp.unresolved.length}`, ...exp.unresolved.slice(0, 10).map((u) => `  ${u.member}: ${u.reference}`));
+        if (exp.clashes.length)
+            lines.push(`Clashes (an id defined differently in two services): ${exp.clashes.length}`, ...exp.clashes.slice(0, 10).map((c) => `  ${c.id}: ${c.members.join(', ')}`));
+    }
+    const missingUrl = snap.members.filter((m) => !m.url).map((m) => m.name);
+    if (missingUrl.length)
+        lines.push(`No URL for: ${missingUrl.join(', ')} → bravos workspace target ${snap.name} <service>=http://127.0.0.1:<port>`);
+    return lines;
+}
+/** The member a path belongs to, by path. */
+export const memberAt = (snap, root) => snap.members.find((m) => resolve(m.path) === resolve(root)) ?? null;
+export const memberName = (path) => basename(resolve(path));

package/docs/GUIDE.md

@@ -0,0 +1,323 @@
+# bravos guide
+
+_Generated from `src/guide.ts` by `bravos guide --markdown`; edit the source, not this file._
+
+Skills are written in Claude Code syntax (`/bravos-ship`); in Codex use `$bravos-ship`, in omp `/skill:bravos-ship`.
+
+## What bravos is and how a session starts
+
+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.
+
+### At session start
+
+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.
+
+### Running a skill
+
+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.
+
+### Plans
+
+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.
+
+### Effort
+
+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.
+
+### Installing
+
+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.
+
+### Your first day
+
+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.
+
+### Hands-off: autopilot
+
+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.
+
+### Free views (no tokens)
+
+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.
+
+## What to do, by role
+
+### Developer
+
+Skills: `/bravos` · `/bravos-annotate` · `/bravos-ship`
+
+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.
+
+### Security engineer
+
+Skills: `/bravos-context` · `/bravos-templatize` · `/bravos-env` · `/bravos-prove` · `/bravos-recheck`
+
+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.
+
+### Team lead or reviewer
+
+Skills: `/bravos-campaign` · `/bravos-schedule` · `/bravos-cicd`
+
+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.
+
+### New to the repo
+
+Skills: `/bravos` · `/bravos-context` · `/bravos-codegraph`
+
+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.
+
+### CI owner
+
+Skills: `/bravos-cicd` · `/bravos-schedule`
+
+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.
+
+## What to do, by task
+
+### Where do I start? What is open?
+
+Skills: `/bravos`
+
+Reads the briefing and names the one next step, with the reason.
+
+### Teach bravos what the app is for
+
+Skills: `/bravos-context`
+
+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.
+
+### Threat-model someone else's project
+
+Skills: `/bravos-context` · `/bravos-annotate`
+
+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.
+
+### Answer bravos's questions as a team
+
+Skills: `/bravos-context`
+
+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.
+
+### I wrote security-relevant code
+
+Skills: `/bravos-annotate`
+
+Annotates what you changed to guardlink's evidence bar and runs the lint gate until clean.
+
+### Cover the whole repo
+
+Skills: `/bravos-campaign`
+
+Rounds of batches with subagents and rests, until the coverage goal or until you stop it.
+
+### Is this exposure real?
+
+Skills: `/bravos-templatize` · `/bravos-env` · `/bravos-prove`
+
+Template → authorized target → run. Only a reproduced run confirms; reading code never does.
+
+### I fixed a finding
+
+Skills: `/bravos-recheck`
+
+Re-verifies stale claims, replays the retest kit, and checks the fix added no new exposure.
+
+### I am about to open a PR
+
+Skills: `/bravos-ship`
+
+The no-mistakes gate: validate, lint since the merge base, disclose new exposure, block confirmed exploits on changed paths.
+
+### Find the routes, callers or blast radius
+
+Skills: `/bravos-codegraph`
+
+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.
+
+### Scan for dependency CVEs, secrets, IaC
+
+Skills: `/bravos-sast`
+
+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.
+
+### What did SAST find, and what happens to it
+
+Skills: `/bravos-sast` · `/bravos-annotate` · `/bravos-templatize` · `/bravos-prove` · `/bravos-recheck`
+
+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.
+
+### Keep it fresh while I work, or nightly
+
+Skills: `/bravos-schedule`
+
+An in-session /loop from .claude/loop.md, the nightly workflow, or a cloud task you create. Loops never send test traffic.
+
+### Add or fix security CI
+
+Skills: `/bravos-cicd`
+
+PR gate, nightly annotation, SARIF to code scanning, script-injection fixes.
+
+### An app made of several repositories (microservices)
+
+Skills: `/bravos-annotate` · `/bravos-codegraph` · `/bravos-prove`
+
+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.
+
+### Write up the assessment, a finding or a retest
+
+Skills: `/bravos-report`
+
+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).
+
+## Every skill
+
+### bravos
+
+Front door: reads the security picture, explains the evidence loop, routes to the right skill.
+
+### bravos-context
+
+Learns what the product intends from the repo and a short interview; records invariants, intended behaviour, actors, assets and boundaries.
+
+### bravos-annotate
+
+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.
+
+### bravos-codegraph
+
+Bounded questions to codegraph-mcp: routes, attack surface, sinks a symbol reaches, liveness, blast radius, annotation gaps in a change.
+
+### bravos-ship
+
+The pre-PR gate. Optional PreToolUse hook (bravos init --pre-pr-hook) runs it on every gh pr create / gh pr ready.
+
+### bravos-templatize
+
+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.
+
+### bravos-env
+
+Brings up a target you own: loopback by default, a committed reviewed scope.yaml, your typed authorization, a real session captured or imported.
+
+### bravos-prove
+
+Runs the authorized test, reads cxg's report and exit code, writes outcomes only through guardlink's hypothesis ledger.
+
+### bravos-recheck
+
+After a fix: stale claims, retest-kit replay, no new exposure, what to test next.
+
+### bravos-sast
+
+Licensed static analysis joined to guardlink claims and reachability; gates on findings new since the base.
+
+### bravos-campaign
+
+A goal over many rounds: disjoint batches, one subagent each, a gate per batch, rests, a final before-and-after.
+
+### bravos-schedule
+
+Recurring upkeep with each harness's own mechanism; never live tests from a loop.
+
+### bravos-cicd
+
+Audits and writes the security workflows.
+
+### bravos-report
+
+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.
+
+## Reading a finding
+
+### open / mitigated / accepted
+
+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.
+
+### untested / confirmed / refuted
+
+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.
+
+### verified / stale
+
+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.
+
+### Severity
+
+Rated by impact on this product × reach × ease, with the reason written down. Without .guardlink/intent.md, severities are defaults, not calibrated.
+
+### unknown is not zero
+
+When a tool is unavailable the briefing says "unknown", never 0. Nothing is called clean unless a gate exited 0.
+
+## The hard rules
+
+### Authorization
+
+No request goes to a host other than loopback without a committed, reviewed scope.yaml and your own typed authorization naming the target.
+
+### Destructive tests
+
+DoS and other destructive classes run only against a disposable loopback target.
+
+### Credentials
+
+Never invented. Test users and sessions are seeded or captured for real, or the run waits for you.
+
+### No hidden agents
+
+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.
+
+### Governance
+
+Agents never write @accepts or @entitles (a human's decision) and never write @confirmed without reproduction evidence in hand.
+
+## Harnesses
+
+### Claude Code
+
+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.
+
+### Codex
+
+Skills in .agents/skills, hook in .codex/hooks.json (trust it once in /hooks), MCP in .codex/config.toml. Also as a plugin.
+
+### omp
+
+Reads the Claude Code skills and MCP; .omp/extensions/bravos.js shows the banner and hands over the briefing.
+
+### opencode
+
+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.
+
+### Antigravity (agy)
+
+Reads .agents/skills; .agents/hooks.json carries a bravos SessionStart group that injects the briefing.
+
+### Cursor
+
+.cursor/rules/bravos.mdc points at the skills when the repo has a .cursor/ folder.
+
+### VS Code (Copilot agent)
+
+Reads hooks from .claude/settings.json (preview), so the briefing can load there too.
+
+### Every repo, or one copy of each skill
+
+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.
+
+### Banner switches
+
+BRAVOS_BANNER=off hides it; BRAVOS_BANNER_COLOR=off or NO_COLOR prints it plain. The briefing for the model is unchanged either way.