@luckydraw/cumulus 1.0.1 → 1.0.2

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

@@ -111,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
 {
@@ -126,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
 
@@ -429,13 +471,25 @@ Serve both halves — `blex.min.js` and `blex-render.js` — **from your own ori
 
 > **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. Measured on `@luckydraw/blex@0.1.16` — its only dynamic `import()` is the bare `"mermaid"` specifier discussed in §4.6b, `Chart.js v4.5.1` is inlined, and `blex-chart.min.js` is an opt-in companion global that nothing requests.)
-- **Static ESM `import` specifiers can't be stamped this way.** `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.
+- **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.)
 
@@ -522,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}"`.
@@ -541,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.

package/examples/web-app-agent/README.md

@@ -76,6 +76,9 @@ server.js                     your serving layer's one job: hand the scoped key
 agent/mcp-shim.js             stdio MCP server the gateway spawns per turn;
                               turns your registry into the model's tools
 gateway.config.example.json   the namespace, the scoped key, the shim
+thread-config.example.json    YOUR management thread's config
+thread-config.visitor.example.json  EVERY visitor's config — the cheap model
+agent/apply-thread-configs.mjs      one command to push both to the gateway
 
 public/index.html             the demo app
 public/app.js                 the demo app + window.HostApp (the adapter)
@@ -114,6 +117,23 @@ It loads two scripts from your own origin (`/agent/blex/…`, served out of the
 installed cumulus package — see above) at mount time, and degrades to plain
 markdown if either is unavailable. Nothing else in the kit depends on it.
 
+**Diagrams need one extra tag.** `~~~blex:mermaid` is the only block type whose
+renderer loads a library at render time, using a **bare** module specifier — and
+an import map is the one thing a browser can resolve that with. `index.html`
+carries it; keep it when you copy:
+
+```html
+<script type="importmap">
+  { "imports": { "mermaid": "/agent/blex/mermaid-esm.js" } }
+</script>
+```
+
+The vendored mermaid bundle is served by the same `/agent/blex/*` route, and only
+fetched when a diagram actually renders. Drop the tag and nothing breaks — the
+renderer checks the document for the mapping and leaves mermaid fences as
+readable text rather than painting an error box. Diagram colours follow the blex
+card's own background, so they match whatever you theme blex to.
+
 The panel is **render-only**: `confirm`, `poll`, `form` and `diff` are not
 rendered, because their buttons have no local half here and a dead "Apply"
 button reads as live in a way raw JSON does not. Denied fences stay visible as
@@ -177,7 +197,7 @@ anything.
 
 ---
 
-## The five things that are easy to get wrong
+## The six things that are easy to get wrong
 
 ### 1. The thread name is the capability
 
@@ -240,14 +260,53 @@ capability. Reads outside the namespace are the ones that `403`. Don't write a
 client that reads `200` as "I'm allowed to enumerate, there just isn't anything
 here" — it will never see a thread, and no error will tell it why.
 
-### 3. Commands act through an adapter, not the DOM
+### 3. Visitor threads need their OWN model config
+
+Your app has two kinds of thread and they should not run the same model:
+
+| File                    | Applies to                             |
+| ----------------------- | -------------------------------------- |
+| `demoapp.config.json`   | your management thread — strong model  |
+| `demoapp-v.config.json` | **every visitor** — small, fast, cheap |
+
+The `-v` is what makes that possible. `server.js` sends `THREAD_ID: 'demoapp-v'`
+and `device-thread.js` appends the device id, so a visitor lands on
+`demoapp-v-<deviceId>`. Config resolves by stripping trailing segments and taking
+the longest match:
+
+```
+demoapp-v-a3f8c2d1.config.json   (none — visitors never get their own)
+demoapp-v.config.json            <- every visitor turn
+demoapp.config.json              (only if the -v file is absent)
+```
+
+**Omit the `-v` file and every anonymous visitor runs your management thread's
+model.** It is invisible in development — with one tester the bill looks fine —
+and it is the most expensive mistake in this kit.
+
+Edit the two `thread-config*.example.json` files and push them:
+
+```bash
+GATEWAY_ORIGIN=http://127.0.0.1:8080 GATEWAY_ADMIN_KEY=sk-... \
+  node agent/apply-thread-configs.mjs --namespace demoapp
+```
+
+The **admin** key, not the app's: a namespace covers `demoapp-*`, so the scoped
+key can write `demoapp-v` but is refused on the bare `demoapp`. The config API
+takes `projectDir`, `template`, `model`, `effort`, `claudeModel` and
+`contextLimit`; `alwaysInclude` and `disallowedTools` have to be added to the file
+on the gateway host (that is deliberate — `alwaysInclude` plus `projectDir` would
+let a public scoped key read any file into its own prompt). The applier reads each
+config back and tells you exactly what didn't stick. No reload needed.
+
+### 4. Commands act through an adapter, not the DOM
 
 `window.HostApp` is the app's own actions exposed as functions. Commands call
 those. That's why validation, persistence, and re-render work identically
 whether a human or the model is driving — and why your commands survive a UI
 rewrite.
 
-### 4. Descriptions are the interface
+### 5. Descriptions are the interface
 
 The model decides what to call based entirely on the `description` string.
 Write for a reader who cannot see your UI, and say what a command is _for_, not
@@ -262,7 +321,7 @@ description: 'Set the on-screen filter so the human sees a subset. ' +
 
 The second one prevents a whole class of annoying behaviour.
 
-### 5. Pick the risk tier honestly
+### 6. Pick the risk tier honestly
 
 | tier      | meaning                                         | gated?                 |
 | --------- | ----------------------------------------------- | ---------------------- |

package/examples/web-app-agent/agent/apply-thread-configs.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/* Apply this app's two thread configs to the gateway — the base thread you work
+   in, and the '-v' sub-namespace every visitor turn inherits.
+ *
+ * WHY A SCRIPT
+ * The visitor config is the one piece of per-app setup with no UI and no obvious
+ * home: it lives in a file on the gateway host, its name encodes a namespace rule
+ * (see thread-config.visitor.example.json), and getting it wrong silently costs
+ * money — every anonymous visitor runs whatever model your management thread uses.
+ * One command, run once per app, beats a paragraph telling you to hand-write JSON
+ * in a directory you may not have shell access to.
+ *
+ *   GATEWAY_ORIGIN=http://127.0.0.1:8080 \
+ *   GATEWAY_ADMIN_KEY=sk-... \
+ *   node agent/apply-thread-configs.mjs [--namespace demoapp] [--dry-run]
+ *
+ * GATEWAY_ADMIN_KEY, not the app's scoped key: a namespace covers '<ns>-*' only,
+ * so a scoped key can write '<ns>-v' but is refused (403) on the bare '<ns>' base
+ * thread. That asymmetry is the P7 access model working, not a bug — this is an
+ * operator action.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const ORIGIN = process.env.GATEWAY_ORIGIN;
+const KEY = process.env.GATEWAY_ADMIN_KEY;
+
+/* Near-miss names fail loudly rather than falling back to a default that might be
+   somebody's real gateway — the same rule server.js applies. */
+const ALIASES = {
+  GATEWAY_URL: 'GATEWAY_ORIGIN',
+  AGENT_GATEWAY_ORIGIN: 'GATEWAY_ORIGIN',
+  GATEWAY_KEY: 'GATEWAY_ADMIN_KEY',
+  ADMIN_KEY: 'GATEWAY_ADMIN_KEY',
+  GATEWAY_API_KEY: 'GATEWAY_ADMIN_KEY (the scoped app key cannot write the base thread)',
+};
+
+function die(msg) {
+  console.error(`\n  ${msg}\n`);
+  process.exit(1);
+}
+
+for (const [wrong, right] of Object.entries(ALIASES)) {
+  if (process.env[wrong] && !(wrong === 'GATEWAY_API_KEY' && KEY)) {
+    die(`${wrong} is set but this script reads ${right}.`);
+  }
+}
+if (!ORIGIN) die('GATEWAY_ORIGIN is required (no default — it must not guess a live gateway).');
+if (!KEY) die('GATEWAY_ADMIN_KEY is required.');
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const nsFlag = args.indexOf('--namespace');
+const namespace = nsFlag !== -1 ? args[nsFlag + 1] : 'demoapp';
+if (!/^[a-z0-9][a-z0-9-]*$/i.test(namespace)) die(`invalid --namespace: ${namespace}`);
+
+/** Read an example config and drop the `_`-prefixed annotation keys. */
+function load(file) {
+  const full = path.join(ROOT, file);
+  if (!fs.existsSync(full)) die(`missing ${file}`);
+  const parsed = JSON.parse(fs.readFileSync(full, 'utf-8'));
+  return Object.fromEntries(Object.entries(parsed).filter(([k]) => !k.startsWith('_')));
+}
+
+const targets = [
+  { thread: namespace, file: 'thread-config.example.json' },
+  { thread: `${namespace}-v`, file: 'thread-config.visitor.example.json' },
+];
+
+let failed = false;
+for (const { thread, file } of targets) {
+  const config = load(file);
+  if (String(config.projectDir || '').startsWith('/absolute/path/')) {
+    die(`${file} still has the placeholder projectDir — edit it before applying.`);
+  }
+  const label = `${thread.padEnd(24)} <- ${file}`;
+  if (dryRun) {
+    console.log(`DRY RUN  ${label}\n         ${JSON.stringify(config)}`);
+    continue;
+  }
+  let res;
+  try {
+    res = await fetch(`${ORIGIN}/api/thread/${encodeURIComponent(thread)}/config`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json', 'X-API-Key': KEY },
+      body: JSON.stringify(config),
+    });
+  } catch (err) {
+    die(`cannot reach ${ORIGIN}: ${err.message}`);
+  }
+  if (res.ok) {
+    console.log(`OK       ${label}`);
+    /* The config API applies a whitelist (projectDir, template, model, effort,
+       claudeModel, contextLimit). alwaysInclude and disallowedTools are NOT in it,
+       deliberately: combined with projectDir, alwaysInclude would let a
+       namespace-scoped key — which ships in your public page — read an arbitrary
+       file into its own prompt. So rather than assume, read the config back and
+       name anything that did not stick. A silent drop here would look like a
+       working persona that was never installed. */
+    try {
+      const check = await fetch(`${ORIGIN}/api/thread/${encodeURIComponent(thread)}/config`, {
+        headers: { 'X-API-Key': KEY },
+      });
+      if (check.ok) {
+        const stored = (await check.json()) ?? {};
+        const missing = Object.keys(config).filter(k => stored[k] === undefined);
+        if (missing.length) {
+          console.log(`         not applied by the API: ${missing.join(', ')}`);
+          console.log(
+            `         add them by hand to ~/.cumulus/threads/${thread}.config.json on the`
+          );
+          console.log('         gateway host — this file is exactly those contents.');
+        }
+      }
+    } catch {
+      /* the write succeeded; a failed read-back is not worth failing over */
+    }
+  } else {
+    failed = true;
+    const body = await res.text();
+    console.error(`FAILED   ${label}\n         ${res.status} ${body.slice(0, 200)}`);
+    if (res.status === 403) {
+      console.error('         403 on the base thread means the key is namespace-scoped.');
+      console.error('         Use the gateway admin key for this one-time setup.');
+    }
+  }
+}
+
+if (failed) process.exit(1);
+if (!dryRun) {
+  console.log(
+    `\nDone. Visitor turns on ${namespace}-v-<deviceId> now read ${namespace}-v.config.json;\n` +
+      `your own ${namespace} thread is unaffected. No gateway reload needed —\n` +
+      'thread config is read per turn.'
+  );
+}

package/examples/web-app-agent/public/index.html

@@ -4,6 +4,19 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
 <title>Demo Notes — cumulus web-app agent</title>
+<!-- KEEP THIS if you want ~~~blex:mermaid diagrams to render in the panel.
+     blex's mermaid renderer resolves the bare specifier "mermaid", and an import
+     map is the only mechanism in a browser that can satisfy one. The library is
+     served out of the installed cumulus package by this app's own /agent/blex/
+     route (see server.js) — not vendored, not cross-origin. The URL is stamped
+     with a content hash at serve time.
+     Drop this tag and nothing breaks: blex-render.js checks for the mapping and
+     leaves mermaid fences as readable text instead of painting an error box. -->
+<script type="importmap">{"imports":{"mermaid":"/agent/blex/mermaid-esm.js"}}</script>
+<!-- Diagram colours are derived from the blex card's own background (the
+     --blex-bg variable), so they follow whatever you theme blex to with no
+     declaration here. Set window.__CUMULUS_MERMAID_THEME to a mermaid theme name
+     ('default' | 'dark' | 'neutral' | 'forest' | 'base') only to override it. -->
 <style>
   /* The six variables the agent panel themes itself from. Define these and
      panel.css needs no edits. */

package/examples/web-app-agent/server.js

@@ -168,9 +168,15 @@ function assetUrlToFile(pathname) {
   // blex-chart.min.js is an OPT-IN companion global (blex.min.js inlines Chart.js
   // and never fetches it). Nothing requests it today; it is allowlisted so an
   // adopter who wants it can add one script tag instead of editing this server.
+  // mermaid-esm.js is the vendored mermaid library wrapped as an ES module. It is
+  // fetched by the browser resolving the bare specifier "mermaid" through the
+  // import map in index.html — never by a script tag — so it must be served from
+  // this app's own origin like the rest.
   if (pathname.startsWith('/agent/blex/')) {
     const name = path.basename(pathname);
-    if (!STATIC_DIR || !/^(blex\.min|blex-render|blex-chart\.min)\.js$/.test(name)) return null;
+    if (!STATIC_DIR || !/^(blex\.min|blex-render|blex-chart\.min|mermaid-esm)\.js$/.test(name)) {
+      return null;
+    }
     return path.join(STATIC_DIR, name);
   }
   const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
@@ -191,16 +197,34 @@ const RUNTIME_LOADED = [
 
 const ASSET_MAP_MARKER = 'window.__AGENT_ASSET_V = {};';
 
-/** Stamp served HTML: `?v=` on every same-origin .js/.css src/href, plus the
-    version map for the runtime-loaded set. */
+/** Stamp served HTML: `?v=` on every same-origin .js/.css src/href AND on
+    import-map values, plus the version map for the runtime-loaded set.
+
+    Import maps need their own pass: the module URL lives in JSON inside a
+    `<script type="importmap">`, where the src/href rule cannot see it — and an
+    unstamped module URL is exactly the multi-hour edge staleness this mechanism
+    exists to prevent. Import-map *keys* are bare specifiers, so they cannot match
+    a pattern that requires a leading `/`. */
 function stampHtml(html) {
-  const stamped = html.replace(
-    /(\s(?:src|href)=")(\/[^"?#]+\.(?:js|css))(")/g,
-    (m, pre, url, post) => {
-      const v = assetVersion(assetUrlToFile(url));
-      return v ? `${pre}${url}?v=${v}${post}` : m;
-    }
-  );
+  const stampUrl = url => {
+    const v = assetVersion(assetUrlToFile(url));
+    return v ? `${url}?v=${v}` : undefined;
+  };
+  const stamped = html
+    .replace(/(\s(?:src|href)=")(\/[^"?#]+\.(?:js|css))(")/g, (m, pre, url, post) => {
+      const s = stampUrl(url);
+      return s ? `${pre}${s}${post}` : m;
+    })
+    .replace(
+      /(<script[^>]*type="importmap"[^>]*>)([\s\S]*?)(<\/script>)/gi,
+      (m, open, body, close) =>
+        open +
+        body.replace(/"(\/[^"?#]+\.m?js)"/g, (inner, url) => {
+          const s = stampUrl(url);
+          return s ? `"${s}"` : inner;
+        }) +
+        close
+    );
   const map = {};
   for (const url of RUNTIME_LOADED) {
     const v = assetVersion(assetUrlToFile(url));

package/examples/web-app-agent/thread-config.example.json

@@ -0,0 +1,22 @@
+{
+  "_readme": [
+    "BASE THREAD CONFIG  ->  ~/.cumulus/threads/demoapp.config.json",
+    "",
+    "This is YOUR management thread for the app — the one you talk to while",
+    "building it. It is NOT a visitor thread: a namespace covers '<ns>-*' only, so",
+    "the bare 'demoapp' name stays owned by your admin key and the app's scoped key",
+    "is rejected (403) on it.",
+    "",
+    "Give this one a strong model. Visitor turns read the sibling file",
+    "thread-config.visitor.example.json instead — see the '_readme' in there for how",
+    "the two are kept apart.",
+    "",
+    "Apply both with:  node agent/apply-thread-configs.mjs",
+    "Keys starting with '_' are annotations and are stripped before sending."
+  ],
+
+  "projectDir": "/absolute/path/to/your/app",
+  "model": "claude",
+  "effort": "high",
+  "alwaysInclude": ["docs/demoapp-system-prompt.md"]
+}

package/examples/web-app-agent/thread-config.visitor.example.json

@@ -0,0 +1,41 @@
+{
+  "_readme": [
+    "VISITOR THREAD CONFIG  ->  ~/.cumulus/threads/demoapp-v.config.json",
+    "",
+    "WHY THIS FILE EXISTS, AND WHY THE '-v' MATTERS",
+    "The server hands the browser THREAD_ID = 'demoapp-v' and device-thread.js",
+    "appends 16 hex characters, so every visitor gets 'demoapp-v-<deviceId>'.",
+    "Config is resolved by prefix-fallback: a turn on 'demoapp-v-a3f8c2d1' looks for",
+    "its own exact file, then strips one trailing '-segment' at a time and takes the",
+    "longest match:",
+    "",
+    "    demoapp-v-a3f8c2d1.config.json   (none — visitors never get their own)",
+    "    demoapp-v.config.json            <- THIS FILE. Every visitor turn.",
+    "    demoapp.config.json              (only if this file is absent)",
+    "",
+    "That middle layer is the whole point. Without it, visitor turns inherit your",
+    "management thread's config and run your expensive model for every anonymous",
+    "visitor. With it, the two are set independently and neither can affect the",
+    "other — writes are always exact, so a visitor session can never mutate this",
+    "file or the base.",
+    "",
+    "COST IS THE MAIN DIAL. Visitor traffic is unbounded and mostly shallow, so a",
+    "small fast model is usually right here even when the base thread runs a large",
+    "one. Both live gateway apps on this box do exactly that.",
+    "",
+    "Apply with:  node agent/apply-thread-configs.mjs",
+    "Keys starting with '_' are annotations and are stripped before sending."
+  ],
+
+  "projectDir": "/absolute/path/to/your/app",
+  "model": "claude",
+  "claudeModel": "claude-haiku-4-5",
+  "effort": "medium",
+  "alwaysInclude": ["docs/demoapp-system-prompt.md"],
+
+  "_disallowedTools": [
+    "Visitor-facing threads should not be able to stop and ask the operator a",
+    "question — there is nobody on the other end, and the turn would hang. Strip it:"
+  ],
+  "disallowedTools": ["AskUserQuestion"]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",
@@ -37,7 +37,7 @@
     "cumulus-gateway": "./dist/gateway/daemon.js"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc && cp -r src/gateway/static dist/gateway/static && cp node_modules/@luckydraw/blex/dist/blex.min.global.js dist/gateway/static/blex.min.js && cp node_modules/@luckydraw/blex/dist/blex-chart.min.global.js dist/gateway/static/blex-chart.min.js",
+    "build": "rm -rf dist && tsc && cp -r src/gateway/static dist/gateway/static && cp node_modules/@luckydraw/blex/dist/blex.min.global.js dist/gateway/static/blex.min.js && cp node_modules/@luckydraw/blex/dist/blex-chart.min.global.js dist/gateway/static/blex-chart.min.js && node scripts/build-mermaid-esm.mjs",
     "dev": "tsc --watch",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
@@ -88,6 +88,7 @@
     "husky": "^9.1.7",
     "ink-testing-library": "^4.0.0",
     "lint-staged": "^16.2.7",
+    "mermaid": "^10.9.8",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.54.0",