doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Point the golden-path doc at the self-test of the golden path

Browse source 
golden-path-check is the capability-1 element that IS the
develop-a-plugin-and-see-it-live walk: authored from the documented 3-file
minimum, built, published, and then reading the manifest it shipped beside. It
was named in two reference docs and NOT in the golden-path document itself, so
the one artifact that proves the path worked was missing from the page that
teaches the path.

Step 5 ended with "Done = the live site shows it, not a green build", which is
the right instruction and leaves the reader with no reference point — they can
only check their own plugin, and if it fails they cannot tell a mistake in their
plugin from a broken platform. The self-test separates those two questions.

Verified on the live catalog before writing it down, as an inheritor would:
HTTP 200, zero console errors, and it reports 19 bundles, 28 profiles, 28 of 28
self-describing, this plugin listed = yes. Cross-checked by two independent
measurements rather than trusting the element — the live bundle is
byte-identical to local at 73,693 bytes, and fetching the live manifest directly
gives the same 19 and 28 from a different path.

The note also states what the self-test does NOT claim, because that is the way
it could mislead. Its four rows are questions about the catalog's SHAPE, so it
stays green even when bundle CONTENT is stale — my own fixes this flight changed
bytes and not counts, and it reports identically on both trees. Freshness is
check:catalog-currency's job, which compares every live bundle's bytes against
the build. The doc now tells the reader to run both and says which answers what.

The URL printed in the doc was fetched before committing: 200. Three separate
gates this flight were failing because they navigated to a URL nobody had
checked, and a doc that sends a reader to a 404 is the same defect with a slower
feedback loop.
This commit is contained in:
doxa-maps-88655c70 2026-09-23 10:19:40 +00:00
parent c7029aaa55
commit bc1b035f6d
1 changed files with 14 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
documentation/develop-a-plugin-and-see-it-live.md
View file

@ -201,6 +201,20 @@ nobody has watched it run, which is not the same as "nothing was produced". Veri
`https://<platform>/plugin-assets/doxa-maps/<plugin>/<plugin>/index.html`.
**Done = the live site shows it, not a green build.**
> **Check the path itself, not just your plugin.** The catalog ships a one-element self-test of
> everything above — open
> `https://<platform>/plugin-assets/doxa-maps/golden-path-check/golden-path-check/index.html`.
> It reads the manifest it was published beside and reports four things: how many bundles and
> profiles the catalog holds, how many profiles describe themselves, and whether it can find
> *itself* listed. If it answers, authoring → build → publish → serve all worked on this platform,
> which is a different question from whether *your* plugin did. Verified on the live catalog
> 2026-09-23: 19 bundles, 28 profiles, 28 of 28 self-describing, listed = yes, zero console errors.
>
> Read what it does **not** claim. Those are questions about the catalog's SHAPE, so it stays green
> even if a bundle's CONTENT is stale — freshness belongs to `bun run check:catalog-currency`, which
> compares every live bundle's bytes against your build. Run both: the self-test says the pipe
> works, the currency gate says what came through it is current.
## Step 6 — Surface it (make it discoverable)
A plugin reachable only by direct URL isn't really "seen live." Good news: **you usually don't have to do