@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,70 @@
+BRAVOS SOFTWARE LICENCE
+Version 1.0, 6 November 2026
+
+Copyright (c) 2026 BugB Technologies. All rights reserved.
+
+Bravos (the "Software") is proprietary software of BugB Technologies
+("BugB"). It is licensed, not sold. By installing or using the Software you
+agree to these terms. If you do not agree, do not install or use it.
+
+1. Free use
+   You may install and use the Software at no charge for the features of
+   the Free plan, as described at https://account.bugb.io/pricing.
+
+2. Paid features
+   The features the Software marks as Team features (at this version: the
+   pre-PR gate and autopilot, the CI and nightly workflows, scheduled
+   upkeep, multi-repository workspaces, campaigns, SAST and the code graph)
+   may be used only with a valid licence issued by BugB through
+   https://account.bugb.io, and only within the plan, seats and term that
+   licence states, including a trial.
+
+3. Restrictions
+   You may not, and may not let anyone else:
+   (a) copy the Software, except as needed to install and run it under
+       these terms;
+   (b) modify, adapt or create derivative works of the Software, except
+       that you may edit the files it writes into your own repositories
+       for your own internal use;
+   (c) remove, disable, bypass or tamper with any licence check, or use a
+       Team feature without a valid licence;
+   (d) redistribute, publish, sublicense, rent, lease, sell, or offer the
+       Software or any part of it as a service to others;
+   (e) reverse engineer the Software or the binaries it downloads, except
+       to the extent applicable law allows this despite this restriction;
+   (f) remove or alter any copyright or licence notice.
+
+4. Your content
+   The threat models, annotations, reports, templates and other output the
+   Software produces from your code belong to you. BugB claims no rights in
+   them.
+
+5. Third-party components
+   The Software depends on, and can install, third-party software
+   (including guardlink, cert-x-gen and open-source npm packages) that is
+   licensed under its own terms. Those terms govern those components.
+
+6. Termination
+   Your rights under these terms end automatically if you breach them. When
+   they end, you must stop using the Software and delete every copy.
+
+7. No warranty
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NON-INFRINGEMENT. Security testing can disturb
+   the systems it runs against; you are responsible for running it only
+   against systems you own or are authorised to test.
+
+8. Limitation of liability
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, BUGB IS NOT LIABLE FOR ANY
+   INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR LOSS OF DATA,
+   PROFITS OR BUSINESS, ARISING FROM THE SOFTWARE. BUGB'S TOTAL LIABILITY
+   IS LIMITED TO THE FEES YOU PAID FOR THE SOFTWARE IN THE TWELVE MONTHS
+   BEFORE THE CLAIM.
+
+9. Other agreements
+   If you have a separate written agreement with BugB that covers the
+   Software, such as an Enterprise order, that agreement prevails where it
+   differs from these terms.
+
+Questions: https://account.bugb.io/contact

package/README.md

@@ -1,3 +1,226 @@
-# Temporary Holding Version
+# Bravos
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bravos is a skills pack plus a thin installer that makes Claude Code and Codex power users of guardlink (threat-model-as-code), cert-x-gen (`cxg`, pentest-as-code) and the code graph, through the harnesses' own skills and hooks. No orchestrator process, no state store: `bravos init` writes skills, MCP wiring and a session-start hook into a repo; the agents do the rest with the real CLIs.
+
+## Install
+
+```bash
+npm install -g @bugb-technologies/bravos
+```
+
+The command it installs is `bravos`.
+
+Then, in order: `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 this 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). Node 20 or newer; guardlink and cxg are installed by `bravos setup --tools -y` or by hand.
+
+**Used the Python `bravos` before?** Its `bravos` command usually sits in `~/.local/bin`, which most shells search before npm's folder, so it would still answer when you type `bravos`. Keep it under another name, and this CLI keeps using its code graph and analyzer until `bravos setup` installs its own:
+
+```bash
+mv ~/.local/bin/bravos ~/.local/bin/bravos-py
+```
+
+Or remove it (`pipx uninstall bravos` or `uv tool uninstall bravos`). `which -a bravos` should then show npm's copy first (its real path ends in `node_modules/@bugb-technologies/bravos/dist/cli.js`).
+
+## Commands
+
+- `bravos init`: write skills, MCP wiring and the session-start hook into the current repo. `--agent claude,codex` picks the harnesses instead of detecting them. `--pre-pr-hook` also registers the PreToolUse gate on `gh pr create` / `gh pr ready` and lists it under `pre_pr` in `.guardlink/config.json`, so guardlink's agent block names it after `guardlink sync`; `--ci` also writes the GitHub Actions workflows; `--scope` writes the loopback-only cxg scope starter to `.guardlink/scope.yaml` when no scope file exists (never overwritten). A repo with a `.cursor/` folder also gets `.cursor/rules/bravos.mdc`, a pointer to the skills.
+- `bravos sync`: refresh the installed skills and wiring to match this version of bravos; it also adds the cxg and codegraph MCP servers once they are installed (bravos's own committed MCP config carries guardlink only). The codegraph server is registered by its full path with the graph store as `BRAVOS_CODEGRAPH_DIR`, so the MCP tools read the graphs `bravos graph build` writes; after a `bravos setup` that stages a new bundle, `sync` refreshes that one entry, and keeps every other existing entry as it is.
+- `bravos setup`: puts the binaries bravos drives on this machine. The analyzer (`bravos-cli`, SAST) and the code graph (`codegraph-build`, `codegraph-mcp`) are signed bundles fetched through the account portal on the Team plan — the portal verifies the licence, the CLI verifies each file's Ed25519 signature before it unpacks, and nothing under `$BRAVOS_HOME` changes until every check has passed; `--tools -y` also installs guardlink (npm) and cxg (cargo). `--check` reports, `--dry-run` says what would happen.
+- `bravos graph`: `graph build [DIR]` indexes a repository (`--scip no-exec` by default, so no repository code runs); `graph <question> [args] --json` asks it — the same answers as the `codegraph_` MCP tools, through a one-call MCP session on stdio; `graph --json` lists every question this machine's binary answers.
+- `bravos sast run`: analyzes the repository with the staged analyzer into `.bravos/sast/<run>/` (not committed), which `bravos sast status` and `candidates` read. Takes the same `--agent`, `--pre-pr-hook`, `--ci` and `--scope` options as `init`, and never runs `guardlink init`.
+- `bravos doctor`: check that the installed pieces and the underlying CLIs are present and healthy.
+- `bravos watch`: a live, read-only view of the repo's security work for a second terminal pane beside any agent (below).
+
+## Skills
+
+| Skill | What it does |
+|---|---|
+| `bravos` | Front door: reads the session briefing and routes to the skill below. |
+| `bravos-annotate` | Grows the threat model in budgeted slices (or deep rounds), gated by `guardlink lint`. |
+| `bravos-codegraph` | One bounded question to the code graph instead of grepping. With the graph built, bravos-templatize targets the route and auth that reach each sink, bravos-recheck follows a fix's callers 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. |
+| `bravos-ship` | The pre-PR security gate. |
+| `bravos-templatize` | Turns open exposures into validated cxg templates, in-session; records classes with no oracle as gaps. |
+| `bravos-env` | Brings up a target the user owns: loopback by default, a reviewed `scope.yaml`, the human's typed authorization, a real session. |
+| `bravos-prove` | Runs the authorized test and writes outcomes back only through guardlink's hypothesis ledger. |
+| `bravos-recheck` | After a fix: re-verifies stale claims, replays retest kits, checks the fix added no exposure. |
+| `bravos-sast` | Licensed static analysis (bravos-cli: Semgrep, request-to-sink taint, dependency CVEs, secrets, IaC) joined to the threat model and the code graph; says plainly when it is unavailable. Its runs land in `.bravos/sast/` (not committed), and `bravos sast candidates` hands them on: reachable findings joined to a claim give bravos-templatize and bravos-prove the route to target, findings not in the threat model are leads for bravos-annotate, and bravos-recheck rescans after a fix. A static finding is a lead; only a run confirms. |
+| `bravos-schedule` | Recurring upkeep: an in-session `/loop`, the nightly workflow, or a cloud task you create. Never live tests. |
+| `bravos-cicd` | Audits and writes the security workflows; fixes broken guardlink calls and script-injection risks. |
+| `bravos-report` | Writes the assessment, one finding, a retest or an executive brief from the evidence `bravos report data` gathers, checks it with `bravos report check`, and exports it to md, txt, html and pdf. |
+
+## Plans and the licence
+
+Bravos is free for one person researching one repository, and licensed per developer for a team.
+
+| Plan | What it gives |
+|---|---|
+| **Free (researcher)** — no licence | bravos-context, bravos-annotate, bravos-templatize, bravos-env, bravos-prove, bravos-recheck, bravos-report and `bravos watch`, in one repository |
+| **Team** (Solo is one seat) | everything above plus the pre-PR gate and autopilot, the CI and nightly workflows, scheduled upkeep, multi-repository workspaces, campaigns, SAST and the code graph |
+
+`bravos licence` says which plan this machine is on, where the licence is and what it unlocks; the same line opens every session's briefing (`Plan: …`), `bravos doctor`, `bravos next` and the `bravos watch` header. `bravos account activate` signs you in once in the browser and writes the licence — a 30-day Team trial with no card when the account has no plan — and `bravos account import <file>` installs one downloaded from [account.bugb.io/dashboard/license](https://account.bugb.io/dashboard/license). A paid command or flag used without a licence explains what it would do and how to start the trial, and writes nothing; a paid hook (the pre-PR gate, autopilot) stands down with one line and never blocks a pull request; a paid skill stops at its first step and says so. The licence is a signed token verified offline (`BRAVOS_LICENCE`, or `licence.jwt` under `$BRAVOS_HOME`, default `~/.bravos`); after expiry it keeps working for min(14 days, a quarter of the term) and says so. Seats are counted in the account portal, not on the machine.
+
+## Several repositories, one app: `bravos workspace`
+
+For microservices, clone the services side by side in one folder and link them:
+
+```bash
+bravos workspace create platform \
+  --member ./gateway=gateway@http://127.0.0.1:8080 \
+  --member ./orders=orders@http://127.0.0.1:8081 \
+  --member ./billing=billing@http://127.0.0.1:8082
+```
+
+That one command:
+- creates a bravos workspace, the source of truth for members, services and URLs;
+- runs `guardlink link-project`, so each repo's `.guardlink/workspace.yaml` names its siblings;
+- runs `bravos init` (or `sync`) in each service, and installs bravos in the shared folder, the **app folder**;
+- writes a snapshot to `.bravos/workspace/` in each of them (gitignored, since its paths are machine-local).
+
+`add`, `remove`, `target NAME SERVICE=URL`, `show [NAME] [--json]` and `sync` keep all three in step. Members can live anywhere, but only the app folder lets the code graph link services: `bravos graph build <app folder> --scip no-exec` connects one service's HTTP, gRPC, GraphQL or OpenAPI client call to another's handler.
+
+**In a service repo:**
+- the briefing names the app, the other services, and the calls into and out of this one;
+- `bravos watch` gets a SERVICES panel, and `s` shows every service and cross-service edge.
+
+**At the app folder:**
+- the briefing lists each service's open, high and confirmed exposures and coverage;
+- `bravos report data --workspace` gathers one report across services, with ids prefixed by service (`orders:EXP-3`) and cross-service calls as `EDGE-n`.
+
+Declare each call to another service as `@flows #<this>-<x> -> #<other>-<y> via http|grpc|queue`, with plain ids prefixed by service. guardlink merge, bravos export and cxg chaining all read this form. guardlink's dotted `#repo.tag` form is not chained by cxg.
+
+## Reports: `bravos report` and the bravos-report skill
+
+Ask the agent to "write the assessment report" (or a single finding, a retest, an executive brief) and the bravos-report skill does it in three steps:
+
+1. `bravos report data` (free, no model) gathers every fact a report may cite into `.bravos/reports/<id>/evidence.json`:
+   - the threat model, and the hypothesis and boundary ledgers;
+   - each cxg run under `.guardlink/pentest-findings/`;
+   - SAST, the code graph, intent, scope and proving;
+   - tool versions.
+
+   Each fact gets an id (`EXP-n`, `LED-…`, `RUN-n/F-n`, `SAST-n`). Each exposure gets an evidence level computed from that evidence: reproduced at runtime, control held at runtime, established by code or configuration review, or suspected, awaiting validation. Token-shaped strings are redacted as they are read.
+2. **The agent writes `report.md`** from the skill's templates. The full assessment follows the eight-section reading order (executive assessment, scope and limitations, system and threat context, coverage and approach, principal attack narratives, findings, remediation roadmap, retest and appendices). Every finding is self-contained, with:
+   - prerequisites;
+   - expected and observed behaviour;
+   - reproduction;
+   - root cause;
+   - impact (demonstrated, supported, uncertain);
+   - a severity rationale and a priority;
+   - remediation and verification.
+
+   Every proof claim cites its evidence ids.
+3. **`bravos report check` fails the report** when any of these is wrong:
+   - a section is missing or out of order, or a finding lacks a field;
+   - a label is stronger than its cited evidence supports, or a cited id is unknown;
+   - a percentage has no denominator, or a CVSS score has no vector;
+   - something looks like a secret.
+
+`bravos report export <id> --format md,txt,html,pdf` renders the checked report beside `report.md`:
+- **html:** a branded page with no script and no external request, and a print stylesheet;
+- **txt:** 80 columns;
+- **pdf:** printed by an installed Chrome, Edge, Brave or Chromium (or Playwright's Chromium) in headless mode, with a throwaway profile. Set `BRAVOS_PDF_BROWSER` to choose one.
+
+`bravos report list` shows the reports. Reports quote evidence, so `.bravos/reports/` carries its own `.gitignore`; sharing an export is a deliberate act. `bravos watch` shows the newest report in a REPORT panel: findings by evidence level and severity, check verdict, exports, and commits since. `p` shows its findings and executive section; `o` opens the pdf or html.
+
+## Answering bravos's questions: `bravos review`
+
+bravos-context no longer pastes thirty questions into chat. By default it assumes you are researching software you do not own: it drafts the intent from upstream's own docs (with links) and asks only the scope decisions — configuration baseline, single organisation or multi-tenant, attackers in scope, and intended-looking behaviours upstream leaves undocumented — which `intent.md` records as Assumptions that severities are rated against; say it is your product for the owner interview. It writes its suggestions to `.guardlink/intent-draft.json` and runs `bravos review intent`, which opens a bravos-branded page served from your machine only (loopback, a random token, answers capped and validated). Every card comes pre-filled with bravos's suggestion, its reason and its source; facts are folded away; decisions are marked "needs your call" and Confirm stays off until each one is clicked, so nobody rubber-stamps them. `intent.md` records each item as accepted as suggested, edited, chosen or draft, with names. Each person's answers are saved to `.guardlink/intent-answers/<name>.json`. Teammates run `bravos review intent` after pulling, or open the page with `--no-serve` and send the downloaded file, and the answers travel through git like any other change. `bravos review intent --summary` prints who agreed and who disagreed, for the agent to settle; `intent.md` marks each item confirmed only by the people who agreed to it. On Claude Code, `--share` renders the page for a private claude.ai artifact with a shared database instead; the agent says first that this puts your security intent on claude.ai.
+
+## Autopilot
+
+`bravos init --autopilot` (or `sync --autopilot`) is for teams who would rather not ask. It registers an end-of-turn check, a Stop hook in Claude Code and Codex, plus the pre-PR gate. When a turn's changes leave any of these, the agent is sent back once with the skill to use:
+- a file with no GuardLink annotation;
+- a confirmed or stale claim on a changed file;
+- open exposures on changed files.
+
+It runs only guardlink's two fast calls (`unannotated` and `ci`, a few seconds even on a large repo); lint and diff stay in the pre-PR gate.
+
+Each finding is raised once per session, and a missing tool or a timeout lets the turn finish.
+
+How new exposures get proven is the team's call, not a fixed rule. The first time proving comes up, the agent asks once: prove automatically on your loopback target, ask each time, on a schedule, or not now; and whether cxg may generate probes through a model API. It records the person's words in `.guardlink/proving.md`, which every briefing shows and which a PR that changes it must mention. Non-loopback targets still need a reviewed scope and typed authorization each time. `BRAVOS_AUTOPILOT=off` pauses the check.
+
+## User-level install and one copy of each skill
+
+`bravos init --global` (and `bravos sync --global` after an upgrade) installs bravos for your user rather than a repo: the skills once in `~/.claude/skills`, linked from `~/.agents/skills` for Codex and other shared-root agents, the session-start hook in `~/.bravos/hooks` registered in `~/.claude/settings.json` and `~/.codex/hooks.json`, and guardlink MCP in `~/.codex/config.toml`. The user hook is quiet in any repo that has its own bravos hook or no `.guardlink/`, so it briefs only repos with a threat model that bravos is not installed in. It is personal: teammates get bravos through `bravos init` in the repo. Because Claude Code prefers personal skills over a repo's, `bravos sync` in any repo also brings an existing user-level install to the same version, so an older personal copy never stands in for the repo's; it never creates one, and `BRAVOS_SYNC_GLOBAL=off` keeps the two separate.
+
+`bravos sync --link-skills` replaces a repo's `.agents/skills` with a link to `.claude/skills`, so each skill exists once; tools that read both folders, such as Warp, otherwise show every skill twice. It removes only bravos's own unchanged copies and refuses, removing nothing, when anything else is there.
+
+## Uninstall
+
+`bravos uninstall` removes bravos from the current repository: every file its lock records that is unchanged, its hook entries in `.claude/settings.json`, `.codex/hooks.json` and `.agents/hooks.json`, its `pre_pr` entry in `.guardlink/config.json`, and `.bravos/`. `bravos uninstall --global` does the same for the user-level install, including the `~/.agents/skills/bravos*` links. Edited files are kept and listed unless `--force`; `--dry-run` lists everything first. It never removes guardlink's own files, a reviewed `scope.yaml`, or MCP entries, which may predate bravos; it lists them.
+
+## A live view: `bravos watch`
+
+`bravos watch` runs in a second terminal pane beside any agent (Claude Code, Codex, omp, opencode, Antigravity) and shows the repo's security work as it changes. A row of tiles (open, high, confirmed, tested, coverage, stale, setup, graph resolution, SAST) sits under a header bar, and bordered panels below it show:
+
+- **Setup**: the nine steps with a progress bar, and the next one with its command.
+- **Threat model**: a severity bar (one glyph per severity, so it reads without colour), the hypothesis ledger (confirmed, refuted, retest, untested), boundary claims held or broken, coverage, annotations, stale claims, drift, orphans, accepted risks and tickets, with sparklines of open exposures and coverage over the session.
+- **Test next**: `guardlink hypothesis next` with severity badges, asset, state and file.
+- **Top threats and assets**, ranked with bars.
+- **Code graph**: currency, files, callables and calls, call resolution per language (with a warning below 50%, where "not reached" is weak evidence), entry points by kind, route access levels, how many declared exposures a test reaches, hot files that change open exposures, accepted risks. A commit leaves the checkout without a graph until it is rebuilt, because bravos keys the graph to the commit; the panel says so and gives the command.
+- **SAST**, **branch and team** (ahead and behind the base, uncommitted files and how many lack annotations, recent commits, PRs, autopilot, pre-PR and CI hooks, intent, proving, review answers, a skills-version mismatch), the **model's size** (`guardlink status`), and **activity**.
+
+It redraws within a couple of seconds of a file change (`fs.watch`, debounced; one snapshot at a time), re-reads boundaries, the model's size and PRs every `--interval` seconds (default 60), and asks the code graph again every `--graph-interval` seconds (default 300). Read-only and free: no model, nothing written to the repo. Autopilot logs each nudge to `.bravos/watch/events.jsonl`, a local log with its own `.gitignore`, capped at 500 lines.
+
+Three columns from 150 wide, two from 110, one column from 80 (a split pane), a compact list below that (`--compact` forces it); the panels scroll when the terminal is shorter than they are. Keys: `n` copies the next command, `r` opens the intent review page, `d` writes guardlink's dashboard to a temp file and opens it, `g` asks the code graph a question (`bravos graph <q>`), `t` shows test-next and stale claims in full, `i` shows the recorded intent (`.guardlink/intent.md`, with who answered the review), `u` refreshes everything now, `j`/`k` (or the arrows, space, `G`) scroll, `?` the guide, `q` quits. Overlays (`t`, `i`, `?`, a graph answer) wrap to the terminal and scroll with the same keys; any other key closes them. `--once` prints one frame (and is what happens when stdout is not a terminal), `--json` one snapshot (`bravos.watch/v1`). `NO_COLOR` or `BRAVOS_WATCH_COLOR=off` prints it plain.
+
+## Getting started: `bravos next`
+
+`bravos next` (free, in a shell) is the setup score for a repo, in the order the steps 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, fine to switch on early). It shows what each unlocks and the exact command for the next one; bravos assumes a licensed bravos-cli. The same line is in the banner (`Next: … → …`, and `setup n/9` on the status line) and in the briefing every harness hands the agent, together with a few coaching rules: offer a few starts once in the first reply, suggest the next bravos step at natural moments (annotate after security edits, the ship check before a PR, a recheck after a fix), plain words first, never nag. Ask "help me get started" for a guided tour. `BRAVOS_COACH=off` keeps only the Setup line.
+
+## The guide
+
+`bravos guide` prints how to use bravos by role (developer, security engineer, team lead, new to the repo, CI owner), by task, skill by skill, how to read a finding, the hard safety rules and what each harness gets. It runs no model. `bravos guide <topic>` prints one topic (`start`, `roles`, `tasks`, `skills`, `states`, `safety`, `harnesses`, `all`); `--harness codex|omp` shows skills in that harness's syntax. The same text is in [docs/GUIDE.md](docs/GUIDE.md).
+
+## Session start: a briefing for the model, a banner for you
+
+The session-start hook prints one JSON object. Its `additionalContext` is the briefing: open exposures by severity, coverage, confirmed findings, what to test next, stale claims, tickets, work in flight and the intent state, sent to the model on every start, resume, clear and compact. On a fresh start only (`source: startup`, or a manual run), its `systemMessage` carries a banner for the human, which the model does not see: the bravos logo, repo and branch, the counts, the top three threats (or the confirmed findings to fix now) beside a three-step quick start chosen from the repo's state, and a short introduction to bravos while `.guardlink/intent.md` is missing. It is plain text within 80 columns. The registered command carries `--harness claude` or `--harness codex` so the quick start prints `/bravos-…` or `$bravos-…`; `bravos sync` replaces the older entry without the flag, and Codex asks you to trust the changed hook once in `/hooks`. Set `BRAVOS_BANNER=off` to hide the banner; the briefing is unchanged. The banner is drawn in bravos's brand colours; `NO_COLOR` or `BRAVOS_BANNER_COLOR=off` prints it plain. Codex lists a hook's message as a warning (behind F2), so Codex gets a two-line summary instead of the art. opencode finds the skills through its skill tool but lists only its own `/commands` and runs no hooks, so when opencode is in use (`.opencode/`, `opencode.json`, or `opencode` on PATH) bravos also writes one `.opencode/commands/<skill>.md` per skill (so `/bravos`, `/bravos-ship` and the rest appear), `.opencode/plugins/bravos.js` (an opencode 2.x plugin that adds the briefing to the system prompt of each request), and guardlink under `mcp` in `opencode.json`. Antigravity (`agy`) reads `.agents/hooks.json`; bravos adds a `bravos` SessionStart group there that hands the briefing to the model, since Antigravity documents no way for a hook to show text to you.
+
+omp runs neither Claude Code's nor Codex's hooks, so when omp is in use (a `.omp/` folder, or `omp` on PATH) `bravos init` and `sync` also write `.omp/extensions/bravos.js`, which omp loads by itself: it shows the same banner above the editor at session start and hands the briefing to the model, hidden, with the first prompt. In none of these harnesses do you need to type a command for the briefing; `/bravos` is for deciding the next step. Anywhere else, the bravos skill runs `node .bravos/hooks/session-start.mjs --briefing`, which prints the briefing as plain text.
+
+## The pre-PR gate
+
+With `--pre-pr-hook`, every `gh pr create` and `gh pr ready` an agent runs first passes the bravos-ship gate: `guardlink validate`, `guardlink lint --since <merge-base>` with no errors, every new unmitigated exposure from `guardlink diff <merge-base> --json` disclosed in the PR body by both its threat and asset id (on `gh pr ready` the body is read with `gh pr view`), and no `@confirmed` claim from `guardlink ci -f json` on a changed file unless that file carries a `@ticket` for it. An exposure paired with `@audit` stays listed by design and is reported, not blocked forever. A gate input that fails or does not parse blocks as "unknown", including `gh pr view` on `gh pr ready`; the gate allows, and says why, in exactly two cases: guardlink is not on PATH, or no merge base with the default branch is found. It runs from the repository's top level whatever directory the agent is in. Before a PR exists, run `node .bravos/hooks/pre-pr.mjs --check` (the line `--pre-pr-hook` lists under `pre_pr` for guardlink's agent block): it blocks on lint errors and confirmed claims on changed files, and prints the new exposures the PR body must disclose. The whole gate shares a 150 s deadline inside the hook's 180 s timeout. Set `BRAVOS_PRE_PR=off` in your own environment to disable it.
+
+## Workflows (`bravos init --ci`)
+
+- `bravos-pr-gate.yml`: the bravos-ship gate on every pull request, with the same rulings as the pre-PR hook (lint errors, undisclosed new exposure by id, a confirmed claim on a changed file without a `@ticket`; a gate input that fails is "unknown" and fails the job). guardlink and jq only, no model, no secret. Uploads guardlink's SARIF to code scanning (skipped for fork PRs).
+- `bravos-nightly-claude.yml` / `bravos-nightly-codex.yml`: a coding agent covers the next slice of unannotated files, the lint gate checks it, and the job opens one small PR. Keep the one for your harness. They annotate only: live testing needs a human's authorization typed in a session, which a scheduled job cannot give.
+
+## Install as a plugin (after 1.0)
+
+The repo also renders a plugin for each harness from the same `skills/` and `hooks/`: `plugin/` for Claude Code (served by `.claude-plugin/marketplace.json`) and `plugin-codex/` for Codex (`.agents/plugins/marketplace.json`). Regenerate both with `npm run build:plugin`; a test fails when either drifts from the source. A plugin marketplace is served from a repository customers can read, and this one is private, so the marketplace route (a small public repo holding only the built plugins, then `claude plugin marketplace add …` / `claude plugin install bravos@bravos`) comes after 1.0; until then `bravos init` is the way in for every harness.
+
+Each plugin carries the skills, the session-start briefing (from the plugin's own copy of the hook) and the guardlink MCP entry. cxg and the code-graph server are left out because they fail to start on machines without them; `bravos init` adds them per repo when they are installed. The Codex build renders skill paths repo-relative (`.agents/skills/<name>`), so the scripts a skill runs (for example bravos-annotate's slice picker) resolve once `bravos init --agent codex` has written `.agents/skills/` into the repo. The pre-PR gate and the workflows come from `bravos init` for both harnesses. Use the plugin or `bravos init`'s session-start hook, not both, or the briefing prints twice.
+
+## How bravos works with the model
+
+Claude Code and Codex are already strong; bravos is an add-on, never a cap. Every budget in a skill
+(files per slice, templates per run, rounds per campaign) is a default the agent may exceed when the
+work needs it, saying why in one line. Only the safety rules are hard: no request to a non-loopback
+host without a committed, reviewed `scope.yaml` and your typed authorization; destructive probe
+classes only on a disposable loopback target; never `@accepts`, `@entitles` or a hand-written
+`@confirmed`; never launch an external agent CLI; never invent credentials; never call anything clean
+unless a gate exited 0.
+
+**Effort** (`low | medium | high | max`) is one dial every skill reads: from your request ("annotate at
+high"), else a `bravos effort: <level>` line in `AGENTS.md` / `CLAUDE.md`, else medium. Run
+`bravos --help` for what each level means per skill.
+
+**bravos-campaign** reaches a goal over many rounds — `/bravos-campaign coverage 100% at max, rest 10m`
+in Claude Code, `$bravos-campaign test every open exposure` in Codex — with disjoint batches, one
+subagent per batch, a gate per batch, a rest between rounds, and a stop when the goal is met.
+
+## Intent-aware annotation
+
+Code patterns alone over-rate features and miss business-logic flaws. `bravos-context` reads the
+repo, drafts answers, and asks you a short interview: what the product is for, who the roles are,
+what data and actions matter most, what must never happen, and what looks dangerous but is
+intended. Answers go into `.guardlink/intent.md` (each item `— confirmed by <name>` or `— draft`)
+and into the threat model as actors, assets, boundaries and one `#inv-…` threat per invariant.
+bravos-annotate then adds a logic pass over user journeys, rates each exposure by impact × reach
+× ease with the reason in the description, and writes an "intended?" `@audit` for you to answer
+rather than claiming a by-design feature as a critical flaw.
+
+## Licence
+
+Bravos is proprietary software of BugB Technologies, free to use on the Free plan and licensed per developer for Team features. See [LICENSE](LICENSE) for the terms, including what you may not do (copy, modify, redistribute, or bypass a licence check). Third-party components it installs keep their own licences.

package/dist/account.js

@@ -0,0 +1,140 @@
+// @comment -- "bravos account: how a licence gets onto this machine. `activate` is the device-code pairing with the account portal (one POST to start, the browser to approve, polling until the portal hands back a signed token); `import` takes a downloaded file. Either way the token is verified by the same offline verifier before it is written, so a token the portal signed with a key this build does not trust is refused here, not at the first gated command. The origin is fixed (BRAVOS_ACCOUNT_ORIGIN overrides it for a local portal), no proxy is read from the environment, and the token is written 0600."
+import { spawn } from 'node:child_process';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { licenceLib, licenceLines } from './licence.js';
+import { BravosError } from './types.js';
+export const ACTIVATION_PATH = '/api/v1/cli/activation';
+export const POLL_PATH = '/api/v1/cli/activation/poll';
+const DEFAULT_INTERVAL = 5;
+const MAX_WAIT_SECONDS = 15 * 60;
+export const accountOrigin = (env, L) => {
+    const raw = (env.BRAVOS_ACCOUNT_ORIGIN || '').trim();
+    if (!raw)
+        return L.ACCOUNT_ORIGIN;
+    if (!/^https?:\/\/[^/\s]+$/.test(raw))
+        throw new BravosError(`BRAVOS_ACCOUNT_ORIGIN must be an origin like https://account.bugb.io, got ${JSON.stringify(raw)}`);
+    return raw;
+};
+const defaultOpen = (url) => {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+    try {
+        spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    }
+    catch {
+        /* the URL is printed anyway */
+    }
+};
+const licenceFile = (env, L) => {
+    const home = L.bravosHome(env);
+    if (!home)
+        throw new BravosError('no home directory: set BRAVOS_HOME to where the licence should be kept');
+    return join(home, L.LICENCE_FILES[0]);
+};
+// @comment -- "Verifies a token with the trusted set and writes it to $BRAVOS_HOME/licence.jwt (0600, folder 0700); a token that does not verify is refused with the verifier's reason and nothing is written."
+export async function installToken(token, env, where) {
+    const L = await licenceLib();
+    const v = L.verify(token.trim());
+    if (v.state === 'invalid')
+        throw new BravosError(`the licence from ${where} is not accepted (${v.reason}): ${v.message}`);
+    const file = licenceFile(env, L);
+    mkdirSync(join(file, '..'), { recursive: true, mode: 0o700 });
+    writeFileSync(file, token.trim() + '\n', { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* best effort on platforms without modes */
+    }
+    return { file, status: L.status(env) };
+}
+export async function importLicence(path, io) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        throw new BravosError(`${path} could not be read`);
+    }
+    const { file, status } = await installToken(text, io.env, path);
+    const L = await licenceLib();
+    return [`Licence written to ${file}`, ...licenceLines(L, status)];
+}
+// @comment -- "The device-code flow: POST /api/v1/cli/activation, show the code and open the verification URL, then poll /api/v1/cli/activation/poll with the device code as a bearer until the portal answers 200 {license} (428 pending, 429 slow down, 410 expired or consumed). The device code never goes anywhere but that origin, and the token it yields is verified before it is written."
+export async function activate(io) {
+    const L = await licenceLib();
+    const origin = accountOrigin(io.env, L);
+    const f = io.fetch ?? fetch;
+    const sleep = io.sleep ?? ((s) => new Promise((r) => setTimeout(r, s * 1000)));
+    const now = io.now ?? (() => Date.now() / 1000);
+    const open = io.open ?? defaultOpen;
+    const ua = { 'User-Agent': 'bravos-cli', Accept: 'application/json' };
+    let start;
+    try {
+        const r = await f(`${origin}${ACTIVATION_PATH}`, { method: 'POST', headers: { ...ua, 'Content-Type': 'application/json' }, body: '{}' });
+        if (r.status === 404 || r.status === 405)
+            throw new BravosError(`${origin} does not offer CLI sign-in yet; download the licence from ${L.ACCOUNT_LICENCES} and run bravos account import <file>`);
+        if (!r.ok)
+            throw new BravosError(`${origin} refused to start an activation (HTTP ${r.status})${r.status === 429 ? ': too many attempts from here, try again later' : ''}`);
+        start = (await r.json());
+    }
+    catch (e) {
+        if (e instanceof BravosError)
+            throw e;
+        throw new BravosError(`could not reach ${origin}: ${e.message}. Download the licence from ${L.ACCOUNT_LICENCES} instead and run bravos account import <file>`);
+    }
+    if (!start || typeof start.device_code !== 'string' || typeof start.user_code !== 'string' || typeof start.verification_url !== 'string') {
+        throw new BravosError(`${origin} answered without a device code; download the licence from ${L.ACCOUNT_LICENCES} and run bravos account import <file>`);
+    }
+    if (!start.verification_url.startsWith(origin + '/'))
+        throw new BravosError(`${origin} pointed the browser somewhere else (${start.verification_url}); refusing`);
+    const interval = Math.max(1, Number(start.interval) || DEFAULT_INTERVAL);
+    const deadline = now() + Math.min(MAX_WAIT_SECONDS, Number(start.expires_in) || MAX_WAIT_SECONDS);
+    io.stdout(`Sign in to ${origin} and enter this code: ${start.user_code}`);
+    io.stdout(`Opening ${start.verification_url} (or open it yourself). Waiting for approval…`);
+    open(start.verification_url);
+    let wait = interval;
+    for (;;) {
+        if (now() >= deadline)
+            throw new BravosError('the activation code expired before it was approved; run bravos account activate again');
+        await sleep(wait);
+        let r;
+        try {
+            r = await f(`${origin}${POLL_PATH}`, { headers: { ...ua, Authorization: `Bearer ${start.device_code}` } });
+        }
+        catch (e) {
+            throw new BravosError(`lost ${origin} while waiting: ${e.message}; run bravos account activate again`);
+        }
+        if (r.status === 428)
+            continue;
+        if (r.status === 429) {
+            wait = Math.min(wait * 2, 60);
+            continue;
+        }
+        if (r.status === 410)
+            throw new BravosError('the activation code expired or was already used; run bravos account activate again');
+        // A portal that only speaks the Python CLI's pairing answers the GET poll with 405.
+        if (r.status === 404 || r.status === 405)
+            throw new BravosError(`${origin} does not offer CLI sign-in for this version yet; download the licence from ${L.ACCOUNT_LICENCES} and run bravos account import <file>`);
+        // The portal answers 402 when the account has no plan and its one trial is used up: nothing is written, Free keeps working.
+        if (r.status === 402) {
+            let upgrade = L.ACCOUNT_UPGRADE;
+            try {
+                const b = (await r.json());
+                if (typeof b?.upgrade === 'string' && b.upgrade.startsWith(origin + '/'))
+                    upgrade = b.upgrade;
+            }
+            catch {
+                /* the default page */
+            }
+            throw new BravosError(`this account's Team trial has ended and it has no plan, so no licence was written; this machine stays on Free (the research loop keeps working). Choose a plan at ${upgrade}, then run bravos account activate again`);
+        }
+        if (!r.ok)
+            throw new BravosError(`${origin} answered HTTP ${r.status} while waiting; run bravos account activate again`);
+        const body = (await r.json());
+        if (typeof body?.license !== 'string')
+            throw new BravosError(`${origin} approved the code but sent no licence; download it from ${L.ACCOUNT_LICENCES} and run bravos account import <file>`);
+        const { file, status } = await installToken(body.license, io.env, origin);
+        return [`Licence written to ${file}`, ...licenceLines(L, status)];
+    }
+}