agentic-mermaid 0.1.0 → 0.1.2

package/docs/design/system/source-preservation-ladder.md

@@ -1,52 +0,0 @@
-# Source preservation ladder
-
-Status: implemented as the Agentic Mermaid family-adoption contract.
-
-Agentic Mermaid edits source, not just pictures. Every family must declare how
-much source it can model and what happens when it encounters syntax outside the
-modeled subset. Silent loss is never an acceptable level.
-
-## Levels
-
-| Level | Name | Contract |
-|---|---|---|
-| L0 | reject/fail loud | The construct is not safely renderable/editable. Parsing or verification returns a named error/warning; no partial IR is serialized as if it were complete. |
-| L1 | whole-body opaque | The family header is recognized, but the body is preserved byte-for-byte as opaque source. Typed narrowers return `null`; render/verify may use a safe legacy/family parser. |
-| L2 | segment-preserving mixed body | Modeled statements are typed-editable; unmodeled blocks/directives/comments remain in ordered opaque segments and serialize without silent loss. |
-| L3 | canonical structured body | Accepted body syntax is modeled; parse → serialize → parse is stable. Unsupported syntax falls back to L1/L2 or fails loud. |
-| L4 | traceable structured model | L3 plus stable source spans, rendered regions, and action/analysis sidecars for load-bearing semantic objects. |
-
-## Construct policy
-
-| Construct class | Required behavior |
-|---|---|
-| Frontmatter / init directives / leading comments | Preserved in `meta.wrapperSource` and re-emitted verbatim by default; canonical wrapper synthesis is opt-in. |
-| In-body comments | Preserved by opaque bodies; structured bodies must either preserve them or report `COMMENT_DROPPED`. |
-| Unknown family syntax | Use L1 opaque preservation when rendering remains safe; otherwise L0 named failure. |
-| Mermaid v11 `@{ ... }` metadata | Must not create phantom nodes or silently drop targets. Current safety floor preserves opaque/unsupported forms and consumes supported label metadata conservatively. Full typed-shape vocabulary remains separate (#44). |
-| Actions/clicks | Never execute during parse/render/analysis. Preserve source intent and expose source-only metadata where modeled. |
-| Render regions | Stable IDs are required for L4 claims; V1 region coverage may be partial but must be documented and tested. |
-
-## Current family levels
-
-| Family | Body preservation level | L4 traceability status |
-|---|---|---|
-| flowchart | L3 for modeled graph syntax; L1 for unsupported syntax/metadata forms | Partial L4: nodes/edges/groups/labels/source map, route certs, action analysis, region MVP |
-| state | L3 structured body | Partial L4 via graph projection, source map, route certs, region MVP |
-| sequence | L2 segment-preserving structured body | Partial L4: participants/messages layout + lifeline certificates |
-| timeline | L3 structured body with opaque fallback | Partial L4: sections/periods/events layout regions/certs |
-| class | L3 structured body with opaque fallback | Partial L4: classes/members source map, geometry validators, orthogonal-box certs |
-| er | L3 structured body with opaque fallback | Partial L4: entities/attrs/cardinalities source map, geometry validators, orthogonal-box certs |
-| journey | L3 structured body with opaque fallback | Partial L4: sections/tasks regions/source map |
-| architecture | L3 structured body | Partial L4: groups/services/junctions/side-anchored certs |
-| xychart | L3 structured body with opaque fallback | Partial L4: plot/marks/labels source map + containment certs |
-| pie | L3 structured body with opaque fallback | Partial L4: slices/legend source map + containment certs |
-| quadrant | L3 structured body with opaque fallback | Partial L4: quadrants/points source map + containment certs |
-| gantt | L2/L3 structured body with schedule resolver and named schedule errors | Partial L4: sections/tasks source map, schedule analysis, containment certs |
-
-## Reviewer rule
-
-A family may advance levels incrementally, but it may not regress silently. New
-syntax support must add one of: typed modeling, opaque preservation, or a named
-failure with docs/tests. Mutation APIs require L3 for the affected construct;
-agents must verify before serializing.

package/docs/design/system/styles-rollout.md

@@ -1,216 +0,0 @@
-# Styles: the composable look system — naming, model, and rollout plan
-
-Status: v2, largely executed on PR #60 — the engine, the consolidated
-`style` primitive, and the product surfaces (CLI `--style`/`--seed` +
-`am styles`, MCP style args + typed SDK declaration, editor style picker
-with seed re-roll, agent docs) have landed; steps below are annotated.
-Nothing has shipped to npm yet, so remaining decisions stay free.
-
-The engine work is done: every diagram family lowers to a SceneGraph of
-semantic marks, and pluggable backends serialize those marks — crisp (the
-unchanged default), rough.js sketch, and hybrid (pressure ribbons, washes).
-
-**The headline is what users and their agents can construct, not what we
-ship.** The built-in looks are proof and raw material: the original sketch
-set (hand-drawn, excalidraw, pen-and-ink, freehand, watercolor, blueprint,
-tufte) plus coverage expanders for accessibility, print, operations,
-physical media, architecture, and editorial/report figures. The product is
-a small set of primitives with one combination rule, from which looks we
-never anticipated can emerge.
-
----
-
-## 1. One concept: style. A theme is a kind of style.
-
-The repo used to have three overlapping vocabularies: *themes* (the
-`THEMES` palette record + `themeVariables` + color options), early private
-role-face experiments, and the pre-consolidation *aesthetics*. Multiple words,
-shapes, and precedence stories answered one question: **how should this diagram look?**
-
-We collapse them into one primitive:
-
-> A **style** is a partial description of how diagrams look. Every field is
-> optional. A style that only sets colors is a palette. A style that sets
-> stroke character, fills, typography, and a palette is a full look.
-
-```ts
-interface StyleSpec {
-  // identity (optional — anonymous inline styles are fine)
-  name?: string
-  blurb?: string
-
-  // palette — the seven tokens every mark references
-  colors?: { bg?; fg?; line?; accent?; muted?; surface?; border? }
-
-  // typography
-  font?: string
-
-  // mark treatment (what the sketch backends read)
-  stroke?: 'crisp' | 'jittered' | 'freehand'
-  fill?: 'none' | 'hachure' | 'solid' | 'wash'
-  roughness?; bowing?; passes?; strokeWidth?; hachureAngle?; hachureGap?;
-  fillWeight?; washOpacity?; washEdge?
-  backdrop?: 'plain' | 'paper-ruled' | 'grid'
-
-  // advisory metadata (documented, never read by the engine)
-  intent?: 'premium' | 'draft' | 'lofi'
-  mono?: boolean
-}
-```
-
-So the answer to "what is the right relationship between styles and themes"
-is: **subsumption, not orthogonality**. A theme is a palette-only style.
-The existing `THEMES` entries register into the style registry at startup
-(their names keep working everywhere a style name is accepted), and
-`themeVariables`/color options remain as the *last* override layer for
-Mermaid compatibility. One registry, one lookup (`getStyle`), one list
-(`knownStyles`) — and the docs answer the theme question in a sentence
-instead of a precedence table.
-
-## 2. One combination rule: the stack
-
-The public option takes a name, a spec, or a **stack** of them:
-
-```ts
-interface RenderOptions {
-  style?: StyleInput | StyleInput[]   // StyleInput = string | StyleSpec
-  seed?: number                        // re-rolls ink wobble, never layout
-}
-
-// a full look
-renderMermaidSVG(src, { style: 'hand-drawn' })
-
-// hand-drawn geometry × dracula palette — "any style × any theme" is just stacking
-renderMermaidSVG(src, { style: ['hand-drawn', 'dracula'] })
-
-// stack a shared brand fragment and a local tweak on top
-renderMermaidSVG(src, { style: ['hand-drawn', acmeBrand, { colors: { accent: '#e11d48' } }] })
-```
-
-Merging is left→right, per field — the CSS intuition everyone already has.
-The full precedence story becomes one line:
-
-```
-defaults  <  style stack (left → right)  <  themeVariables  <  explicit color options
-```
-
-This one rule replaces separate theme/style/variant parameters. It is also the
-agent-native shape: an agent composes a look by concatenating fragments it
-was given, retrieved, or wrote itself.
-
-## 3. Simplifications this unlocks (missed in plan v1)
-
-1. **No `backend` field for authors.** Which backend a style needs is
-   derivable from what it asks for: `stroke: 'freehand'` or `fill: 'wash'`
-   ⇒ hybrid; any rough parameter or `stroke: 'jittered'` ⇒ rough; otherwise
-   ⇒ default. Authors describe the *look*; the engine picks the machinery.
-   (An explicit `backend` override remains for code-backed extensions, but
-   it disappears from the tutorial path.)
-2. **No aesthetic/style/theme triage.** One word in the API, the CLI, the
-   MCP schema, the docs. `THEMES` stays exported for compatibility of
-   in-repo code but is defined *as* registered palette-only styles.
-3. **No compatibility shims anywhere** — pre-release, the in-repo callers
-   of the old option just update.
-4. **`intent`/`mono` demote to advisory metadata.** The engine never
-   branches on them; they exist for pickers, galleries, and the authoring
-   rubric. (The mono *contract* stays a test on built-ins, not an engine
-   switch.)
-5. **One registry, one gallery.** `knownStyles()` drives the CLI list, the
-   editor picker, and the poster harness — registering a style is the only
-   step to appear in all three.
-6. **Fragments are the sharing unit.** A JSON file with three fields is a
-   complete, valid, shareable style. Packs are just arrays of named
-   fragments — no schemaVersion ceremony until a real need appears.
-
-## 4. Designed for emergence
-
-Following the "design for emergence" argument (UX Mag): when user needs are
-heterogeneous and unpredictable — and custom looks are exactly that — ship
-simple elements and combination rules, not finished solutions; keep the
-floor low, the ceiling high, and the walls wide.
-
-- **Low floor**: `style: 'hand-drawn'` — one string.
-- **Wide walls**: fragments compose across axes we don't enumerate. A
-  palette fragment × a line-character fragment × a typography fragment — we
-  ship full looks, but the space users can reach is
-  the product of every fragment anyone writes. Nobody designs "corporate
-  memo hand-drawn dark"; it emerges from a stack.
-- **High ceiling**: `registerBackend` + the SceneGraph types for the rare
-  code-backed capability (a new fill algorithm, a layout-aware dialect).
-  Styles stay data; code is the escape hatch, not the path.
-- **Safety rails that make wild combinations viable**: the prototype WCAG
-  contrast audit and text-halo policy showed the right contract. Production
-  now has deterministic stacking and built-in looks that route structural
-  ink through the active theme foreground; a full arbitrary-stack WCAG gate
-  remains the missing guardrail.
-- **Reproducible sharing**: determinism means `(source, stack, seed)` is a
-  complete, portable description of an image. A gist with a JSON fragment
-  IS the artifact. This is the hashtag/spreadsheet property: the unit of
-  user invention is trivially copyable.
-- **Agents as the emergence engine**: `docs/style-authoring.md` (spec
-  template + quality rubric + worked good/bad examples) is linked from
-  `llms.txt` and the agent instructions, so an agent can author a fragment
-  from a sentence ("make it look like our brand deck"), render it, check
-  contrast, and iterate — the loop that produced the 31-style prototype,
-  now available to every user's agent.
-- **Deliberately not built** (over-specification kills emergence): no
-  inheritance/`extends` graphs (stacking covers it), no per-diagram-family
-  style hooks in v1, no marketplace/registry service — a JSON fragment in
-  a repo is the distribution mechanism until the community proves a need.
-
-## 5. npm package changes
-
-First release ships as `agentic-mermaid` **0.x minor** (crisp default
-byte-identical, corpus-gated):
-
-- **API**: `RenderOptions.style` (name | spec | stack), `RenderOptions.seed`,
-  `registerStyle`, `getStyle`, `knownStyles`, `validateStyleSpec` (JSON
-  schema included in the package), and for extensions `registerBackend`,
-  `StyleBackend`, plus SceneGraph types (`SceneDoc`, `SceneNode`,
-  `SemanticChannels`, `SceneRole`). `THEMES` remains, redefined as
-  palette-only styles.
-- **Runtime dependencies**: `roughjs@4.6.6` and `perfect-freehand@1.2.3`,
-  pinned exactly — seeded geometry must not shift under a bump; a bump is a
-  golden-fixture change (`[approve-goldens]`). They are `dependencies`
-  because the `bun` export condition resolves raw `src/*.ts`; the Node dist
-  bundles them (~80 KB minified). A `agentic-mermaid/styles` subpath split
-  is the escape hatch if crisp-only weight ever matters.
-- **Docs in the box**: README leads with the matrix image, a one-string
-  quick start, and a *custom fragment stack* example; `docs/api.md` gets the
-  option + precedence line; CHANGELOG states the model in three sentences.
-- **Deferred**: styled PNG parity (blocked on bundling the OFL faces as
-  reviewed production assets — notices already exist); CLI/MCP surfaces
-  land in the rollout below.
-
-## 6. Rollout, emergence-first
-
-1. **Collapse the primitives**: rename `aesthetic` → `style`; make all
-   `StyleSpec` fields optional; implement the stack merge; register `THEMES`
-   as styles; infer backends. (Everything else builds on the final shape.)
-   *Status: DONE — resolveStyleStack / inferBackend / validateStyleSpec in
-   src/scene/style-registry.ts; RenderOptions.style is the union; public
-   role-key objects were removed before launch.*
-2. **Agent surface**: MCP render tool + SDK declaration accept `style`
-   (name | spec | stack) and `seed`; authoring guide linked for agents.
-3. **CLI**: `am render --style <name|file.json>` (repeatable = stack),
-   `--seed`, `am styles [--json]`; PNG threading with an explicit
-   font-fallback warning.
-4. **Editor**: style picker and palette picker for built-in looks; `seed` stays
-   an API/CLI/share-link field rather than a persistent topbar control.
-5. **README + gallery** generated from the registry.
-6. **Fonts for PNG parity** (OFL faces as reviewed assets).
-
-## 7. How we explain it
-
-- One sentence: *"A style is a small data record describing how diagrams
-  look; stack styles to combine them — a color-only style is a theme."*
-- Crisp stays the default, stated with receipts (corpus-verified byte
-  identity), and styling covers **all 12 diagram types uniformly**.
-- Three promises for the supported path: **readable** built-in stacks
-  (halos, theme-friendly structural ink, and generated evidence),
-  **deterministic** (`seed` shuffles ink, never layout — cacheable,
-  diffable, golden-testable), **portable** (a JSON fragment + seed
-  reproduces the image anywhere). A full WCAG gate for arbitrary user
-  fragments is still a follow-up.
-- The README example is a custom fragment stack, not a built-in name —
-  the message *is* the primary value.

package/docs/design/system/ugly-layouts.md

@@ -1,119 +0,0 @@
-# What Makes a Layout Ugly
-
-This document states the working definition of an *ugly* diagram layout that
-this project has converged on, and maps each defect to a detector. It is the
-specification for `eval/ugly-detector/` (which audits **rendered** output —
-SVG, PNG, ASCII — not just the internal geometry the rubric checks).
-
-## The one-line definition
-
-> **A layout is ugly when an edge's geometry isn't forced by the node
-> positions** — when it bends, floats, splays, crosses, or breaks symmetry in
-> a way a clearer alternative would avoid for the *same* layout. Every bend,
-> offset, and asymmetry should be the cheapest one the node positions allow,
-> or it shouldn't be there. Ugliness is **unexplained geometry**.
-
-## The defects (and how we detect them)
-
-Grouped by the layer they live in. The first group are **hard** — they must
-never appear in a finished render. The second are **soft** — present in good
-layouts only when forced, and ranked below.
-
-### Hard defects (a finished render must have zero)
-
-| Defect | What it looks like | Detector |
-|---|---|---|
-| **Diagonal segment** | an edge segment that is neither horizontal nor vertical, in an orthogonal drawing | segment with `|dx| > ε` AND `|dy| > ε` |
-| **Edge through a node** | an edge crossing a node's interior (occlusion) | segment intersects a non-endpoint node's body deeper than stroke width |
-| **Floating endpoint** | an edge ending at an arbitrary point on the outline, not a designated connection point | endpoint not within tolerance of the shape's outline / a designated port |
-| **Node overlap** | two node bodies overlapping | bbox/footprint intersection |
-| **Hitch / dogleg** | a short perpendicular jog on a run whose lane is clear | a segment much shorter than its collinear neighbours, perpendicular, with a clear straight alternative |
-| **Label off its route** | a label pill sitting away from the edge it names | label centroid far from its edge's polyline |
-
-### Soft ranking (good layouts minimize these, in this priority order)
-
-The operative priority, distilled from Purchase 1997/2002 and Ware 2002 and
-from the choices made across this project:
-
-1. **Straightness / continuity** — fewest bends; a multi-edge path reads as a
-   line. (Beats everything below.)
-2. **Designated-port attachment** — endpoints sit on a *named*, deterministic
-   connection point, not a target-determined float. **Subtlety we encode:**
-   straightness normally beats port-exactness (the strict-ports experiment was
-   measured and rejected), *except* when a designated port is reachable
-   **without costing a bend** — then take it. The diamond 8-port model exists
-   precisely to make E/F/G/K port-exact *and* straight/symmetric at once.
-3. **Symmetry / balance** — where the structure is symmetric (peer fan-ins,
-   reciprocal pairs), the drawing should be too: a centered hub, two equal
-   parallel lines, no peer privileged over another.
-4. **Fewest bends and crossings** — after the above.
-
-### Specific ugly shapes we have named
-
-- **Cramming at a sharp point** — two lines crowded onto a vertex when they
-  could be spread (the ±6 reciprocal-on-a-diamond-tip, before facet-mids).
-- **Pinch-then-splay / hourglass** — edges converging to a narrow pair of ports
-  then fanning back out to wider targets (the rejected F facet-mid+bend).
-- **A line through a shape's body** — routing the short way *through* a node
-  instead of around it (the rejected G facet-mid prototype).
-- **Asymmetry where symmetry is natural** — a fan-in hub stuck at the top of
-  its sources, or a reciprocal pair of unequal lengths.
-
-## Why detect from rendered output (not just geometry)
-
-The `assessLayout` rubric (`src/layout-rubric.ts`) checks the **internal
-geometry** (`PositionedGraph`). The ugly-detector checks the **rendered
-artifact** — the SVG/PNG/ASCII a consumer actually sees — so it:
-
-1. catches rendering bugs where clean geometry renders wrong;
-2. works on *any* diagram, including external SVGs and golden fixtures not
-   produced by our layout pass;
-3. validates the ASCII pipeline, which is a separate renderer that never sees
-   the `RouteCertificate` contracts.
-
-The three formats degrade in fidelity: **SVG** is the authoritative analysis
-(vector paths + shape geometry are recoverable exactly); **PNG** is a faithful
-raster of an SVG, so its check is "analyze the source SVG, plus a coarse
-pixel-orthogonality sanity pass"; **ASCII** is a glyph grid, so detection is
-limited to what the grid reveals (diagonal line glyphs, edge glyphs inside a
-box interior).
-
-## Running the audit
-
-```
-bun run audit:ugly                # render every corpus to SVG/PNG/ASCII, report
-bun run audit:ugly -- --verbose   # also list soft findings
-bun run audit:ugly -- --json      # machine-readable report
-```
-
-The runner (`eval/ugly-detector/audit.ts`) renders every diagram corpus in the
-project — the contact-sheet scenarios, the heuristic-tracker examples, the
-site samples, the layout-compare fixtures, and the ASCII/Unicode golden
-fixture sources — to all three formats and runs the detectors. It exits
-non-zero if any **hard** finding is present, so it doubles as a CI gate.
-`src/__tests__/ugly-detector.test.ts` pins the detector's behavior.
-
-### What the audit found (2026-06)
-
-Current result on PR #30 after the nested-subgraph route fixes:
-
-```text
-338 diagrams / 1009 format-audits
-0 hard layout defects
-0 soft layout findings
-6 render/corpus errors
-```
-
-The non-clean entries are **render errors** (a diagram type or config header a
-given renderer rejects), not layout defects, and are bucketed as such.
-
-Historical note: an earlier audit found one real hard defect — a
-cross-hierarchy edge into a nested subgraph missing the containing subgraph's
-offset. That is now fixed by hosting cross-hierarchy edges at their lowest
-common compound and by treating subgraph IDs as container endpoints; the
-regressions live in `src/__tests__/subgraph-direction.test.ts`.
-
-Two findings the audit initially raised were **detector** false positives, now
-fixed and regression-tested: a cylinder's footprint must union its cap ellipses
-(not just the body rect), and a sub-pixel endpoint jog within the curved-shape
-clip floor (~1.5px) is not a visible dogleg.

package/docs/diagram-families.md

@@ -1,193 +0,0 @@
-# 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 matrix
-
-| Family | Header(s) | Render | Structured mutation | Notes |
-|---|---|---|---|---|
-| Flowchart | `flowchart`, `graph` | SVG/PNG/ASCII | ✓ | 6 graph ops; narrow with `asFlowchart`. |
-| State | `stateDiagram-v2` | SVG/PNG/ASCII | ✓ | Dedicated `StateBody` (BUILD-19): narrow with `asState`, 8 state-shaped ops. `asFlowchart` returns null. |
-| Sequence | `sequenceDiagram` | SVG/PNG/ASCII | structured (5 ops) | Notes/alt/loop bodies are segment-preserving; un-segmentable syntax falls back to opaque. |
-| Timeline | `timeline` | SVG/PNG/ASCII | ✓ | Supports sections, periods, events, title changes. |
-| Class | `classDiagram` | SVG/PNG/ASCII | ✓ | Classes, members, relations, notes. |
-| ER | `erDiagram` | SVG/PNG/ASCII | ✓ | Entities, attributes, relations. |
-| Journey | `journey` | SVG/PNG/ASCII | structured (10 ops) | `asJourney` narrows documented Journey syntax: title, accTitle/accDescr, sections, scored tasks, and actors. |
-| XY chart | `xychart`, `xychart-beta` | SVG/PNG/ASCII | structured (8 ops) | Vertical/horizontal bar/line/mixed charts; modeled subset is structurally mutable via `asXyChart`. |
-| Pie | `pie` | SVG/PNG/ASCII | structured (7 ops) | `asPie` narrows title/showData/slices; malformed entries and accTitle/accDescr stay opaque. |
-| Quadrant | `quadrantChart` | SVG/PNG/ASCII | structured (7 ops) | `asQuadrant` narrows title/axes/quadrant labels/points; styling and out-of-range coords stay opaque. |
-| Architecture | `architecture-beta` | SVG/PNG/ASCII | structured (10 ops) | `asArchitecture` narrows the modeled subset (groups/services/junctions/edges); the `{group}` boundary modifier and accTitle/accDescr stay opaque. |
-| Gantt | `gantt` | SVG/PNG/ASCII | structured (9 ops) | `asGantt` narrows title/sections/tasks; calendar directives, `click` lines, and comments ride along verbatim as opaque segments. Deterministic: the today marker draws only from a caller-supplied `ganttToday`. See [design/families/gantt.md](./design/families/gantt.md). |
-
-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` (BUILD-19): narrow with `asState` and apply the 8 typed ops (`add_state`, `remove_state`, `rename_state`, `set_state_label`, `add_transition`, `remove_transition`, `set_transition_label`, `make_composite`). The modeled subset is simple states, transitions, `[*]` start/end pseudostates, nestable composite blocks, and `direction`. Anything outside it — `<<fork>>`/`<<choice>>`/`<<join>>`, history states, concurrency `--`, notes, `classDef`/`class`/`:::` styling — falls back to a lossless opaque body and stays source-level. Verify still 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
-```
-
-Simple participants/messages are structured. Rich Mermaid sequence blocks such as notes, `alt`, `loop`, and activation syntax are preserved as opaque source when not modeled.
-
-## 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` and expose 10 structured ops (sections, tasks, scores, actors). 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 subset (bare title, named/categorical/range axes, bar/line series with finite values) is structurally mutable: narrow with `asXyChart` and apply the 8 typed ops (`set_title`, `set_x_axis`, `set_y_axis`, `add_series`, `remove_series`, `set_series_values`, `set_series_name`, `reorder_series`). Quoted text, multi-statement `;` lines, and accTitle/accDescr fall back to opaque and stay 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: `asPie` exposes 7 ops (`set_title`, `set_show_data`, `add_slice`, `remove_slice`, `rename_slice`, `set_slice_value`, `reorder_slice`); slices are addressed by their unique label.
-
-## 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`) and `classDef` lines are accepted for render compatibility but are not modeled for typed mutation; the agent path preserves those charts as opaque source and emits `UNSUPPORTED_SYNTAX` as an advisory warning. 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: `asQuadrant` exposes 7 ops (`set_title`, `set_axis_labels`, `set_quadrant_label`, `add_point`, `remove_point`, `move_point`, `rename_point`); points are addressed by their unique label and coordinates stay in `[0, 1]`.
-
-## 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` exposes 9 ops (`set_title`, `add_section`, `rename_section`, `remove_section`, `add_task`, `remove_task`, `rename_task`, `set_task_status`, `set_task_dates`) on 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.
-
-## 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
-```