Take main before landing

README.md

@@ -29,7 +29,7 @@ tier that you can still embed on its own. `plugin-designs/doxa-maps-spa/`
 ![Capability 5 — the Research Gallery app shell (doxa-maps-spa)](documentation/readme-images/cap5-doxa-maps-spa.png)
 
 <details>
-<summary><b>What the Research Gallery is made of — all five capabilities in one plugin</b></summary>
+<summary><b>What the Research Gallery is made of — seven production maps, an Experimental shelf, all five capabilities in one plugin</b></summary>
 
 ```text
 Research Gallery                          <doxa-maps-spa>          capability 5
@@ -51,7 +51,12 @@ Research Gallery                          <doxa-maps-spa>          capability 5
 ├─ Gospel Research
 │  ├─ Cities with Internet                connectivity-map         capability 1
 │  └─ Gospel Resources                    resources-map            capability 1
-└─ Experimental                           every other bundle, discovered automatically
+└─ Experimental (a folded shelf, filled automatically from manifest.json)
+   ├─ prayer walk planner                 prayer-walk-planner      capability 1
+   ├─ UPG neighbor                        upg-neighbor             capability 3
+   ├─ all people groups                   all-people-groups        capability 1
+   ├─ country posters                     country-posters          capability 4
+   └─ vision card                         doxa-vision-card         capability 2
 ```
 
 </details>
@@ -95,7 +100,12 @@ One folder, one `.vue`, one element. `plugin-designs/all-people-groups/`
 
 ### 1. iframe — the prayer map on any site ✅ production
 
-One `<iframe>` tag, no build step. Copy the `embed.iframe` snippet from `manifest.json`.
+One `<iframe>` tag, no build step. Each plugin's exact snippet is `embed.iframe` in `manifest.json`:
+
+```html
+<iframe src="https://YOUR_HOST/doxa-maps/doxa-simple-map/doxa-simple-map/prayer/index.html?utm_source=YOUR_SOURCE"
+        width="100%" height="600" style="border:none;border-radius:12px;" allowfullscreen></iframe>
+```
 
 ![Method 1 — the prayer map embedded in a host page's iframe](documentation/readme-images/deploy1-iframe.png)
 
@@ -109,8 +119,16 @@ print options that wrap to fit. `bun run check:mobile` · `bun run phone` (needs
 ### 3. JavaScript embed — the Research Gallery on dx-life ✅ production
 
 The whole capability-5 app on the dx-life research page, from one `<script src>` and one element —
-replacing the separate research map, list and regions dashboards the page used to carry. Copy the
-`embed.script` snippet (SRI-pinned) from `manifest.json`.
+replacing the separate research map, list and regions dashboards the page used to carry. The exact
+snippet is `embed.script` in `manifest.json`; copy its `integrity` hash from there, as it changes with
+every build:
+
+```html
+<script>window.MAP_APP_API_URL="https://pray.doxa.life";</script>
+<script src="https://YOUR_HOST/doxa-maps/doxa-maps-spa/doxa-maps-spa.js"
+        integrity="sha384-…" crossorigin="anonymous"></script>
+<doxa-maps-spa profile-config='{"profile":"doxa-maps-spa","tk":"YOUR_MAPBOX_TOKEN","utmSource":"YOUR_SOURCE","assetsBase":"https://YOUR_HOST/doxa-maps/assets"}'></doxa-maps-spa>
+```
 
 ![Method 3 — the Research Gallery JS-embedded on the dx-life research page](documentation/readme-images/deploy3-js-embed-dxlife.png)
 

documentation/README-SECTION-3-cli-commands.md

@@ -82,7 +82,7 @@ The scripts these commands are grounded in (from this branch's `package.json`):
 
 ```bash
 bun install
-bun run build          # builds every plugin-designs/* bundle -> public/doxa-maps/
+BUILD_ALLOW=1 bun run build          # builds every plugin-designs/* bundle -> public/doxa-maps/
 bun run serve          # optional: serves public/ at http://localhost:4173
 ```
 
@@ -147,7 +147,7 @@ iOS is not set up.
 **Install:** Bun.
 
 ```bash
-bun run build
+BUILD_ALLOW=1 bun run build
 ```
 
 Then paste the profile's `embed.script` snippet from `manifest.json` — a `<script src>`
@@ -200,7 +200,7 @@ absolute URLs. That is a deployment choice, not a defect.
 **The simple path** — no plugin needed, same artifacts as methods 1 and 3:
 
 ```bash
-bun run build
+BUILD_ALLOW=1 bun run build
 ```
 
 Then paste either the iframe snippet **or** the `<script src> + SRI` snippet from

documentation/README-longform.md

@@ -226,7 +226,7 @@ bun run dev        # the plugin STUDIO: http://localhost:5173 (or the next free
                    # deep-linkable. `bun run smoke:studio` checks the studio (~5s); `bun run
                    # smoke:gallery` proves every element boots on the archived /__gallery page
 
-bun run build      # the build step: every plugin-designs/<map>/ becomes
+BUILD_ALLOW=1 bun run build      # the build step: every plugin-designs/<map>/ becomes
                    # public/doxa-maps/<map>/<map>.js  +  a standalone index.html per map
 
 bun run serve      # preview the BUILT tree (the SPA shell + every embed page)

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

@@ -52,12 +52,17 @@ it's a HIGH BAR (see [reference.md](reference.md) §governance). Full walkthroug
 
 ## Step 3 — Build (one step)
 
-From `doxa-maps-plugin-studio/`:
+From the repo root:
 
 ```sh
-bun run build      # discovers plugin-designs/*, bundles each, writes public/doxa-maps/<plugin>/<plugin>.js
+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 + 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).

documentation/readme-images/shot-bundles.json

@@ -5,31 +5,31 @@
  },
  "cap2-adoption": {
   "bundle": "doxa-simple-map",
-  "sha256": "a94db2c47d598dbc59daec6903afaac93862add9c0b7a532891b9c3c0608ce02"
+  "sha256": "08a7c14bc19b0ab915aca468af11e6466ae08c367ea4545252c72aff64d32357"
  },
  "cap2-engagement": {
   "bundle": "doxa-simple-map",
-  "sha256": "a94db2c47d598dbc59daec6903afaac93862add9c0b7a532891b9c3c0608ce02"
+  "sha256": "08a7c14bc19b0ab915aca468af11e6466ae08c367ea4545252c72aff64d32357"
  },
  "cap2-prayer": {
   "bundle": "doxa-simple-map",
-  "sha256": "a94db2c47d598dbc59daec6903afaac93862add9c0b7a532891b9c3c0608ce02"
+  "sha256": "08a7c14bc19b0ab915aca468af11e6466ae08c367ea4545252c72aff64d32357"
  },
  "cap3-monolithic-research": {
   "bundle": "doxa-research-map",
-  "sha256": "eb305958dffd4a067de6f00155c3f396452adfc6d20e842cc9ae4f921e54f44a"
+  "sha256": "69ad4bce104fa445de704e7a308913e4e4a19601d54c4d43e85bcc406197dfdb"
  },
  "cap4-upg100-list": {
   "bundle": "my-upg-100-list",
-  "sha256": "04e217ca6851d9aec3f9a9331c5105f1f63c60c76c8bc268b9f6c2ea26cf614f"
+  "sha256": "31c438fa0c17075b3de9ec45ac72ca345d4cd254778ac871b862627bc1063445"
  },
  "cap4-upg100-mfe": {
   "bundle": "my-upg-100-list",
-  "sha256": "04e217ca6851d9aec3f9a9331c5105f1f63c60c76c8bc268b9f6c2ea26cf614f"
+  "sha256": "31c438fa0c17075b3de9ec45ac72ca345d4cd254778ac871b862627bc1063445"
  },
  "cap4-upg100-poster-wall": {
   "bundle": "my-upg-100-list",
-  "sha256": "04e217ca6851d9aec3f9a9331c5105f1f63c60c76c8bc268b9f6c2ea26cf614f"
+  "sha256": "31c438fa0c17075b3de9ec45ac72ca345d4cd254778ac871b862627bc1063445"
  },
  "cap5-doxa-maps-spa": {
   "bundle": "doxa-maps-spa",
@@ -41,6 +41,6 @@
  },
  "deploy2-mobile-upg100": {
   "bundle": "my-upg-100-list",
-  "sha256": "04e217ca6851d9aec3f9a9331c5105f1f63c60c76c8bc268b9f6c2ea26cf614f"
+  "sha256": "31c438fa0c17075b3de9ec45ac72ca345d4cd254778ac871b862627bc1063445"
  }
 }

documentation/tutorial.md

@@ -33,7 +33,7 @@ Most days you live in steps 3 and 4.
    sibling `doxa-maps/` may also exist; it is a different, older tree and has no `plugin-designs/`.)
 3. **Run `bun run dev`.** Your staging page opens, showing **all** your maps.
 4. **Make changes** — or tell an AI agent to — and watch them appear **instantly**.
-5. **When you're happy, run `bun run build`.** This packages your maps for the website.
+5. **When you're happy, run `BUILD_ALLOW=1 bun run build`.** This packages your maps for the website.
 6. **The website picks them up** on the next page load.
 
 > **Burn this in:** while you're *developing* you do **not** build. `bun run dev` is the
@@ -124,7 +124,7 @@ cp -r plugin-designs/template-bundle plugin-designs/harvest-map   # 1. copy the
 #    strings in index.html, and the .vue filenames (delete the second one if you want one
 #    screen). Full checklist: plugin-designs/template-bundle/README.md
 # 3. it shows up in staging automatically — no list to touch
-bun run build                                                 # 4. when ready, publish
+BUILD_ALLOW=1 bun run build                                                 # 4. when ready, publish
 ```
 
 ### What the starter gives you for free
@@ -145,7 +145,7 @@ is entirely yours**.
 ## Publishing, and the one-line embed
 
 ```bash
-bun run build
+BUILD_ALLOW=1 bun run build
 ```
 
 This packages your map into the served web-root, `public/`. To put it on a page you get a