agentic-mermaid 0.1.1 → 0.2.0

package/docs/features.md

@@ -1,40 +1,36 @@
 # Features — capability inventory
 
-What Agentic Mermaid can do, organized by capability area. The npm import paths are `agentic-mermaid` and `agentic-mermaid/agent`; implementation history lives in [`project/divergences.md`](./project/divergences.md); active backlog is only [`../TODO.md`](../TODO.md).
+What Agentic Mermaid can do, organized by capability area. The npm import paths are `agentic-mermaid` and `agentic-mermaid/agent`; audit and trusted host-resource helpers remain repository tooling. Implementation history lives in [`project/divergences.md`](./project/divergences.md); active backlog is only [`../TODO.md`](../TODO.md).
 
 ## Core IR & editing loop
 
 - **Typed `ValidDiagram` IR** — parse Mermaid into a sealed, typed value.
-- **`parseMermaid(source)`** → `Result<ValidDiagram, ParseError[]>`. Never
+- **`parseRegisteredMermaid(source)`** → `Result<ValidDiagram, ParseError[]>`. Never
   throws on malformed input; structured errors.
-- **`mutate(d, op)`** — family-overloaded typed mutation. Ops per family:
-  flowchart (6), state (8), sequence (5), timeline (10), class (10), ER (7),
-  journey (10), architecture (10), xychart (8), pie (7), quadrant (7), gantt (9).
-- **`verifyMermaid(d, opts)`** — structural verification (no pixels).
+- **`mutate(d, op)`** — family-overloaded typed mutation. The generated
+  `am capabilities --json` response and SDK declaration expose the authoritative
+  operation menu for every registered family.
+- **`verifyMermaid(d, opts)`** — structural and geometric verification plus a
+  strict render-parity gate, with deterministic semantic facts available for
+  meaning-level checks.
 - **`serializeMermaid(d)`** — back to canonical source.
 - **Round-trip** — structured bodies serialize to canonical, idempotent
   source; opaque bodies preserve original indentation/comments verbatim.
-- **Narrowers** — `asFlowchart`/`asState`/`asSequence`/`asTimeline`/`asClass`/`asEr`/
-  `asJourney`/`asArchitecture`/`asXyChart`/`asPie`/`asQuadrant`/`asGantt`
-  return `null` on a non-matching or source-level/opaque body (steers agents
-  off the unsafe path).
-
-## Diagram families (12)
-
-| Family | Parse/render/round-trip | Structured mutation |
-|---|---|---|
-| Flowchart | ✅ | ✅ (6 ops) |
-| State | ✅ | ✅ (8 ops via `asState`; `<<fork>>`/notes/`--`/`classDef` → opaque) |
-| Sequence | ✅ | ✅ (5 ops; alt/loop/note ride along verbatim as segments) |
-| Timeline | ✅ | ✅ (10 ops) |
-| Class | ✅ | ✅ (10 ops) |
-| ER | ✅ | ✅ (7 ops) |
-| Journey | ✅ | ✅ (10 ops via `asJourney`) |
-| XY chart | ✅ | ✅ (8 ops via `asXyChart`) |
-| Architecture | ✅ | ✅ (10 ops via `asArchitecture`) |
-| Pie | ✅ | ✅ (7 ops via `asPie`) |
-| Quadrant | ✅ | ✅ (7 ops via `asQuadrant`) |
-| Gantt | ✅ | ✅ (9 ops via `asGantt`; calendar directives/click/comments ride along verbatim as segments) |
+- **Narrowers** — each family descriptor owns its generated SDK narrower;
+  discover the current names through `am capabilities --json`. A narrower
+  returns `null` on a non-matching or source-level/opaque body, steering agents
+  off the unsafe path without maintaining a second family roster here.
+
+## Diagram families
+
+The canonical `FamilyDescriptor` registry owns headers, discovery, examples,
+operations, rendering hooks, positioned projections, semantic roles, and
+capability evidence. Run `am capabilities --json` for the current roster and
+per-family operation shapes; the generated Section A matrix records native,
+source-preserved, diagnosed, and not-applicable capabilities without a copied
+table. `absent` belongs to the validation vocabulary but is rejected from the
+shipped syntax ledger:
+[`project/section-a-capability-report.md`](./project/section-a-capability-report.md).
 
 **Structured-or-opaque rule:** every family either has a structured body
 or preserves source verbatim. Constructs are never silently dropped.
@@ -43,27 +39,33 @@ or preserves source verbatim. Constructs are never silently dropped.
 
 Agentic Mermaid outputs **SVG, PNG, ASCII, Unicode, and JSON layout** from the same renderer foundation.
 
-- **Styles** — every SVG/PNG render accepts `style`: a full look
-  (`hand-drawn`, `excalidraw`, `pen-and-ink`, `freehand`, `watercolor`,
-  `blueprint`, `tufte`, `accessible-high-contrast`, `patent-drawing`,
-  `status-dashboard`, `ops-schematic`, `chalkboard`, `risograph`,
-  `architectural-plan`, `publication-figure`), any theme name (a theme is a
-  palette-only style), an inline JSON record, or a stack merged left → right
+- **Styles** — every SVG/PNG render accepts `style`: any registered Look or
+  Palette discovered through `knownStyleDescriptors()`, an inline JSON record,
+  or a stack merged left → right
   (`{ style: ['hand-drawn', 'dracula'] }`). `seed` re-rolls styled ink and
   never moves layout. CLI: `am render --style … --seed N`, `am styles`;
   MCP render tools take `style`/`seed`; RENDER_FAILED-gated verify means a
   clean verify proves the styled source renders. Authoring guide, schema, and
   cookbook: `docs/style-authoring.md`, `docs/schemas/style-spec.schema.json`,
-  and `docs/custom-style-cookbook.md`.
+  and `docs/custom-style-cookbook.md`. Custom font selection and resolution:
+  `docs/custom-fonts.md`.
 
 - **SVG** — `renderMermaidSVG` (`compact`, `security:'strict'`, CSS
-  variable fonts, `idPrefix` namespacing). CLI exposes `--security strict`.
-- **ASCII / Unicode** — `renderMermaidASCII` (CJK/emoji width, FE0F/ZWJ,
-  `maxWidth` wrapping, trunk-shared fanouts).
-- **PNG** — `renderMermaidPNG(source, { fitTo, background, style, seed, fontDirs, loadSystemFonts, onWarning })` or `am render diagram.mmd --format png --output diagram.png` (offline `@resvg/resvg-js`; bundled Inter — the metrics font — with DejaVu fallback plus the built-in style faces,
-  cross-runtime deterministic on same-machine x86_64/ARM64 where Node + built `dist/` are present). Characters without bundled coverage (CJK, emoji) warn loudly; supply `--font-dirs <dir>` / `fontDirs` or `--system-fonts` / `loadSystemFonts: true`.
-- **JSON layout** — `layoutMermaid` / `am render --format json`; add `--certificates` (or `layoutMermaid(d, { debug: true })`) to include opt-in graph route certificates, family edge-route certificates (class/ER/architecture/sequence), region-containment certificates (timeline/charts), V1 region/action sidecars, exact ports, and side/slot/role assignments where applicable.
-- **ASCII with metadata** — `renderMermaidASCIIWithMeta` → `{ ascii, regions, warnings, routeParity }`
+  variable fonts, all-family semantic `data-id`/`data-role` identities, typed
+  relation ARIA, and `idPrefix` namespacing for markers, filters, clip paths,
+  paints, hrefs, and ARIA references). CLI exposes `--security strict`.
+- **ASCII / Unicode** — `renderMermaidASCII` uses grapheme/display-cell geometry
+  across every family. `targetWidth` is a hard bound with typed impossible-width
+  errors; deprecated `maxWidth` remains best-effort only.
+- **PNG** — `renderMermaidPNG(source, { ...sharedRenderOptions, fitTo, background, fontDirs, loadSystemFonts, onWarning })` or `am render diagram.mmd --format png --output diagram.png` (offline `@resvg/resvg-js`; bundled Inter — the metrics font — with DejaVu fallback plus the built-in style faces,
+  cross-runtime deterministic on same-machine x86_64/ARM64 where Node + built `dist/` are present; explicit sRGB + cICP metadata with no conflicting ICC profile). Characters without bundled coverage (CJK, emoji) warn loudly; supply `--font-dirs <dir>` / `fontDirs` or `--system-fonts` / `loadSystemFonts: true`.
+  Trusted hosts can bind one registered graphical backend across SVG, native
+  PNG, and browser PNG with `createMermaidRenderer`,
+  `createMermaidPNGRenderer`, and `createMermaidBrowserPNGRenderer`; backend
+  selection is host policy and cannot be smuggled through serializable render
+  options or Styles.
+- **JSON layout** — `layoutMermaid` / `am render --format layout`; add `--certificates` (or `layoutMermaid(d, { debug: true })`) to include opt-in graph route certificates, family edge-route certificates (class/ER/architecture/sequence), region-containment certificates (timeline/charts), V1 region/action sidecars, exact ports, and side/slot/role assignments where applicable.
+- **ASCII with metadata** — `renderMermaidASCIIWithMeta` → `{ ascii, regions, actions, warnings, routeParity }`
   for TUI click-mapping.
 - **Reverse** — `asciiToMermaid` reconstructs flowchart source from ASCII
   (best-effort, lossy, structural round-trip).
@@ -73,8 +75,8 @@ Agentic Mermaid outputs **SVG, PNG, ASCII, Unicode, and JSON layout** from the s
 - **Tier 1 (structural, universal):** EMPTY_DIAGRAM, EDGE_MISANCHORED,
   OFF_CANVAS, GROUP_BREACH, UNKNOWN_SHAPE, LABEL_OVERFLOW, UNRESOLVABLE_SCHEDULE,
   RENDER_FAILED (a clean verify proves the source actually renders).
-- **Tier 2 (geometric — route tripwires for flowchart/state, anchor/overlap checks for class/ER):** NODE_OVERLAP, ROUTE_SELF_CROSS, and the route-contract tripwires ROUTE_HITCH, ROUTE_UNEXPLAINED_BEND, ROUTE_LABEL_ON_SHARED_TRUNK, ROUTE_CONTAINER_MISANCHOR, ROUTE_SHAPE_MISANCHOR, ROUTE_STALE_AFTER_NODE_MOVE.
-- **Tier 3 (lint, advisory):** DUPLICATE_EDGE, UNREACHABLE_NODE, DECISION_BRANCH_UNLABELED, COMMENT_DROPPED, UNSUPPORTED_SYNTAX, CONTENT_DROPPED_ON_ROUNDTRIP, INEFFECTIVE_CONFIG.
+- **Tier 2 (geometric — route tripwires for flowchart/state, anchor/overlap checks for class/ER):** NODE_OVERLAP, ROUTE_SELF_CROSS, and the route-contract tripwires ROUTE_HITCH, ROUTE_UNEXPLAINED_BEND, ROUTE_LABEL_ON_SHARED_TRUNK, ROUTE_SELF_LOOP_OCCUPANCY, ROUTE_CONTAINER_MISANCHOR, ROUTE_SHAPE_MISANCHOR, ROUTE_STALE_AFTER_NODE_MOVE.
+- **Tier 3 (lint and inspect-only policy):** DUPLICATE_EDGE, UNREACHABLE_NODE, DECISION_BRANCH_UNLABELED, COMMENT_DROPPED, UNSUPPORTED_SYNTAX, CONTENT_DROPPED_ON_ROUNDTRIP, INEFFECTIVE_CONFIG, LOW_CONTRAST, BRAND_CONSTRAINT_WARNING, BRAND_CONSTRAINT_ERROR. Brand constraints inspect final contrast, accent area, or monochrome role paint without repainting/relayout; only the caller-selected `action: "error"` code flips `verify.ok`.
 - **Perceptual quality** — `measureQuality` / `checkQuality` (edge
   crossings, label legibility, whitespace balance, …). See [`quality.md`](./quality.md).
 
@@ -89,7 +91,8 @@ Agentic Mermaid outputs **SVG, PNG, ASCII, Unicode, and JSON layout** from the s
 ## Security
 
 - **Strict mode** (`security:'strict'`) — zero external-fetch references in
-  the SVG (no Google Fonts `@import`).
+  the SVG (no Google Fonts `@import`) after one shared transform plus residual
+  verification policy.
 - **`verifyNoExternalRefs(svg)`** — scanner / CI gate / agent self-check.
 - No `<image>`/`<script>`/external-href injection; click directives
   sanitized. See [`../SECURITY.md`](../SECURITY.md).
@@ -99,7 +102,9 @@ Agentic Mermaid outputs **SVG, PNG, ASCII, Unicode, and JSON layout** from the s
 `render` (svg/ascii/unicode/json with multi-input results; png uses one
 input plus `--output`; `--security strict`, `--watch`), `render-markdown` (skip bad blocks),
 `parse`, `verify`, `mutate` (`--op` or `--ops`), `preview` (strict standalone HTML + optional `--open`), `format`, `describe` (text/json),
-`capabilities --json` (including `families[].editPolicy` + `families[].mutationOps`), `batch --jsonl` (including mutate),
+`capabilities --json` (including `families[].editPolicy`,
+`families[].mutationOps`, and the machine-readable `sectionA` contract matrix),
+`batch --jsonl` (including mutate),
 `llms-txt`, `init-agent`, `--agent-instructions`. `mutate` verifies before emitting source; `init-agent` writes a non-clobbering `AGENTS.md` section, root `skills/` bundle, and `.mcp.json` sample into a consumer repo.
 Exit codes 0/2/3/4; parse and verify-failure errors include structured `error.details` arrays.
 
@@ -107,21 +112,23 @@ Exit codes 0/2/3/4; parse and verify-failure errors include structured `error.de
 
 Local `agentic-mermaid-mcp` is Code Mode-first: `execute(code)` runs synchronous
 JavaScript in a local `node:vm` sandbox with a typed `mermaid.*` SDK declaration,
-plus narrow `render_png` and `describe` helpers. It supports stdio by default and
+plus narrow `describe_sdk`, `render_png`, and `describe` helpers. The initial
+Code Mode declaration carries only the core SDK; `describe_sdk` returns one
+family's mutation schema on demand. It supports stdio by default and
 HTTP/SSE via `agentic-mermaid-mcp --transport http`; local `render_png` can
 return base64 bytes or managed file/URL artifacts with MIME type, byte count, and
 SHA-256 metadata.
 
 The hosted endpoint at `https://agentic-mermaid.dev/mcp` is stateless
-Streamable HTTP. It exposes eight bounded MCP JSON-RPC tools: `execute` in a
-Cloudflare Dynamic Worker isolate, pure `render_svg` / `render_ascii` /
-`render_png` / `verify` / `describe`, and declarative `mutate` / `build` for
+Streamable HTTP. It exposes nine bounded MCP JSON-RPC tools: `execute` in a
+Cloudflare Dynamic Worker isolate, pure `describe_sdk` / `render_svg` /
+`render_ascii` / `render_png` / `verify` / `describe`, and declarative `mutate` / `build` for
 structured edits. Hosted inputs are capped at 64 KB, PNG is base64-only, and the
 endpoint is a convenience surface rather than a REST render API.
 
 ## Distribution
 
-- npm library (`agentic-mermaid` plus the `agentic-mermaid/agent` subpath) with Node-runnable bins (`am`, `agentic-mermaid`, `agentic-mermaid-mcp`).
+- npm library (`agentic-mermaid` and `agentic-mermaid/agent`) with Node-runnable bins (`am`, the package-runner alias `agentic-mermaid`, and `agentic-mermaid-mcp`).
 - **Single binary** — `bun run build:binary` → `dist/am`, standalone
   executable, no runtime dependency (#1018).
 - **llms.txt** agent-discovery digest, derived from capabilities.
@@ -132,8 +139,8 @@ endpoint is a convenience surface rather than a REST render API.
   SVG layout/ASCII; full-corpus ASCII repeated-run guard; cross-runtime guards
   exist for bun ≡ node on same-machine x86_64/ARM64 when Node + built `dist/`
   artifacts are present.
-- **Corpus gates** — 271-entry mermaid-js docs corpus + 132-case
-  MermaidSeqBench, gated in CI.
+- **Corpus gates** — pinned Mermaid documentation and MermaidSeqBench corpora,
+  gated in CI; their manifests, rather than this prose, own current counts.
 - **Benchmarks** — `eval/benchmark/RESULTS.md` (measured vs mmdc, termaid).
 - **Agent-usage validation** — `eval/agent-usage/` scenarios,
   anti-pattern linter, sandbox trace instrumentation, and stored Code Mode eval runner.

package/docs/fork-differences.md

@@ -10,7 +10,7 @@ The canonical live site is **[agentic-mermaid.dev](https://agentic-mermaid.dev/)
 - Live editor: <https://agentic-mermaid.dev/editor>
 - Family comparisons (Mermaid vs Beautiful Mermaid vs Agentic Mermaid): <https://agentic-mermaid.dev/comparisons/>
 
-Alongside the static surface (the public website, machine-readable manifests, schemas, recipes, and skill files), the Cloudflare Worker serves a stateless hosted MCP endpoint at `/mcp` (`https://agentic-mermaid.dev/mcp`) — eight tools: Code Mode `execute` in per-request Dynamic Worker isolates, the `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` pure tools, and the declarative `mutate`/`build` structured-edit tools. There is still no REST render API: `/mcp` speaks MCP JSON-RPC only.
+Alongside the static surface (the public website, machine-readable manifests, schemas, recipes, and skill files), the Cloudflare Worker serves a stateless hosted MCP endpoint at `/mcp` (`https://agentic-mermaid.dev/mcp`) — registry-checked tools: Code Mode `execute` in per-request Dynamic Worker isolates, `describe_sdk` for one family's mutation schema on demand, the `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` pure tools, and the declarative `mutate`/`build` structured-edit tools. There is still no REST render API: `/mcp` speaks MCP JSON-RPC only.
 
 GitHub Pages is no longer a deployed surface; its samples-gallery generator has been retired. The live editor is served at [agentic-mermaid.dev/editor](https://agentic-mermaid.dev/editor) and built by `scripts/site/editor.ts` (also used by `website/build.ts`), and is exercised in a real browser by `e2e/browser.test.ts`.
 
@@ -18,7 +18,7 @@ GitHub Pages is no longer a deployed surface; its samples-gallery generator has
 
 Agentic Mermaid is published as `agentic-mermaid` and adds a typed editing surface for AI agents under the `agentic-mermaid/agent` subpath export, plus an `am` CLI and an `agentic-mermaid-mcp` Code Mode MCP server (stdio plus opt-in HTTP/SSE transport with managed render artifacts). A render-only library forces an agent to regenerate the whole diagram to change one node; here, new diagrams are authored as source then parsed/verified/rendered, while existing structured diagrams go parse → narrow → mutate → verify → serialize.
 
-Twelve of the twelve families are structured-when-narrowed: flowchart (6 ops), state (8 ops via a dedicated `StateBody` and `asState`), sequence (5 ops, **segment-preserving** — notes/`alt`/`loop` blocks ride along verbatim while the ops stay live), timeline (10), class (10), ER (7), journey (14, including move_task/move_section ordering and accessibility-metadata ops), XY chart (8), architecture (10), pie (7 via `asPie`), quadrant (7 via `asQuadrant`), and Gantt (9 via `asGantt`). Any unmodeled syntax still round-trips losslessly via preserved source (opaque fallback). Layout is deterministic and verified byte-identical across processes, and `verifyMermaid` returns structured warnings in three tiers (structural, geometric, lint) plus perceptual quality metrics (`measureQuality`) covering every family. See [`AGENT_NATIVE.md`](../AGENT_NATIVE.md) and [`Instructions_for_agents.md`](../Instructions_for_agents.md). Upstream has no equivalent; for a three-way functionality view including Mermaid itself, see [`comparison.md`](./comparison.md).
+Every registered family is structured when narrowed; segment-preserving families retain unsupported statements in source order, and any whole-body fallback round-trips losslessly. Layout is deterministic and verified byte-identical across processes, and `verifyMermaid` returns structured structural, geometric, and lint warnings plus perceptual quality metrics covering every family. See [`AGENT_NATIVE.md`](../AGENT_NATIVE.md) and [`Instructions_for_agents.md`](../Instructions_for_agents.md). Upstream has no equivalent; for a three-way functionality view including Mermaid itself, see [`comparison.md`](./comparison.md).
 
 ## New and expanded diagram support
 
@@ -35,6 +35,9 @@ This fork renders a wider set of Mermaid families in both the gallery and editor
 - Pie charts (`pie`, with `showData`)
 - Quadrant charts (`quadrantChart`) — not yet rendered anywhere else in the beautiful-mermaid network
 - Gantt charts (`gantt`) with date axes, sections, dependencies, milestones, exclusions, and vertical markers
+- Mindmaps (`mindmap`) with indentation-sensitive hierarchy, shapes, icons, and classes
+- Git graphs (`gitGraph`) with deterministic replayed commits, branches, merges, and cherry-picks
+- Radar charts (`radar-beta`) — spider/star charts plotting multivariate profiles across equi-angular axes from a shared center
 
 The live editor has registry-backed example coverage for every built-in family
 (`src/__tests__/editor-examples.test.ts`). Browser E2E still spot-checks several
@@ -106,7 +109,7 @@ Users can discover fork features through:
   Mermaid.js places `a2` inside `one` and `c1` inside `three`; this fork keeps `a2`
   and `c1` at the top level (only `a1`/`c2` are inside those subgraphs). See it both
   ways: [open in Mermaid Live](https://mermaid.live/edit#pako:eNp10DELwjAQBeC_Et7cDjpmcBBXJ50kyzW5NoU2V9KEIqX_XbSoRXB87z44eDOsOIZG3clkPcWkrkcTlFLK7sryQPs1jLlqIg1eSeC1oe2Zg_txaZK1qZ6u-u98ZN48tF-JAj3HnloHjdkgee7ZQBs4ril3yWBBAcpJLvdgoVPMXCBKbjx0Td3IBfLgKPGppSZS_yYDhZvIJ7Jrk8TzOsRrj-UBwvBYkQ)
-  · [open in the fork editor](https://agentic-mermaid.dev/editor#eyJzb3VyY2UiOiJmbG93Y2hhcnQgVEJcbiAgICBjMS0tPmEyXG4gICAgc3ViZ3JhcGggb25lXG4gICAgYTEtLT5hMlxuICAgIGVuZFxuICAgIHN1YmdyYXBoIHR3b1xuICAgIGIxLS0+YjJcbiAgICBlbmRcbiAgICBzdWJncmFwaCB0aHJlZVxuICAgIGMxLS0+YzJcbiAgICBlbmQifQ==).
+  · [open in the fork editor](https://agentic-mermaid.dev/editor/#deflate:q1Yqzi8tSk5VslJKy8kvT85ILCpRCHGKyVNQUFBINtTVtUs0gnCKS5PSixILMhTy81IhIonI0ql5KWjqSsrzISJJIHVJuNVlFKVCTQRbmIxQqVQLAA).
 
   This is a deliberate divergence, not a bug: it gives deterministic
   *definition-scope* membership with no surprising re-parenting when a node is

package/docs/getting-started.md

@@ -25,8 +25,8 @@ cd agentic-mermaid && bun install && bun run build
 ## Render to SVG
 
 `renderMermaidSVG` takes Mermaid source and returns a self-contained SVG string.
-It supports all 12 diagram families (flowchart, sequence, class, ER, state, gantt,
-pie, …) — just pass the source.
+It supports every registered diagram family (including flowchart, sequence,
+class, ER, state, Gantt, Mindmap, and GitGraph) — just pass the source.
 
 ```ts
 import { renderMermaidSVG } from 'agentic-mermaid'
@@ -64,8 +64,11 @@ const png = renderMermaidPNG(`flowchart TD
 writeFileSync('diagram.png', png)
 ```
 
-`PngOptions`: `scale` (default `2`, for retina), `background`, and
-`fitTo: { width?, height? }`.
+Portable PNG controls are `scale` (default `2`, for retina), `background`, and
+the mutually exclusive `fitTo: { width? }` / `fitTo: { height? }`; the same
+controls are available through the browser adapter, CLI, and local/hosted MCP.
+Node/Bun additionally accepts trusted-host `fontDirs`, `loadSystemFonts`, and
+the library-only `onWarning` callback.
 
 ## Render to ASCII / Unicode
 
@@ -85,21 +88,22 @@ See [`ascii.md`](./ascii.md) for supported families and cell-to-region metadata.
 
 ## Theming
 
-Theme from two colors, or spread one of the 21 built-in themes. Colors are applied
+Build a palette from two colors, or select one discovered through
+`knownStyleDescriptors()` or `am styles`. Colors are applied
 as CSS variables, so the SVG stays self-contained.
 
 ```ts
-import { renderMermaidSVG, THEMES } from 'agentic-mermaid'
+import { renderMermaidSVG } from 'agentic-mermaid'
 
-// Two-color theme
+// Two-color palette
 const dark = renderMermaidSVG('flowchart TD\n  A --> B', {
   bg: '#1a1b26',
   fg: '#a9b1d6',
 })
 
-// A built-in theme (zinc-light, tokyo-night, nord, dracula, catppuccin-mocha, …)
+// A built-in palette (zinc-light, tokyo-night, nord, dracula, catppuccin-mocha, …)
 const themed = renderMermaidSVG('flowchart TD\n  A --> B', {
-  ...THEMES['tokyo-night'],
+  style: 'tokyo-night',
 })
 
 // Transparent background, for embedding on any page
@@ -109,7 +113,7 @@ const transparent = renderMermaidSVG('flowchart TD\n  A --> B', {
 ```
 
 Common `RenderOptions`: `bg`, `fg`, `font`, `transparent`, and `security`. See
-[`theming.md`](./theming.md) for custom themes and Shiki/VS Code theme import.
+[`theming.md`](./theming.md) for custom Palettes and Shiki/VS Code theme import.
 
 ### Untrusted input
 
@@ -148,7 +152,7 @@ See [`react.md`](./react.md) for the zero-flash, live-theme-switching setup.
 | SVG | `agentic-mermaid` |
 | ASCII / Unicode | `agentic-mermaid` |
 | PNG (native rasterizer) | `agentic-mermaid/agent` |
-| Themes (`THEMES`, `fromShikiTheme`) | `agentic-mermaid` |
+| Palettes (`knownStyleDescriptors`, `fromShikiTheme`) | `agentic-mermaid` |
 | Everything in one path | `agentic-mermaid/agent` |
 | Typed editing (parse/mutate/verify) | `agentic-mermaid/agent` |
 
@@ -157,15 +161,18 @@ single import path for all formats, import everything from there.
 
 ## Prefer the command line?
 
-The same renderers ship as the `am` CLI — no code required:
+The same renderers ship as the `am` CLI — no code required. After the local
+install above, use the package runner so the command resolves without a global
+install:
 
 ```bash
-am render diagram.mmd --format svg
-am render diagram.mmd --format png --output diagram.png
-am render diagram.mmd --ascii
+npx --no-install agentic-mermaid render diagram.mmd --format svg
+npx --no-install agentic-mermaid render diagram.mmd --format png --output diagram.png
+npx --no-install agentic-mermaid render diagram.mmd --format ascii
 ```
 
-Run `am --help` for the full command set.
+Run `npx --no-install agentic-mermaid --help` for the full command set. Inside
+an npm script, the shorter `am …` binary name is available automatically.
 
 ## Next steps
 

package/docs/issue-derived-test-cases.md

@@ -1,6 +1,13 @@
-# Issue-derived test-case candidates
+# Issue-derived coverage evidence
 
-These are public Mermaid / Beautiful Mermaid issues worth turning into small, educational fixtures. The goal is not to clone every upstream bug; it is to keep representative examples that teach the renderer/agent surface what users actually expect.
+Status: evidence and coverage inventory, not a fixture backlog. Root `TODO.md` is
+the sole authority for scheduled work. Uncovered fixture and heuristic ideas
+below are unscheduled unless a stable root TODO item promotes them.
+
+These public Mermaid / Beautiful Mermaid issues explain what the existing
+fixtures cover and preserve candidate evidence for future decisions. The goal is
+not to clone every upstream bug; it is to retain representative examples that
+teach the renderer/agent surface what users actually expect.
 
 ## Already covered or newly covered
 
@@ -35,7 +42,7 @@ These are public Mermaid / Beautiful Mermaid issues worth turning into small, ed
   - Why it matters: ER/class ASCII labels and compartment text are semantic content, not decoration; long labels must not silently disappear when connectors are tight.
   - Current coverage: exact ASCII/Unicode golden files cover class compartments/relationship labels and ER relationship labels. ER same-row layout now widens the inter-entity gap to preserve full labels.
 
-## High-value future fixtures
+## Candidate fixture evidence (unscheduled)
 
 - [mermaid-js/mermaid#6271 — unexpected graph direction](https://github.com/mermaid-js/mermaid/issues/6271)
   - Suggested fixture: a graph whose author order implies a clear primary direction but whose cross/back edges tempt the layout engine to flip ranks. Assert source-order progression and bounded aspect ratio.
@@ -44,7 +51,7 @@ These are public Mermaid / Beautiful Mermaid issues worth turning into small, ed
 - [Mermaid v11.3+ `@{ shape: ... }` typed node metadata](https://mermaid.js.org/syntax/flowchart.html) — **safety floor fixed as BUILD-23 / [#29](https://github.com/adewale/agentic-mermaid/issues/29); full typed-shape vocabulary remains #44**
   - Why it matters: this syntax carries the ISO 5807/ANSI X3.5 flowchart symbol vocabulary (manual input, document, delay, preparation, …); Mermaid's docs use it extensively, so agent-generated sources will contain it.
   - Current behavior (June 2026): the three issue #29 repro classes are pinned by `src/__tests__/flowchart-metadata.test.ts`; they no longer silently drop targets/edges or fabricate `shape`/`label` phantom nodes. Unsupported forms preserve source opaquely; supported label metadata renders as a conservative rectangle fallback.
-  - Future fixtures: #44 should model the full Mermaid v11 typed-shape vocabulary without weakening the no-silent-loss safety floor.
+  - Candidate coverage: #44 records the full Mermaid v11 typed-shape vocabulary without weakening the no-silent-loss safety floor; this ledger does not schedule it.
 - [Mermaid frontmatter `config.layout`/`config.look`](https://mermaid.js.org/intro/syntax-reference.html) — **wrapper-fidelity gaps found by probing the official examples, fixed as BUILD-21**
   - Why it mattered: round-tripping a diagram through the editor flattened `config:`-nested frontmatter to top-level keys Mermaid ignores (silently killing the author's layout/look request on interop), duplicated `%%{init}%%` directives into synthesized frontmatter, and dropped leading comments.
   - Current coverage: `src/__tests__/agent-wrapper-fidelity.test.ts` pins byte-verbatim wrapper round-trip (frontmatter, directives incl. multiline, leading comments, combined), mutation wrapper preservation, canonical-mode config nesting + directive folding, and the `COMMENT_DROPPED` lint matrix.
@@ -58,19 +65,17 @@ A May 2026 GitHub issue/PR search found recurring layout-quality themes in both
 - [mermaid-js/mermaid#5060 — Avoidable overlapping curves in flow-chart](https://github.com/mermaid-js/mermaid/issues/5060)
   - Fixture status: `src/__tests__/aesthetic-issue-regressions.test.ts` renders repeated parallel labeled edges and asserts distinct edge paths, zero crossings, no hard defects, and separated label boxes.
 - [mermaid-js/mermaid#6046 — subgraph links should affect positioning more than inter-graph links](https://github.com/mermaid-js/mermaid/issues/6046)
-  - Fixture idea: nested subgraphs with invisible/loose links. Assert group order follows source intent and cross-group edges do not dominate internal layout.
-- [mermaid-js/mermaid#7492 — C4 overlapping labels/text overflow/crossing arrows](https://github.com/mermaid-js/mermaid/issues/7492)
-  - Fixture idea: labels near containers. Assert text stays inside boxes and edge labels keep minimum clearance from unrelated nodes.
+  - Candidate fixture evidence: nested subgraphs with invisible/loose links; group order follows source intent and cross-group edges do not dominate internal layout.
 - [mermaid-js/mermaid#2792 — graph lines sometimes overlap boxes](https://github.com/mermaid-js/mermaid/issues/2792)
   - Fixture status: `src/__tests__/aesthetic-issue-regressions.test.ts` renders a transitive route and asserts the ugly-detector reports no edge-through-node defect.
 - [lukilabs/beautiful-mermaid#83 — TD/TB flowchart layout flipping horizontal](https://github.com/lukilabs/beautiful-mermaid/issues/83)
-  - Fixture idea: vertical process with repeated feedback edges. Assert TD/TB diagrams remain height-dominant or within a bounded aspect ratio.
+  - Candidate fixture evidence: vertical process with repeated feedback edges; TD/TB diagrams remain height-dominant or within a bounded aspect ratio.
 - [lukilabs/beautiful-mermaid#68 — fan-in groups not target-aware](https://github.com/lukilabs/beautiful-mermaid/issues/68)
-  - Fixture idea: multiple roots feeding separate targets. Assert roots cluster by target and unrelated routes do not share misleading trunks.
+  - Candidate fixture evidence: multiple roots feeding separate targets; roots cluster by target and unrelated routes do not share misleading trunks.
 - [lukilabs/beautiful-mermaid#63 — misleading edge overlap in routing](https://github.com/lukilabs/beautiful-mermaid/pull/63)
-  - Fixture idea: two fan-in edges followed by two fan-out edges. Assert an outgoing branch does not visually reuse an unrelated incoming corridor.
+  - Candidate fixture evidence: two fan-in edges followed by two fan-out edges; an outgoing branch does not visually reuse an unrelated incoming corridor.
 - [lukilabs/beautiful-mermaid#89 — CJK subgraph title layout drift](https://github.com/lukilabs/beautiful-mermaid/issues/89)
-  - Fixture idea: fullwidth group labels. Assert group header bounds account for CJK width.
+  - Candidate fixture evidence: fullwidth group labels; group header bounds account for CJK width.
 - [lukilabs/beautiful-mermaid#121 — ER/class ASCII labels truncated/overlapping](https://github.com/lukilabs/beautiful-mermaid/issues/121)
   - Fixture status: representative class/ER golden files now assert labels survive and connectors remain attached; keep this theme in the generated matrix for longer label/attribute variants.
 
@@ -100,14 +105,11 @@ deferred, and policy-out-of-scope cases remain recorded below.
   whitespace + aspect — `agent-quality.test.ts`), `#1301` (long-range Gantt
   axis labels stay clear of task bars — `gantt-layout.test.ts`), and `#1765` (activation/note/block
   clearance — `sequence-layout.test.ts`).
-- **`#7492` (C4 overlapping labels/arrows)** — no fixture yet: the C4 family
-  is not rendered. Tracked under **BUILD-6** (new upstream families); add the
-  fixture when C4 lands.
-- **`#3723` (same-rank constraint) and `#5420` (manual node positioning)** —
-  documented **won't-do by policy**, no fixture. `#3723` is "watch-only"
-  (adopt only if Mermaid core standardizes a `config:` key — see C6); `#5420`
-  is out of scope (the agent loop is the substitute — see C1). Neither is a
-  bug we can regression-guard, because not implementing them is the decision.
+- **`#3723` (same-rank constraint)** — planned under `BUILD-24` as typed
+  request/mutation metadata, not new Mermaid syntax; its fixture lands with
+  that implementation. **`#5420` (manual node positioning)** remains out of
+  scope: arbitrary coordinates and dragging are distinct from structural
+  auto-layout constraints. There is therefore no #5420 regression fixture.
 
 These guards assert "Agentic Mermaid does not exhibit the complaint," not
 "the upstream Mermaid bug is fixed" — every cited issue is a defect in
@@ -125,7 +127,7 @@ Current useful heuristics:
 - layout-quality heuristic tests for declared-direction progress (`TD`/`BT`/`LR`/`RL`), edge-vs-node collisions excluding attached endpoints, feedback-process cleanliness, root node vs top-level subgraph source order, and self-loop clearance;
 - PNG/SVG screenshot comparison for artifacts that layout JSON cannot see, such as rounded-fill raster artifacts.
 
-High-value next heuristics for layout-improvement corpora:
+Candidate heuristic evidence (unscheduled):
 
 - route corridor reuse by unrelated edge families;
 - target-aware fan-in/fan-out clustering score;
@@ -145,12 +147,17 @@ practitioner guides consistently name these as the top flowchart mistakes):
   fits issue #26 workstream 14 as an analysis fact alongside the existing
   graph entry/feedback-edge outputs, not as a hard error.
 
-These can drive a generated fixture matrix: vary direction, feedback-edge density, self-loops, parallel edges, label length, CJK labels, nested subgraphs, fan-in/fan-out shape, and styling. Each generated case should assert semantic preservation first, then one or more layout heuristics. Screenshot tests should be reserved for cases where the visual artifact is genuinely pixel/raster-level.
+If promoted through root `TODO.md`, these could drive a generated fixture matrix
+varying direction, feedback-edge density, self-loops, parallel edges, label
+length, CJK labels, nested subgraphs, fan-in/fan-out shape, and styling. Each
+case would assert semantic preservation first, then one or more layout
+heuristics; screenshot tests would be reserved for genuinely pixel/raster-level
+artifacts.
 
 ## Test-design rules for issue fixtures
 
 - Prefer smallest meaningful source examples over screenshots alone.
 - Assert semantics first: labels, edges, groups, source-preserved metadata.
-- Add screenshot/SVG regression only when geometry/visual polish is the bug.
+- Use screenshot/SVG regression only when geometry/visual polish is the bug.
 - For unsupported Mermaid syntax, assert opaque/source-preserved fallback rather than lossy normalization.
 - For security issues, assert both removal of dangerous refs and preservation of safe SVG output.

package/docs/mcp-code-mode-rationale.md

@@ -1,8 +1,8 @@
 # MCP Code Mode rationale
 
-Local `agentic-mermaid-mcp` is intentionally Code Mode first. Its primary tool is `execute(code)`, which runs synchronous JavaScript against the typed `mermaid.*` SDK in a local `node:vm` sandbox. This is a local implementation inspired by Code Mode as a product shape; it is not Cloudflare Codemode, not backed by `@cloudflare/codemode`, and not an OS/container security boundary. The local helper tools (`render_png` and `describe`) are narrow conveniences, not a second full authoring API.
+Local `agentic-mermaid-mcp` is intentionally Code Mode first. Its primary tool is `execute(code)`, which runs synchronous JavaScript against the typed `mermaid.*` SDK in a local `node:vm` sandbox. This is a local implementation inspired by Code Mode as a product shape; it is not Cloudflare Codemode, not backed by `@cloudflare/codemode`, and not an OS/container security boundary. The local helper tools (`describe_sdk`, `render_png`, and `describe`) are narrow conveniences, not a second full authoring API.
 
-There is now also a **hosted** MCP at `https://agentic-mermaid.dev/mcp` (stateless Streamable HTTP; see [`docs/project/hosted-mcp-cloudflare-plan.md`](./project/hosted-mcp-cloudflare-plan.md)). It keeps `execute` but runs agent code in a per-request Cloudflare Dynamic Worker isolate (`globalOutbound: null`, empty env, `cpuMs` budget) instead of a local `node:vm` — there the isolate configuration *is* the security boundary — and adds direct `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` tools so the common render/verify paths avoid a billable isolate, plus the declarative `mutate`/`build` tools (see below). Both share the same hardened `mermaid.*` facade; their semantics are pinned against each other by a differential test suite.
+There is now also a **hosted** MCP at `https://agentic-mermaid.dev/mcp` (stateless Streamable HTTP; see the [as-built record](./project/archive/hosted-mcp-cloudflare-plan.md)). It keeps `execute` but runs agent code in a per-request Cloudflare Dynamic Worker isolate (`globalOutbound: null`, empty env, `cpuMs` budget) instead of a local `node:vm` — there the isolate configuration *is* the security boundary — and adds `describe_sdk` plus direct `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` tools so schema discovery and common render/verify paths avoid a billable isolate, plus the declarative `mutate`/`build` tools (see below). Both share the same hardened `mermaid.*` facade; their semantics are pinned against each other by a differential test suite, with one explicit host-policy divergence: both hosted `renderMermaidSVG*` execute methods and the direct `render_svg` tool force `security: 'strict'` and `embedFontImport: false`, even if agent code asks for weaker values. Local Code Mode retains the library's caller-selectable policy.
 
 ## Why the MCP server exists
 
@@ -41,14 +41,21 @@ gets wrong through `execute`. For everything richer, use `execute`, the CLI
 
 ## What the non-Code-Mode MCP tools are for
 
-Local MCP keeps only two helpers:
+Local MCP keeps only three helpers:
 
-- `render_png(source)` exists because PNG is binary output and returning base64 from a dedicated MCP tool is simpler than putting binary handling into Code Mode snippets. For clients that cannot comfortably carry large base64 payloads, `render_png({source, output:"file"})` writes a managed local artifact and `output:"url"` returns an HTTP-served artifact when the server runs with HTTP/SSE transport.
+- `describe_sdk({ family, detail })` returns version-matched mutation operations for one family without running Code Mode. `detail: "signatures"` returns a compact menu; `detail: "fields"` returns the exact field schema. The initial `execute` declaration stays limited to the core SDK, while `mermaid.describeOps` and `mermaid.opSignatures` expose the same registry inside an execution.
+
+- `render_png(source)` exists because PNG is binary output and returning base64 from a dedicated MCP tool is simpler than putting binary handling into Code Mode snippets. Local and hosted tools share portable `scale`, `background`, and mutually exclusive `fitTo.width`/`fitTo.height` controls; local additionally accepts trusted-host `fontDirs`/`loadSystemFonts` remedies and returns deterministic configuration/font-coverage warnings. For clients that cannot comfortably carry large base64 payloads, `render_png({source, output:"file"})` writes a managed local artifact and `output:"url"` returns an HTTP-served artifact when the server runs with HTTP/SSE transport. Because those modes create managed files, the local tool is annotated as non-read-only and non-idempotent.
 - `describe(source)` exists because one-shot natural-language summaries are common for screen readers, docs, and context compaction.
 
-The hosted endpoint adds direct pure tools (`render_svg`, `render_ascii`, `render_png`, `verify`, `describe`) because every hosted `execute` spins a Dynamic Worker isolate; common render/verify calls should be ordinary Worker invocations and edge-cacheable. Hosted `mutate` and `build` are the only declarative authoring tools, and they exist to apply typed op lists with the verify-before-emit contract without asking a weaker model to write JavaScript. They do not introduce a separate mutation engine.
+The hosted endpoint adds the same direct discovery tool and direct pure tools (`render_svg`, `render_ascii`, `render_png`, `verify`, `describe`) because every hosted `execute` contacts a Dynamic Worker; schema discovery and common render/verify calls should be ordinary Worker invocations eligible for the private compute cache. Hosted `mutate` and `build` are the only declarative authoring tools, and they exist to apply typed op lists with the verify-before-emit contract without asking a weaker model to write JavaScript. They do not introduce a separate mutation engine.
+
+Direct render tools accept shared render fields only through the canonical
+nested `options` object, generated from the shared RenderOptions descriptors.
+Palette selection uses `options.style`; `theme` and top-level
+`bg`/`fg`/`style`/`seed` are not tool inputs.
 
-Local managed artifacts are generated under the server artifact directory with safe names, size limits, TTL cleanup, MIME type, byte count, and SHA-256 metadata; they are not arbitrary user-chosen file writes. Hosted `render_png` returns base64 only.
+Local managed artifacts are generated under one exclusively owned server artifact directory with safe names, per-file and aggregate limits, persisted TTL cleanup, MIME type, byte count, and SHA-256 integrity metadata; they are not arbitrary user-chosen file writes. A second live owner fails closed instead of racing a stale manifest. Hosted `render_png` returns base64 only.
 
 ## Equivalence example
 

package/docs/mcp-http-transport.md

@@ -2,9 +2,9 @@
 
 `agentic-mermaid-mcp` defaults to stdio for local MCP clients. Use HTTP/SSE only when a client needs a reachable endpoint or when PNG artifacts should be fetched by file/URL instead of returned as large base64 strings.
 
-> Looking for a zero-setup endpoint? A **hosted** MCP already runs at `https://agentic-mermaid.dev/mcp` (`claude mcp add --transport http agentic-mermaid https://agentic-mermaid.dev/mcp`). It is a different implementation — stateless Streamable HTTP, Cloudflare-backed, tools `execute`/`render_svg`/`render_ascii`/`render_png`/`verify`/`describe`/`mutate`/`build`, inputs capped at 64KB, and no file/URL PNG artifacts (base64 only). See [`docs/project/hosted-mcp-cloudflare-plan.md`](./project/hosted-mcp-cloudflare-plan.md). Run the local server below when you need file/URL artifacts, larger inputs, offline use, or your own auth.
+> Looking for a zero-setup endpoint? A **hosted** MCP already runs at `https://agentic-mermaid.dev/mcp` (`claude mcp add --transport http agentic-mermaid https://agentic-mermaid.dev/mcp`). It is a different implementation — stateless Streamable HTTP, Cloudflare-backed, tools `execute`/`describe_sdk`/`render_svg`/`render_ascii`/`render_png`/`verify`/`describe`/`mutate`/`build`, inputs capped at 64KB, and no file/URL PNG artifacts (base64 only). See the [as-built record](./project/archive/hosted-mcp-cloudflare-plan.md). Run the local server below when you need file/URL artifacts, larger inputs, offline use, or your own auth.
 >
-> **Privacy:** every hosted call (`execute`, `render_*`, `verify`, `describe`, `mutate`, `build`) sends your diagram source or code to the agentic-mermaid.dev server, and successful responses are edge-cached for up to a day. For diagrams that must not leave your machine, use the library, the CLI, or the local stdio/HTTP server on this page — the pipeline is fully local and needs no network.
+> **Privacy and caching:** every hosted call (`execute`, `render_*`, `verify`, `describe`, `mutate`, `build`) sends your diagram source or code to the agentic-mermaid.dev server. Successful deterministic pure-tool results may be reused by a private server-side Workers Cache for up to 24 hours; `execute`, `mutate`, and `build` bypass it. The JSON-RPC HTTP response itself is always `cache-control: no-store`; `x-agentic-mermaid-compute-cache` reports `hit`, `miss`, `mixed`, `bypass`, or `disabled`. For diagrams that must not leave your machine, use the library, the CLI, or the local stdio/HTTP server on this page — the pipeline is fully local and needs no network.
 
 ## Which endpoint returns plain JSON?
 
@@ -40,11 +40,11 @@ HTTP endpoints:
 |---|---|
 | `GET /health` | Readiness probe, returns `{ "ok": true }`. |
 | `GET /sse` | MCP SSE session endpoint. First event contains the `/message?sessionId=...` URL. |
-| `POST /message?sessionId=...` | JSON-RPC requests for an SSE session. The HTTP response is just `202 {"ok":true}`; the JSON-RPC response is emitted on the SSE stream as `event: message` / `data:` frames. |
+| `POST /message?sessionId=...` | JSON-RPC requests for an SSE session. Requests get `202 {"ok":true}` while the JSON-RPC response is emitted on the SSE stream; notifications get an empty `202` and no stream frame. |
 | `POST /rpc` | Direct JSON-RPC endpoint for tests/scripts/simple integrations. Replies with plain `application/json` (no SSE framing). |
 | `GET /artifacts/<name>` | Fetch managed artifacts returned by `render_png` `output: "url"`. |
 
-`/rpc` and `/message` require `content-type: application/json`; browser-simple `text/plain` form posts are rejected. Non-loopback hosts require `Authorization: Bearer <token>`.
+`/rpc` and `/message` require `content-type: application/json`; browser-simple `text/plain` form posts are rejected. Non-loopback hosts require `Authorization: Bearer <token>` on `/rpc`, `/sse`, `/message`, and `/artifacts/*`, and the same Origin check covers those routes. SSE sessions are capped (32 by default); an exhausted server returns `503` instead of retaining another session.
 
 ## Direct JSON-RPC examples: `render_png`
 
@@ -60,7 +60,9 @@ Request:
   "params": {
     "name": "render_png",
     "arguments": {
-      "source": "flowchart TD\n  A --> B"
+      "source": "flowchart TD\n  A --> B",
+      "fontDirs": ["./fonts"],
+      "loadSystemFonts": false
     }
   }
 }
@@ -84,7 +86,7 @@ Response shape:
     "content": [
       {
         "type": "text",
-        "text": "{\"ok\":true,\"png_base64\":\"iVBORw0KGgo...\"}"
+        "text": "{\"ok\":true,\"png_base64\":\"iVBORw0KGgo...\",\"warnings\":[]}"
       }
     ],
     "isError": false
@@ -92,6 +94,8 @@ Response shape:
 }
 ```
 
+`warnings` always appears. `PNG_FONT_COVERAGE` names missing CJK/emoji coverage and points to `fontDirs`/`loadSystemFonts`; source configuration diagnostics use the same deterministic warning envelope.
+
 ### File output
 
 Request:
@@ -166,7 +170,7 @@ Fetch the artifact:
 curl -L -o diagram.png 'http://127.0.0.1:3000/artifacts/<name>.png'
 ```
 
-If the server is behind a reverse proxy, set `--public-url https://example.com/artifacts` so returned URLs are externally reachable.
+If the server is behind a reverse proxy, set `--public-url https://example.com/artifacts` so returned URLs are externally reachable. The URL must be absolute HTTP(S); its origin (here `https://example.com`) is also accepted by the `/rpc`, `/sse`, `/message`, and `/artifacts/*` browser-origin guard. Other browser origins remain forbidden.
 
 ## Sample SSE flow
 
@@ -202,14 +206,16 @@ data: {"jsonrpc":"2.0","id":4,"result":{}}
 
 | Option | Default | Purpose |
 |---|---:|---|
-| `--transport stdio\|http` | `stdio` | Select stdio or HTTP/SSE transport. `--http` is an alias for `--transport http`. |
+| `--transport stdio\|http` | `stdio` | Select stdio or HTTP transport. |
 | `--host <host>` | `127.0.0.1` | HTTP bind host. Non-loopback hosts require `--auth-token`. |
 | `--port <port>` | `3000` | HTTP bind port. Use `0` for an ephemeral test port. |
 | `--artifact-dir <dir>` | OS temp dir | Directory for managed file/URL artifacts. Files use generated safe names. |
-| `--public-url <url>` | `http://<host>:<port>/artifacts` | URL prefix returned by `output: "url"`; useful behind reverse proxies. |
-| `--auth-token <token>` | unset | Bearer token required for `/rpc` and `/message` when binding non-loopback. Optional on loopback. |
+| `--public-url <url>` | `http://<host>:<port>/artifacts` | Absolute HTTP(S) prefix returned by `output: "url"`; its origin is accepted by the HTTP/SSE browser-origin guard. |
+| `--auth-token <token>` | unset | Bearer token required for every non-health HTTP route when binding non-loopback. Optional on loopback. |
 | `--max-artifact-bytes <n>` | `20971520` | Maximum bytes for a single managed artifact. |
-| `--artifact-ttl-ms <n>` | `3600000` | How long managed artifacts remain fetchable by this server process. |
+| `--max-artifact-total-bytes <n>` | `209715200` | Aggregate byte budget for unexpired managed artifacts. |
+| `--max-artifacts <n>` | `1000` | Maximum number of unexpired managed artifacts. |
+| `--artifact-ttl-ms <n>` | `3600000` | How long managed artifacts remain fetchable. |
 | `--max-rpc-body-bytes <n>` | `1048576` | Maximum HTTP JSON-RPC request body size. |
 | `--max-sandbox-timeout-ms <n>` | `30000` | Maximum `execute` timeout accepted over any transport. |
 
@@ -217,7 +223,8 @@ data: {"jsonrpc":"2.0","id":4,"result":{}}
 
 - HTTP binds to loopback by default.
 - Non-loopback binding requires `--auth-token`.
-- `/rpc` and `/message` reject non-JSON content types and cross-origin browser posts.
+- `/rpc` and `/message` reject non-JSON content types; every non-health route rejects browser origins other than the internal server or configured public origin.
 - Request bodies and artifact sizes are bounded.
-- URL/file artifacts are generated under a managed store, served only if the current process created and still tracks them, and checked against TTL on read.
+- URL/file artifacts use a persisted, integrity-checked manifest; aggregate quotas and TTL survive clean restarts, and cache headers never outlive the stored expiry.
+- Exactly one live store owns an artifact directory. A second server fails before reading or writing state, preventing stale-manifest quota bypass. After an unclean stop, remove `.agentic-mermaid-artifacts-v1.lock` only after confirming no server still uses that directory.
 - `execute(code)` still runs in local `node:vm`, not an OS/container security boundary. Do not expose HTTP/SSE to hostile users without an outer isolation layer.