diff --git a/documentation/README-SECTION-3-cli-commands.md b/documentation/README-SECTION-3-cli-commands.md
index fbcaf81a8..8a6b133d2 100644
--- a/documentation/README-SECTION-3-cli-commands.md
+++ b/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
diff --git a/documentation/README-longform.md b/documentation/README-longform.md
index 2160e2e8d..fd46b57cd 100644
--- a/documentation/README-longform.md
+++ b/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)
diff --git a/documentation/develop-a-plugin-and-see-it-live.md b/documentation/develop-a-plugin-and-see-it-live.md
index 3c40fa80e..527bb4acb 100644
--- a/documentation/develop-a-plugin-and-see-it-live.md
+++ b/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).
diff --git a/documentation/tutorial.md b/documentation/tutorial.md
index b326dbc1f..4b37bf80d 100644
--- a/documentation/tutorial.md
+++ b/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