diff --git a/docs/reference.md b/docs/reference.md index 3cf315aa3..7e459e1cb 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -208,6 +208,24 @@ standalone page per instance at `//index.html`. Recipe: **Bun is required.** `bun.lock` is the committed lockfile; `bun x vite` runs project-local Vite. `npm run …` resolves the same scripts but Bun must be on PATH. +### Standalone gates — the SILENT failure classes + +These are **not** in `build:unlocked`, deliberately: each checks something a fresh build would mask, +so running it inside the build would make it unfalsifiable. Run them before publishing. + +| Script | Catches | Why it cannot live in the build | +|---|---|---| +| `bun run check:composite` | a composite (cap-4/cap-5) still shipping an OLD copy of a child it nests — a one-bundle rebuild does NOT recompile its parents | a full build makes every composite fresh *by construction*, so it could never fail there | +| `bun run check:shots` | a README screenshot that predates the bundle it shows — **a stale screenshot looks exactly like a current one** | needs a browser to repair (`bun run shots`), which CI does not have | +| `bun run check:library-index` | `docs/reference-library-index.md` fallen behind `library/` — its header promises it "can't drift", which is only true if regenerated (`bun run library-index`) | a fresh checkout gives every file the same mtime, so mtime comparison always passes in CI (CI regenerates + diffs instead) | +| `bun run check:done-evidence` | a backlog card marked `done` with no bluf **and** no fields — a status word the next team cannot reconcile against the code | reads `_qa-cycle/`, which is not in any repo CI clones | +| `bun run verify:gate1` | the Gate-1 chain end-to-end against LIVE data: header filter → composite props → real grid re-filter → count back up | needs network; it is an acceptance test, not a build step | + +`bun run verify:5-caps` proves all five capability tiers mount and render. It needs a token — +`MAPBOX_TOKEN=$(curl -s ) bun run verify:5-caps` — and it sets **both** `?tk=` +(the top-level element) **and** `window.MAP_TOKEN` (a composite's nested children read the global, +not the query param). Without a token it reports the token outage rather than the capabilities. + --- ## `vite.doxa-maps-build-config.json` fields