Document the preconditions three gates need, so a bare run is not read as failure

Running the gate list I completed last tick, two entries reported FAIL:
smoke:gallery and smoke:share. Neither is a defect. smoke:gallery needs a
dev server on :5174 and says so; smoke:share needs --url arguments and prints
usage. Both exit non-zero, so in a batch run they read exactly like the real
failures the list exists to surface.

A checklist that turns a precondition into a red line trains its reader to
ignore red lines, which is how a real failure gets skipped. Added a
preconditions table stating what each needs and what a bare run actually
does, measured by running them.

Also recorded that the token-dependent gates DEGRADE rather than fail:
without MAPBOX_TOKEN, smoke:embeds reports map profiles as timeouts -- it
once read 27/40 for that reason and 40/40 with a token. A timeout there means
"no token" far more often than "broken plugin".

Two claims corrected before shipping. I wrote that the token endpoint needs a
browser User-Agent; measured, a plain curl gets 200 identically -- that
requirement belongs to pray.doxa.life, a different host. And I tested rather
than asserted the limitation now in the doc: verify:map-paint PASSES on a
leaf whose tiles 403, because a live GL context, a sized canvas and
attribution are all true while the basemap stays empty. The gate is correctly
scoped; the name invites over-reading, so the scope is now written down.

documentation/reference.md

@@ -236,6 +236,35 @@ so running it inside the build would make it unfalsifiable. Run them before publ
 | `bun run check:capability-exemplars` | `documentation/reference-capability-exemplars.md` drifting from the manifest's real tiers (regenerate with `bun run capability-exemplars`) | the table is generated *from* the manifest, so running it mid-build would compare a file against the thing that just wrote it |
 | `bun run check:settled` | measuring or publishing a tree **mid-build** — a build's `clean` step `rm -rf`s `public/doxa-maps`, so samples taken seconds apart give opposite answers | it exists to be run *around* builds, not inside one |
 
+### Before you run the list — three gates need a PRECONDITION, or they look broken
+
+A bare `bun run <gate>` is not always meaningful, and the failure text does not always say so.
+Measured 2026-09-22, by running each one:
+
+| Gate | Needs | What a bare run does |
+|---|---|---|
+| `smoke:gallery` (and `smoke:playground`, its alias) | a dev server: `bun x vite` on **:5174** | exits non-zero with *"cannot read http://localhost:5174/__plugin-gallery/registry.json — is `bun x vite` running?"* — a **precondition**, not a defect |
+| `smoke:share` | `--url <page>` arguments **and** the dev server | prints `usage:` and exits non-zero |
+| `smoke:embeds` · `verify:map-paint` · `verify:5-caps` | `MAPBOX_TOKEN` in the environment | **does not fail — it DEGRADES.** Without a token map profiles cannot mount, and `smoke:embeds` reports them as TIMEOUTS. It once read 27/40 for this reason and 40/40 with a token. A timeout here means "no token" far more often than "broken plugin" |
+
+```sh
+# the token every map gate wants. Verified 2026-09-22: returns 200 to a plain curl (no browser
+# User-Agent needed — that requirement belongs to pray.doxa.life, a different host) and yields a
+# 90-char pk. token.
+export MAPBOX_TOKEN=$(curl -s https://doxa.life/api/maps/token | python3 -c 'import json,sys;print(json.load(sys.stdin)["token"])')
+```
+
+> **The token is URL-restricted, and that limits what these gates can prove here.** Measured: tiles
+> return **200** with a `doxa.life` Referer and **403** from `127.0.0.1`, `localhost`, `nuxtbase.app`
+> or no Referer. So on this box a map can *mount*, load its style and paint its data layer while the
+> basemap stays empty — `verify:map-paint` still passes, because a live GL context and attribution
+> are exactly what it asserts. Judging "does it LOOK right" needs an allow-listed origin.
+
+> **★ AN EXIT CODE IS NOT A VERDICT UNTIL YOU HAVE READ THE MESSAGE.** Two of these read as FAIL in a
+> batch run and are neither passing nor failing — they never started. A checklist that turns a
+> precondition into a red line trains its reader to ignore red lines, which is how a real failure
+> gets skipped.
+
 The rest, grouped by what they guard — same rule (outside the build, run before publishing):
 
 | Script | Catches |