Shared memory

Findings and the Dossier keep what you learned where the Builder and the next operator will find it.

Two things outlive a session on a Build. The Findings say what needs attention. The Dossier says how this Build works and what never to touch. Both live on the server, under the identity that wrote them.

Findings: the Build's to-do list

bworlds findings list storefront

ID                                    STATUS      SEVERITY  AREA        TITLE
5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b  open        high      operations  Checkout fails silently when /api/leads returns 500
2a41f0e9-7d6c-4b5a-9e8f-3c2d1b0a9f8e  needs_user  medium    security    Rate limiting: confirm the Cloudflare rule covers /api/*
c09b8a7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d  resolved    high      security    Database is open to the public

Move a Finding as work happens. The reason you give becomes part of its history in the app:

bworlds findings update-status storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b in_progress \
  --reason "Fix in review on branch fix/checkout-errors" \
  --confirm

bworlds findings update-status storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b resolved \
  --reason "Shipped in 2f8a1c0, verified in production" \
  --confirm

Use needs_user when only the Builder can move it forward, and say what you need from them:

bworlds findings update-status storefront 2a41f0e9-7d6c-4b5a-9e8f-3c2d1b0a9f8e needs_user \
  --decision-summary "Confirm whether the Cloudflare rate-limit rule also covers /api/webhooks" \
  --confirm

Statuses are open, needs_user, in_progress, resolved, and dismissed. Their meaning is in the Product model. Creating a Finding is covered in Production evidence.

Edit content and inspect attributed activity through the same Build-scoped surface:

bworlds findings edit storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b \
  --severity medium \
  --confirm
bworlds findings history storefront 5e7d1c2b-8a9f-4e3d-b6c5-2f1a0e9d8c7b

Both commands resolve the Finding inside the named Build. A direct Finding ID never grants access outside the Build's Workspace.

Dossier: context and guardrails

bworlds dossier pull storefront

Workspace: /Users/lea/.local/share/bworlds/prod/storefront
Pulled context (4812 bytes, updated 2026-09-02T16:40:11Z by maxime)
Pulled guardrails (1290 bytes, updated 2026-09-02T16:40:11Z by maxime)

Read context.md and guardrails.md before changing anything, and have your agent read them too. When nobody has written a Dossier yet, the pull succeeds with a notice. That is the normal state of a fresh Build.

Edit the files, then publish:

bworlds dossier push storefront --confirm

Pushed context (5104 bytes)
Pushed guardrails (1290 bytes)

What keeps the Dossier trustworthy:

Pull at the start of a session, push right after you edit. The server is the source of truth and the last push wins. Attribution shows who overwrote what.
The workspace is outside every clone. Nothing from the Dossier goes into the Builder's repository.
context.md holds how the app works and what matters to its Builder. guardrails.md holds what never to touch and what to check before shipping.

Findings: the Build's to-do list

Dossier: context and guardrails

On this page