diff --git a/docs/deployment/assets/docs.js b/docs/deployment/assets/docs.js
new file mode 100644
index 0000000..1046b17
--- /dev/null
+++ b/docs/deployment/assets/docs.js
@@ -0,0 +1,157 @@
+/* Eureka deployment docs — diagram enhancer.
+ *
+ * Loaded as a CLASSIC script (not an ES module) on purpose: Chrome blocks
+ * `<script type="module">` from file:// origins (CORS, origin "null"), which
+ * made the mermaid diagrams show up as raw text when the docs are opened as
+ * local files. A classic script + the UMD mermaid build renders reliably from
+ * file:// and over http.
+ *
+ * For each `.diagram` panel it:
+ *   1. captures the raw mermaid source (before mermaid replaces it with SVG),
+ *   2. renders the diagram (default view),
+ *   3. adds a Diagram/Source toggle and a Copy-source button.
+ */
+(function () {
+  if (typeof mermaid === "undefined") {
+    console.error("mermaid failed to load");
+    return;
+  }
+
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: "loose",
+    theme: "base",
+    fontFamily: "'IBM Plex Mono', monospace",
+    themeVariables: {
+      darkMode: true,
+      background: "#0e131c",
+      fontFamily: "'IBM Plex Mono', monospace",
+      fontSize: "14px",
+      primaryColor: "#18212f",
+      primaryBorderColor: "#c9f24e",
+      primaryTextColor: "#e9eef5",
+      secondaryColor: "#121927",
+      secondaryBorderColor: "#5fd5ee",
+      secondaryTextColor: "#e9eef5",
+      tertiaryColor: "#0e131c",
+      tertiaryBorderColor: "#7e8da0",
+      tertiaryTextColor: "#b9c4d2",
+      lineColor: "#5fd5ee",
+      textColor: "#b9c4d2",
+      mainBkg: "#18212f",
+      nodeBorder: "#c9f24e",
+      clusterBkg: "rgba(95,213,238,0.05)",
+      clusterBorder: "rgba(150,180,220,0.25)",
+      titleColor: "#e9eef5",
+      edgeLabelBackground: "#0a0e14",
+      actorBkg: "#18212f",
+      actorBorder: "#b69cff",
+      actorTextColor: "#e9eef5",
+      actorLineColor: "#7e8da0",
+      signalColor: "#5fd5ee",
+      signalTextColor: "#b9c4d2",
+      labelBoxBkgColor: "#121927",
+      labelBoxBorderColor: "#5fd5ee",
+      labelTextColor: "#e9eef5",
+      loopTextColor: "#b9c4d2",
+      noteBkgColor: "rgba(255,180,84,0.12)",
+      noteBorderColor: "#ffb454",
+      noteTextColor: "#e9eef5",
+      activationBkgColor: "#18212f",
+      activationBorderColor: "#c9f24e",
+      nodeTextColor: "#e9eef5",
+    },
+    flowchart: { curve: "basis", htmlLabels: true, padding: 14 },
+    sequence: { actorMargin: 46, messageAlign: "center", mirrorActors: false, useMaxWidth: true },
+  });
+
+  function enhance(panel) {
+    var pre = panel.querySelector("pre.mermaid");
+    if (!pre) return;
+
+    var source = pre.textContent.replace(/^\s*\n/, "").replace(/\s+$/, "");
+
+    // Views: rendered graph (holds the mermaid <pre>) and a raw-source view.
+    var graph = document.createElement("div");
+    graph.className = "dgm-graph";
+    graph.appendChild(pre);
+
+    var srcView = document.createElement("pre");
+    srcView.className = "dgm-source";
+    srcView.hidden = true;
+    var code = document.createElement("code");
+    code.textContent = source;
+    srcView.appendChild(code);
+
+    var body = document.createElement("div");
+    body.className = "dgm-body";
+    body.appendChild(graph);
+    body.appendChild(srcView);
+
+    // Toolbar: segmented toggle + copy.
+    var bar = document.createElement("div");
+    bar.className = "dgm-bar";
+    bar.innerHTML =
+      '<div class="dgm-seg" role="tablist">' +
+      '<button class="dgm-tab is-active" data-view="graph" aria-selected="true">Diagram</button>' +
+      '<button class="dgm-tab" data-view="source" aria-selected="false">Source</button>' +
+      "</div>" +
+      '<button class="dgm-copy" type="button" aria-label="Copy Mermaid source">Copy</button>';
+
+    var cap = panel.querySelector(".cap");
+    if (cap) cap.appendChild(bar);
+    else panel.insertBefore(bar, panel.firstChild);
+    panel.appendChild(body);
+
+    var tabs = bar.querySelectorAll(".dgm-tab");
+    tabs.forEach(function (tab) {
+      tab.addEventListener("click", function () {
+        var view = tab.getAttribute("data-view");
+        tabs.forEach(function (t) {
+          var active = t === tab;
+          t.classList.toggle("is-active", active);
+          t.setAttribute("aria-selected", active ? "true" : "false");
+        });
+        graph.hidden = view !== "graph";
+        srcView.hidden = view !== "source";
+      });
+    });
+
+    var copy = bar.querySelector(".dgm-copy");
+    copy.addEventListener("click", function () {
+      var done = function () {
+        copy.textContent = "Copied";
+        copy.classList.add("ok");
+        setTimeout(function () {
+          copy.textContent = "Copy";
+          copy.classList.remove("ok");
+        }, 1400);
+      };
+      if (navigator.clipboard && navigator.clipboard.writeText) {
+        navigator.clipboard.writeText(source).then(done, fallback);
+      } else {
+        fallback();
+      }
+      function fallback() {
+        var range = document.createRange();
+        range.selectNodeContents(code);
+        var sel = window.getSelection();
+        sel.removeAllRanges();
+        sel.addRange(range);
+        try { document.execCommand("copy"); } catch (e) { /* ignore */ }
+        sel.removeAllRanges();
+        done();
+      }
+    });
+  }
+
+  document.addEventListener("DOMContentLoaded", function () {
+    document.querySelectorAll(".diagram").forEach(enhance);
+    // Render every mermaid block (now nested inside .dgm-graph). Pass an
+    // explicit querySelector — some mermaid builds throw if run() is given an
+    // options object without `nodes`/`querySelector` instead of defaulting.
+    mermaid.run({ querySelector: ".dgm-graph pre.mermaid" }).catch(function (err) {
+      console.error("mermaid render error:", err);
+    });
+  });
+})();
diff --git a/docs/deployment/assets/mermaid-init.js b/docs/deployment/assets/mermaid-init.js
deleted file mode 100644
index 49f05d2..0000000
--- a/docs/deployment/assets/mermaid-init.js
+++ /dev/null
@@ -1,57 +0,0 @@
-// Mermaid 11 (ESM) initialised with a custom theme that matches the
-// "deployment console / blueprint" palette used across these docs.
-import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
-
-mermaid.initialize({
-  startOnLoad: true,
-  securityLevel: 'loose',
-  theme: 'base',
-  fontFamily: "'IBM Plex Mono', monospace",
-  themeVariables: {
-    darkMode: true,
-    background: '#0e131c',
-    fontFamily: "'IBM Plex Mono', monospace",
-    fontSize: '14px',
-
-    primaryColor: '#18212f',
-    primaryBorderColor: '#c9f24e',
-    primaryTextColor: '#e9eef5',
-    secondaryColor: '#121927',
-    secondaryBorderColor: '#5fd5ee',
-    secondaryTextColor: '#e9eef5',
-    tertiaryColor: '#0e131c',
-    tertiaryBorderColor: '#7e8da0',
-    tertiaryTextColor: '#b9c4d2',
-
-    lineColor: '#5fd5ee',
-    textColor: '#b9c4d2',
-    mainBkg: '#18212f',
-    nodeBorder: '#c9f24e',
-    clusterBkg: 'rgba(95,213,238,0.05)',
-    clusterBorder: 'rgba(150,180,220,0.25)',
-    titleColor: '#e9eef5',
-    edgeLabelBackground: '#0a0e14',
-
-    // sequence diagrams
-    actorBkg: '#18212f',
-    actorBorder: '#b69cff',
-    actorTextColor: '#e9eef5',
-    actorLineColor: '#7e8da0',
-    signalColor: '#5fd5ee',
-    signalTextColor: '#b9c4d2',
-    labelBoxBkgColor: '#121927',
-    labelBoxBorderColor: '#5fd5ee',
-    labelTextColor: '#e9eef5',
-    loopTextColor: '#b9c4d2',
-    noteBkgColor: 'rgba(255,180,84,0.12)',
-    noteBorderColor: '#ffb454',
-    noteTextColor: '#e9eef5',
-    activationBkgColor: '#18212f',
-    activationBorderColor: '#c9f24e',
-
-    // state / flowchart accents
-    nodeTextColor: '#e9eef5',
-  },
-  flowchart: { curve: 'basis', htmlLabels: true, padding: 14 },
-  sequence: { actorMargin: 46, messageAlign: 'center', mirrorActors: false, useMaxWidth: true },
-});
diff --git a/docs/deployment/assets/styles.css b/docs/deployment/assets/styles.css
index 050bd30..20a547a 100644
--- a/docs/deployment/assets/styles.css
+++ b/docs/deployment/assets/styles.css
@@ -166,6 +166,34 @@ li::marker { color: var(--signal-dim); }
 .diagram .cap::before { content: "◆"; color: var(--cyan); font-size: 9px; }
 .mermaid { display: flex; justify-content: center; padding: 8px; }
 
+/* Diagram toolbar — Diagram/Source toggle + copy ------------------------- */
+.diagram .cap { flex-wrap: wrap; }
+.dgm-bar { display: inline-flex; align-items: center; gap: 8px; margin-left: auto; }
+.dgm-seg { display: inline-flex; border: 1px solid var(--line-2); border-radius: 8px; overflow: hidden; }
+.dgm-tab {
+  font-family: var(--mono); font-size: 11px; letter-spacing: 0.04em; text-transform: none;
+  padding: 5px 11px; background: transparent; color: var(--muted); border: 0; cursor: pointer;
+  transition: background .15s, color .15s;
+}
+.dgm-tab + .dgm-tab { border-left: 1px solid var(--line-2); }
+.dgm-tab:not(.is-active):hover { color: var(--text); background: var(--ink-3); }
+.dgm-tab.is-active { background: var(--signal); color: var(--ink); font-weight: 600; }
+.dgm-copy {
+  font-family: var(--mono); font-size: 11px; letter-spacing: 0.04em;
+  padding: 5px 11px; background: var(--ink-3); color: var(--text-soft);
+  border: 1px solid var(--line-2); border-radius: 8px; cursor: pointer;
+  transition: color .15s, border-color .15s;
+}
+.dgm-copy:hover { color: var(--text); border-color: var(--cyan); }
+.dgm-copy.ok { color: var(--signal); border-color: var(--signal-dim); }
+.dgm-graph { display: flex; justify-content: center; padding: 8px; }
+.dgm-source {
+  margin: 6px 0 0; border: 0; border-left: 3px solid var(--violet);
+  background: var(--ink); border-radius: 0 10px 10px 0; max-height: 540px; overflow: auto;
+}
+.dgm-source code { color: var(--text-soft); background: none; border: 0; padding: 0; }
+[hidden] { display: none !important; }
+
 /* Callouts ---------------------------------------------------------------- */
 .note {
   border-left: 3px solid var(--accent, var(--cyan));
diff --git a/docs/deployment/index.html b/docs/deployment/index.html
index a430514..d495aa5 100644
--- a/docs/deployment/index.html
+++ b/docs/deployment/index.html
@@ -140,6 +140,7 @@ <h4>Rotate a secret</h4>
     </div>
   </footer>
 
-  <script type="module" src="assets/mermaid-init.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <script src="assets/docs.js"></script>
 </body>
 </html>
diff --git a/docs/deployment/pipeline.html b/docs/deployment/pipeline.html
index a03ef4a..0802f5a 100644
--- a/docs/deployment/pipeline.html
+++ b/docs/deployment/pipeline.html
@@ -146,6 +146,7 @@ <h2>Where the data goes</h2>
     </div>
   </footer>
 
-  <script type="module" src="assets/mermaid-init.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <script src="assets/docs.js"></script>
 </body>
 </html>
diff --git a/docs/deployment/security.html b/docs/deployment/security.html
index 9b4964f..d9652bf 100644
--- a/docs/deployment/security.html
+++ b/docs/deployment/security.html
@@ -98,7 +98,7 @@ <h2>What the deployer can — and can’t — do</h2>
         <thead><tr><th>Role</th><th>Grants</th><th>Why it’s needed</th></tr></thead>
         <tbody>
           <tr><td><code>cloudbuild.builds.editor</code></td><td>Submit / run builds</td><td>Trigger the image build</td></tr>
-          <tr><td><code>storage.objectAdmin</code> + bucket <code>storage.admin</code></td><td>Write to the staging bucket</td><td>Upload build source</td></tr>
+          <tr><td><code>storage.admin</code> <span class="pill">project</span></td><td>Bucket get/list + object write</td><td><code>builds submit</code> stages source (needs project-level bucket access)</td></tr>
           <tr><td><code>serviceusage.serviceUsageConsumer</code></td><td>Use project APIs</td><td>Required for <code>builds submit</code></td></tr>
           <tr><td><code>artifactregistry.writer</code></td><td>Read/write images</td><td>Reference the pushed image on deploy</td></tr>
           <tr><td><code>run.admin</code></td><td>Manage Cloud Run</td><td>Create revisions, set public access</td></tr>
@@ -158,6 +158,7 @@ <h3>Injected, not baked</h3>
     </div>
   </footer>
 
-  <script type="module" src="assets/mermaid-init.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <script src="assets/docs.js"></script>
 </body>
 </html>
diff --git a/docs/deployment/tradeoffs.html b/docs/deployment/tradeoffs.html
index 3d0b409..172af4c 100644
--- a/docs/deployment/tradeoffs.html
+++ b/docs/deployment/tradeoffs.html
@@ -104,6 +104,7 @@ <h2>The throughline</h2>
     </div>
   </footer>
 
-  <script type="module" src="assets/mermaid-init.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
+  <script src="assets/docs.js"></script>
 </body>
 </html>