agentic-mermaid 0.4.1 → 0.5.3

package/Instructions_for_agents.md

@@ -10,7 +10,16 @@ Do not use the hosted MCP for private diagrams; use the local library, CLI, or s
 
 ## Quick start
 
-Choose the narrowest channel. New diagrams: build with `buildMermaid(kind, ops)` — or `createMermaid(kind)` then typed mutations — and verify/render the result; author Mermaid source directly only for syntax the typed ops do not model. Existing structured diagrams: parse → narrow → mutate → verify → serialize. Code Mode/library are best for multi-step edits; CLI is best for one-shot verify/render/preview. Code Mode exposes `mermaid.*`; library users import the same names from `agentic-mermaid/agent` — including `describeOps(family)` and `opSignatures(family)`, which return each op's exact fields, required-ness, inlined enum values, and constraint/default notes (e.g. journey score `integer 1..5`, flowchart shape `default: rectangle`) so you can look up an unfamiliar op instead of guessing; use `describeMermaidFacts` / `checkMermaid` when you need semantic read-back such as `edge Processing -> [*] : done`, `member Duck +quack()`, or `task Docs start after core`. A hosted MCP at `agentic-mermaid.dev/mcp` (stateless Streamable HTTP JSON-RPC) exposes `execute` (Code Mode), `describe_sdk` (one family's mutation schema on demand), `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, and the declarative `mutate` (edit a `source`) and `build` (author from a `family`) — which apply a JSON op list and return `{ok,family,source,verify}`, prescriptive `{ok:false,…,error}` on a bad op; prefer them for structured edits and reserve `execute` for logic the ops do not express — all with 64KB input caps; the call shape is a plain POST (stateless, no initialize handshake): `POST /mcp` with `content-type: application/json` and body `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify","arguments":{"source":"flowchart TD\n  A --> B"}}}`. Prefer the local library, CLI, or a self-hosted MCP and reach for the hosted endpoint only when you cannot install. Agentic Mermaid outputs ASCII, PNG, and SVG; Unicode text and JSON layout are also available. Flowchart authoring facts: quote any label carrying punctuation (`id["HTTPS /api/sessions*"]`); `\n` inside a quoted label is a line break and canonicalizes to `<br>` on serialize; `subgraph id["Title"] … end` groups nodes; labeled and dotted edges are `A -- "label" --> B`, `A -.-> B`, and `A -. "label" .-> B`. For every other family, read that family's exact header, edge, and relationship syntax from its `example` in `am capabilities --json` (`capabilities.json` `families[].example`) rather than assuming flowchart syntax — e.g. class inheritance `Base <|-- Derived`, ER cardinality `A ||--o{ B : label`, architecture edges `api:R --> L:db`.
+<!-- BEGIN GENERATED: family-narrowing -->
+Narrowing selects a structured, typed family with an as* helper. It does not select one element or freeze layout coordinates.
+<!-- END GENERATED: family-narrowing -->
+
+Use the [library vocabulary](https://agentic-mermaid.dev/docs/api/#vocabulary)
+for family, Scene part and resolved primitive. Keep source objects distinct
+from drawing parts.
+
+<!-- complete: hosted-mcp-tools -->
+Choose the narrowest channel. <!-- BEGIN GENERATED: agent-workflow -->New diagrams: author Mermaid source directly, then parse → verify → render or return it. `buildMermaid(kind, ops)` / `createMermaid(kind)` build a diagram from typed ops when you are generating one programmatically (for example, from data). Existing structured diagrams: parse → narrow → mutate → verify → serialize.<!-- END GENERATED: agent-workflow --> Local MCP exposes `mutate` and `build` for atomic JSON edit batches; use `execute` or the library for custom logic. CLI is best for one-shot verify/render/preview. Code Mode exposes `mermaid.*`; library users import the same names from `agentic-mermaid/agent` — including `describeOps(family)` and `opSignatures(family)`, which return each op's exact fields, required-ness, inlined enum values, and constraint/default notes (e.g. journey score `finite number 1..5`, flowchart shape `default: rectangle`) so you can look up an unfamiliar op instead of guessing; use `describeMermaidFacts` / `checkMermaid` when you need semantic read-back such as `edge Processing -> [*] : done`, `member Duck +quack()`, or `task Docs start after core`. A hosted MCP at `agentic-mermaid.dev/mcp` (stateless Streamable HTTP JSON-RPC) exposes `execute` (Code Mode), `describe_sdk` (one family's mutation schema on demand), `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, and the declarative `mutate` (edit a `source`) and `build` (author from a `family`) — which apply a JSON op list and return `{ok,family,source,verify}`, prescriptive `{ok:false,…,error}` on a bad op; prefer them for structured edits and reserve `execute` for logic the ops do not express — all with 64KB input caps; the call shape is a plain POST (stateless, no initialize handshake): `POST /mcp` with `content-type: application/json` and body `{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"verify","arguments":{"source":"flowchart TD\n  A --> B"}}}`. Prefer the local library, CLI, or a self-hosted MCP and reach for the hosted endpoint only when you cannot install. Agentic Mermaid outputs ASCII, PNG, and SVG; Unicode text and JSON layout are also available. Flowchart authoring facts: quote any label carrying punctuation (`id["HTTPS /api/sessions*"]`); `\n` inside a quoted label is a line break and canonicalizes to `<br>` on serialize; `subgraph id["Title"] … end` groups nodes; labeled and dotted edges are `A -- "label" --> B`, `A -.-> B`, and `A -. "label" .-> B`. For every other family, read that family's exact header, edge, and relationship syntax from its `example` in `am capabilities --json` (`capabilities.json` `families[].example`) rather than assuming flowchart syntax — e.g. class inheritance `Base <|-- Derived`, ER cardinality `A ||--o{ B : label`, architecture edges `api:R --> L:db`.
 
 ```ts
 const source = 'flowchart TD\n  API --> DB'
@@ -29,52 +38,64 @@ if (!verify.ok) return { phase: 'verify', warnings: verify.warnings }
 return { source: mermaid.serializeMermaid(d1.value) }
 ```
 
-Blank-slate authoring stays on the typed path — no hand-written source:
+A new diagram is authored as source, parsed, and verified — no mutation ceremony:
 
 ```ts
-const built = mermaid.buildMermaid('flowchart', [
-  { kind: 'add_node', id: 'API', label: 'API' },
-  { kind: 'add_node', id: 'DB', label: 'DB' },
-  { kind: 'add_edge', from: 'API', to: 'DB' },
-], { direction: 'LR' })
-if (!built.ok) return { phase: 'build', error: built.error }
-
-const check = mermaid.verifyMermaid(built.value)
+const source = 'flowchart LR\n  API --> DB'
+const parsed = mermaid.parseRegisteredMermaid(source)
+if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
+
+const check = mermaid.verifyMermaid(parsed.value)
 if (!check.ok) return { phase: 'verify', warnings: check.warnings }
 
-return { source: mermaid.serializeMermaid(built.value) }
+return { source }
 ```
 
 Before mutating an existing diagram, use the matching narrower advertised by `am capabilities --json` or `describe_sdk` (for example, `asFlowchart` or `asState`). State diagrams own a dedicated body: `asState` narrows them — including concurrency regions, notes, `<<fork>>`/`<<join>>`/`<<choice>>`, history pseudostates, and class/inline paint — and state-shaped ops (`add_state`, `add_transition`, `make_composite`, `add_note`, `set_state_class`, …) apply; `asFlowchart` returns null on a state diagram. Sequence diagrams are segment-preserving: `alt`/`opt`/`loop`/`par` fragments are typed, their messages appear in describe/facts/verify, and fragment/branch/message mutation ops can author and edit them. Other constructs such as `Note`/`box`/`critical`/`activate`/`autonumber`/`title` ride along verbatim; top-level `remove_message`/`set_message_text` indexes remain separate from fragment messages. Only an un-segmentable sequence (e.g. an unbalanced `end`) falls back to opaque. Gantt charts are segment-preserving too: title/section/task ops stay live while calendar directives (`dateFormat`, `excludes`, …), `click` lines, and comments ride along verbatim; gantt rendering never reads the wall clock — pass `ganttToday` to draw the today marker — and the opt-in `gantt.dependencyArrows`/`gantt.criticalPath` render options overlay dependency arrows and critical-path emphasis without any new Mermaid syntax. In Code Mode, SDK-returned diagrams are read-only; structured edits must go through `mermaid.mutate`. Opaque-fallback bodies (any unmodeled syntax) round-trip losslessly as source-level bodies but do not expose structured mutation; return an unsupported-family result unless the task explicitly asks for source-level editing, then re-parse and verify before returning.
 
+For an explicitly requested source-level edit of an opaque Class or Flowchart,
+use `mermaid.mutatePreservingSource(diagram, op)` (library: the same export).
+Supported operations are Class `add_member`/`remove_member` and Flowchart
+`set_label`/`rename_node`; removal requires an unambiguous whole member line,
+and renames refuse unsupported class/style/click/href dependencies or colliding
+group identities. Save `value.source` exactly after inspecting
+`verifyMermaid(value.diagram)`. The diagram stays opaque and its portability
+warning remains; portable Mermaid export is not promised. Atomic batches use
+`applyOps({ source, ops, mode: 'source-preserving' })`, or MCP `mutate` with
+`mode: 'source-preserving'`. The editor adapter exposes programmatic
+`applyOps(source, ops, 'source-preserving')` through its worker. Unsupported or
+ambiguous ownership refuses without emitting partial edited source; builders
+do not accept this mode.
+
 ## The verify-before-commit rule
 
-Run `verifyMermaid` at every commit point — anywhere the result would be saved, sent, or shown. For new diagrams, verify the authored source. For existing diagrams, verify after mutation and before serializing. You may batch several `mutate` calls between verifications, but never serialize a `ValidDiagram` whose `verify` result you have not inspected. `verify.ok` is structural, not a visual-quality or semantic-correctness score; for task-critical meaning, inspect `describeMermaidFacts(d)` or call `checkMermaid(d, requiredFacts)` before returning.
+Run `verifyMermaid` at every commit point — anywhere the result would be saved, sent, or shown. For new diagrams, verify the authored source. For existing diagrams, verify after mutation and before serializing. You may batch several `mutate` calls between verifications, but never serialize a `ValidDiagram` whose `verify` result you have not inspected. `verify.ok` means no unsuppressed error was detected, including measured content occlusion; it is not a visual-quality or semantic-correctness score. For task-critical meaning, inspect `describeMermaidFacts(d)` or call `checkMermaid(d, requiredFacts)` before returning.
 
 ## Tier 1 vs Tier 2 vs Tier 3 warnings
 
-Tier 1 (structural, reliable, universal): `EMPTY_DIAGRAM`, `EDGE_MISANCHORED`, `OFF_CANVAS`, `GROUP_BREACH`, `UNKNOWN_SHAPE`, `LABEL_OVERFLOW` (rendered-line char count over the longest displayed line — `<br>`/`\n` split lines, XML entities decode to one char, formatting tags strip; default cap 40, raise via `labelCharCap` / `am verify --label-cap N` when long labels are intentional instead of truncating the user's text), `UNRESOLVABLE_SCHEDULE` (gantt: parses but the schedule cannot resolve — render would fail; `reason` names the `GANTT_*` error), `RENDER_FAILED` (any family: the source verifies structurally but the strict render parser throws, so rendering would fail; `reason` carries the renderer error — a clean verify proves the diagram actually renders). Applies to every family. Never suppress Tier 1 errors.
+Tier 1 (structural, reliable, universal): <!-- BEGIN GENERATED: warning-summaries:structural -->`EMPTY_DIAGRAM`, `EDGE_MISANCHORED`, `OFF_CANVAS`, `GROUP_BREACH`, `UNKNOWN_SHAPE`, `LABEL_OVERFLOW`, `UNRESOLVABLE_SCHEDULE`, `RENDER_FAILED`, `INTERNAL_ERROR`. `LABEL_OVERFLOW` means a label's longest displayed line is over the char cap — `<br>`/`\n` split lines, XML entities decode to one char, formatting tags strip (families that draw text literally count them); default cap 40, raise via `labelCharCap` / `am verify --label-cap N` when long labels are intentional instead of truncating the user's text. `UNRESOLVABLE_SCHEDULE` means a gantt parses but its schedule cannot resolve, so render would fail; `reason` names the `GANTT_*` error. `RENDER_FAILED` means the parser, the strict render parser, layout, or theme colors reject the source or its configuration (any family; `origin` says which), so rendering would fail; `reason` carries the renderer error — a clean verify proves the diagram actually renders. `INTERNAL_ERROR` means Agentic Mermaid hit an internal defect, not caused by the source; `defaultRender` is `succeeds-unchecked` when an ordinary render still produces output that the failed consistency checks cannot vouch for, or `fails` when rendering throws — do not rewrite the diagram to work around it; report it with the source.<!-- END GENERATED: warning-summaries:structural --> Applies to every family. Never suppress Tier 1 errors.
 
-Tier 2 (geometric, advisory, flowchart-specific): `NODE_OVERLAP`, `ROUTE_SELF_CROSS`, plus 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` (docs/design/system/route-contracts.md — the layout pipeline upholds these itself, so they fire only on pipeline regressions). Route tripwires fire for flowchart/state; class and ER additionally run boundary-anchor and overlap checks (`ROUTE_SHAPE_MISANCHOR`, `NODE_OVERLAP` on class/entity boxes). For other families, geometric concerns surface via perceptual metrics (`measureQuality(layoutMermaid(d))`). See `docs/quality.md`. Don't gate CI on Tier 2 alone.
+Tier 2 (geometric): <!-- BEGIN GENERATED: warning-summaries:geometric -->`NODE_OVERLAP`, `CONTENT_OCCLUDED`, `LAYOUT_LIMIT_EXCEEDED`, `ROUTE_SELF_CROSS`, `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`.<!-- END GENERATED: warning-summaries:geometric --> `CONTENT_OCCLUDED` fails verification when measured paint hides content. `LAYOUT_LIMIT_EXCEEDED` reports an unmet budget while retaining content. The `ROUTE_*` codes are route-contract tripwires (docs/design/system/route-contracts.md — the layout pipeline upholds these itself, so they fire only on pipeline regressions). Route tripwires fire for flowchart/state. `NODE_OVERLAP` also checks class, ER, journey, timeline and sequence boxes, and class/ER add boundary-anchor checks (`ROUTE_SHAPE_MISANCHOR`). Other geometric concerns surface via perceptual metrics (`measureQuality(layoutMermaid(d))`). See `docs/quality.md`. Gate on error severity; use the remaining geometric warnings to assess layout quality.
 
-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`. Advisory lint never flips `verify.ok`; a caller-authored Brand constraint with `action: "error"` emits `BRAND_CONSTRAINT_ERROR` and does. Brand constraints inspect final contrast, accent area, or monochrome role paint without repainting or relayout. `DECISION_BRANCH_UNLABELED` means a multi-exit decision diamond has an unlabeled branch. `COMMENT_DROPPED` means in-body `%%` comments will not survive structured serialization; the leading wrapper (frontmatter, `%%{init}%%` directives, comments before the header) always round-trips byte-verbatim. `UNSUPPORTED_SYNTAX` means either a Mermaid construct (for example flowchart edge IDs, edge metadata, click/href, or markdown strings) is preserved losslessly as source but is not fully modeled by local structured mutation/render semantics, or `syntax: "empty_layout"` means the source carries content but the local layout produced a 0x0 canvas with no nodes, edges, or groups. Inspect the warning message and `verify.layout` before accepting the artifact. `CONTENT_DROPPED_ON_ROUNDTRIP` means the structured node/edge/group tally changed across a parse → serialize → re-parse cycle — canonical serialization is silently dropping or duplicating content even though the bytes may re-parse; treat it as a faithfulness bug to report. `INEFFECTIVE_CONFIG` means a Mermaid config field was accepted for compatibility but has no effect on this family's output (the warning names the field). `LOW_CONTRAST` means a concrete authored paint remains authoritative but misses a measurable contrast threshold against the final resolved opaque background; the warning reports both colors, the measured ratio, and the minimum without repainting. Transparent output is not measured because its host backdrop is unknown.
+Tier 3 (lint and inspect-only policy): <!-- BEGIN GENERATED: warning-summaries:lint -->`DUPLICATE_EDGE`, `UNREACHABLE_NODE`, `DECISION_BRANCH_UNLABELED`, `FLOW_IMBALANCE`, `COMMENT_DROPPED`, `UNSUPPORTED_SYNTAX`, `CONTENT_DROPPED_ON_ROUNDTRIP`, `EVENT_SOURCE_TYPE`, `INEFFECTIVE_CONFIG`, `LOW_CONTRAST`, `LABELS_HIDDEN`, `SCALE_RANGE_EXCLUDES_ZERO`, `BAR_RANGE_EXCLUDES_ZERO`, `VALUES_OUTSIDE_RANGE`, `BRAND_CONSTRAINT_WARNING`, `BRAND_CONSTRAINT_ERROR`. `DECISION_BRANCH_UNLABELED` means a multi-exit decision diamond has an unlabeled branch. `FLOW_IMBALANCE` means a sankey intermediate node receives a different total than it emits — conservation across stages is the domain's defining property, so the warning names the node, its inflow, its outflow, and the unaccounted amount (which otherwise renders silently as node height); balance the flows or add an explicit remainder link. `COMMENT_DROPPED` means a payload carries known comment loss; current serializers retain detected comments, but cannot recover text already omitted from an older payload. `UNSUPPORTED_SYNTAX` means either a Mermaid construct (for example flowchart edge IDs, edge metadata, click/href, or markdown strings) is preserved losslessly as source but is not fully modeled by local structured mutation/render semantics, or `syntax: "empty_layout"` means the source carries content but the local layout produced a 0x0 canvas with no nodes, edges, or groups. Inspect the warning message and `verify.layout` before accepting the artifact. `CONTENT_DROPPED_ON_ROUNDTRIP` means the structured node/edge/group tally changed across a parse → serialize → re-parse cycle — canonical serialization is silently dropping or duplicating content even though the bytes may re-parse; treat it as a faithfulness bug to report. `EVENT_SOURCE_TYPE` means inspect the named Event Modeling source and target frame types; rendering preserves the authored connection. `INEFFECTIVE_CONFIG` means a Mermaid config field has no effect on this family's output — it was accepted for compatibility but is not wired, is unknown to the family, or has an invalid value (the warning names the field). `LOW_CONTRAST` means a concrete authored paint remains authoritative but misses a measurable contrast threshold against the final resolved opaque background; the warning reports both colors, the measured ratio, and the minimum without repainting. Transparent output is not measured because its host backdrop is unknown. `LABELS_HIDDEN` means a chart left out text the source asked for because it did not fit: for an XY chart, `target: "x-axis"` lists the category names the axis does not draw (thinned or dropped) and `target: "data-labels"` lists the bars whose value label has no room (shorten the names, flip the chart with `set_orientation {horizontal: true}`, or widen the value range); for a quadrant chart, `target: "point-labels"` lists the points whose label collides with labels placed first (spread the points, shorten the names, or enlarge the chart). `BAR_RANGE_EXCLUDES_ZERO` means an XY chart with bar series has an authored y-axis range that excludes zero, so bars start at the reported `baseline` and their lengths are not proportional to their values; include zero with `set_y_axis`, or draw the series as a line. `VALUES_OUTSIDE_RANGE` means an XY chart series has values outside the authored y-axis range: a bar stops at the edge of the range, so its length understates the value, and a line point is drawn past the plot; the warning names the `series` and its `values` outside the `range`. Widen the range with `set_y_axis`, or remove it.<!-- END GENERATED: warning-summaries:lint --> Advisory lint never flips `verify.ok`; a caller-authored Brand constraint with `action: "error"` emits `BRAND_CONSTRAINT_ERROR` and does. Brand constraints inspect final contrast, accent area, or monochrome role paint without repainting or relayout.
 
 ## CLI verbs
 
-`am capabilities --json` — JSON envelope listing families, `families[].editPolicy`, `families[].mutationOps`, warning codes, output formats (`svg`, `ascii`, `unicode`, `png`, `layout`). Schema-stable; use it to self-discover.
-`am batch --jsonl` — JSONL stdin → JSONL stdout for render/verify/parse/serialize/mutate. Malformed lines surface error but don't abort the stream.
-`am render <file…> --format svg|ascii|unicode|layout [--security strict] [--style <names|file.json>] [--seed N]` — layout emits the JSON layout shape; --security strict = no external-fetch refs; `--style` takes a stack (comma-separated names and/or .json spec files, merged left → right, e.g. `--style hand-drawn,dracula`) and applies to graphical and terminal projection; `--seed` re-rolls styled ink. Multiple files → results array for non-PNG formats. `--watch` is single-file/non-PNG only. PNG uses `--format png --output file.png` for one input and does not support watch/multi-input.
+<!-- complete: cli-verbs -->
+`am capabilities --json` — JSON envelope listing families, `families[].editPolicy`, `families[].mutationOps`, warning codes, output formats (<!-- BEGIN GENERATED: render-formats -->`svg`, `ascii`, `unicode`, `png`, `layout`<!-- END GENERATED: render-formats -->). Schema-stable; use it to self-discover.
+`am batch --jsonl` — JSONL stdin → JSONL stdout for render/verify/parse/serialize/mutate. Mutation requests opt into bounded source edits with `preserveSource: true`. Malformed lines surface error but don't abort the stream.
+`am render <file…> --format svg|ascii|unicode|layout [--security strict] [--style <names|file.json>] [--seed N]` — layout emits the JSON layout shape; --security strict = no external-fetch refs; `--style` takes a stack (comma-separated names and/or .json spec files, merged left → right, e.g. `--style hand-drawn,dracula`) and applies to graphical and terminal projection; `--seed` re-rolls styled ink. Multiple files → results array for non-PNG formats. `--watch` is single-file/non-PNG only. PNG uses `--format png --output file.png` for one input and does not support watch/multi-input; `--fit-width`/`--fit-height` constrain raster size and `--min-label-px` emits `BELOW_READABLE_SIZE` when measurable configured text falls below the selected effective-pixel floor (provisional default 9; `0` disables).
 `am preview <file|-> [--output out.html] [--open] [--json] [--security strict]` — standalone strict-mode HTML preview for human inspection.
-`am mutate <file|-> (--op '<JSON>'|--ops '<JSON array|file>') [--json]` — apply mutation(s), run verify, emit source only if verify succeeds. JSON success includes `{ok,source,verify}`; verify failure exits 3 and omits source.
+`am mutate <file|-> (--op '<JSON>'|--ops '<JSON array|file>') [--preserve-source] [--json]` — apply mutation(s), run verify, emit source only if verify succeeds, or if its only errors are `INTERNAL_ERROR` defects the input already had (same reason and `defaultRender`; `verify` then still reports them). `--preserve-source` opts into the bounded opaque Class/Flowchart edits above. JSON success includes `{ok,source,verify}` and `mode: 'source-preserving'` when selected; verify failure exits 3 (4 when every error is `INTERNAL_ERROR`) and omits source.
 `am verify <file|-> [--json] [--label-cap N] [--suppress CODES] [--style <names|file.json>]` — full tiered verify; `--style` evaluates inspect-only Brand constraints against the same styled Scene used by render; exit 3 only on error-severity findings. `am parse` (ValidDiagram JSON), `am serialize` (ValidDiagram JSON on stdin → canonical source), and `am format` (idempotent reformat) round out the loop.
-`am describe <file|-> [--format text|json|facts]` — prose summary, structured AX tree (`{nodes,edges,entryPoints,sinks}`, #7349), or semantic fact lines. Library: `describeMermaid(d, {format})`, `describeMermaidFacts(d)`, `checkMermaid(d, facts)`.
+`am describe <file|-> [--format text|json|facts]` — prose summary, structured AX tree (`{kind,nodes,edges,entryPoints,sinks}`, #7349), or semantic fact lines. Library: `describeMermaid(d, {format})`, `describeMermaidFacts(d)`, `checkMermaid(d, facts)`.
 `am styles [--json]` — list registered styles: the default, full looks, and palette-only themes, with backends and blurbs.
 `am llms-txt` — agent-discovery digest (llms.txt convention).
 `am init-agent [--dir .] [--force]` — writes a non-clobbering AGENTS.md section, root skills/ bundle, and .mcp.json sample into a consumer repo.
 `am render-markdown <file.md> [--ascii]` — render each Mermaid fenced block; skips invalid diagrams, never aborts the file. JSON: `{blocks:[{index,ok,output|error}]}`.
-Exit codes: `0` ok, `2` arg/parse/mutation error, `3` verify-failed, `4` internal. Parse and verify-failure errors carry `error.details` arrays, not stringified blobs.
+Exit codes: `0` ok, `2` arg/parse/mutation error, `3` verify-failed, `4` internal (including a verify whose errors are all `INTERNAL_ERROR`). Parse and verify-failure errors carry `error.details` arrays, not stringified blobs.
 
-Library extras: `renderMermaidPNG(src,{fitTo,background,style,seed,fontDirs})` returns PNG bytes; `renderMermaidASCIIWithMeta(src)` → `{ascii,regions,actions,warnings,routeParity}` for TUI click-mapping; `describeMermaidFacts(d)` / `checkMermaid(d, facts)` expose deterministic semantic facts; `analyzeMermaid(d)` / `analyzeMermaidSource(source)` returns non-rendering feedback/action/Gantt analysis; `asciiToMermaid(ascii)` reverses flowchart ASCII (best-effort, lossy); `verifyNoExternalRefs(svg)` asserts no external fetch; `renderMermaidSVG(src,{idPrefix})` namespaces def ids for multi-diagram pages. See SECURITY.md.
+Library extras: `renderMermaidPNG(src,{fitTo,background,minLabelPx,onWarning,style,seed,fontDirs})` returns PNG bytes and reports bounded raster warnings through `onWarning`; `BELOW_READABLE_SIZE` is evidence of configured-text shrinkage, not a general readability verdict. `renderMermaidASCIIWithMeta(src)` → `{ascii,regions,actions,warnings,routeParity}` for TUI click-mapping; `describeMermaidFacts(d)` / `checkMermaid(d, facts)` expose deterministic semantic facts; `analyzeMermaid(d)` / `analyzeMermaidSource(source)` returns non-rendering feedback/action/Gantt analysis; `asciiToMermaid(ascii)` reverses flowchart ASCII (best-effort, lossy); `verifyNoExternalRefs(svg)` asserts no external fetch; `renderMermaidSVG(src,{idPrefix})` namespaces def ids for multi-diagram pages. See SECURITY.md.
 
 ## Styles
 
@@ -85,5 +106,5 @@ Every library render call accepts `style`: a registered Look or Palette discover
 - Regenerating an existing parsed diagram instead of mutating it. Defeats round-trip; produces noise.
 - Verifying only after a long risky edit chain. Loses precision about which op broke it.
 - Serializing before reading `verify.ok` / `verify.warnings` / `verify.layout`.
-- Concatenating source to edit an existing structured diagram when a typed `mutate` op exists. For new diagrams prefer `buildMermaid`/`createMermaid`; direct source authoring is fine for unmodeled syntax.
+- Concatenating source to edit an existing structured diagram when a typed `mutate` op exists. (Authoring a new diagram as source is the default path, not an anti-pattern.)
 - Calling `mutate` on an opaque-fallback body; the structured-family narrower returns null for unmodeled syntax, so edit its preserved source instead.

package/LICENSES/Khroma-MIT.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019-present Fabio Spampinato, Andrew Maney
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/LICENSES/Mermaid-MIT.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 - 2022 Knut Sveidqvist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/es-toolkit-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Viva Republica, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSES/pele-MIT.txt

@@ -0,0 +1,40 @@
+MIT License
+
+Copyright (c) 2026 kepano
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The reset icon of the zoom controls is "rotate-ccw" from Lucide v1.14.0
+(https://lucide.dev), under the ISC License:
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/LICENSES/zenuml-core-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Peng Xiao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,21 +4,30 @@
 
 **Beautiful diagrams, made with your agent.**
 
-Agentic Mermaid is an open-source Mermaid toolkit for people who want AI agents to create diagrams that look finished: SVG and PNG renders, ASCII and Unicode for review, deterministic layout, and Style + Palette controls for brand colors, typography, strokes, fills, and backdrops.
+Agentic Mermaid helps coding agents create styled diagrams from Mermaid source and edit existing diagrams through typed operations. Export SVG or PNG for documents, and ASCII or Unicode for terminal review.
 
-It is forked from [`lukilabs/beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid). Published on npm as `agentic-mermaid`; the GitHub repository is `adewale/agentic-mermaid`; the canonical live site is [`agentic-mermaid.dev`](https://agentic-mermaid.dev/), a Cloudflare Workers deployment.
+It is forked from [`lukilabs/beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid). Published on npm as `agentic-mermaid`; the GitHub repository is `adewale/agentic-mermaid`; the live site is [`agentic-mermaid.dev`](https://agentic-mermaid.dev/).
 
-![Agentic Mermaid: Mermaid source plus typed edit ops on the left, the verified SVG render in the middle, and the same diagram as ASCII on the right](assets/hero.png)
+![A login flow with credential validation, an MFA decision, two retry paths, session creation and a dashboard, rendered in the hand-drawn style](assets/hero.png)
 
-[Live Demo & Samples](https://agentic-mermaid.dev/) · [Live Editor](https://agentic-mermaid.dev/editor)
+A login flow with MFA, rendered directly by Agentic Mermaid.
+[Mermaid source](examples/styles/readme-hero.mmd) · [Style and reproduction command](examples/styles/readme-hero.md)
 
-Docs: [docs index](./docs/) · [getting started](./docs/getting-started.md) · [agent guide](./Instructions_for_agents.md) · [agent API cookbook](./docs/agent-api-cookbook.md) · [design system](https://github.com/adewale/agentic-mermaid/blob/main/DESIGN.md) · [skills](./skills/) · [fork differences](./docs/fork-differences.md) · [vs Mermaid & Beautiful Mermaid](./docs/comparison.md) · [changelog](./CHANGELOG.md)
+[Live Demo & Samples](https://agentic-mermaid.dev/) · [Live Editor](https://agentic-mermaid.dev/editor)
 
 </div>
 
+**Ask your coding agent:**
+
+> Read `Instructions_for_agents.md` in this repository, or https://agentic-mermaid.dev/llms.txt if you don't have a checkout. Draw Browser → API → Database using the hand-drawn style and nord-light palette. Verify it, then return the Mermaid source and an SVG.
+
+[Agent setup and skills](#agent-quick-start) · [Try the same diagram in JavaScript](#svg)
+
+Docs: [docs index](./docs/) · [getting started](./docs/getting-started.md) · [agent guide](./Instructions_for_agents.md) · [agent API cookbook](./docs/agent-api-cookbook.md) · [design system](https://github.com/adewale/agentic-mermaid/blob/main/DESIGN.md) · [skills](./skills/) · [fork differences](./docs/fork-differences.md) · [vs Mermaid & Beautiful Mermaid](./docs/comparison.md) · [changelog](./CHANGELOG.md)
+
 ## Why Agentic Mermaid
 
-Use it when you want to describe a diagram in plain language and get back something you can publish without a design cleanup pass.
+Choose a built-in style, or keep your diagram's colors and fonts in a JSON style file. Inspect the rendered result before publishing.
 
 | You want | Agentic Mermaid gives you |
 |---|---|
@@ -32,40 +41,27 @@ The agent workflow is the guardrail behind the polish: agents should not guess f
 
 ## Highlights
 
-- **Descriptor-registered diagram families** — built-ins and namespaced extensions share one discovery and capability contract.
-- **SVG, PNG, ASCII, Unicode, JSON** — one resolved request with explicit graphical, terminal, and positioned-layout projections.
-- **Synchronous, zero-DOM SVG renderer** — no Puppeteer, no browser flash.
-- **Composable styles** — `{ style: ['hand-drawn', 'dracula'] }` stacks a look over a palette; discoverable full looks cover sketch, watercolor, blueprint, accessibility, print, operational, physical-media, architecture, and editorial/report use cases. Custom styles are plain JSON records any agent can author (`docs/style-authoring.md`). `seed` re-rolls the ink, never the layout.
-- **Discoverable palettes + Shiki compatibility** — a theme is a palette-only style: discover the canonical catalog at runtime, theme from two colors, or adapt a VS Code theme.
-- **Agent-native editing** — typed mutation for every registered renderable family; source-level round-trip only for opaque fallbacks containing unmodeled syntax.
-- **CLI + MCP + library** — `am`, `agentic-mermaid-mcp`, `agentic-mermaid`, `agentic-mermaid/agent`, and the browser/workerd-safe `agentic-mermaid/agent/core`. Audit reports and trusted host-resource helpers remain repository tooling instead of published runtime entry points.
+- **Discover supported diagrams and edits** — `am capabilities --json` reports what the installed version supports, including registered extensions.
+- **SVG, PNG, ASCII, Unicode, JSON** — export images, review diagrams in the terminal, or inspect positions as JSON layout.
+- **Render SVG without a browser** — the synchronous JavaScript API runs without a DOM or Puppeteer.
+- **Composable styles** — `{ style: ['hand-drawn', 'dracula'] }` combines a look with a palette. Set colors, fonts, strokes, fills and backdrops in a [JSON style](./docs/style-authoring.md). `seed` re-rolls the ink, never the layout.
+- **Match your editor's colors** — choose a built-in palette, theme from two colors, or adapt a VS Code theme with Shiki.
+- **Agent-native editing** — use typed operations for modeled syntax. Inputs with unmodeled syntax retain their source; [source-preserving edits](./docs/agent-mutation-policy.md) cover selected Class and Flowchart operations.
+- **CLI + MCP + library** — use `am`, connect `agentic-mermaid-mcp`, or import `agentic-mermaid/agent` for rendering and editing. See the [API reference](./docs/api.md) for the other library and browser entry points.
 
 ## Installation
 
+Requires **Node.js 22 or later**, or **Bun 1.4.0 or later**. The package is ESM-only; use `import`, or dynamic `import()` from CommonJS.
+
 ```bash
 npm install agentic-mermaid       # or: bun add agentic-mermaid / pnpm add agentic-mermaid
 npx --no-install agentic-mermaid --help
-npx --no-install agentic-mermaid mcp
-```
-
-For repository development, install from source and run the Bun entrypoints:
-
-```bash
-git clone https://github.com/adewale/agentic-mermaid
-cd agentic-mermaid
-bun install
-bun run build
-bun run bin/am.ts --help
-bun run bin/agentic-mermaid-mcp.ts   # MCP stdio server
 ```
 
-> **ESM-only.** `agentic-mermaid` ships ES modules (there is no CommonJS build);
-> `require()` consumers should use dynamic `import()` instead. Requires Node ≥ 22.
->
-> The `am …` examples below name the published bin. After a project-local npm
-> install, invoke it from a shell as `npx --no-install agentic-mermaid …` (or
-> from an npm script as `am …`). From a source checkout, use
-> `bun run bin/am.ts …` instead.
+The `am …` examples below name the published bin. After a project-local npm
+install, invoke it from a shell as `npx --no-install agentic-mermaid …` (or
+from an npm script as `am …`). From a source checkout, use
+`bun run bin/am.ts …` instead.
 
 ## Output quick starts
 
@@ -73,13 +69,27 @@ Use `agentic-mermaid/agent` when you want one import path for styled renders, ou
 
 ### SVG
 
-```ts
+Save this as `diagram.mjs`:
+
+```js
+import { writeFileSync } from 'node:fs'
 import { renderMermaidSVG } from 'agentic-mermaid/agent'
 
-const svg = renderMermaidSVG(`flowchart TD
-  Start --> Done`, { security: 'strict' })
+const svg = renderMermaidSVG(`flowchart LR
+  Browser --> API --> Database`, {
+  style: ['hand-drawn', 'nord-light'],
+  security: 'strict',
+})
+
+writeFileSync('diagram.svg', svg)
 ```
 
+```bash
+node diagram.mjs
+```
+
+Open `diagram.svg` to see **Browser → API → Database** in the hand-drawn style with the `nord-light` palette.
+
 ### PNG
 
 ```ts
@@ -125,28 +135,33 @@ If it only has shell access:
 am --agent-instructions
 am capabilities --json
 am preview diagram.mmd --security strict --open
-am mutate diagram.mmd --op '{"kind":"add_node","id":"Cache","label":"Cache"}' --json
+am mutate diagram.mmd --op '{"kind":"set_label","target":"API","label":"API gateway"}' --json
 ```
 
-Zero-install prompt for a coding agent: read `https://agentic-mermaid.dev/llms.txt` and follow the parse → narrow → mutate → verify → serialize workflow. To wire Agentic Mermaid into another repo, run `npx agentic-mermaid init-agent` (or `bun run bin/am.ts init-agent` from a source checkout); it writes a non-clobbering `AGENTS.md` section, root `skills/` bundle, and `.mcp.json` sample.
+For an existing diagram, follow parse → narrow → mutate → verify → serialize. For a new diagram, author Mermaid source, then parse and verify it. To wire Agentic Mermaid into another repo, run `npx agentic-mermaid init-agent` (or `bun run bin/am.ts init-agent` from a source checkout); it writes a non-clobbering `AGENTS.md` section, root `skills/` bundle, and `.mcp.json` sample.
 
 Use strict `preview` for human inspection and `mutate --op/--ops` for verified one-shot or batched edits.
 
-For multi-step MCP edits, connect `agentic-mermaid-mcp` and use Code Mode `execute(code)` with the same `mermaid.*` SDK names. Stdio is the default transport; `agentic-mermaid-mcp --transport http` starts HTTP/SSE and managed PNG file/URL artifacts. See the [agent API cookbook](./docs/agent-api-cookbook.md) for copy-pasteable library, CLI, and MCP recipes.
+For multi-step MCP edits, use Code Mode `execute(code)` with the same `mermaid.*` SDK names. See the [agent API cookbook](./docs/agent-api-cookbook.md) for library, CLI and MCP recipes.
 
 ## MCP server
 
 Agentic Mermaid ships a Model Context Protocol server so MCP-capable agents can render and safely edit diagrams without shelling out.
 
-- **Self-hosted (default).** `agentic-mermaid-mcp` runs a stdio server exposing `execute` (Code Mode sandbox), `describe_sdk` (one family's mutation schema on demand), `render_png`, and `describe`. Package runners can use `npx -y agentic-mermaid mcp`; the `mcp` argument routes the package-name binary to the same stdio server. Add `--transport http` for HTTP/SSE with managed PNG file/URL artifacts. See [`docs/mcp-http-transport.md`](./docs/mcp-http-transport.md) and [`docs/mcp-code-mode-rationale.md`](./docs/mcp-code-mode-rationale.md).
-- **Hosted.** A stateless Streamable HTTP endpoint is available at `https://agentic-mermaid.dev/mcp` (tools: `execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, `build`; 64 KB input caps). Call `describe_sdk` for compact signatures or exact fields before authoring unfamiliar ops. It is MCP JSON-RPC only, not a REST render API. Hosted `execute` runs the same `mermaid.*` facade in a Cloudflare Dynamic Worker isolate with no network; hosted PNG returns base64 only.
+After installation, start the local stdio server:
+
+```bash
+npx --no-install agentic-mermaid mcp
+```
 
-Local-first is the default posture: prefer the library, CLI, or a self-hosted MCP for anything sensitive, offline, larger than the hosted caps, or needing local PNG file/URL artifacts. The hosted endpoint is a public, unauthenticated convenience for zero-install render/verify/describe and bounded structured edits.
+Use the library, CLI or local MCP for private diagrams, offline work, larger inputs or local PNG files. The [MCP transport guide](./docs/mcp-http-transport.md) covers HTTP/SSE and file/URL artifacts; [agent setup](#agent-quick-start) shows how to generate a sample client configuration. The [tool reference and Code Mode guide](./docs/mcp-code-mode-rationale.md) explains the available tools and multi-step edits.
 
-Directory maintainers can use the canonical [MCP listing record](./docs/MCP-DIRECTORY-LISTINGS.md). Hosted data handling is described in the [MCP privacy notice](./docs/MCP-PRIVACY.md).
+An optional public, unauthenticated MCP endpoint runs at `https://agentic-mermaid.dev/mcp`. It accepts MCP JSON-RPC rather than REST render requests, caps inputs at 64 KB and returns PNG as base64. Hosted calls send your source or code to the server; see the [privacy notice](./docs/MCP-PRIVACY.md). Directory maintainers can use the [MCP listing record](./docs/MCP-DIRECTORY-LISTINGS.md).
 
 ## Structured edit example
 
+Change the API node's displayed label while keeping its connection to DB:
+
 ```ts
 import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
 
@@ -156,39 +171,49 @@ if (!parsed.ok) throw new Error('parse failed')
 const flow = asFlowchart(parsed.value)
 if (!flow) throw new Error(`not a structured flowchart: ${parsed.value.kind}`)
 
-const next = mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })
+const next = mutate(flow, { kind: 'set_label', target: 'API', label: 'API gateway' })
 if (!next.ok) throw new Error(next.error.message)
 
 const verify = verifyMermaid(next.value)
 if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))
 
 const source = serializeMermaid(next.value)
+console.log(source)
+```
+
+Output:
+
+```text
+flowchart TD
+  API[API gateway] --> DB
 ```
 
+The node ID is still `API`; its displayed label is now `API gateway`, and the `API → DB` connection remains. Verification checks for structural and geometry problems; review the rendered result and confirm it expresses your intent before saving.
+
 Rules:
 
 - Use the matching exported `as<Family>` narrower before mutating an existing structured diagram.
 - Mutation ops use `kind`, not `type`.
 - Run `verifyMermaid` before every commit point.
 - Do not call `mutate` on opaque fallback bodies; the narrower returns `null` for unmodeled syntax.
+- For opaque Class/Flowchart inputs, bounded [source-preserving edits](./docs/agent-mutation-policy.md) support Class `add_member`/`remove_member` and Flowchart `set_label`/`rename_node`. Use `mutatePreservingSource`, `applyOps` with `mode: 'source-preserving'`, or CLI `--preserve-source`; MCP and the editor worker expose the same explicit mode. Save exact source and inspect the retained portability diagnostics; ambiguous ownership and unsupported dependencies refuse atomically.
 
 ## Supported diagram families
 
-Family support and its executable evidence are projected from the
-`FamilyDescriptor` registry into the generated
-[Section A capability report](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/section-a-capability-report.md).
-See [diagram families](./docs/diagram-families.md) for syntax examples and
-compatibility notes.
+Run `am capabilities --json` for the supported families and edit operations in
+your installed version. See [diagram families](./docs/diagram-families.md) for
+syntax examples and compatibility notes.
 
 ## More documentation
 
-- [System architecture](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) — **start here** for the rendered resolved-request, family-descriptor, positioned-artifact, and output-security overview (dogfooded, drift-proof).
+- [System architecture](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) — how Mermaid source becomes a diagram, from parsing to layout and output.
 - [API reference](./docs/api.md) — renderers, agent API, options, CLI/MCP pointers.
+- [Vocabulary](./docs/api.md#vocabulary) — families, source objects, Scene parts, resolved primitives and typed-family narrowing.
 - [Agent API cookbook](./docs/agent-api-cookbook.md) — practical recipes for agents.
 - [Theming](./docs/theming.md) — two-color themes, built-ins, Shiki compatibility.
 - [Custom style cookbook](./docs/custom-style-cookbook.md) — JSON style files, screenshots, schema usage, and CLI commands.
 - [Fonts in custom styles](./docs/custom-fonts.md) — font selection, SVG declarations, PNG directories, fallbacks, and browser usage.
-- [React integration](./docs/react.md) — zero-flash `useMemo` rendering.
+- [React integration](./docs/react.md) — browser-safe, family-loaded rendering.
 - [ASCII output](./docs/ascii.md) — terminal output, color modes, XY charts.
 - [Mermaid config](./docs/config.md) — frontmatter, init directives, runtime config.
 - [Features](./docs/features.md), [quality](./docs/quality.md), [security](./SECURITY.md), [fork differences](./docs/fork-differences.md).
@@ -202,6 +227,21 @@ compatibility notes.
 - [`examples/mcp-vs-cli-complex-diagrams.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/mcp-vs-cli-complex-diagrams.ts)
 - [`examples/agent-improve-auth-flow.ts`](https://github.com/adewale/agentic-mermaid/blob/main/examples/agent-improve-auth-flow.ts)
 
+## Contributing and reporting bugs
+
+[Report a bug](https://github.com/adewale/agentic-mermaid/issues) with the Mermaid source, render options and the result you expected. For changes to the project, read the [contributor instructions](https://github.com/adewale/agentic-mermaid/blob/main/CLAUDE.md) for implementation and testing rules.
+
+To work from a source checkout, use Bun 1.4.0 or later:
+
+```bash
+git clone https://github.com/adewale/agentic-mermaid
+cd agentic-mermaid
+bun install
+bun run build
+bun run bin/am.ts --help
+bun run bin/agentic-mermaid-mcp.ts   # MCP stdio server
+```
+
 ## Attribution
 
 Agentic Mermaid is a fork of Beautiful Mermaid by [Luki Labs](https://github.com/lukilabs/beautiful-mermaid). The ASCII rendering engine is based on [`mermaid-ascii`](https://github.com/AlexanderGrooff/mermaid-ascii) by Alexander Grooff and extended for Agentic Mermaid.
@@ -209,3 +249,6 @@ Agentic Mermaid is a fork of Beautiful Mermaid by [Luki Labs](https://github.com
 ## License
 
 MIT
+
+Native Event Modeling and ZenUML authoring and rendering have documented
+[capability and runtime contracts](docs/eventmodeling-and-zenuml.md).