diff --git a/README.md b/README.md
index 2f0ab01d1..c8a293b7e 100644
--- a/README.md
+++ b/README.md
@@ -169,7 +169,7 @@ Quick reference:
 | 1 | **iframe embed** | Bun | `bun install` → `bun run build` → `bun run serve` (or drop `public/doxa-maps/` on any host) |
 | 2 | **Mobile (Android)** | Bun · Android SDK + `adb` · JDK 17 · Capacitor (devDep) | `bun run phone` |
 | 3 | **Direct-JS / dashboard** | Bun | `bun run build`, then paste the `<script src> + integrity` snippet from `manifest.json` |
-| 4 | **WordPress** | Bun | `bun run build`, then install the `wordpress/doxa-maps-embed/` PHP plugin (shortcode + Gutenberg block) *(built, not yet shot — plugin written, install never captured live)* |
+| 4 | **WordPress** | Bun | `bun run build`, then install the `wordpress/doxa-maps-embed/` PHP plugin (shortcode + Gutenberg block) *(built + contract-proven via `bun run check:wp-embed`; not yet shot on a live WP install)* |
 | 5 | **Desktop (Tauri)** | Rust + Tauri CLI *(not yet scaffolded)* | *aspirational — no Tauri code exists yet* |
 
 Every build writes `public/doxa-maps/manifest.json` — a machine-readable index carrying the ready-to-paste
diff --git a/docs/README-SECTION-3-cli-commands.md b/docs/README-SECTION-3-cli-commands.md
index 37f149c80..bb50f2d1c 100644
--- a/docs/README-SECTION-3-cli-commands.md
+++ b/docs/README-SECTION-3-cli-commands.md
@@ -13,15 +13,26 @@ map exists there, `bun run build` picks it up automatically — no per-map wirin
 The scripts these commands are grounded in (from this branch's `package.json`):
 
 ```jsonc
-"dev":         "bun x vite",
-"build":       "bun run clean && bun run token && for d in plugin-designs/*/; do BUNDLE=$(basename \"$d\") bun x vite build || exit 1; done && bun run tree && bun run check:drop && bun run check:drop && bun run check:parse && bun run verify && bun run gallery",
-"preview":     "bun x vite preview",
-"serve":       "python3 -m http.server 4173 --bind 0.0.0.0 --directory public",
-"cap:sync":    "bunx cap sync android",
-"cap:verify":  "test -f capacitor/android/app/src/main/assets/public/index.html && echo \"OK webDir copied\" || (echo \"FAIL ...\" && exit 1)",
-"apk:debug":   "bun run build && bun run cap:sync && bun run cap:verify && cd capacitor/android && ./gradlew assembleDebug",
-"apk:install": "adb install -r capacitor/android/app/build/outputs/apk/debug/app-debug.apk",
-"phone":       "bun run apk:debug && bun run apk:install"
+// TRANSCRIBED FROM package.json 2026-09-20. The previous copy had DRIFTED: it listed
+// `check:drop` twice, omitted `check:template-literal` and `check:sri`, and still showed
+// the old inline `build` pipeline — which has since moved behind a LOCK WRAPPER.
+// ★ `build` is now `bash internal/build-lock.sh`; the real pipeline is `build:unlocked`.
+//   The lock SERIALIZES concurrent builds (a `clean` rm -rf's the shared output tree at the
+//   START of every build, so two builds racing give opposite answers seconds apart). Use
+//   BUILD_LOCK_WAIT=600 to QUEUE rather than collide. Note the lock serializes but does NOT
+//   dedupe: N queued builds = N full rebuilds.
+// If you edit package.json, re-transcribe this block — a doc that QUOTES a config is
+// claiming to be ground truth, and this one had silently stopped being it.
+"dev":             "bun x vite",
+"build":           "bash internal/build-lock.sh",
+"build:unlocked":  "bun run check:template-literal && bun run clean && bun run token && for d in plugin-designs/*/; do BUNDLE=$(basename \"$d\") bun x vite build || exit 1; done && bun run tree && bun run check:drop && bun run check:parse && bun run verify && bun run check:sri && bun run gallery",
+"preview":         "bun x vite preview",
+"serve":           "python3 -m http.server 4173 --bind 0.0.0.0 --directory public",
+"cap:sync":        "bunx cap sync android",
+"cap:verify":      "test -f capacitor/android/app/src/main/assets/public/index.html && echo \"OK webDir copied\" || (echo \"FAIL: empty assets/public -> blank white screen. Check webDir.\" && exit 1)",
+"apk:debug":       "bun run build && bun run cap:sync && bun run cap:verify && cd capacitor/android && ./gradlew assembleDebug",
+"apk:install":     "adb install -r capacitor/android/app/build/outputs/apk/debug/app-debug.apk",
+"phone":           "bun run apk:debug && bun run apk:install"
 ```
 
 `bun run build` writes the whole deployable tree to `public/doxa-maps/`, including
@@ -35,7 +46,7 @@ The scripts these commands are grounded in (from this branch's `package.json`):
 | 1 | **iframe embed** | Bun | `bun install` → `bun run build` → `bun run serve` (or drop `public/doxa-maps/` on any host) |
 | 2 | **Mobile app (Android)** | Bun · Android SDK + `adb` on PATH · JDK 17 (Gradle) · Capacitor (already a devDep) | `bun run phone` (= `apk:debug` build + `apk:install` to a connected device/emulator) |
 | 3 | **Direct-JS / dashboard** | Bun | `bun run build`, then paste the `<script src> + integrity` (SRI) snippet from `manifest.json` |
-| 4 | **WordPress** | Bun (build only) | `bun run build`, then paste the same iframe or script snippet into a WordPress **Custom HTML** block. *(No dedicated WP build script — deferred POC.)* |
+| 4 | **WordPress** | Bun (+ `php` CLI to run the contract gate) | `bun run build`, then either paste the iframe/script snippet into a **Custom HTML** block, **or** install `wordpress/doxa-maps-embed/` (shortcode + Gutenberg block). `bun run check:wp-embed` verifies the emitted markup. *(Contract-proven; not yet shot on a live WP install.)* |
 | 5 | **Desktop (Tauri)** | Rust toolchain + Tauri CLI *(not yet scaffolded)* | **Deferred POC** — no command exists on this branch yet. |
 
 ---
@@ -109,18 +120,41 @@ with a Subresource-Integrity (SRI) hash plus the custom-element tag:
 The element accepts props / emits events, so it can wire into a surrounding page as a
 unified research dashboard (deploy-3 proof). The SRI hash regenerates on every build.
 
-### 4. WordPress *(deferred POC)*
+### 4. WordPress *(built + contract-proven; not yet shot on a live WP install)*
 
-No dedicated WordPress build step exists on this branch. WordPress is served by the
-**same** artifacts as methods 1 and 3:
+> **Corrected 2026-09-20.** This section previously read *"deferred POC — no dedicated
+> WordPress build step exists on this branch"*. That is no longer true: a first-class
+> plugin exists at `wordpress/doxa-maps-embed/` (a `[doxa_map]` shortcode + a Gutenberg
+> block), and its emitted markup is now verified by a gate.
+
+**The simple path** — no plugin needed, same artifacts as methods 1 and 3:
 
 ```bash
 bun run build
 ```
 
 Then paste either the iframe snippet **or** the `<script src> + SRI` snippet from
-`manifest.json` into a WordPress **Custom HTML** block. A first-class WP plugin/build
-step is a deferred POC (see backlog `_meta`: "deploy methods 4/5 are DEFERRED").
+`manifest.json` into a WordPress **Custom HTML** block.
+
+**The plugin path** — `wordpress/doxa-maps-embed/` registers the bundle through WordPress's
+own dependency graph, so the SRI hash and `crossorigin` survive and the script loads once
+per page rather than once per embed.
+
+```bash
+bun run check:wp-embed     # renders the REAL shortcode with no WordPress installed
+```
+
+That gate stubs the ~20 WordPress functions the plugin actually calls (`wordpress/tests/`),
+renders the shortcode against the REAL built `manifest.json`, and asserts the contract
+`HOW-TO-TEST.md` defines: the element tag is emitted, `profile-config` decodes to valid
+JSON, the script `src` equals the catalog path, the SRI `integrity` is injected by the
+`script_loader_tag` filter, `crossorigin="anonymous"` is present — plus a negative test
+that a **malformed** integrity is rejected.
+
+**Status honesty — say "contract-proven", not "proven".** What is proven: the plugin emits
+the correct markup, repeatably and in CI. What is *not*: that WordPress renders the page,
+that the block editor registers it, or that a browser executes the result. Those still need
+a real WP install (`wp-env start` — see `wordpress/doxa-maps-embed/HOW-TO-TEST.md`).
 
 ### 5. Desktop — Tauri *(deferred POC)*