agentic-mermaid 0.1.2 → 0.2.0

package/docs/custom-style-cookbook.md

@@ -0,0 +1,275 @@
+# Custom style cookbook
+
+Custom styles are JSON files. Put the file under version control, pass it to
+`--style`, and add a `seed` when you want reproducible sketch variation.
+
+```bash
+am render diagram.mmd --format svg --style examples/styles/transit-route-map.style.json --seed 11 > diagram.svg
+am render diagram.mmd --format png --style examples/styles/transit-route-map.style.json --seed 11 --output diagram.png
+```
+
+The schema is published in this repo as
+[`docs/schemas/style-spec.schema.json`](./schemas/style-spec.schema.json) and
+from the package as `agentic-mermaid/style-spec.schema.json`. Example files use
+`$schema` so editors can offer field completion. The renderer ignores that
+field.
+
+Runtime validation still matters. A schema catches the file shape; the renderer
+uses `validateStyleSpec` before accepting untrusted records.
+
+```ts
+import { readFileSync } from 'node:fs'
+import { validateStyleSpec } from 'agentic-mermaid'
+
+const style = JSON.parse(readFileSync('examples/styles/transit-route-map.style.json', 'utf8'))
+const problems = validateStyleSpec(style)
+if (problems.length) throw new Error(problems.join('\n'))
+```
+
+The `font` field names a family; the output environment still has to provide
+that face. See [Fonts in custom styles](./custom-fonts.md) for SVG behavior,
+PNG `fontDirs`, system fonts, fallbacks, and browser usage.
+
+## Public brand-inspired prototypes — documentation only
+
+These three files are the highest supported non-built-in form of a Style probe:
+version-controlled public `StyleSpec` records with schema validation, executable
+fixtures, deterministic screenshot gates, strict rendering, inspect-only
+constraints, and optional process-local registration. The reviewed image hashes
+are pinned in
+[`eval/style-prototype-evidence/visual-approval.json`](../eval/style-prototype-evidence/visual-approval.json).
+They are not package-owned built-ins, installed BrandPacks, claims of pixel
+equivalence, or endorsements.
+
+### Cupertino-inspired prototype
+
+Complete file:
+[`examples/styles/cupertino-prototype.style.json`](../examples/styles/cupertino-prototype.style.json).
+
+This is an implementation example, not a built-in Style. Agentic Mermaid ships
+the opt-in file but does not register `cupertino`, give it a package-owned
+runtime identity, expose it in a built-in catalog or picker, or retain a
+registered short name. Load the JSON explicitly when you want to study or
+adapt the prototype:
+
+![Documentation-only Cupertino prototype](./assets/style-cookbook/cupertino-prototype.png)
+
+```bash
+am render examples/styles/cupertino-prototype.mmd --format svg \
+  --style examples/styles/cupertino-prototype.style.json \
+  --options '{"shadow":true}' \
+  --output diagram.svg
+```
+
+Library hosts can opt into a reusable name without creating a built-in registry
+identity. Registration is explicit, process-local, and disposable:
+
+```ts
+import { readFileSync } from 'node:fs'
+import { registerStyle, renderMermaidSVG, validateStyleSpec } from 'agentic-mermaid'
+
+const prototype = JSON.parse(
+  readFileSync('examples/styles/cupertino-prototype.style.json', 'utf8'),
+)
+const source = readFileSync('examples/styles/cupertino-prototype.mmd', 'utf8')
+const problems = validateStyleSpec(prototype)
+if (problems.length) throw new Error(problems.join('\n'))
+
+const unregister = registerStyle(prototype)
+try {
+  const svg = renderMermaidSVG(source, {
+    style: 'look:cupertino-prototype',
+    shadow: true,
+  })
+} finally {
+  unregister()
+}
+```
+
+The public `StyleSpec` expresses the prototype's palette, font, weight-based
+role typography, surface-first border policy, padding, geometry, and inspect-only
+contrast/accent-area constraints. Its 10-unit node corners, 26-unit group
+corners, and 16-unit connector bend radius make the intended Cupertino-inspired
+curve discipline directly inspectable; `shadow` remains the shared render option
+supplying elevation. The file still does not claim pixel equivalence with an
+Apple interface: it uses bundled Inter rather than licensed SF Pro, has no
+motion/spring system, and provides no designed dark companion.
+
+Agentic Mermaid is independent of and not affiliated with Apple Inc.;
+“Cupertino” describes the prototype's design inspiration, not an Apple product
+or endorsed implementation.
+
+### Vercel-inspired prototype
+
+Complete file:
+[`examples/styles/vercel-inspired-prototype.style.json`](../examples/styles/vercel-inspired-prototype.style.json).
+
+![Documentation-only Vercel-inspired prototype](./assets/style-cookbook/vercel-inspired-prototype.png)
+
+```bash
+am verify examples/styles/vercel-inspired-prototype.mmd \
+  --style examples/styles/vercel-inspired-prototype.style.json
+am render examples/styles/vercel-inspired-prototype.mmd --format svg \
+  --style examples/styles/vercel-inspired-prototype.style.json > diagram.svg
+```
+
+This static prototype uses the public palette and role records for dark surfaces,
+hairlines, compact typography, and restrained geometry. Its executable XYChart
+fixture exercises `bar-0` and `line-0` category bindings through named semantic
+slots; contrast and accent-area policy remains inspect-only. It deliberately
+does not imitate Geist assets, Vercel motion, live application chrome, or a
+complete product design system.
+
+Agentic Mermaid is independent of and not affiliated with Vercel Inc.;
+“Vercel-inspired” describes visual research, not a Vercel product or endorsed
+implementation.
+
+### Cloudflare Workers-inspired prototype
+
+Complete file:
+[`examples/styles/cloudflare-workers-inspired-prototype.style.json`](../examples/styles/cloudflare-workers-inspired-prototype.style.json).
+
+![Documentation-only Cloudflare Workers-inspired prototype](./assets/style-cookbook/cloudflare-workers-inspired-prototype.png)
+
+```bash
+am verify examples/styles/cloudflare-workers-inspired-prototype.mmd \
+  --style examples/styles/cloudflare-workers-inspired-prototype.style.json
+am render examples/styles/cloudflare-workers-inspired-prototype.mmd --format svg \
+  --style examples/styles/cloudflare-workers-inspired-prototype.style.json > diagram.svg
+```
+
+This static prototype combines warm surface tokens, sans/mono role typography,
+Gantt section-category bindings, and visible `outline`/`pattern` cues. The cues
+survive no-color terminal projection where that family supports them; contrast
+and accent-area rules diagnose without repainting. It does not reproduce
+Cloudflare application chrome, motion, tinted multi-layer shadow systems, or a
+complete Workers design system.
+
+Agentic Mermaid is independent of and not affiliated with Cloudflare, Inc.;
+“Cloudflare Workers-inspired” describes visual research, not a Cloudflare
+product or endorsed implementation.
+
+## Transit route map
+
+Complete file:
+[`examples/styles/transit-route-map.style.json`](../examples/styles/transit-route-map.style.json).
+
+![Transit route map custom style](./assets/style-cookbook/transit-route-map.png)
+
+This style is a good route-map example because it stresses brand colors and
+connector weight. It also shows the current limit: JSON styles can set a
+route-map palette, but they cannot yet assign stable route colors or station-dot
+glyphs per path.
+
+Use it when you want to test whether a style keeps connectors readable:
+
+```json
+{
+  "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
+  "name": "look:transit-route-map",
+  "colors": {
+    "bg": "#fbfbf8",
+    "fg": "#171923",
+    "line": "#d22630",
+    "accent": "#0067a8",
+    "surface": "#ffffff"
+  },
+  "font": "DejaVu Sans",
+  "stroke": "crisp",
+  "strokeWidth": 4
+}
+```
+
+## Mid-century report
+
+Complete file:
+[`examples/styles/mid-century-report.style.json`](../examples/styles/mid-century-report.style.json).
+
+![Mid-century report custom style](./assets/style-cookbook/mid-century-report.png)
+
+This is the easiest uncovered cluster to teach with today's StyleSpec. It is
+mostly palette, typography, and page treatment. No new backend capability is
+needed.
+
+Use it when you want a report figure with visible section bands and square
+technical connectors:
+
+```json
+{
+  "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
+  "name": "look:mid-century-report",
+  "colors": {
+    "bg": "#f4ead8",
+    "fg": "#24211d",
+    "line": "#2f4858",
+    "accent": "#d49a2a",
+    "surface": "#78a69b"
+  },
+  "font": "DejaVu Sans",
+  "stroke": "crisp",
+  "strokeWidth": 1.6
+}
+```
+
+## Star chart atlas
+
+Complete file:
+[`examples/styles/star-chart-atlas.style.json`](../examples/styles/star-chart-atlas.style.json).
+
+![Star chart atlas custom style](./assets/style-cookbook/star-chart-atlas.png)
+
+This example exercises the page axis: dark host, grid backdrop, pale strokes,
+serif labels, and lightly rough geometry. It is useful because it reveals
+hard-coded light fills quickly.
+
+Use it when you need a dark page style that still keeps labels readable:
+
+```json
+{
+  "$schema": "https://agentic-mermaid.dev/schemas/style-spec.schema.json",
+  "name": "look:star-chart-atlas",
+  "colors": {
+    "bg": "#0b1026",
+    "fg": "#ece4c4",
+    "line": "#8a96c0",
+    "accent": "#f0d98a",
+    "surface": "#101733"
+  },
+  "font": "EB Garamond",
+  "stroke": "jittered",
+  "roughness": 0.35,
+  "fill": "none",
+  "backdrop": "grid"
+}
+```
+
+## Which uncovered clusters belong in guides
+
+Three clusters make good cookbook examples now:
+
+- **Transit/route-map semantics.** It teaches thick connector palettes and the
+  difference between a global palette and a true route identity system.
+- **Retro editorial palettes.** Bauhaus, mid-century, and report figures fit
+  the current fields well: color tokens, solid fills, and typography.
+- **Star-chart/page treatments.** Dark pages and grid backdrops test whether
+  every family routes text and strokes through style tokens.
+
+Three clusters should wait for new capabilities:
+
+- **Stained glass, ukiyo-e, and codex.** They need material backdrops, spot
+  palettes, and stronger fill texture rules than the public JSON fields expose.
+- **Glass, CRT amber, and neon arcade.** They need compositor/filter fields:
+  glow, blur, translucent panels, and static-export fallbacks.
+- **Graffiti or spray paint.** They need spray, overspray, layered text
+  outlines, and drip/splatter operators before the result is more than a bright
+  marker style.
+
+## Regenerate the screenshots
+
+```bash
+bun run scripts/docs/custom-style-cookbook.ts
+bun run scripts/docs/custom-style-cookbook.ts --check
+```
+
+The generator renders the same flowchart through each JSON file. If a
+screenshot changes, inspect it before committing the new PNG.

package/docs/diagram-families.md

@@ -0,0 +1,218 @@
+# Diagram families
+
+Agentic Mermaid supports Mermaid's common diagram families through a split pipeline: parse source, layout typed structures, render SVG/PNG/ASCII, and verify structural warnings.
+
+## Capability authority
+
+The checked roster and per-family capability states are generated from `FamilyDescriptor` in the [Section A capability report](./project/section-a-capability-report.md). Agents can discover the live roster and operation shapes through `am capabilities --json`; its compact Section A summary links to the exhaustive audit. Library and Code Mode callers can use `describeOps(family)` for the exact mutation schema. This guide keeps examples and family-specific caveats, not a second inventory.
+
+Opaque fallback does not mean unsupported: those bodies parse, render, verify, and round-trip losslessly, but agents should edit preserved source deliberately instead of calling `mutate`.
+
+## Flowchart
+
+```mermaid
+flowchart TD
+  API --> DB
+  API --> Cache
+```
+
+Structured ops include node and edge add/remove/rename/set-label operations. Use `asFlowchart(parsed.value)` before mutation.
+
+## State
+
+```mermaid
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Running
+```
+
+State diagrams own a dedicated `StateBody`: narrow with `asState`. States, transitions, start/end, composites, concurrency regions, fork/join/choice and history pseudostates, notes, declarations, direction, and paint are modeled. Use `describeOps('state')` for the current mutation schema; malformed or otherwise unmodeled syntax falls back losslessly and stays source-level. Verify runs the full Tier 1 + Tier 2 geometric path by projecting the body to a graph.
+
+## Sequence
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant API
+  User->>API: Login
+  API-->>User: Session
+```
+
+Participants and messages are structured. Rich statements such as notes, `alt`, `loop`, and activation syntax remain ordered verbatim segments while participant/message operations stay live; only un-segmentable input falls back to a whole opaque body.
+
+## Timeline
+
+```mermaid
+timeline
+  title Release plan
+  section Build
+    Parser : complete
+    Renderer : polish
+```
+
+Structured ops cover title, section, period, and event changes.
+
+## Class
+
+```mermaid
+classDiagram
+  class User {
+    +string id
+    +login()
+  }
+  User --> Session
+```
+
+Structured ops cover classes, members, relations, notes, and renames.
+
+## ER
+
+```mermaid
+erDiagram
+  CUSTOMER ||--o{ ORDER : places
+  ORDER ||--|{ LINE_ITEM : contains
+```
+
+Structured ops cover entities, attributes, relation add/remove, and renames.
+
+## Journey
+
+```mermaid
+journey
+  title Checkout
+  section Cart
+    Add item: 5: Customer
+    Pay: 3: Customer, Gateway
+```
+
+Journey diagrams narrow via `asJourney`; discover the exact section, task, score, actor, ordering, and accessibility operation schema with `describeOps('journey')`. Documented Mermaid accessibility directives (`accTitle`, inline `accDescr`, and block `accDescr { ... }`) stay structured and round-trip through canonical serialization. Malformed or unknown Journey syntax falls back to a lossless opaque body.
+
+SVG rendering uses Mermaid's left-to-right Journey metaphor rather than the older Agentic card layout: sections span task columns, actors appear in a left legend, per-task actor dots show participation, and scores map to sentiment markers on a progression baseline. Mermaid `journey` config fields for actor colors, section fills/text colors, task/title fonts, task spacing, and actor label width are honored. Agentic Mermaid `style` and palette colors also reach Journey-specific surfaces such as section spans, actor dots, score markers, and the baseline.
+
+## XY chart
+
+```mermaid
+xychart-beta
+  title "Latency"
+  x-axis [p50, p95, p99]
+  y-axis "ms" 0 --> 500
+  line [50, 180, 420]
+```
+
+The modeled title, axes, orientation, and bar/line series are structurally mutable through `asXyChart`; use `describeOps('xychart')` for the exact schema. Unmodeled or malformed syntax falls back losslessly and stays source-level. See [`design/families/xychart.md`](./design/families/xychart.md) for compatibility details and layout notes.
+
+## Pie
+
+```mermaid
+pie showData
+  title Pets adopted by volunteers
+  "Dogs" : 386
+  "Cats" : 85
+  "Rats" : 15
+```
+
+Pie charts accept the `pie` header with optional `showData`, an optional `title`, and `"label" : value` entries with positive numeric values. Slices render clockwise in source order. `showData` adds the raw value beside each legend label; the legend always shows the computed percentage. Malformed entries (negative/zero values, missing colon, unquoted labels) fall back to a lossless opaque body — never silently dropped — and the renderer still surfaces the loud error at render time. The ASCII renderer draws a proportional bar list. Pie is structured when narrowed through `asPie`; slices are addressed by their unique label. The operation schema is generated from the registry rather than duplicated here.
+
+## Quadrant
+
+```mermaid
+quadrantChart
+  title Reach and engagement of campaigns
+  x-axis Low Reach --> High Reach
+  y-axis Low Engagement --> High Engagement
+  quadrant-1 We should expand
+  quadrant-2 Need to promote
+  quadrant-3 Re-evaluate
+  quadrant-4 May be improved
+  Campaign A: [0.3, 0.6]
+  Campaign B: [0.45, 0.23]
+```
+
+Quadrant charts accept the `quadrantChart` header, an optional `title`, `x-axis <left> --> <right>` and `y-axis <bottom> --> <top>` axis labels (the far side is optional), four `quadrant-1..quadrant-4 <label>` region labels, and `<Label>: [x, y]` points with coordinates in `[0, 1]`. Quadrant numbering follows Mermaid core: **1 = top-right, 2 = top-left, 3 = bottom-left, 4 = bottom-right**. The SVG renderer draws a square plot split into four theme-tinted quadrants with the points as circles; the ASCII renderer draws a bordered grid with a coordinate legend. Official point style metadata (`radius`, `color`, `stroke-color`, `stroke-width`), `classDef` lines, and class assignments are modeled for rendering and typed mutation. Malformed lines — out-of-range/non-numeric coordinates, missing brackets, duplicate point labels, and unknown point style metadata — fall back to a lossless opaque body, never silently dropped, and the renderer still surfaces the loud error at render time. Quadrant is structured when narrowed through `asQuadrant`; points are addressed by their unique label and coordinates stay in `[0, 1]`. The operation schema is generated from the registry rather than duplicated here.
+
+## Radar
+
+```mermaid
+radar-beta
+  title Skills
+  axis speed["Speed"], power["Power"], range["Range"]
+  curve now["Current"]{4, 3, 5}
+  curve goal["Target"]{5, 5, 4}
+  max 5
+```
+
+Radar (spider) chart — multivariate profiles compared across equi-angular axes from a shared center; one closed translucent area per entity. The `radar-beta` header takes an optional `title`, `axis <id>["Label"], …` declarations, one `curve <id>["Label"]{v1, v2, …}` per entity (one value per axis, in axis order), and optional `max`/`min`/config lines. The SVG renderer draws the axis spokes, concentric grid, and per-curve polygons; the ASCII renderer draws a grouped proportional-bar table like pie. Malformed lines fall back to a lossless opaque body, never silently dropped. Radar is structured when narrowed through `asRadar`; axes and curves are addressed by their unique id. The operation schema is generated from the registry rather than duplicated here.
+
+## Gantt
+
+```mermaid
+gantt
+  title A Gantt Diagram
+  dateFormat YYYY-MM-DD
+  excludes weekends
+  section Section
+    A task          :a1, 2014-01-01, 30d
+    Another task    :after a1, 20d
+  section Another
+    Task in Another :2014-01-12, 12d
+    another task    :24d
+```
+
+Gantt charts accept the `gantt` header, `title`, calendar directives (`dateFormat`, `axisFormat`, `tickInterval`, `inclusiveEndDates`, `topAxis`, multiple `excludes`/`includes` lines, `weekend friday|saturday`, `weekday <day>`, `todayMarker`), `section` lines, and task lines `Label :[tags,] [id,] [start,] end` where tags are `active`/`done`/`crit`/`milestone`/`vert`, start is a date or `after id…`, and end is a date, a duration token (`ms s m h d w M y`, decimals allowed), or `until id…`. Dependencies resolve in a pure scheduler ([design/families/gantt.md](./design/families/gantt.md)): `after` starts at the latest referenced end, `until` ends at the earliest referenced start, working durations extend over excluded days, `includes` overrides `excludes`, and dependency cycles / unknown references / invalid dates are named structured errors (`GANTT_*`), never wall-clock fallbacks. Rendering is deterministic: the `todayMarker` draws only when the caller passes `ganttToday` (a date in the diagram's `dateFormat`), and `todayMarker off` always wins. `displayMode: compact` (frontmatter or `config.gantt`) packs non-overlapping tasks of a section into shared rows; `vert` markers draw a full-height line without consuming a task row. `click … href` is sanitized under strict security and `click … call` is parsed but never executed. Gantt is structured when narrowed and segment-preserving: `asGantt` edits title/sections/tasks while calendar directives, click lines, and comments ride along verbatim as opaque segments; duplicate task ids or an unclosed `accDescr` block fall back to a lossless whole-opaque body.
+
+## Mindmap
+
+```mermaid
+mindmap
+  root((Product))
+    Research
+      Evidence
+    Delivery
+```
+
+Mindmap uses indentation for parentage and supports Mermaid node shapes, `::icon(...)`, `:::class`, accessibility directives, deterministic tree layout, and structured mutation through `asMindmap`. Duplicate semantic ids are rejected. Use `describeOps('mindmap')` for the exact operation schema; see [`design/families/mindmap.md`](./design/families/mindmap.md).
+
+## GitGraph
+
+```mermaid
+gitGraph
+  commit id:"base"
+  branch feature
+  commit id:"work"
+  checkout main
+  merge feature id:"merge"
+```
+
+GitGraph replays commits and branch movement in source order and exposes structured mutation through `asGitGraph`. Generated ids are deterministic `c<N>` values and duplicate custom ids are rejected. Use `describeOps('gitgraph')` for the exact operation schema; see [`design/families/gitgraph.md`](./design/families/gitgraph.md).
+
+## Architecture
+
+```mermaid
+architecture-beta
+  group api(cloud)[API]
+  service web(server)[Web] in api
+  service db(database)[DB]
+  web:R --> L:db
+```
+
+See [`design/families/architecture-beta.md`](./design/families/architecture-beta.md) for parser/layout/render notes.
+
+## Output formats
+
+All families use the same public output paths:
+
+```ts
+import { renderMermaidSVG, renderMermaidPNG, renderMermaidASCII } from 'agentic-mermaid/agent'
+
+const svg = renderMermaidSVG(source, { security: 'strict' })
+const png = renderMermaidPNG(source, { fitTo: { width: 1200 }, background: '#fff' })
+const text = renderMermaidASCII(source)
+```
+
+CLI equivalents:
+
+```bash
+am render diagram.mmd --format svg > diagram.svg
+am render diagram.mmd --format png --output diagram.png
+am render diagram.mmd --format ascii > diagram.txt
+```

package/docs/features.md

@@ -0,0 +1,154 @@
+# Features — capability inventory
+
+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.
+- **`parseRegisteredMermaid(source)`** → `Result<ValidDiagram, ParseError[]>`. Never
+  throws on malformed input; structured errors.
+- **`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** — 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.
+
+## Output formats
+
+Agentic Mermaid outputs **SVG, PNG, ASCII, Unicode, and JSON layout** from the same renderer foundation.
+
+- **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`. Custom font selection and resolution:
+  `docs/custom-fonts.md`.
+
+- **SVG** — `renderMermaidSVG` (`compact`, `security:'strict'`, CSS
+  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).
+
+## Verification tiers
+
+- **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_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).
+
+## Accessibility
+
+- `accTitle`→`<title>`, `accDescr`→`<desc>`, `role="img"`, `aria-labelledby`.
+- **AX tree** — `describeMermaid(d, {format:'json'})` → `{nodes, edges,
+  entryPoints, sinks}`; prose summary in `{format:'text'}`.
+- Auto-contrast node text on custom fills (WCAG luminance).
+- External CSS class emission (Mermaid `classDef` assignments → SVG classes).
+
+## Security
+
+- **Strict mode** (`security:'strict'`) — zero external-fetch references in
+  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).
+
+## CLI (`am`)
+
+`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`, 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.
+
+## MCP server
+
+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 `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 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` 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.
+
+## Guarantees & evidence
+
+- **Determinism** — byte-identical across repeated runs and processes for
+  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** — 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.
+- **Unit, browser/e2e, typecheck, build, binary-build, eval, and lint gates**
+  are part of the verification contract.
+
+## Not browser-dependent
+
+The entire core (parse/verify/mutate/serialize/ASCII/PNG/SVG) runs with no
+DOM, no headless browser, synchronously. This is the structural
+differentiator vs Puppeteer-based Mermaid CLIs.