From 08dca05f6392528fc49ab835fb91e35cdfc63357 Mon Sep 17 00:00:00 2001
From: doxa-maps-88655c70
 <88627970+doxa-maps-88655c70@users.noreply.github.com>
Date: Fri, 25 Sep 2026 03:29:36 +0000
Subject: [PATCH] Golden path: a six-step table first, the incident notes in a
 log at the bottom

The first doc a DX developer follows now opens with one table (what you do,
the command, what "done" looks like), then one short section per step with
its command. The nine dated measurement notes move, unabridged in substance,
to a "Notes and history" log at the end. 2,612 -> 1,501 words.

Also corrected two stale facts: the deployment status table now matches the
README (WordPress and Tauri are proofs of concept; mobile is built), and the
Experimental shelf is described as it works, not by a 2026-09-21 row list
that no longer matches.
---
 .../develop-a-plugin-and-see-it-live.md       | 309 ++++++------------
 1 file changed, 104 insertions(+), 205 deletions(-)

diff --git a/documentation/develop-a-plugin-and-see-it-live.md b/documentation/develop-a-plugin-and-see-it-live.md
index 527bb4acb..9eb37531d 100644
--- a/documentation/develop-a-plugin-and-see-it-live.md
+++ b/documentation/develop-a-plugin-and-see-it-live.md
@@ -1,32 +1,32 @@
 # Develop a plugin and see it live — the golden path
 
-> **The one thing that matters:** author a map plugin, run one build, and see it live on the platform.
-> This page THREADS the existing docs into that read-order — it does not duplicate them. Follow the six
-> steps; each links to the doc that teaches that piece in depth. Brand-neutral: any team on any platform
-> inherits this same path.
+**Author a map plugin, build it once, prove it mounts, and see it live — in six steps.** Each step links
+to the doc that teaches that piece in depth.
 
-## The path at a glance
+| Step | You do | Command | Done when |
+|---|---|---|---|
+| **1. Pick a capability** | choose how much your plugin nests | — | you know your tier (1–5) |
+| **2. Author** | write 3 files in `plugin-designs/<your-plugin>/` | — | the folder has `.vue` + `index.js` + `index.html` |
+| **3. See it in the studio** | iterate with hot reload, no build | `bun run dev` | your plugin appears at http://localhost:5173/ |
+| **4. Build** | produce the deployable tree | `BUILD_ALLOW=1 bun run build` | exit 0, all guards PASS |
+| **5. Prove it mounts** | open every plugin in a real browser | `bun run smoke:embeds` | `N/N pages mount cleanly` |
+| **6. Publish and see it live** | copy the tree to your host, embed it | see Step 6 | the live URL shows it |
 
-```
-   author            build             publish            see it live
- plugin-designs/  →  bun run build  →  merge to catalog  →  https://<platform>/plugin-assets/…
-   (one folder)      (one step)        (the runbook)        (a tab, an iframe, a <script>)
-```
+Everything you build is a **compiled Vue custom element**: one folder → one bundle → one `<tag>`. A static
+HTML page is never a plugin (it can only be iframed).
 
-Everything you build is a **compiled Vue custom element** — one folder → one bundle → one `<tag>`. A static
-HTML page is never a plugin (it can only be iframed). See [reference.md](reference.md) for the capability model.
+---
 
-## Step 1 — Understand the 5 capabilities (30 sec)
+## Step 1 — Pick a capability
 
 A plugin is one of five tiers, simplest → most composable:
-**single-element → prop-table → monolithic → nested-element SPA → nested-SPA (app-shell)**.
-You declare the tier in `<bundle>.meta.json` (`{"type": …}`) for the composite tiers. Read
-[reference.md](reference.md) §capabilities; imitate the nearest reference plugin in `plugin-designs/`.
+**single element → prop-table → multi-view → composite (nested elements) → app shell (nested SPAs)**.
+Composite tiers declare themselves in `<bundle>.meta.json` (`{"type": …}`). Imitate the nearest reference
+plugin: [reference-capability-exemplars.md](reference-capability-exemplars.md) names one per tier.
 
-## Step 2 — Author the plugin (the 4-file pattern)
+## Step 2 — Author: three files are enough
 
-In **`plugin-designs/<your-plugin>/`** create these files (imitate the nearest reference plugin, never author
-a plugin as a page). **Three are required; the rest are opt-in:**
+In **`plugin-designs/<your-plugin>/`**:
 
 | File | Required? | What it is |
 |---|---|---|
@@ -34,219 +34,118 @@ a plugin as a page). **Three are required; the rest are opt-in:**
 | `index.js` | **required** | `defineCustomElement(RootVue)` → `customElements.define('<your-tag>', El)` — register ONLY your own tag |
 | `index.html` | **required** | the staging entry page that mounts `<your-tag>` — the build fails without it |
 | `<your-plugin>.meta.json` | composite tiers only | `{"type": "<machine key>", "composes": […], "label": "…"}` |
-| `<your-plugin>.instances.json` | optional | preset instances — supplying one makes the bundle **prop-table** (cap-2) |
+| `<your-plugin>.instances.json` | optional | preset instances — supplying one makes the bundle **prop-table** (cap 2) |
 | `src/` | optional | private components used only by this plugin |
 
-> **Measured 2026-09-21, so you can calibrate.** Across the 18 shipped bundles the folder holds **3 to 8
-> files** — not one has "exactly four." `all-people-groups` is the true minimum at **3** (root `.vue` +
-> `index.js` + `index.html`) and is a fully working, manifest-listed plugin. **9 of 18 carry no `.meta.json`
-> at all**, because single and prop-table tiers are inferred rather than declared. Start at three and add a
-> file only when you need what it does.
->
-> `index.html` really is load-bearing: moving it out of `demo-map/` made the build error and dropped the
-> bundle from the buildable list (18 → 17). Restoring it returned a clean build.
+**`plugin-designs/` is your free zone.** Contribute to the shared `library/` (`@map`) only when a component
+is genuinely **reusable and parameterized** — a library edit reaches every plugin. Walkthrough:
+[tutorial.md](tutorial.md).
 
-**`plugin-designs/` is your FREE ZONE** — build freely here. Only contribute a component to the shared
-`library/` (`@map`) if it is genuinely **reusable + parameterized** — a library edit reaches every plugin, so
-it's a HIGH BAR (see [reference.md](reference.md) §governance). Full walkthrough: [tutorial.md](tutorial.md).
+## Step 3 — See it in the studio (seconds, no build)
 
-## Step 3 — Build (one step)
+```sh
+bun run dev          # vite on :5173; `/` is the Plugin Studio, every plugin in one place
+bun run smoke:studio # ~5s: asserts the studio mounts and every plugin is a real subtree
+```
 
-From the repo root:
+This is the loop to live in while authoring: about 5 seconds, against a full build of 1–4 minutes.
+The build is for publishing, not for looking.
+
+## Step 4 — Build the deployable tree
 
 ```sh
 BUILD_ALLOW=1 bun run build      # discovers plugin-designs/*, bundles each, writes public/doxa-maps/<plugin>/<plugin>.js
 ```
 
-`BUILD_ALLOW=1` is deliberate: without it the build refuses (exit 75), because a full build first
-wipes `public/doxa-maps/`, which every other agent or developer in a shared checkout is reading. On
-your own machine, set it. To check just your plugin without touching the rest of the tree, use
-`BUNDLE=<your-plugin> bun x vite build`.
+**Exit 0 + every guard PASS = a good build.** Your plugin now exists under `public/doxa-maps/<your-plugin>/`
+with a standalone leaf page and a `manifest.json` entry. `BUILD_ALLOW=1` is deliberate: a full build first
+wipes `public/doxa-maps/`, so it refuses (exit 75) in a shared checkout unless you mean it. To compile only
+your plugin: `BUNDLE=<your-plugin> bun x vite build`. Recipes: [how-to.md](how-to.md).
 
-Exit 0 + all DX guards PASS + `inline-parse-check` PASS = a good build. Your plugin now exists as a real
-custom-element bundle under `public/doxa-maps/<your-plugin>/`, with a standalone leaf page and a manifest
-entry. Recipes: [how-to.md](how-to.md).
+## Step 5 — Prove it mounts in a real browser
 
-## Step 3a — The FAST loop: see it in the studio (~5s, no build)
-
-Before the four-minute build, iterate in the **plugin studio** — the single staging environment, where
-every plugin appears in one place as a real mounted element:
+**A green build is a static result**: it proves files exist, parse and carry correct hashes. It never opens
+your element, and an element that throws on setup renders nothing while the build stays green.
 
 ```sh
-bun run dev          # vite on :5173; `/` mounts <plugin-studio>, one tab per profile
-bun run smoke:studio # ~5s: asserts the studio mounts and every tab is a real subtree
-```
-
-Measured 2026-09-22: **PASS in 4.7s — 29 tabs, 0 failed requests**, against a full `bun run build` of
-**43s–4min** on the same box (it runs 19 bundles sequentially and queues behind any other build, so
-the spread is real). An order of magnitude either way: this is the loop to live in while authoring.
-The build is for publishing, not for looking.
-
-> **★ The studio catches a class the built tree structurally cannot.** The dev manifest hands
-> **rooted** refs (`/plugin-designs/…`) while the built manifest hands **relative** ones
-> (`./bundle/bundle.js`). A base-join bug is therefore invisible in one surface and fatal in the
-> other — which is why both this step and the next exist, rather than one replacing the other.
-
-There is exactly **one** staging environment. If you find yourself looking at a second index of
-plugins, it is the archived gallery at `/__gallery` — kept because the dev server still imports its
-renderer, not because it is a place to review work.
-
-## Step 3b — Prove it MOUNTS in a browser (before you publish)
-
-A green build is a **static** result: the guards check that files exist, parse, carry a correct SRI hash and
-resolve. None of them opens your element. A bundle can pass every guard above and still render nothing —
-a thrown `setup()` removes the subtree silently, and the build stays green.
-
-> **This was measured, not assumed (2026-09-21).** A `throw` was injected into `template-map-a.vue`'s
-> `setup()` and the bundle rebuilt. Result: the build **succeeded** (206 kB emitted, exit 0), `check:parse`
-> **PASS**, `check:drop` **PASS** — and `smoke:embeds` reported **0/2 pages mount cleanly**. One deliberate
-> defect, invisible to every static guard, caught only in a browser. That gap is the entire reason this
-> step exists.
-
-```sh
-# A token is required or map profiles cannot mount. Take it from the build config, which is
-# the one source that works from a local gate — see the note below before changing this.
 MAPBOX_TOKEN=$(python3 -c "import json;print(json.load(open('vite.doxa-maps-build-config.json'))['token'])")
-
-MAPBOX_TOKEN=$MAPBOX_TOKEN bun run smoke:embeds                 # every profile in the manifest
+MAPBOX_TOKEN=$MAPBOX_TOKEN bun run smoke:embeds                                 # every plugin
 MAPBOX_TOKEN=$MAPBOX_TOKEN node internal/embed-smoke.mjs --grep <your-plugin>   # just yours
 ```
 
-> **Do not fetch the token from `https://doxa.life/api/maps/token` here — measured 2026-09-23, it does
-> not work for this.** That endpoint serves a token URL-restricted to `doxa.life`, so a tile request
-> without that Referer returns **403** and every basemap in your smoke test renders blank while the pins
-> draw fine. That is the exact symptom first reported as *"it's loading the pins, but it's not
-> loading the actual underlying map"*, and it is why `tokenUrl` was emptied in the build config on
-> 2026-09-22. This doc used to hand you that command, so an inheritor's first run reproduced the bug.
->
-> The `token` field in `vite.doxa-maps-build-config.json` is the one that works: measured, the config
-> token returns **200** for a tile request with no Referer while the endpoint token returns **403**. It
-> is a `pk.` public key, baked deliberately (a project decision, 2026-09-21) so a map works on any host —
-> protected by URL restrictions rather than secrecy. `check:public-hygiene` allows `pk.` and fails the
-> build on `sk.`/`tk.`, so this is safe to read and never a secret to guard.
+**Expect `N/N pages mount cleanly`.** The token matters: without it every *map* plugin fails to mount while
+every non-map plugin passes, which looks like many broken plugins and is not. Take the token from the
+build config, as above ([why](#notes-and-history)).
 
-`smoke:embeds` serves `public/` and opens **every bundle × profile × preconfigured instance** from
-`manifest.json`, asserting each custom element defines, attaches a shadow root and fills it. Expect
-`N/N pages mount cleanly`. Measured 2026-09-21: **40/40**.
+## Step 6 — Publish and see it live
 
-> **The token is not optional, and its absence is loud.** Without `MAPBOX_TOKEN` every *map* profile fails
-> its mount assertion while every *DOM* profile passes — 27/40, which reads like 13 broken plugins and is
-> not. The run prints a two-line warning when the token is missing; believe the warning, not the failures.
-> `?tk=` alone is also not enough for a composite: it reaches only the top-level element's `profile-config`,
-> while **nested children read `window.MAP_TOKEN`**. The smoke sets both.
-
-**This step is not in CI.** CI is the single authoritative builder but installs no browser binary (no
-`playwright install` step), so the mount check is a LOCAL gate an author runs deliberately. That is exactly
-why it belongs here in the golden path rather than being left to be remembered.
-
-## Step 4 — Publish to the live catalog
-
-The platform serves from the **catalog repo** (`platform/mfe-index`), NOT from where you develop. Publishing
-= merging your built bundles into the catalog. **The tested procedure, in one block:**
+**Copy the built tree to any static host, then embed from it.** The tree is `public/doxa-maps/`; every
+plugin's ready-made snippets are in its `manifest.json`.
 
 ```sh
-set -e   # ← FIRST LINE, not a style choice. Explained below; without it this block is unsafe.
-
-# 0. PRECONDITION: never publish a tree a build is rewriting. `clean` empties public/doxa-maps at
-#    the START of every build, so a concurrent build makes the source momentarily EMPTY.
-bun run check:settled
-
-# 1. clone the catalog fresh (fetch-first, never force)
-git clone --depth 1 <catalog-repo-url> /tmp/catalog
-# 2. merge your built bundles into its doxa-maps subtree (--delete mirrors removals)
-rsync -a --delete public/doxa-maps/ /tmp/catalog/app/doxa-maps/
-# 3. VERIFY — these are commands, not a reminder. Under `set -e` a failure aborts before the push.
-bun run check:sri                 # every leaf's baked integrity matches the bundle it loads
-bun run check:embed-targets       # every embed.iframe src in the manifest resolves to a real file
-git -C /tmp/catalog diff --stat -- . ':(exclude)app/doxa-maps' | grep -q . \
-  && { echo 'ABORT: diff touches files outside app/doxa-maps'; exit 1; } || true
-# 4. commit (product-only message), then push with a RAISED BUFFER (see below):
-git -C /tmp/catalog -c http.postBuffer=524288000 push origin HEAD:main
+set -e                                   # first line: a failing check must stop the publish
+bun run check:settled                    # never publish a tree a build is rewriting
+bun run check:sri                        # every leaf's integrity hash matches its bundle
+bun run check:embed-targets              # every embed snippet points at a real file
+rsync -a --delete public/doxa-maps/ <your-host-checkout>/doxa-maps/
+# commit and push the host checkout; for a large tree: git -c http.postBuffer=524288000 push …
 ```
 
-> **★ Why `set -e` is the first line, and why step 3 is commands rather than a comment.** Both halves
-> of this once took the live catalog down with a 404. 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, which faithfully mirrored that emptiness into the catalog.
-> `--delete` is what makes a mid-churn source catastrophic — it deletes the live tree to match your
-> empty one. So the settled check is a precondition, not a courtesy, and a verify that cannot abort
-> is not a verify.
-
-> **★ `http.postBuffer=524288000` is load-bearing, not optional.** The tree is ~39 MB and git's 1 MB
-> default cannot stream it. Without the flag the push fails with `The remote end hung up unexpectedly`
-> — which reads as a SERVER rejection (permissions? branch protection? repo full?) and sends you
-> debugging the wrong machine entirely. It is a local buffer limit. This one line is the difference
-> between step 4 working and step 4 looking like an access problem.
-
-
-The platform serves the catalog directly, so a pushed change is live at once — verify at the URL in Step 5.
-(The fuller runbook with every gotcha lives in the project's deploy-cycle notes; the block above is the
-load-bearing sequence.)
-
-(The end-state is the Forgejo CI build-gate — push source, CI builds + publishes automatically. Until a runner
-is registered, the runbook is the manual path. Same `build:unlocked` seam.)
-
-## Step 5 — See it live (the 5 deployment methods)
-
-Your one element deploys five ways (only an element supports all five — a page supports iframe only):
-
-| # | Method | How | Status today |
+| # | Deployment method | How | Status |
 |---|---|---|---|
-| 1 | **iframe** | point an `<iframe>` at the plugin's leaf page | ✅ proven |
-| 3 | **JavaScript embed** | `<script src=".../<plugin>.js">` + `<your-tag>` (SRI-hashed) | ✅ proven |
-| 2 | **mobile** | `bun run phone` (Capacitor) — build step, no new code | 🔶 built, not shot |
-| 4 | **WordPress plugin** | the `deployment/wordpress/doxa-maps-embed/` PHP wrapper emits the embed snippet | 🔶 built, not shot |
-| 5 | **desktop (Tauri)** | `bun run tauri:build` → a real binary + `.deb` wrapping the same `public/` tree | 🔶 built, not shot |
+| 1 | **iframe** | point an `<iframe>` at the plugin's leaf page | ✅ production |
+| 2 | **mobile app** | `bun run phone` (Capacitor) — same tree, no new code | ✅ built |
+| 3 | **JavaScript embed** | `<script src=".../<plugin>.js">` + `<your-tag>` (SRI-pinned) | ✅ production |
+| 4 | **WordPress / Disciple Tools** | `deployment/wordpress/doxa-maps-embed/` emits the embed snippet | 🧪 proof of concept |
+| 5 | **desktop (Tauri)** | `bun run tauri:build` — a binary and `.deb` wrapping the same tree | 🧪 proof of concept |
 
-Say "proven" ONLY for 1 & 3. For 2, 4 and 5 say "built, not shot" — each is scaffolded and
-contract-checked, and what is missing differs per method: 2 has no APK (no Android SDK here), 4 has
-no capture of a live WordPress install, and 5 **does** emit artifacts — a 67 MB binary and a 60 MB
-`.deb` are on disk — but no window has been opened, because this box is headless. "Not shot" means
-nobody has watched it run, which is not the same as "nothing was produced". Verify at
-`https://<platform>/plugin-assets/doxa-maps/<plugin>/<plugin>/index.html`.
-**Done = the live site shows it, not a green build.**
+**Done = the live site shows it, not a green build.** To check the whole pipe at once, open the
+`golden-path-check` plugin on your host: it reads the manifest beside it and reports how many bundles
+it can see and whether it finds itself. To check that what you published is *current*, run
+`bun run check:catalog-currency`.
 
-> **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
-anything.**
-
-**It is already surfaced — automatically.** The cap-5 SPA reads the built `manifest.json` at runtime and
-auto-discovers every bundle that is neither already placed in a curated section nor on the small
-`NOT_EXPERIMENTAL` exclusion list (the two shells, the template, and bundles that are nested *inside* another
-tab). Your plugin appears in the collapsible **Experimental** folder at the bottom of the rail, marked 🧪, with
-its label and description read from the manifest. No `TAB_DEFS` entry, no `NAV_MODEL` row, no code edit.
-
-> Verified 2026-09-21 in a browser: the rail rendered **11 rows — 6 curated, then 5 auto-discovered**
-> (`all-people-groups`, `country-posters`, `demo-map`, `doxa-vision-card`, `stack-demo`), each carrying the
-> 🧪 marker. Discovery is fail-soft: if the manifest is unreachable the folder stays empty and the curated
-> rail is unaffected — a discovery failure never takes down the app.
-
-**Promote it to a curated tab (optional).** The curated sections encode a deliberate teaching order, so a
-plugin graduates out of Experimental only when it earns a place in that order. That is the edit Step 6 used to
-describe as mandatory: add a `TAB_DEFS` entry plus a `NAV_MODEL` row in `plugin-designs/doxa-maps-spa/`, then
-rebuild + republish.
-
-**One rail row per BUNDLE, not per profile.** A bundle's profiles (gospel-resources ships four) are alternate
-views reached *inside* the pane. The rail is an onboarding ramp, not an inventory.
+**Your plugin surfaces itself.** The Research Gallery (`doxa-maps-spa`) reads the built `manifest.json`
+and puts every bundle it doesn't already curate into its folded **Experimental** shelf, with the label and
+description from the manifest — no code edit. Promoting it to a curated tab is an optional edit to
+`TAB_DEFS` and `NAV_MODEL` in `plugin-designs/doxa-maps-spa/`. One row per bundle: a bundle's extra
+profiles are views inside its pane.
 
 ---
 
-**That's the whole path: author in `plugin-designs/` → `bun run build` → prove it MOUNTS (`smoke:embeds`) →
-publish via the runbook → see it live → and it surfaces itself in the SPA's Experimental folder.** Only two
-of those six steps are edits you write: the plugin, and the optional promotion out of Experimental. Deep
-dives: [tutorial.md](tutorial.md) · [how-to.md](how-to.md) · [reference.md](reference.md) · [why.md](why.md).
+**The whole path:** author in `plugin-designs/` → see it in the studio → `BUILD_ALLOW=1 bun run build`
+→ prove it mounts (`smoke:embeds`) → publish → it appears on the Experimental shelf. Deep dives:
+[tutorial.md](tutorial.md) · [how-to.md](how-to.md) · [reference.md](reference.md) · [why.md](why.md).
+
+---
+
+## Notes and history
+
+The measurements behind the steps above, kept for whoever needs the reasoning.
+
+- **Step 2 — how many files a plugin really has (measured 2026-09-21).** Across 18 bundles a folder held
+  3 to 8 files. `all-people-groups` is the true minimum at 3 (root `.vue` + `index.js` + `index.html`), and
+  9 of 18 had no `.meta.json` because single and prop-table tiers are inferred. Removing `index.html` from
+  `demo-map/` made the build error and dropped the bundle (18 → 17 buildable).
+- **Step 3 — studio vs build timing (measured 2026-09-22).** `smoke:studio` passed in 4.7 s (29 tabs,
+  0 failed requests); a full build took 43 s–4 min on the same box. The studio also catches a bug class the
+  built tree cannot: the dev manifest hands rooted refs (`/plugin-designs/…`), the built one relative refs
+  (`./bundle/bundle.js`), so a base-join bug is invisible in one and fatal in the other.
+- **Step 5 — why the browser check exists (measured 2026-09-21).** A `throw` injected into
+  `template-map-a.vue`'s `setup()` still built (exit 0), passed `check:parse` and `check:drop`, and
+  `smoke:embeds` reported 0/2 mounted. Without a token, 27/40 mount — every map profile fails. A composite
+  also needs `window.MAP_TOKEN`, because `?tk=` reaches only the top-level element; the smoke sets both.
+  The browser check is not in CI (no browser binary there), so it is a local gate you run on purpose.
+- **Step 5 — which token (measured 2026-09-23).** The `https://doxa.life/api/maps/token` endpoint serves a
+  token restricted to `doxa.life`: a tile request without that Referer returns 403, so basemaps render
+  blank while pins draw. The build-config `token` returns 200 from any origin. It is a `pk.` public key,
+  restricted by URL rather than kept secret; `check:public-hygiene` allows `pk.` and fails on `sk.`/`tk.`.
+- **Step 6 — why `set -e` comes first.** An earlier publish took the live catalog down with a 404 twice
+  over: the verify was chained so a failing check fell through to the push, and `rsync --delete` ran from
+  a tree a concurrent build had just emptied, mirroring the emptiness to the host. Hence `check:settled`
+  as a precondition and a verify that can abort.
+- **Step 6 — `http.postBuffer=524288000`.** The tree is ~39 MB; git's 1 MB default cannot stream it, and
+  the failure (`The remote end hung up unexpectedly`) reads like a server rejection when it is a local
+  buffer limit.
+- **Step 6 — deployment status wording.** "Proof of concept" means the code exists and its contract check
+  passes, but it is not production-ready: method 4 has no capture on a live WordPress install, and method 5
+  emits a real binary and `.deb` (~67 MB and ~60 MB) that has not been launched on a desktop.