Docs · Workflow

Workflow

How a change goes from a branch to the Worker and the sidecar, and which check proves which claim. The rules behind each check are in AGENTS.project.md.

One roof

Docs are claims about the repo, and each claim has one check. Every markdown check reads the doc through scripts/md.ts, one Bun.markdown pass that returns headings, links, images and tables, so a doc parses the same way whichever check reads it.

The same pass draws /docs. scripts/docs-plugin.mjs runs Bun.markdown.react on each doc in PUBLIC_DOCS when the app is built, because the Worker has no Bun, and src/components/docs/doc-view.tsx renders the tree with the token classes every screen uses. A doc is published only when it is on that list. The app has no sign-in, so docs that name hosts, accounts or secrets stay off it. A link to a doc that is not published shows as plain text. public/llms.txt and public/docs/manifest.json are committed snapshots of that list, with each doc's outline and a SHA-256 of its source, so editing a published doc means running bun run cli contract --write and committing the result. The pre-commit hook runs cli contract --staged, which reads the staged copy of every file, and the gate runs cli contract.

bun run gate runs all of them and refuses a regression against gate.baseline.json. Nothing deploys from a commit the gate has not passed.

A change, start to finish

1. Branch from an up-to-date main. One change per branch: a fix, a feature, or one dependency upgrade.
2. While editing, run the fast checks. bun run cli design, bun run cli proof and bun run cli contract finish in well under a second.
3. A UI change that shows on a documented screen gets a new capture of that screen. docs/dashboard.md lists them, one row for every route in docs/goal.md and every data screen. Capture with bun run cli shot capture <url> --out screenshots/<name>.png --width <w> --height <h>, then run bun run cli proof --write so the table matches the file.
4. A new color, size or radius is a row in docs/design.md and a line in each theme block of src/styles.css. Components use the token, never a hex value. A page name, nav label, hotkey, URL value, heading, subtitle, table label, storage key, theme or flag changes in docs/site.md, by hand or with bun run cli site set / flag, never in a component.
5. Run bun run gate before pushing. The pre-commit hook runs the guard. Pre-push runs gate --reuse, except under the Cursor hook dispatcher, which does not forward pre-push.
6. Open the pull request with what changed, how it was checked, and the gate line it printed. Merge into main.
7. Ship the Worker and the sidecar from the same main commit: bun run deploy:cf, then bun run deploy:sidecar. Both run gate --reuse first.

Order of work

Land open pull requests before starting a cross-cutting branch. A branch that touches every screen, like a token or layout pass, conflicts with every branch still open, and the gate baseline moves under each of them.

After that, unify one surface per branch, smallest first, each with its own capture and gate run:

1. Tokens. Every color, size and radius comes from docs/design.md, proven by cli design.
2. Shared parts. Every page shares Brand and NavLinks. A new shared part is one branch, with a capture.
3. One wall. Fold the F402 tape into the command center, as docs/standing.md lists under Next.