Product model
Build, Workspace, Audit, Control, Finding, Dossier, and the production signals around them. The words the CLI speaks.
The CLI uses the vocabulary of the app. A handful of words cover almost everything.
Build
A Build is one app a Builder ships: a live URL, optionally a connected GitHub repository, and everything BWorlds has observed about it. Every command that touches a Build takes its slug, the short name shown by bworlds repo list and in the app's URL.
Workspace and Membership
A Workspace owns Builds and the token balance that pays for Audits. Every Builder has a personal Workspace. Its Owner can invite other Builders as Members from Workspace sharing in the app. A Membership is the whole grant: a Member operates every Build of that Workspace, from the app and from the CLI, until the Owner removes them.
This documentation calls a Builder acting on a Build through the CLI an operator, whether they type the command or delegate it to a coding agent. Operator is not a separate role. Active Owner and Member Memberships carry the same operational rights across that Workspace's Builds; a personal token carries its creator's current rights.
Audit, Control, Control result
An Audit collects evidence about a Build. The CLI can run any available Audit. Omitting the Audit slug selects First Look, which probes the live app and asks the Builder three questions about how it is run. Its 17 Controls are organized in areas:
| Area | Area ID | What First Look covers |
|---|---|---|
| Security | security | exposed secrets, public database, HTTPS, browser protections, public debugging files, open sign-up, private pages |
| Operations | operations | first-load speed, error handling, error alerts, uptime alerts, backups, version control |
| Legal and compliance | legal-compliance | privacy policy, trackers before consent, code ownership |
| Code quality | code-quality | known flaws in the libraries the page loads |
Four repository Audits read the connected GitHub repository and require one: Security checks exposed credentials, sign-in protection, and unsafe input paths. Costs checks limits on expensive requests and asks about AI, hosting, and per-user spending caps. Shipping checks whether the code is organized so changes remain safe to make. Rights & Licenses checks direct software licences and the path to request account deletion. Their CLI slugs are listed in Audits and Controls.
Each check or question is a Control with a stable ID such as app-open-access. Its result is one of pass, fail, error, not-applicable, pending, or dismissed. The app folds those into three buckets a Builder reads at a glance:
| Bucket | Control results | Meaning |
|---|---|---|
| Covered | pass, not-applicable | evidence passed, or the Control does not apply here |
| Attention | fail, error | evidence failed, or could not be gathered |
| Pending | pending, no result yet | still running, or waiting for the Builder's answer |
A Builder can also dismiss a Control from the app. It stays visible and leaves the coverage score.
A failed Control carries three things the CLI prints and the JSON exposes: what BWorlds found (whatWeFound), why it matters (whyItMatters), and how to fix it (howToFix), plus the raw signals behind the verdict. These are written for the Builder's coding tool as much as for the Builder.
An Audit run is one execution. The server owns it: closing your terminal never cancels a run, and audit status reads it back by ID.
An override is your correction of a verdict, with a written reason, recorded under your identity. Use it when you verified something the probe could not see. It applies to what the Builder sees and persists across runs until cleared.
Finding
A Finding is one item on the Build's to-do list: what needs attention, why it matters, how to fix it, and where it stands. Failed Controls create Findings on their own, and a passing rerun resolves them. Operators and agents create Findings for anything they discover outside an Audit. Each Finding has a severity (critical, high, medium), an area, a service line, and a lifecycle status:
| Status | Meaning |
|---|---|
open | needs attention |
needs_user | waiting for the Builder: an answer, an approval, a publication |
in_progress | someone is working on it |
resolved | no longer needs action |
dismissed | deliberately set aside, with a reason |
The service line says which part of the job a Finding belongs to: launch for getting ready for production, run for keeping it running, improve for making it better. Audit Findings are launch. What you find in production telemetry is usually run.
The origin says who raised a Finding:
| Origin | Raised by |
|---|---|
audit | a failed Control |
operator | an operator or agent, with findings create |
telemetry | BWorlds itself, from production errors and sessions |
findings list returns every origin. The Builder's Findings screen, Overview, and sidebar count show audit and operator Findings. They show telemetry Findings only when BWorlds enables them. A Finding's own page opens from its link whatever its origin, so an open link does not prove that the Builder's list shows it. findings edit changes a Finding's content, never its origin.
Production signals
Once the Builder installs the BWorlds SDK in the app, three kinds of evidence accumulate and are readable from the CLI:
- Errors: client-side errors grouped by message, with counts and last-seen time, plus whether the SDK is still reporting.
- Sessions: what a visitor did, page by page, with errors, console output, and rage clicks (repeated clicks on the same element, the signature of friction with no exception).
- Uptime: current status, daily uptime and response time, recent incidents.
They match the Errors, Sessions, and Uptime screens of the Build in the app.
Dossier
The Dossier is the Build's shared operator memory: two documents, context.md (how this app works and what matters to its Builder) and guardrails.md (what never to touch, what to check before shipping). It lives on the server, so every operator and agent starts from the same baseline. The CLI syncs it into a local operator workspace, always outside the cloned repository, so nothing of it ends up in the Builder's code.
Repository
When the Builder connected GitHub, the CLI can clone, refresh, and push the repository with a short-lived credential scoped to that one repository. It can also bring up a local Supabase instance seeded with the Build's shared fixture, so you reproduce a production problem on realistic data. See Fix in the repository.