agentic-mermaid 0.1.1 → 0.2.0

package/dist/mcp-cli-5J47WEY3.js

@@ -0,0 +1,17 @@
+import {
+  MCP_CLI_HELP,
+  MCP_FLAG_SPECS,
+  parseMcpCliOptions,
+  runMcpCli
+} from "./chunk-2P5FKUQC.js";
+import "./chunk-2SILJDW2.js";
+import "./chunk-FDM43XU7.js";
+import "./chunk-MYPDVZCO.js";
+import "./chunk-BJYMBT4I.js";
+export {
+  MCP_CLI_HELP,
+  MCP_FLAG_SPECS,
+  parseMcpCliOptions,
+  runMcpCli
+};
+//# sourceMappingURL=mcp-cli-5J47WEY3.js.map

package/docs/README.md

@@ -1,6 +1,6 @@
 # Agentic Mermaid documentation
 
-This directory holds the long-form documentation. The root README is intentionally short and routes readers here.
+This directory holds the long-form documentation. The root README is intentionally short and routes readers here. Consumer guides are included in the npm package; repository-only links use canonical GitHub URLs so this hub also works from an installed tarball.
 
 ## User docs
 
@@ -11,7 +11,9 @@ This directory holds the long-form documentation. The root README is intentional
 | [`diagram-families.md`](./diagram-families.md) | Supported Mermaid families, examples, and edit policy. |
 | [`theming.md`](./theming.md) | Two-color themes, built-in themes, custom themes, Shiki import. |
 | [`style-authoring.md`](./style-authoring.md) | Style model, stack semantics, field reference, rubric, and validation commands. |
-| [`custom-style-cookbook.md`](./custom-style-cookbook.md) | Complete custom style JSON files, screenshots, schema usage, and CLI commands. |
+| [`custom-style-cookbook.md`](./custom-style-cookbook.md) | Complete custom style JSON files, screenshots, schema usage, CLI commands, and the documentation-only Cupertino-, Vercel-, and Cloudflare Workers-inspired prototypes. |
+| [`design/families/style-switch-contact-sheet.html`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/style-switch-contact-sheet.html) | Self-contained interactive contact sheet for every registered family and every built-in Look/Palette Style resource. |
+| [`custom-fonts.md`](./custom-fonts.md) | How custom Styles select and resolve fonts across SVG, PNG, browser, and MCP surfaces. |
 | [`react.md`](./react.md) | Zero-flash React rendering with CSS variables. |
 | [`ascii.md`](./ascii.md) | Terminal output, ASCII vs Unicode, color modes, XY charts. |
 | [`config.md`](./config.md) | `mermaidConfig`, YAML frontmatter, and init directives. |
@@ -30,11 +32,11 @@ This directory holds the long-form documentation. The root README is intentional
 | [`agent-api-cookbook.md`](./agent-api-cookbook.md) | Copy-pasteable library/CLI/MCP recipes. |
 | [`agent-mutation-policy.md`](./agent-mutation-policy.md) | Structured-vs-source-level edit policy. |
 | [`mcp-code-mode-rationale.md`](./mcp-code-mode-rationale.md) | Why MCP is Code Mode first. |
+| [`code-mode-impact.md`](./code-mode-impact.md) | Measured client/server impact, comparison with Cloudflare and Anthropic, and operational costs. |
 | [`mcp-http-transport.md`](./mcp-http-transport.md) | Local HTTP/SSE MCP quickstart plus hosted `/mcp` call-shape notes. |
-| [`project/hosted-mcp-cloudflare-plan.md`](./project/hosted-mcp-cloudflare-plan.md) | As-built hosted MCP record: Dynamic Workers `execute`, pure tools, limits, cache, and non-goals. |
 | [`agent-workflow-examples.md`](./agent-workflow-examples.md) | Runnable MCP/CLI and improvement-loop examples. |
 | [`../skills/`](../skills/) | Agent-agnostic skill bundles. |
-| [`../skill-evals/`](../skill-evals/) | Skill eval manifest, fixtures, and benchmark instructions. |
+| [`../skill-evals/`](https://github.com/adewale/agentic-mermaid/tree/main/skill-evals) | Skill eval manifest, fixtures, and benchmark instructions. |
 
 ## Contributor / project docs
 
@@ -45,25 +47,26 @@ The design docs split into two tiers — **system** (how the engine works, cross
 
 | Doc | Purpose |
 |---|---|
-| [`design/system/`](./design/system/README.md) | **Start here.** Rendered three-stacks architecture overview (dogfooded, drift-proof) routing to the audit and design docs. |
-| [`design/system/abstraction-audit.md`](./design/system/abstraction-audit.md) | Whole-system abstraction audit: the three-stacks model and ranked issue list I1–I9. |
-| [`design/system/abstraction-recommendations.md`](./design/system/abstraction-recommendations.md) | Literature-grounded recommendations for I1–I9, with a prioritized roadmap. |
-| [`design/system/route-contracts.md`](./design/system/route-contracts.md) | Route contracts: edge classification, direct-lane proofs, certifying straightener (issue #25). |
-| [`design/system/layout-rubric.md`](./design/system/layout-rubric.md) | Deterministic layout-quality rubric: metrics, CI gates, and property oracles. |
-| [`design/system/source-preservation-ladder.md`](./design/system/source-preservation-ladder.md) | The structured\|opaque family-adoption contract (levels L0–L4). |
-| [`design/system/ugly-layouts.md`](./design/system/ugly-layouts.md) | Ugly-layout detector: catalogued failure shapes and heuristics. |
+| [`project/brand-primitives-plan.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/brand-primitives-plan.md) | Normative appearance/family-contract decision and A/B dependency/acceptance plan; live status is owned by root `TODO.md`. |
+| [`design/system/`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) | **Start here.** Current resolved-request, family-descriptor, positioned-artifact, and output-security architecture overview (dogfooded, drift-proof). |
+| [`design/system/route-contracts.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/route-contracts.md) | Route contracts: edge classification, direct-lane proofs, certifying straightener (issue #25). |
+| [`design/system/layout-rubric.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/layout-rubric.md) | Deterministic layout-quality rubric: metrics, CI gates, and property oracles. |
+| [`design/system/source-preservation-ladder.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/source-preservation-ladder.md) | The structured\|opaque family-adoption contract (levels L0–L4). |
+| [`design/mermaid-family-fidelity-audit.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/mermaid-family-fidelity-audit.md) | Mermaid 11.16 syntax accounting and Mermaid/Wikipedia visual-metaphor audit for every registered family. |
+| [`design/style-palette-compatibility.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/style-palette-compatibility.md) | Registry-derived exhaustive algebra plus complexity-aware variable-strength Style/Palette/family compatibility receipt. |
+| [`design/system/ugly-layouts.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/ugly-layouts.md) | Ugly-layout detector: catalogued failure shapes and heuristics. |
 
 ### Per-family design notes
 
 | Doc | Purpose |
 |---|---|
-| [`design/families/`](./design/families/README.md) | Per-family hub: which families have a design note, and where each family's other surfaces live. |
-| [`design/families/architecture-beta.md`](./design/families/architecture-beta.md) | `architecture-beta` diagram-type implementation notes. |
-| [`design/families/gantt.md`](./design/families/gantt.md) | Gantt support specification and compatibility boundaries. |
-| [`design/families/gantt-research.md`](./design/families/gantt-research.md) | Gantt literature review and commercial UX survey. |
-| [`design/families/journey.md`](./design/families/journey.md) | Journey diagram implementation notes. |
-| [`design/families/xychart.md`](./design/families/xychart.md) | XY chart implementation notes. |
-| [`design/families/flowchart-parser-conformance.md`](./design/families/flowchart-parser-conformance.md) | Flowchart syntax conformance catalogue and unsupported-syntax warning policy (issue #36). |
+| [`design/families/`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/README.md) | Per-family hub: which families have a design note, and where each family's other surfaces live. |
+| [`design/families/architecture-beta.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/architecture-beta.md) | `architecture-beta` diagram-type implementation notes. |
+| [`design/families/gantt.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/gantt.md) | Gantt support specification and compatibility boundaries. |
+| [`design/families/gantt-research.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/gantt-research.md) | Gantt literature review and commercial UX survey. |
+| [`design/families/journey.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/journey.md) | Journey diagram implementation notes. |
+| [`design/families/xychart.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/xychart.md) | XY chart implementation notes. |
+| [`design/families/flowchart-parser-conformance.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/flowchart-parser-conformance.md) | Flowchart syntax conformance catalogue and unsupported-syntax warning policy (issue #36). |
 
 > All per-family notes live in `design/families/` and all cross-cutting notes in `design/system/`.
 
@@ -71,16 +74,21 @@ The design docs split into two tiers — **system** (how the engine works, cross
 
 | Doc | Purpose |
 |---|---|
-| [`contributing/adding-diagram-types.md`](./contributing/adding-diagram-types.md) | How to add a Mermaid-supported diagram family. |
-| [`contributing/visual-review-evidence.md`](./contributing/visual-review-evidence.md) | Which reproducible visual artifacts are required for layout/rendering changes. |
-| [`contributing/diagram-family-citizenship.md`](./contributing/diagram-family-citizenship.md) | Enforced good-citizen checklist and matrix for family/surface drift (issue #41). |
-| [`contributing/harvesting-upstream-tests.md`](./contributing/harvesting-upstream-tests.md) | How to vendor upstream/fork test suites into an executable compatibility bench. |
-| [`contributing/releasing.md`](./contributing/releasing.md) | How to cut an npm release (GitHub Release → provenance publish) and flip the "published" copy. |
-| [`layout-characterization/README.md`](./layout-characterization/README.md) | Layout and visual testing approach: properties, contact sheets, raster contracts, and approval artifacts. |
-| [`project/divergences.md`](./project/divergences.md) | Deliberate divergences and guardrails. |
-| [`project/lessons-learned.md`](./project/lessons-learned.md) | Cumulative fork implementation narrative (loops 1–22). |
-| [`contributing/lessons-learned.md`](./contributing/lessons-learned.md) | Dated contributor process lessons (newest first). |
-| [`project/dogfooding-docs-strategy.md`](./project/dogfooding-docs-strategy.md) | How we render and pin our own docs with our own tools. |
+| [`contributing/adding-diagram-types.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/adding-diagram-types.md) | How to add a Mermaid-supported diagram family. |
+| [`contributing/visual-review-evidence.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/visual-review-evidence.md) | Which reproducible visual artifacts are required for layout/rendering changes. |
+| [`contributing/diagram-family-citizenship.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/diagram-family-citizenship.md) | Enforced good-citizen checklist and matrix for family/surface drift (issue #41). |
+| [`contributing/harvesting-upstream-tests.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/harvesting-upstream-tests.md) | How to vendor upstream/fork test suites into an executable compatibility bench. |
+| [`contributing/releasing.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/releasing.md) | How to cut an npm release (GitHub Release → provenance publish) and flip the "published" copy. |
+| [`layout-characterization/README.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/layout-characterization/README.md) | Layout and visual testing approach: properties, contact sheets, raster contracts, and approval artifacts. |
+| [`svg-semantic-contract.md`](./svg-semantic-contract.md) | Typed Scene identity, geometry, references, and accessibility contract. |
+| [`mutation-testing.md`](./mutation-testing.md) | Mutation lanes, survivor handling, and fault-sensitivity evidence. |
+| [`project/divergences.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/divergences.md) | Deliberate divergences and guardrails. |
+| [`project/lessons-learned.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/lessons-learned.md) | Evergreen engineering lessons distilled from the archived fork narrative. |
+| [`project/agent-interface-contract-audit-2026-07.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/agent-interface-contract-audit-2026-07.md) | PR #162 defect provenance, review of PRs #157/#160, testing root causes, and recurrence controls. |
+| [`project/complexity-aware-test-portfolio-plan.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/complexity-aware-test-portfolio-plan.md) | Implemented measured migration from overlapping family/style matrices to automatic complexity-aware conformance, variable-strength interaction coverage, and periodic contact-sheet review. |
+| [`contributing/lessons-learned.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/lessons-learned.md) | Dated contributor process lessons (newest first). |
+| [`project/dogfooding-docs-strategy.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/dogfooding-docs-strategy.md) | How we render and pin our own docs with our own tools. |
+| [`project/archive/`](https://github.com/adewale/agentic-mermaid/tree/main/docs/project/archive) | Status-marked landing/completion evidence and frozen historical records; never live backlog authority. |
 | [`issue-derived-test-cases.md`](./issue-derived-test-cases.md) | Issue-derived regression coverage map. |
 | [`mermaid-layout-complaints.md`](./mermaid-layout-complaints.md) | Mermaid layout complaint catalog, root causes, and coverage scorecard. |
 
@@ -89,8 +97,8 @@ The design docs split into two tiers — **system** (how the engine works, cross
 - [`../README.md`](../README.md) — landing page and quick starts.
 - [`../CHANGELOG.md`](../CHANGELOG.md) — release notes.
 - [`../SECURITY.md`](../SECURITY.md) — conventional security entrypoint.
-- [`../TODO.md`](../TODO.md) — only active backlog with unchecked boxes.
+- [`../TODO.md`](https://github.com/adewale/agentic-mermaid/blob/main/TODO.md) — only active backlog with unchecked boxes.
 - [`../Instructions_for_agents.md`](../Instructions_for_agents.md) — canonical agent guide emitted by CLI.
 - [`../AGENT_NATIVE.md`](../AGENT_NATIVE.md) — agent-native architecture/spec entrypoint.
-- [`../PRODUCT.md`](../PRODUCT.md) — canonical product brief (brand register).
-- [`../DESIGN.md`](../DESIGN.md) — canonical website design system.
+- [`../PRODUCT.md`](https://github.com/adewale/agentic-mermaid/blob/main/PRODUCT.md) — canonical product brief (brand register).
+- [`../DESIGN.md`](https://github.com/adewale/agentic-mermaid/blob/main/DESIGN.md) — canonical website design system.

package/docs/agent-api-cookbook.md

@@ -30,13 +30,13 @@ All channels expose the same core contract: parse, optionally narrow, mutate, ve
 Use direct source authoring for new diagrams. Do not construct a diagram by calling `mutate` repeatedly unless you specifically need a mutation trace.
 
 ```ts
-import { parseMermaid, verifyMermaid, renderMermaidSVG } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, verifyMermaid, renderMermaidSVG } from 'agentic-mermaid/agent'
 
 const source = `flowchart LR
   User --> Login
   Login --> Dashboard`
 
-const parsed = parseMermaid(source)
+const parsed = parseRegisteredMermaid(source)
 if (!parsed.ok) throw new Error(parsed.error.map(e => e.message).join('\n'))
 
 const verify = verifyMermaid(parsed.value)
@@ -56,9 +56,9 @@ am render diagram.mmd --format svg > diagram.svg
 ## Recipe: edit an existing flowchart safely
 
 ```ts
-import { parseMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
 
-const parsed = parseMermaid('flowchart TD\n  API --> DB')
+const parsed = parseRegisteredMermaid('flowchart TD\n  API --> DB')
 if (!parsed.ok) throw new Error('parse failed')
 
 const flow = asFlowchart(parsed.value)
@@ -92,10 +92,10 @@ am mutate flow.mmd --ops '[
 When applying several edits, keep the previous verified value. If a mutation or verification fails, return the last known-good diagram and the failure reason.
 
 ```ts
-import { parseMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid, type FlowchartMutationOp } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid, type FlowchartMutationOp } from 'agentic-mermaid/agent'
 
 export function applyFlowchartOps(source: string, ops: FlowchartMutationOp[]) {
-  const parsed = parseMermaid(source)
+  const parsed = parseRegisteredMermaid(source)
   if (!parsed.ok) return { ok: false as const, phase: 'parse', error: parsed.error }
 
   let current = asFlowchart(parsed.value)
@@ -127,9 +127,9 @@ export function applyFlowchartOps(source: string, ops: FlowchartMutationOp[]) {
 Every built-in renderable family has a typed mutation path when its modeled subset narrows successfully. Unmodeled syntax is preserved as an opaque fallback body: it still parses, verifies, renders, and serializes losslessly, but family narrowers return `null` for that particular body.
 
 ```ts
-import { parseMermaid, asFlowchart, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, asFlowchart, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
 
-const parsed = parseMermaid(source)
+const parsed = parseRegisteredMermaid(source)
 if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
 
 const flow = asFlowchart(parsed.value)
@@ -145,16 +145,16 @@ if (!flow) {
 const verify = verifyMermaid(flow)
 ```
 
-For source-level edits, preserve as much original source as possible, then run `parseMermaid` and `verifyMermaid` again before returning it.
+For source-level edits, preserve as much original source as possible, then run `parseRegisteredMermaid` and `verifyMermaid` again before returning it.
 
 ## Recipe: inspect quality without screenshots
 
 `verifyMermaid` is structural. It catches reliable warning codes and returns layout JSON; it is not a subjective aesthetics score.
 
 ```ts
-import { parseMermaid, verifyMermaid, measureQuality, layoutMermaid, analyzeMermaid } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, verifyMermaid, measureQuality, layoutMermaid, analyzeMermaid } from 'agentic-mermaid/agent'
 
-const parsed = parseMermaid(source)
+const parsed = parseRegisteredMermaid(source)
 if (!parsed.ok) throw new Error('parse failed')
 
 const verify = verifyMermaid(parsed.value, { labelCharCap: 28 })
@@ -173,15 +173,39 @@ return {
 }
 ```
 
+For a unified render plus inert action regions, use
+`renderMermaidWithActions`. ASCII and Unicode artifacts include structured
+terminal `warnings`; an `ASCII_RENDER_FAILED` condition throws instead of
+returning an empty output as a successful artifact. SVG actions are marked
+`embedded-inert` only when their target metadata is present in that SVG.
+This includes Sequence `link`/`links` actor menus as well as admitted
+Flowchart, Class, and Gantt interactions; strict SVG removes authored href
+metadata and reports those actions through the sidecar only.
+
 Route, family-edge, and region certificates are opt-in; when graph-edge or family-edge certificates are present, `sourcePort`/`targetPort` are exact endpoint anchors where the family exposes them, and `sourcePortAssignment`/`targetPortAssignment` describe side, ordered slot, slot count, and semantic role for graph routes. Timeline/chart certificates use region-containment fields instead. Debug layouts also expose V1 `regions` and source-only `actions` sidecars so agents can attach UI affordances without executing Mermaid callbacks.
 
+For a renderer-neutral hit surface, use the same API for every output:
+
+```ts
+import { renderMermaidWithActions } from 'agentic-mermaid/agent'
+
+const rendered = renderMermaidWithActions(source, {
+  format: 'png',
+  options: { fitTo: { width: 1200 } },
+})
+// rendered.output is PNG bytes; actionSurface actions reference pixel regions.
+for (const action of rendered.actionSurface.actions) {
+  if (action.region) console.log(action.target, action.disposition, action.region.bounds)
+}
+```
+
 Use render artifacts for human visual review:
 
 ```ts
 import { renderMermaidSVG, renderMermaidASCII, renderMermaidPNG } from 'agentic-mermaid/agent'
 
 const svg = renderMermaidSVG(diagram, { security: 'strict' })
-const ascii = renderMermaidASCII(diagram, { useAscii: true })
+const ascii = renderMermaidASCII(diagram, { useAscii: true, targetWidth: 80 })
 const png = renderMermaidPNG(diagram, { fitTo: { width: 1600 }, background: '#fff' })
 ```
 
@@ -191,9 +215,9 @@ Library channel:
 
 ```ts
 import { writeFileSync } from 'node:fs'
-import { parseMermaid, verifyMermaid, renderMermaidSVG, renderMermaidPNG, renderMermaidASCII } from 'agentic-mermaid/agent'
+import { parseRegisteredMermaid, verifyMermaid, renderMermaidSVG, renderMermaidPNG, renderMermaidASCII } from 'agentic-mermaid/agent'
 
-const parsed = parseMermaid(source)
+const parsed = parseRegisteredMermaid(source)
 if (!parsed.ok) throw new Error(parsed.error.map(e => e.message).join('\n'))
 
 const verify = verifyMermaid(parsed.value)
@@ -218,7 +242,7 @@ MCP channel:
 - Local MCP: use Code Mode for parse/narrow/mutate/verify/serialize.
 - Local MCP: use the `render_png` helper for base64 PNG bytes when the host needs a raster artifact.
 - Local HTTP/SSE mode: use `render_png` with `output: "file"` or `output: "url"` when the host wants a managed artifact instead of inline base64.
-- Hosted MCP: use direct `render_svg`, `render_ascii`, `render_png`, `verify`, and `describe` for one-shot work; use declarative `mutate`/`build` for straightforward op-list edits; reserve hosted `execute` for logic those tools do not express.
+- Hosted MCP: call `describe_sdk` for one family's compact op signatures or exact field schema, then use direct `render_svg`, `render_ascii`, `render_png`, `verify`, and `describe` for one-shot work; `render_ascii` accepts `targetWidth` as a hard display-cell bound and returns `ASCII_TARGET_WIDTH_IMPOSSIBLE` details when it cannot fit. Use declarative `mutate`/`build` for straightforward op-list edits; reserve hosted `execute` for logic those tools do not express.
 - Use local library/CLI/MCP for sensitive diagrams, offline work, larger inputs, or local file/URL PNG artifacts.
 
 ## Recipe: MCP Code Mode
@@ -226,7 +250,7 @@ MCP channel:
 In MCP Code Mode, do not import. The server injects `mermaid.*` as a global. Return JSON-serializable values.
 
 ```ts
-const parsed = mermaid.parseMermaid('flowchart TD\n  API --> DB')
+const parsed = mermaid.parseRegisteredMermaid('flowchart TD\n  API --> DB')
 if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
 
 const flow = mermaid.asFlowchart(parsed.value)
@@ -247,24 +271,9 @@ Code Mode constraints:
 - SDK-returned diagrams are read-only; edit through `mermaid.mutate`.
 - Binary output such as PNG should usually be produced by a narrow helper or host code, not by large Code Mode payloads. `agentic-mermaid-mcp --transport http` serves managed URL artifacts from `/artifacts/<name>`.
 
-## Mutation op crib sheet
+## Mutation operation discovery
 
-Use `am capabilities --json` for machine-readable discovery. Current typed mutation families are:
-
-| Family | Narrower | Op kinds |
-|---|---|---|
-| Flowchart | `asFlowchart` | `add_node`, `remove_node`, `rename_node`, `set_label`, `add_edge`, `remove_edge` |
-| State | `asState` | `add_state`, `remove_state`, `rename_state`, `set_state_label`, `add_transition`, `remove_transition`, `set_transition_label`, `make_composite` |
-| Sequence | `asSequence` | `add_participant`, `remove_participant`, `add_message`, `remove_message`, `set_message_text` |
-| Timeline | `asTimeline` | `set_title`, `add_section`, `remove_section`, `set_section_label`, `add_period`, `remove_period`, `set_period_label`, `add_event`, `remove_event`, `set_event_text` |
-| Class | `asClass` | `set_title`, `add_class`, `remove_class`, `rename_class`, `add_member`, `remove_member`, `add_relation`, `remove_relation`, `add_note`, `remove_note` |
-| ER | `asEr` | `add_entity`, `remove_entity`, `rename_entity`, `add_attribute`, `remove_attribute`, `add_relation`, `remove_relation` |
-| Journey | `asJourney` | `set_title`, `add_section`, `remove_section`, `set_section_label`, `add_task`, `remove_task`, `set_task_text`, `set_task_score`, `set_task_actors`, `rename_actor`, `move_task`, `move_section`, `set_accessibility_title`, `set_accessibility_description` |
-| Architecture | `asArchitecture` | `add_service`, `remove_service`, `rename_service`, `set_service_label`, `set_service_icon`, `move_service`, `add_group`, `remove_group`, `add_edge`, `remove_edge` |
-| XY chart | `asXyChart` | `set_title`, `set_x_axis`, `set_y_axis`, `add_series`, `remove_series`, `set_series_values`, `set_series_name`, `reorder_series` |
-| Pie | `asPie` | `set_title`, `set_show_data`, `add_slice`, `remove_slice`, `rename_slice`, `set_slice_value`, `reorder_slice` |
-| Quadrant | `asQuadrant` | `set_title`, `set_axis_labels`, `set_quadrant_label`, `add_point`, `remove_point`, `move_point`, `rename_point` |
-| Gantt | `asGantt` | `set_title`, `add_section`, `rename_section`, `remove_section`, `add_task`, `remove_task`, `rename_task`, `set_task_status`, `set_task_dates` |
+Use `am capabilities --json` for the registry-derived family roster, edit policy, narrower, and mutation-op names. In the library or Code Mode, use `describeOps(family)` or `opSignatures(family)` for exact fields, requiredness, enums, constraints, and defaults. Hosted MCP callers can request one family's schema with `describe_sdk`. These surfaces are generated from the same registry; this cookbook deliberately does not maintain another crib sheet.
 
 Unsupported typed mutation is a stop signal, not a prompt to fake structure. Either report the unsupported family or perform explicit source-level editing followed by parse/verify.
 
@@ -283,9 +292,9 @@ Tier 1 warnings are reliable structural/source checks. Do not suppress Tier 1 er
 | `UNRESOLVABLE_SCHEDULE` | Gantt parses but its schedule cannot resolve; render would fail |
 | `RENDER_FAILED` | Any family: verifies structurally but the strict render parser rejects the canonical source; `reason` carries the renderer error |
 
-Tier 2 warnings are advisory geometric checks — route tripwires for flowchart/state, plus boundary-anchor/overlap checks on class/ER entity boxes: `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 2 warnings are advisory geometric checks — route tripwires for flowchart/state, plus boundary-anchor/overlap checks on class/ER entity boxes: `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 warnings are advisory lint checks for common agent mistakes or source-preserved Mermaid syntax that is not fully modeled: `DUPLICATE_EDGE`, `UNREACHABLE_NODE`, `DECISION_BRANCH_UNLABELED`, `COMMENT_DROPPED`, `UNSUPPORTED_SYNTAX`, `CONTENT_DROPPED_ON_ROUNDTRIP`, `INEFFECTIVE_CONFIG` (a config field is accepted for Mermaid compatibility but has no effect on this family). They do not flip `verify.ok`, but they are worth fixing when the caller asks for clean maintainable diagrams.
+Tier 3 covers advisory lint plus caller-selected inspect-only Brand 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`. `LOW_CONTRAST` preserves authored paint and reports its foreground, final opaque background, ratio, and minimum; transparent output is not measured because its host backdrop is unknown. Brand constraints inspect final contrast, accent-area, or mono-role evidence without repainting or relayout. Advisory findings do not flip `verify.ok`; `BRAND_CONSTRAINT_ERROR` does only because the caller explicitly selected `action: "error"`.
 
 ## Common anti-patterns
 

package/docs/agent-mutation-policy.md

@@ -34,7 +34,7 @@ When a particular body does not narrow, agents are not told it can be safely edi
 Structured mutation is exposed for every built-in renderable family when its modeled subset narrows:
 
 - flowchart/state;
-- sequence (BUILD-18 — segment-preserving: participant/message ops stay live even when the diagram has Note/alt/loop/par/activate/autonumber/title, which ride along verbatim as opaque-block segments. `remove_message`/`set_message_text` indexes address only top-level messages — messages inside an opaque block are never touched. Only un-segmentable input, e.g. an unbalanced `end`, falls back to whole-body opaque);
+- sequence (segment-preserving: `alt`/`opt`/`loop`/`par` are typed fragments with read-back and mutation ops; Note/box/critical/activate/autonumber/title ride along verbatim as opaque-block segments. Top-level message indices stay separate from fragment-message indices. Only un-segmentable input, e.g. an unbalanced `end`, falls back to whole-body opaque);
 - timeline;
 - class;
 - ER;

package/docs/agent-workflow-examples.md

@@ -12,11 +12,11 @@ bun run examples/mcp-vs-cli-complex-diagrams.ts
 
 What it demonstrates:
 
-- MCP Code Mode path: `tools/call execute` runs `parseMermaid → asFlowchart → mutate[] → verifyMermaid → serializeMermaid` in one sandboxed call.
+- MCP Code Mode path: `tools/call execute` runs `parseRegisteredMermaid → asFlowchart → mutate[] → verifyMermaid → serializeMermaid` in one sandboxed call.
 - CLI path: `am mutate auth-flow.mmd --ops ops.json --json` applies the same mutation batch and verifies before emitting source.
 - The example asserts both channels produce byte-identical Mermaid source for multiple non-trivial cases: an Auth Flow with decisions/feedback loops and an Order Domain ER diagram.
 
-This is the intended local equivalence story: MCP Code Mode and CLI/library can create the same diagram. The local non-Code-Mode helpers remain narrow (`render_png`, `describe`); the hosted `/mcp` endpoint additionally offers direct pure render/verify/describe tools plus declarative `mutate`/`build` for bounded structured edits.
+This is the intended local equivalence story: MCP Code Mode and CLI/library can create the same diagram. The local non-Code-Mode helpers remain narrow (`describe_sdk`, `render_png`, `describe`); `describe_sdk` returns one family's version-matched mutation schema on demand. The hosted `/mcp` endpoint additionally offers direct pure render/verify/describe tools plus declarative `mutate`/`build` for bounded structured edits.
 
 ## Improve a diagram through an agent loop