174300c211
The golden-path doc's Step 4 gave the reader a copy-pasteable publish sequence
with no `set -e`, and its verification step was a COMMENT — "# 3. VERIFY every
manifest bundle's <name>/<name>.js resolves BEFORE push". A comment does not
verify anything. Pasted as written, the block clones, rsyncs with --delete, does
nothing, and pushes.
That is both halves of an incident this project already paid for, recorded as
AP-publish-verify-not-gating-plus-midchurn-rsync in the deploy-cycle notes: the
verify was chained into a compound command so a failing check still fell through
to the push, and rsync --delete ran from a source a concurrent build had just
emptied, faithfully mirroring that emptiness into the catalog. The live maps
catalog went to 404.
Step 3 is now three real commands — check:sri, check:embed-targets, and a git
diff that aborts if anything outside app/doxa-maps changed — and `set -e` is the
first line so any of them aborts before the push. Added `bun run check:settled`
as step 0, because `clean` empties public/doxa-maps at the START of every build,
which is what makes --delete catastrophic rather than merely wrong: it deletes
the live tree to match your momentarily-empty one.
The doc was already right to stay narrow ("the fuller runbook with every gotcha
lives in the project's deploy-cycle notes"), and it already carried postBuffer
with a good explanation. `set -e` is not a gotcha to defer — it is what makes
the four-step block safe at all, so it belongs with the block it protects.
Verified rather than assumed: all three commands exist in package.json, the
block extracted on its own passes `bash -n`, and the exclude-pathspec abort was
run against a real diff — it correctly passes when the diff is scoped and would
fire otherwise. Five gates pass.
Also corrected the runbook's own first instruction while checking it, in the
_qa-cycle notes (not a tracked file). It read "EXIT 0 + all 6 DX guards PASS".
No subset called "DX guards" exists anywhere in the repo, and the count was
wrong besides — build:unlocked chains 32 steps including 25 distinct check:*
gates, and that set grew by five in one flight. A hardcoded gate count is a
snapshot of a moving target. The chain is &&-joined under set -e, so EXIT 0
already means every step passed; that is the assertion that stays true as gates
are added, and the note now says so and gives a one-liner to list the current
set rather than copying it.
|
||
|---|---|---|
| .. | ||
| architecture | ||
| assets | ||
| contributing | ||
| readme-images | ||
| screenshots | ||
| CONTRIBUTING.md | ||
| develop-a-plugin-and-see-it-live.md | ||
| explanation.md | ||
| how-to.md | ||
| README-embed-example.md | ||
| README-longform.md | ||
| README-SECTION-3-cli-commands.md | ||
| README.md | ||
| reference-capability-exemplars.md | ||
| reference-library-index.md | ||
| reference.md | ||
| slide-deck-outline.md | ||
| tutorial.md | ||
| why.md | ||
documentation/ — pick your path
"what is this?" "teach me" "how do I …?" "look it up" "all the detail"
│ │ │ │ │
why.md ──────────► tutorial.md ────► how-to.md ────► reference.md ───► architecture/
(2 min, 1 diagram) (first map) (task recipes) (tables) (contracts)
- why.md — the problem and the "map islands" idea. Start here.
- tutorial.md — build your first map, no jargon.
- how-to.md — recipes: embed, iframe, SPA, colors, CDN, mobile, tokens.
- reference.md — config fields, build scripts, the
profile-configcontract. - explanation.md — the model in 15 lines.
- architecture/ — the deep end: full contracts, the per-file catalog.
- README-embed-example.md — the drop-in README used when this bundler is embedded inside a host repo.
Nothing on the simple path is longer than a few minutes; everything complex lives in
architecture/, linked from where you'd need it.