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 build list and in the app's URL.
Workspace and Membership
A Workspace owns Builds and the credit 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 recorded result is one of pass, fail, error, not-applicable, not-observed, pending, or dismissed. The status the Builder sees, effectiveStatus in the JSON, also follows the Control's Finding. It can differ from result.status in two more ways. An error caused by the Builder's app or its URL reads as not-observed. A review that reached no verdict reads as inconclusive. In both cases result.status stays error. The app sorts every Control into one bucket a Builder reads at a glance:
| Bucket | Statuses | Meaning |
|---|---|---|
| Covered | pass, not-applicable | evidence passed, or the Control does not apply here |
| Attention | fail | evidence failed |
| Technical error | error | BWorlds failed to run the check; retry later |
| Couldn't confirm | not-observed, inconclusive | no verdict, or the app or its URL stopped the check |
| Dismissed | dismissed | the Builder set the Control aside |
| Pending | pending, waiting-for-builder, in-progress, no result | still running, waiting for the Builder, or being fixed |
A Couldn't confirm Control stopped by the app or its URL keeps its cause, App unreachable, Invalid URL, or Private URL, and the app tells the Builder how to fix it. The coverage score leaves out technical errors, Controls BWorlds couldn't confirm, and dismissed Controls. They stay visible. In the portfolio JSON of audit list --json, controlSummary counts technical errors and unconfirmed Controls inside pendingCount. findingSummary counts them apart as technicalProblemControlCount and unconfirmedControlCount.
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 and thematic Audit exploration create Findings. A passing Control rerun resolves its Finding. An exploratory Finding needs targeted verification of its recorded claim; absence from a later Audit run does not resolve it. Operators and agents create Findings for anything they discover outside an Audit. Each Finding has a severity (critical, high, medium, low), 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 detection says how a Finding was found:
| Detection | How it was found |
|---|---|
audit | a failed Control or thematic Audit exploration |
manual | a person or agent typed it, with findings create |
telemetry | BWorlds' own analysis of production errors and sessions |
For an Audit Finding, auditOrigin.kind is control or exploration. findings verify selects the recorded evidence from that origin. Exploration verification updates the Finding without creating or changing a Control result. Systematic coverage counts Controls only.
findings list returns every detection. The Builder's Findings screen, Overview, and sidebar count show audit and manual Findings. They show telemetry Findings only when BWorlds enables them. A Finding's own page opens from its link whatever its detection, so an open link does not prove that the Builder's list shows it. findings edit changes a Finding's content, never its detection.
Production signals
Once the Builder installs the BWorlds SDK in the app (Install the SDK), 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, BWorlds reads that repository to run its code Controls and to recheck a Finding after a fix. You change the code in your own checkout, with your own Git: see Fix in your own checkout.