@luckydraw/cumulus 1.0.0 → 1.0.2

package/dist/gateway/static/widget.js

@@ -409,6 +409,19 @@
     '.blex-block-container[data-blex-ready="true"] {',
     '  min-height: auto;',
     '}',
+    /* Raw-fence fallback: shown when nothing claims the container (user message,
+       changelog, or blex.min.js failed to load). Better a visible fence than the
+       blank rectangle min-height used to produce. */
+    '.blex-fallback {',
+    '  margin: 0; padding: 0.6em 0.8em;',
+    '  background: rgba(255,255,255,0.04);',
+    '  border: 1px solid rgba(255,255,255,0.08);',
+    '  border-radius: 8px;',
+    '  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;',
+    '  font-size: 0.82em; line-height: 1.45;',
+    '  white-space: pre-wrap; word-break: break-word;',
+    '  opacity: 0.85;',
+    '}',
     /* Blex CSS isolation — revert widget resets inside blex blocks */
     '.blex-block-container * { margin: revert; padding: revert; line-height: revert; list-style: revert; border-spacing: revert; border: revert; }',
     '.blex-block-container { isolation: isolate; }',
@@ -2037,8 +2050,8 @@
 
   // ── Blex Integration ─────────────────────────────────────────────────────
 
-  // WeakMap: DOM element -> BlockHandle[] for lifecycle management
-  var blexHandles = typeof WeakMap !== 'undefined' ? new WeakMap() : null;
+  // Handle lifecycle (element -> BlockHandle[]) lives in blex-render.js — one
+  // owner, so destroy() cannot miss handles the other side created.
 
   // Per-thread store for blex interaction values (poll answers, confirm clicks, etc.)
   // Key: "threadName" → Map<"msgTimestamp:blockIdx", interactionValue>
@@ -2189,136 +2202,99 @@
     });
   }
 
-  // Extract ~~~blex:TYPE\n{json}\n~~~ fences from text
-  // Returns { text: string (with placeholders), blocks: Array<{type, json, idx}> }
+  // ── Shared renderer seam (task 131) ────────────────────────────────────────
+  //
+  // Extraction, placeholder markup, block rendering and handle lifecycle live in
+  // /blex-render.js — ONE implementation shared with the web-app-agent kit and
+  // any embedding app. chat.html loads it before this file.
+  //
+  // The EMBEDDED widget (a bare <script src="/widget.js"> on a third-party page)
+  // loads neither blex.min.js nor blex-render.js, and never has — blex has only
+  // ever worked on /chat. There, fences degrade to literal text, which is what
+  // an author who typed one would expect to see.
+  function blexCore() {
+    return typeof CumulusBlexRender !== 'undefined' ? CumulusBlexRender : null;
+  }
+
+  // Fenced-code regex, sourced from the shared module so the blex extractor and
+  // Phase 1 of renderMarkdown cannot disagree about where a code block starts —
+  // a fence falling through that gap is exactly the bug this seam closes.
+  function codeFenceRe() {
+    var core = blexCore();
+    return new RegExp(core ? core.CODE_FENCE_SRC : '```([^\\n`]*)\\n([\\s\\S]*?)```', 'g');
+  }
+
   function extractBlexBlocks(text) {
-    var blocks = [];
-    var BLEX_PREFIX = '\x00BLEX_';
-    var replaced = text.replace(/~~~blex:(\w[\w-]*)\n([\s\S]*?)\n~~~/g, function (_, type, json) {
-      var idx = blocks.length;
-      blocks.push({ type: type, json: json.trim(), idx: idx });
-      return BLEX_PREFIX + idx + '\x00';
-    });
-    return { text: replaced, blocks: blocks };
+    var core = blexCore();
+    return core ? core.extractBlocks(text) : { text: text, blocks: [] };
   }
 
-  // Render blex blocks into placeholder divs within a message element
-  function renderBlexBlocks(el, blexBlocks, isStreaming, msgKey, threadName) {
-    if (!blexBlocks || blexBlocks.length === 0) return;
-    if (typeof Blex === 'undefined') {
-      console.warn('[blex] Blex library not loaded — blex.min.js may have failed to fetch');
-      return;
-    }
-    var placeholders = el.querySelectorAll('.blex-block-container');
-    // Get the interaction store for this thread
+  // The widget's adapter over the shared renderer. It supplies all five members;
+  // a render-only surface (the web-app-agent kit's panel) supplies the three
+  // required ones and lets addChip/persist default to no-ops.
+  //
+  // `el` is captured because it may be DETACHED by the time an interaction fires
+  // — renderPanelMessages rebuilds the message list — which is why the panel
+  // lookup falls back to a document query.
+  function widgetBlexAdapter(el, threadName) {
     var store = threadName
       ? blexInteractionStore[threadName] || (blexInteractionStore[threadName] = {})
       : null;
 
-    placeholders.forEach(function (container) {
-      var idx = parseInt(container.getAttribute('data-blex-idx'), 10);
-      if (isNaN(idx) || idx >= blexBlocks.length) return;
-      var block = blexBlocks[idx];
-      var storeKey = msgKey ? msgKey + ':' + idx : null;
-
-      try {
-        var data = JSON.parse(block.json);
-        var blockObj = { type: block.type, id: block.type + '-' + idx, data: data };
-
-        if (isStreaming) {
-          // During streaming, show placeholder skeleton
-          Blex.renderPlaceholder(block.type, container);
-        } else {
-          // Check for previously stored interaction value
-          var renderOpts = {};
-          if (store && storeKey && store[storeKey]) {
-            renderOpts.previousValue = store[storeKey];
-          }
+    function panelFor() {
+      return (
+        el.closest('.cumulus-thread-panel') ||
+        el.closest('.cumulus-panel') ||
+        document.querySelector('.cumulus-thread-panel') ||
+        document.querySelector('.cumulus-panel')
+      );
+    }
 
-          // Final render — full interactive block
-          Blex.renderBlock(blockObj, container, renderOpts)
-            .then(function (handle) {
-              // Store handle immediately (inside async callback, not after sync loop)
-              if (blexHandles) {
-                var existing = blexHandles.get(el) || [];
-                existing.push(handle);
-                blexHandles.set(el, existing);
-              }
-              // Attach resize handle (drag to resize, double-click to reset)
-              attachBlexResize(container, threadName, storeKey);
-              if (handle && handle.onInteraction) {
-                // Wire interaction handler
-                handle.onInteraction(function (interaction) {
-                  // Store the interaction value for persistence across re-renders + refreshes
-                  if (store && storeKey && interaction.value !== undefined) {
-                    store[storeKey] = interaction.value;
-                    _flushBlexStore();
-                  }
+    return {
+      // The widget is the interactive surface: every type is allowed here.
+      allowType: function () {
+        return true;
+      },
+      getInput: function () {
+        var panel = panelFor();
+        return panel
+          ? panel.querySelector('[data-testid="webchat-input"]')
+          : document.querySelector('[data-testid="webchat-input"]');
+      },
+      getSendButton: function () {
+        var panel = panelFor();
+        return panel ? panel.querySelector('[data-testid*="send"]') : null;
+      },
+      addChip: function (interaction, handle, sourceId) {
+        addInteractionChip(panelFor(), interaction, handle, sourceId);
+      },
+      readPersisted: function (storeKey) {
+        if (!store || !storeKey) return undefined;
+        return store[storeKey] || undefined;
+      },
+      persist: function (storeKey, value) {
+        if (!store || !storeKey) return;
+        store[storeKey] = value;
+        _flushBlexStore();
+      },
+      onRendered: function (container, storeKey) {
+        attachBlexResize(container, threadName, storeKey);
+      },
+    };
+  }
 
-                  // Find the panel — try el.closest first, fall back to document query
-                  // (el may be detached from DOM if renderPanelMessages rebuilt the message list)
-                  var panel = el.closest('.cumulus-thread-panel') || el.closest('.cumulus-panel');
-                  if (!panel) {
-                    panel =
-                      document.querySelector('.cumulus-thread-panel') ||
-                      document.querySelector('.cumulus-panel');
-                  }
-                  var inputEl = panel
-                    ? panel.querySelector('[data-testid="webchat-input"]')
-                    : document.querySelector('[data-testid="webchat-input"]');
-
-                  if (inputEl && interaction.serialized) {
-                    if (interaction.immediate) {
-                      // Immediate: prepend any existing input text, then auto-send
-                      var existingText = inputEl.value.trim();
-                      inputEl.value = existingText
-                        ? existingText + '\n\n' + interaction.serialized
-                        : interaction.serialized;
-                      inputEl.dispatchEvent(new Event('input', { bubbles: true }));
-                      // Find and click the send button
-                      var sendBtn = panel ? panel.querySelector('[data-testid*="send"]') : null;
-                      if (sendBtn) {
-                        sendBtn.click();
-                      }
-                    } else {
-                      // Deferred: add to chip tray (sourceId deduplicates rapid-fire from same block)
-                      addInteractionChip(panel, interaction, handle, block.type + '-' + idx);
-                    }
-                  }
-                });
-              }
-            })
-            .catch(function (err) {
-              container.innerHTML =
-                '<pre style="color:#f66;font-size:0.85em;padding:0.5em;">Blex error: ' +
-                (err.message || err) +
-                '</pre>';
-            });
-        }
-      } catch (e) {
-        container.innerHTML =
-          '<pre style="color:#f66;font-size:0.85em;padding:0.5em;">Invalid blex JSON: ' +
-          e.message +
-          '</pre>';
-      }
+  function renderBlexBlocks(el, blexBlocks, isStreaming, msgKey, threadName) {
+    var core = blexCore();
+    if (!core) return;
+    core.render(el, blexBlocks, widgetBlexAdapter(el, threadName), {
+      msgKey: msgKey,
+      streaming: isStreaming,
     });
-
-    // Note: handles are stored inside the async .then() callback above,
-    // not here — by this point the promises haven't resolved yet.
   }
 
-  // Destroy blex block handles for a message element
   function destroyBlexBlocks(el) {
-    if (!blexHandles) return;
-    var handles = blexHandles.get(el);
-    if (handles) {
-      handles.forEach(function (h) {
-        try {
-          h.destroy();
-        } catch (e) {}
-      });
-      blexHandles.delete(el);
-    }
+    var core = blexCore();
+    if (core) core.destroy(el);
   }
 
   // Add a deferred interaction chip to the chip tray
@@ -2681,7 +2657,12 @@
     return out;
   }
 
-  function renderMarkdown(text) {
+  // opts.streaming — suppress the raw-fence fallback body while a turn is still
+  // streaming. A completed-but-not-yet-rendered fence would otherwise flash its
+  // JSON before flipping to the rendered block at `done`.
+  function renderMarkdown(text, opts) {
+    var streaming = !!(opts && opts.streaming);
+
     // Phase 0.5: Extract blex fences BEFORE code blocks
     var blexResult = extractBlexBlocks(text);
     text = blexResult.text;
@@ -2690,7 +2671,7 @@
     // Phase 1: Extract fenced code blocks — replace with unique tokens
     var codeBlocks = [];
     var TOKEN_PREFIX = '\x00CODEBLOCK_';
-    var processed = text.replace(/```([^\n`]*)\n([\s\S]*?)```/g, function (_, lang, code) {
+    var processed = text.replace(codeFenceRe(), function (_, lang, code) {
       var idx = codeBlocks.length;
       var langLabel = lang.trim() || 'text';
       var escapedCode = escapeHtml(code.replace(/\n$/, '')); // trim trailing newline
@@ -2767,10 +2748,14 @@
       return codeBlocks[parseInt(idx, 10)];
     });
 
-    // Phase 7.5: Reinsert blex block placeholders
-    html = html.replace(/\x00BLEX_(\d+)\x00/g, function (_, idx) {
-      return '<div class="blex-block-container" data-blex-idx="' + idx + '"></div>';
-    });
+    // Phase 7.5: Reinsert blex block placeholders — shared markup, so the widget
+    // and any embedding app produce byte-identical containers and one renderer
+    // can claim either. See blex-render.js for why the placeholder carries the
+    // raw fence as its body.
+    var core = blexCore();
+    if (core) {
+      html = core.insertPlaceholders(html, blexBlocks, { streaming: streaming });
+    }
 
     return { html: html, blexBlocks: blexBlocks };
   }
@@ -3760,7 +3745,7 @@
         el.className = 'cumulus-msg assistant';
         if (isStreaming) el.setAttribute('data-testid', 'webchat-streaming');
         if (content) {
-          var mdResult = renderMarkdown(content);
+          var mdResult = renderMarkdown(content, { streaming: isStreaming });
           el.innerHTML = mdResult.html;
           if (isStreaming) {
             el.innerHTML += '<span class="cumulus-cursor"></span>';
@@ -7461,7 +7446,7 @@
         el.className = 'cumulus-msg assistant';
         if (isStreaming) el.setAttribute('data-testid', 'webchat-streaming');
         if (content) {
-          var mdResult = renderMarkdown(content);
+          var mdResult = renderMarkdown(content, { streaming: isStreaming });
           el.innerHTML = mdResult.html;
           if (isStreaming) {
             el.innerHTML += '<span class="cumulus-cursor"></span>';

package/docs/web-app-agent-guide.md

@@ -92,6 +92,8 @@ Default is off; with it off every bridge surface is inert.
           "command": "node",
           "args": ["/path/to/myapp/mcp-shim.js"],
           "env": {
+            // 8080 is the fresh-install default — use your gateway's actual
+            // top-level "port" here (jq .port ~/.cumulus/gateway.config.json).
             "GATEWAY_ORIGIN": "http://127.0.0.1:8080",
             "GATEWAY_API_KEY": "sk-myapp-<same-scoped-key>",
             "BRIDGE_THREAD": "{thread}",
@@ -109,11 +111,28 @@ Namespace semantics (locked in task 097):
 - Longest prefix wins, so `myapp-demo` can be its own nested namespace under `myapp` later.
 - The scoped key is **confined**: it can read/write only `myapp-*` threads, gets an empty list from every enumeration surface (`/api/threads`, `/api/agents`, dashboard), and is rejected (403) everywhere else.
 
-### 2.3 Create the base thread config
+### 2.3 Create the thread configs — two of them, and the second is the one people miss
 
-Visitor threads inherit their config from the base by **prefix-fallback** (task 098): a turn on `myapp-a3f8c2d1` that has no exact `myapp-a3f8c2d1.config.json` reads `myapp.config.json` instead. Writes stay exact, so a visitor session can never mutate the base.
+Config is resolved by **prefix-fallback** (task 098): a turn strips one trailing `-segment` at a time and takes the longest match. Writes are always exact, so a visitor session can never mutate a config it inherited.
 
-`~/.cumulus/threads/myapp.config.json` (real Pursuit example):
+Your app has **two** thread configs, because it has two kinds of thread:
+
+| File                  | Applies to                              | Typical shape             |
+| --------------------- | --------------------------------------- | ------------------------- |
+| `myapp.config.json`   | your own management thread, `myapp`     | strong model, high effort |
+| `myapp-v.config.json` | **every visitor**, `myapp-v-<deviceId>` | small fast model          |
+
+The `-v` layer is not decoration — it is the seam that lets those two differ. The server hands the browser `THREAD_ID = "myapp-v"` and `device-thread.js` appends the device id, so resolution for `myapp-v-a3f8c2d1` goes:
+
+```
+myapp-v-a3f8c2d1.config.json   (none — visitors never get their own)
+myapp-v.config.json            <- every visitor turn
+myapp.config.json              (only if the -v file is absent)
+```
+
+**Skip the `-v` file and every anonymous visitor runs your management thread's model.** That is the single most expensive omission in this guide, and it is invisible in development: with one tester the bill looks fine.
+
+`~/.cumulus/threads/myapp.config.json`:
 
 ```json
 {
@@ -124,9 +143,34 @@ Visitor threads inherit their config from the base by **prefix-fallback** (task
 }
 ```
 
+`~/.cumulus/threads/myapp-v.config.json`:
+
+```json
+{
+  "projectDir": "/home/you/projects/myapp",
+  "model": "claude",
+  "claudeModel": "claude-haiku-4-5",
+  "effort": "medium",
+  "alwaysInclude": ["docs/myapp-system-prompt.md"],
+  "disallowedTools": ["AskUserQuestion"]
+}
+```
+
 - `projectDir` — the working directory for the agent's turns (where `alwaysInclude` paths resolve).
-- `alwaysInclude` — the app's **system prompt document**: what the app is, how to talk to its users, when to use which commands, tone. This is where the agent's product knowledge and persona live.
-- `model` / `effort` — per-app quality/latency dial.
+- `alwaysInclude` — the app's **system prompt document**: what the app is, how to talk to its users, when to use which commands, tone. This is where the agent's product knowledge and persona live. Usually the same document for both threads.
+- `model` / `effort` / `claudeModel` — the per-thread quality, latency and cost dial. `claudeModel` pins the specific Claude model; leave it out to follow the gateway default.
+- `disallowedTools` — on visitor threads, strip `AskUserQuestion`: there is no operator on the other end, so a turn that asks one hangs.
+
+Both files ship as editable examples in the kit (`thread-config.example.json`, `thread-config.visitor.example.json`), with a one-command applier:
+
+```bash
+GATEWAY_ORIGIN=https://gw.example.com GATEWAY_ADMIN_KEY=sk-... \
+  node agent/apply-thread-configs.mjs --namespace myapp
+```
+
+Use the **admin** key: a namespace covers `myapp-*`, so the app's scoped key can write `myapp-v` but is refused (403) on the bare `myapp` base thread. Note that the config API applies a whitelist — `projectDir`, `template`, `model`, `effort`, `claudeModel`, `contextLimit` — so `alwaysInclude` and `disallowedTools` must be added to the file on the gateway host. (That is deliberate: `alwaysInclude` plus `projectDir` would let a scoped key read an arbitrary file into its own prompt.) The applier reads each config back and names anything that did not stick, so the gap is visible rather than silent.
+
+No gateway reload is needed — thread config is read per turn.
 
 ### 2.4 Verify
 
@@ -191,6 +235,7 @@ The front end then calls `AgentStart()` once the config arrives, and `AgentStop(
 Notes:
 
 - **Yes, the scoped key reaches the browser.** That is the design: it is worthless outside `myapp-*`, can enumerate nothing, and each visitor's thread name is its own secret. Ship only the namespace-scoped key — never an admin key.
+- **Enumeration fails as `200` + empty, not `403`.** `/api/threads` and `/api/agents` answer `200 {"threads":[]}` to a scoped key even when the namespace holds hundreds of threads — a scoped caller already knows the one name it needs, and listing siblings would hand out every other visitor's capability. `403` is reserved for reaching _outside_ the namespace. Worth knowing if your client branches on status.
 - **Gate it on a session anyway.** Pursuit takes the older route and injects the key into `<head>` at serve time, which puts it in public HTML, in view-source, and in any intermediary cache. It works, and the blast radius is bounded by the namespace — but a session-gated endpoint is strictly better and costs one route. Use it for new apps.
 - In production, pass the key via a systemd drop-in (`Environment=MYAPP_API_KEY=...`), not a file in the repo.
 - `THREAD_ID` is the **base name**; the browser appends the per-device suffix (§4.1). Minting the suffix client-side keeps the full thread name — the actual capability — from ever travelling server → client.
@@ -292,7 +337,7 @@ MyAppAgent.register(def)   MyAppAgent.call(name, params)
 MyAppAgent.list()          MyAppAgent.manifest()   // → [{ name, description, risk, input_schema }]
 ```
 
-Risk tiers gate what happens without a human in the loop: `read` and `display` run freely, `mutate` runs but is journaled, and **`export` never auto-runs** — the gateway forces a confirm round-trip (§5.3) regardless of caller flags.
+The gate is binary, and only one tier is on the gated side. **`export` never auto-runs** — the gateway forces a confirm round-trip (§5.3) regardless of caller flags. `read`, `display` and `mutate` all dispatch immediately; the tier is advisory, riding in the tool description the model sees (`[mutate] …`) so it can weigh the call, but nothing stops it. So the question when tiering a command is not "is this irreversible?" — it is **"must a human see this before it happens?"** If yes, it is `export`, whatever the verb is.
 
 Two commands every app should register (the agent's eyes):
 
@@ -418,6 +463,54 @@ Delivery is decoupled via an event — `window.dispatchEvent(new CustomEvent('my
 
 **The `data-agent-ref` convention** is what makes captured feedback _addressable_: any element rendering a record carries `data-agent-ref="accounts:ACME-01"` (optionally `/field:owner`). Ref collection walks ancestors and contained elements of the selection/target, so "this row is wrong" arrives at the agent with the exact records attached.
 
+### 4.6b Rich blocks (`blex-mount.js`, ~110 lines)
+
+The gateway instructs **every** thread to emit `~~~blex:TYPE` fences for tabular data, status boards, metrics, charts and diagrams. That rule is in the global includes and `mergeConfigs` is union-only, so a thread cannot opt out of it. The consequence is sharp and easy to miss: **a panel with no blex renderer shows the visitor raw JSON**, and it does so for exactly the content the model was told to present richly. Two independent halves of the system, each correct, never introduced.
+
+Serve both halves — `blex.min.js` and `blex-render.js` — **from your own origin, resolved out of the installed cumulus package**, exactly as the kit already does for the bridge client (`server.js` → `/agent/blex/*`). Do not vendor them: `blex-render.js` is cumulus's own renderer, shared with the standalone chat widget, so a copy in your tree forks the seam contract and drifts the first time either side moves.
+
+> **Do not `<script src="${GATEWAY_ORIGIN}/blex.min.js">`.** That recipe is correct only when your app is on a _different_ origin from the gateway. The common production shape is the opposite: `GATEWAY_ORIGIN` is your own hostname and an edge (Caddy, Cloudflare) routes just `/bridge*` and `/api/thread/*` through to the gateway. Your hostname has no `/blex.min.js`, so the load 404s and the panel degrades silently to plain text. Serving from your own origin is correct in **both** deployments, which is why the kit does it unconditionally.
+
+**Diagrams need one extra tag: an import map.** `~~~blex:mermaid` is the one block type whose renderer loads a library at render time, and it does so with a **bare** module specifier (`await import("mermaid")`). A browser has exactly one mechanism for resolving a bare specifier — an import map — so without it the load fails and blex paints the literal string `Mermaid render error` where the fence used to be. Copy the tag from the kit's `index.html`:
+
+```html
+<script type="importmap">
+  { "imports": { "mermaid": "/agent/blex/mermaid-esm.js" } }
+</script>
+```
+
+The library it points at is the vendored mermaid bundle, served out of the installed cumulus package by the same `/agent/blex/*` route as the rest — not vendored into your tree, and not cross-origin. It is fetched only when a mermaid block actually renders (≈1MB gzipped), so pages without diagrams pay nothing.
+
+If you leave the tag out, nothing breaks and you get no error box: `blex-render.js` checks whether the document declares the mapping and, if not, leaves the fence as readable text. That check is on the **document**, not on your adapter, so it protects a surface whose adapter allows everything. Diagram colours are derived from the blex card's own background (`--blex-bg`), so they follow your theme automatically; set `window.__CUMULUS_MERMAID_THEME` to a mermaid theme name only to override it.
+
+**Correct origin cache headers are not a defence.** Measured in both directions on this project's own edge, and independently reproduced on a second one: the origin answers `/widget.js` with `Cache-Control: no-cache, must-revalidate` and the browser is handed `max-age=14400`. A CDN-class edge rewrites by **file extension**, regardless of what the origin said. So the `?v=` stamp is not belt-and-braces over your headers — behind such an edge it is the _only_ mechanism you have, and a reader who concludes "my origin already sends no-cache" will skip the one thing that would have worked. HTML is the exception (`no-cache`, `cf-cache-status: DYNAMIC`), which is exactly why an HTML-level stamp works at all — and why everything fetched _after_ the HTML is the hole.
+
+Three cache traps — the first two measured at a real Cloudflare edge, and each one makes a _correct_ deploy look broken:
+
+- **404s are cached too.** If you probe the route before it exists, the edge caches the 404 for its default TTL (measured: `max-age=14400` with `cf-cache-status: HIT`, overriding the origin's `no-cache`) — so a correct deploy keeps serving "no library" for four hours. This is nastier than stale content because it reads as "my route isn't registered", sending you to re-debug working code. After adding a route the edge has already seen 404, purge or cache-bust before concluding anything about the route.
+- **An HTML stamp only reaches what HTML requests.** A `?v=` on a `<script src>` versions that file and nothing the file goes on to fetch by itself — so a loader that pulls its own dependencies at runtime has to propagate the version token, or the parent is versioned and its children are not. The kit's `server.js` stamps every `src`/`href` it can see in the served HTML, and — because `panel.css` and the two blex scripts are attached from _inside_ JavaScript — also fills a `window.__AGENT_ASSET_V` map that those loaders consult via `window.agentAsset(url)`. **Do not lift the token off `document.currentScript.src`.** It is the obvious shortcut and it has already shipped broken in a real adopter: that token describes _your_ build, but the library it stamps comes out of the _installed cumulus package_, so a cumulus upgrade changes the bytes while your build — and therefore the URL — stands still, and browsers keep the old library indefinitely. A server-published map gives each file its **own** hash, so the upgrade busts it even though the loader's own bytes didn't move. If you test this, assert that the library URL's token moves when the **package** file changes, not when your build does; a test that rebuilds the app passes against the broken version. (This is a general rule, not a blex problem: `blex.min.js` fetches nothing by URL. Measured on `@luckydraw/blex@0.1.16` — its only dynamic `import()` is the bare `"mermaid"` specifier above, `Chart.js v4.5.1` is inlined, and `blex-chart.min.js` is an opt-in companion global that nothing requests.)
+- **Import-map values _are_ stampable; static `import` specifiers are not.** The mermaid module URL lives in JSON inside a `<script type="importmap">`, which the server rewrites along with every `src`/`href` — so that library is versioned like any other, and it needs no runtime token map (there is only one file, so there is no loader→dependency edge at all). Static specifiers are the case that stays uncovered: `bridge-mount.js` imports `client.js`, which imports `protocol.js`; both are fetched bare. They ship from the cumulus package and change only on upgrade, and the kit serves them `no-cache, must-revalidate` — which, per the paragraph above, a CDN-class edge will override anyway. Treat these as genuinely unstamped: excluding `/agent/` from your CDN is the fix, not a precaution.
+
+(One caveat if you probe with `curl -I`: the gateway answers `HEAD` on static assets with `401` while `GET` returns `200` with `Access-Control-Allow-Origin: *`. Probe with `GET`; the asset is not auth-gated.)
+
+Drive it with an adapter. The required trio is `allowType` / `getInput` / `getSendButton`; `addChip` and `persist` are optional, **and leaving them out is what makes a surface render-only** — there is no mode flag to set.
+
+```js
+window.CumulusBlexRender.renderOnlyAdapter({
+  getInput: () => document.querySelector('[data-testid="agent-input"]'),
+  getSendButton: () => document.querySelector('[data-testid="agent-send"]'),
+});
+```
+
+`renderOnlyAdapter` denies `confirm`, `poll`, `form` and `diff`. The test the allow set is derived from is: _a type may render iff every affordance it draws either completes locally or is purely visual._ Selection in `table`/`code`/`file-tree`/`timeline`/`image` is a highlight, so a no-op is invisible. `terminal`/`svg` draw labelled buttons but the clipboard write and the object-URL download both run **before** the emit — the emit is a receipt, not the mechanism. `diff` fails the test: Apply/Reject have no local half, so on a render-only surface they are guaranteed dead buttons that read as "click to apply" — worse than not rendering, because a dead button looks alive in a way raw JSON does not.
+
+Two implementation traps:
+
+- **Extract fences before your code-block pass**, not after. Otherwise a fence someone is _showing_ inside a ``` block is eaten by the extractor and vanishes from the block that exists to display it.
+- **Do not implement deny with `unregisterBlockType`.** The registry is module-global, so unregistering `confirm` removes it for every surface sharing that module instance. Deny is a per-render gate. (Nor can you route denials to a library fallback renderer — the global bundle exports no such thing; it exists only on the ESM surface. Leaving the container unclaimed shows the raw fence, which is the honest outcome and costs nothing.)
+
+Nothing is lost by not rendering `confirm`: export-tier confirms arrive over the **bridge** as a native, audited chip (§4.3), never through message content.
+
 ### 4.7 Testability (house rules)
 
 Per the global standards: every interactive element gets a `data-testid` (`agent-panel-*`, `agent-fb-pop|input|send|caret|queue`), the message list carries `data-loading`/`aria-busy` while streaming, and `window.__PUPPET_TEST_MODE__` sets `data-test-mode` to kill animations.
@@ -483,7 +576,7 @@ Operational corollaries:
      .then(() => console.log("config OK"), e => { console.error(e.message); process.exit(1); })' "$(npm root -g)"
    ```
 
-3. Write `<app>.config.json` (projectDir, model, effort, `alwaysInclude` system-prompt doc) and the system-prompt doc itself.
+3. Write **both** thread configs — `<app>.config.json` (yours) and `<app>-v.config.json` (every visitor, cheap model) — plus the system-prompt doc they include. `node agent/apply-thread-configs.mjs` covers the API-settable fields; §2.3 says which ones it cannot.
 4. Ask the gateway admin to reload the gateway (if needed), then run the §2.4 probes.
 
 **App backend:** 5. Serve `__AGENT_CONFIG__` from a session-gated route (key from env, not the repo) — §3.1. 6. Copy `examples/web-app-agent/agent/mcp-shim.js`; point its env at your gateway + key; wire it in `extraMcpServers` with `BRIDGE_THREAD: "{thread}"`.
@@ -502,19 +595,22 @@ development and will hit on your first real day.
 
 Every path below exists in the shipped package — this is the runnable kit, not a description of someone else's repo.
 
-| Layer     | File                                                 | Role                                                      |
-| --------- | ---------------------------------------------------- | --------------------------------------------------------- |
-| Gateway   | `~/.cumulus/gateway.config.json`                     | namespace, scoped key, `executorProxy`, `extraMcpServers` |
-| Gateway   | `examples/web-app-agent/gateway.config.example.json` | the fragment to merge into it                             |
-| Gateway   | `~/.cumulus/threads/myapp-v.config.json`             | base config visitor threads inherit (model, prompt, cwd)  |
-| Gateway   | `dist/gateway/bridge/{protocol,gateway,client}.js`   | the bridge itself — cumulus-owned, never forked           |
-| Serving   | `examples/web-app-agent/server.js`                   | session-gated `/api/agent-config`                         |
-| Shim      | `examples/web-app-agent/agent/mcp-shim.js`           | manifest → MCP tools; calls → `/bridge/call`              |
-| Front end | `public/agent/device-thread.js`                      | per-visitor thread identity (16-hex)                      |
-| Front end | `public/agent/commands.js`                           | **the command registry — the file you write**             |
-| Front end | `public/agent/bridge-mount.js`                       | wires the cumulus browser client to your registry         |
-| Front end | `public/agent/chat-client.js`                        | SSE chat against `/api/thread/:name/message`              |
-| Front end | `public/agent/panel.js`, `panel.css`                 | chat window + home bar                                    |
-| Front end | `public/app.js` (`window.HostApp`)                   | the adapter commands act through — never the DOM          |
+| Layer     | File                                                    | Role                                                      |
+| --------- | ------------------------------------------------------- | --------------------------------------------------------- |
+| Gateway   | `~/.cumulus/gateway.config.json`                        | namespace, scoped key, `executorProxy`, `extraMcpServers` |
+| Gateway   | `examples/web-app-agent/gateway.config.example.json`    | the fragment to merge into it                             |
+| Gateway   | `~/.cumulus/threads/myapp.config.json`                  | YOUR management thread: strong model                      |
+| Gateway   | `~/.cumulus/threads/myapp-v.config.json`                | EVERY visitor turn: cheap model, prompt, cwd (§2.3)       |
+| Gateway   | `examples/web-app-agent/thread-config*.example.json`    | both of the above, as editable examples                   |
+| Gateway   | `examples/web-app-agent/agent/apply-thread-configs.mjs` | one-command applier for the API-settable fields           |
+| Gateway   | `dist/gateway/bridge/{protocol,gateway,client}.js`      | the bridge itself — cumulus-owned, never forked           |
+| Serving   | `examples/web-app-agent/server.js`                      | session-gated `/api/agent-config`                         |
+| Shim      | `examples/web-app-agent/agent/mcp-shim.js`              | manifest → MCP tools; calls → `/bridge/call`              |
+| Front end | `public/agent/device-thread.js`                         | per-visitor thread identity (16-hex)                      |
+| Front end | `public/agent/commands.js`                              | **the command registry — the file you write**             |
+| Front end | `public/agent/bridge-mount.js`                          | wires the cumulus browser client to your registry         |
+| Front end | `public/agent/chat-client.js`                           | SSE chat against `/api/thread/:name/message`              |
+| Front end | `public/agent/panel.js`, `panel.css`                    | chat window + home bar                                    |
+| Front end | `public/app.js` (`window.HostApp`)                      | the adapter commands act through — never the DOM          |
 
 Two pieces described in this guide are **not** in the starter kit, to keep it small: the selection/right-click feedback composer (§4.6) and a rich markdown renderer with entity chips. Both are additive — add them once the core loop works.