agentic-mermaid 0.1.0 → 0.1.2

package/docs/contributing/diagram-family-citizenship.md

@@ -1,82 +0,0 @@
-# Diagram-family citizenship ratchet
-
-Issue: #41. Status: enforced checklist + checked matrix.
-
-A diagram family is a **good citizen** when it is integrated into every runtime, documentation, agent, editor, eval, and distribution surface that teaches users or agents what Agentic Mermaid supports. Rendering is not enough: a family must be discoverable, safely editable when its modeled body narrows, verifiable before render, represented in examples/evals, and either backed by evidence or tracked as an explicit exception.
-
-## Source of truth
-
-`BUILTIN_FAMILY_METADATA` in `src/agent/families.ts` is the canonical shipped-family registry. It records the family id, label, Mermaid headers, typed narrower, live-editor example id/type, and editor glyph. The registry has compile-time coverage against `DiagramKind`; tests then project it into CLI capabilities, MCP/Code Mode, docs, editor examples, eval fixtures, package keywords, and generated discovery docs.
-
-The checked citizenship matrix lives at [`diagram-family-citizenship.matrix.json`](./diagram-family-citizenship.matrix.json). It is intentionally separate from the registry: the registry says “this family ships”; the matrix says “these citizenship surfaces are satisfied, and these remaining gaps are tracked.”
-
-## Semantic correctness vs. system citizenship
-
-Keep these distinct in reviews:
-
-- **Semantic correctness** asks whether a parser/IR/serializer/verifier/renderer preserves the family’s own Mermaid meaning. Examples: Gantt schedule resolution, flowchart route certificates, sequence segment preservation, pie percentage invariants, XY axis/domain laws.
-- **System citizenship** asks whether every supported entry point points to the same typed path. Examples: `am capabilities`, `llms.txt`, `am init-agent`, MCP initialize guidance, SDK declarations, Code Mode sandbox narrowers, editor examples/glyphs, eval fixtures, generated site samples, package exports, and docs tables.
-
-A new family can be semantically good and still fail citizenship if an agent discovering the package through a different surface cannot find the same parse → narrow → mutate → verify → serialize path.
-
-## Checklist surfaces
-
-The matrix has one cell per family for each surface below. A cell is either `satisfied` with concrete evidence paths, or `exception` with a tracked TODO/issue reference. CI fails if a registered family is missing a row, a surface, evidence, or exception tracking.
-
-| Surface | Contract |
-|---|---|
-| `registryDiscovery` | Family appears in `BUILTIN_FAMILY_METADATA`, registered plugins, CLI capability metadata, and typed IDs. |
-| `detectionParse` | Shared detector, agent parse, SVG render, ASCII render, CLI, and MCP paths route consistently; state’s flowchart renderer split is the only documented exception. |
-| `semanticModel` | Modeled syntax subset and opaque/source-preservation ladder are explicit. |
-| `serializeRoundTrip` | Modeled syntax has parse → serialize → parse stability; opaque/segment-preserved syntax round-trips losslessly. |
-| `typedMutation` | A public narrower and mutation ops exist, and opaque fallback bodies do not fake structured mutation. |
-| `verifyRenderSeam` | Modeled syntax has no “verify ok, render throws” path; render-blocking conditions surface as named warnings/errors. |
-| `determinism` | No ambient wall clock/random/locale/process-order dependence; runtime knobs such as `ganttToday` are explicit. |
-| `svgRender` | SVG/PNG-capable rendering path is covered for the family. |
-| `asciiUnicodeRender` | ASCII/Unicode output is covered when advertised. |
-| `layoutProjection` | `layoutMermaid`, quality metrics, and verify layout expose truthful geometry, not placeholder data. |
-| `stableRegions` | Region metadata for editor/TUI/accessibility is present or explicitly tracked as a gap. |
-| `editorExample` | Live editor has a working `Supported diagrams` example and explicit glyph for the family. |
-| `docsAgentSurfaces` | README/docs/spec/skills/agent instructions/SDK declaration/llms surfaces stay in sync. |
-| `evalFixture` | Shared skill benchmark has at least one fixture-backed case tagged `family:<id>`. |
-| `upstreamHarvest` | Official upstream Mermaid examples/tests are harvested into an executable docs corpus, family bench, or accounted parser/DB bench. |
-| `divergenceLedger` | Known compatibility divergences in harvested upstream examples/tests are executable and cannot rot, or tracked for ledger work. |
-| `domainProperties` | Family-specific invariants/properties exist beyond “renders without throwing.” |
-| `goldensEvidence` | Text/SVG/visual evidence exists where reviewer judgment needs artifacts. |
-| `generatedSite` | Site samples/gallery/generated docs include the family or have explicit exceptions. |
-| `distributionPackage` | Package exports/files/consumer init artifacts include the public family surface. |
-| `mutationLane` | Targeted mutation/sabotage lane exists, or a tracked exception explains the gap. |
-
-## Worked example: Gantt
-
-Gantt is the bar for a new family entering the system:
-
-- registry + mutation: `BUILTIN_FAMILY_METADATA`, `asGantt`, typed Gantt ops, CLI capabilities, SDK declaration, MCP sandbox, and `am init-agent` all expose the same path;
-- semantics: `src/gantt/parser.ts`, `src/gantt/schedule.ts`, `src/gantt/layout.ts`, and `src/agent/gantt-body.ts` keep scheduling pure and wall-clock-free;
-- verify/render seam: `UNRESOLVABLE_SCHEDULE` turns render-blocking schedule failures into named verification output;
-- compatibility: `eval/mermaid-gantt-bench/` has cases plus executable exclusions; `src/__tests__/gantt-upstream-bench.test.ts` runs it;
-- properties: `src/__tests__/property-gantt-schedule.test.ts` includes the CPM shadow-model property;
-- evidence: SVG snapshots, ASCII/Unicode goldens, `docs/assets/improvements/gantt-family.png`, and `mutation-test:gantt` cover reviewer-visible and sabotage paths;
-- editor/skill-evals/docs: editor examples, eval fixtures, docs, `llms.txt`, and MCP/Code Mode surfaces are all registry-checked.
-
-## Non-Gantt audit: XY chart
-
-XY chart proves the checklist works for an older family that was promoted after the registry existed:
-
-- citizenship surfaces are satisfied for registry, detection, typed mutation (`asXyChart`), CLI/MCP docs, editor examples, eval fixtures, generated site samples, package exposure, SVG/ASCII output, and layout projection;
-- semantic correctness is pinned by parser/integration/layout/renderer tests and `src/__tests__/property-xychart.test.ts`;
-- mutation-testing citizenship is satisfied through `mutation-test:families`, which mutates `src/xychart/*` together with Architecture;
-- stable region citizenship is satisfied through `src/__tests__/agent-ascii-meta.test.ts`;
-- upstream-docs harvest/divergence citizenship is satisfied through the regenerated `eval/mermaid-docs-corpus/corpus.json`, executable `divergences.json` ledger, `eval/mermaid-gantt-bench/`, and the fully accounted cross-family parser/DB bench in `eval/mermaid-upstream-suite-bench/`.
-
-This is the intended ratchet shape: historical gaps are either closed or represented by a live checked cell. After the BUILD-22 backfill, the matrix has zero exceptions; if a future family introduces one, it must be tracked before merge.
-
-## Review workflow
-
-When adding or changing a family:
-
-1. Add/update `BUILTIN_FAMILY_METADATA` first.
-2. Add/update parser, renderer, agent body, mutation ops, verify behavior, and examples.
-3. Update the citizenship matrix row in the same PR. Prefer `satisfied` with evidence; use `exception` only with a concrete TODO/issue reference.
-4. Run `bun test src/__tests__/diagram-family-citizenship.test.ts src/__tests__/agent-doc-sync.test.ts src/__tests__/editor-examples.test.ts src/__tests__/cli-capabilities.test.ts` before wider validation.
-5. For any matrix exception introduced by the PR, add a follow-up issue or `TODO.md` entry before merge.

package/docs/contributing/harvesting-upstream-tests.md

@@ -1,126 +0,0 @@
-# Harvesting Upstream Test Suites
-
-How to turn "we are compatible with Mermaid" from a claim into a measured,
-CI-gated number — by vendoring the *actual test suites* of upstream
-implementations and running their inputs against ours. First applied to Gantt
-(`eval/mermaid-gantt-bench/`); this guide generalizes the method so any family
-can repeat it. Pairs with [`adding-diagram-types.md`](./adding-diagram-types.md):
-do the harvest no later than the family's first release, and for not-yet-built
-families do it **before** implementation — it is the cheapest way to learn the
-real (as opposed to documented) semantics.
-
-## What a harvest produces
-
-```
-eval/mermaid-<family>-bench/
-  README.md        provenance (repos, files, fetch date, licenses), schema, reason codes
-  cases.json       portable parity cases: upstream inputs + upstream-derived expectations
-  exclusions.json  every upstream case we deliberately do NOT match, each with a reason
-src/__tests__/<family>-upstream-bench.test.ts   the runner (CI, every PR)
-```
-
-The contract that keeps it honest:
-
-1. **Every portable case passes.** Cases assert what upstream asserts —
-   nothing more (our own stronger guarantees belong in our unit/property
-   tests, not in the parity bench).
-2. **Every exclusion is explained by a reason code**, and where the entry
-   names an `oursErrorCode`, the runner **executes it** — proving we fail
-   with exactly that named error. A divergence ledger that runs cannot rot.
-3. **API-internal upstream tests are listed as not-portable** in the bench
-   README (state-reset tests, internal helper unit tests, renderer DOM
-   assertions) so "the entirety of their suite" is fully accounted for.
-
-Template to copy: `eval/mermaid-gantt-bench/` +
-`src/__tests__/gantt-upstream-bench.test.ts`.
-
-## Where the upstream tests live
-
-| Source | Path | What to take |
-|---|---|---|
-| mermaid grammar specs | `packages/mermaid/src/diagrams/<family>/parser/<family>.spec.js` | Source strings + structural assertions (titles, ids, tags, click bindings). Mostly portable. |
-| mermaid semantics specs | `packages/mermaid/src/diagrams/<family>/<family>Db.spec.ts` (some families: `<family>Db.spec.js`, or logic specs beside the db) | The valuable layer: resolved values, ordering, edge cases. Portable after normalization; this is where wall-clock/TZ landmines hide. |
-| mermaid rendering specs | `cypress/integration/rendering/<family>.spec.js` | Inputs only — assertions target THEIR svg dom. Usually redundant with the docs corpus. |
-| mermaid docs examples | `packages/mermaid/src/docs/syntax/<file>.md` | Already wired: add the file to `FILE_TO_FAMILY` in `eval/mermaid-docs-corpus/build-corpus.ts` and floors to `src/__tests__/agent-mermaid-corpus.test.ts`. Docs are de facto behavior — they contain tolerated junk (see gotcha 3). |
-| ASCII forks | `pgavlin/mermaid-ascii` (`pkg/<family>/<family>_test.go`), `kais-radwan/ascii-mermaid` (`ts/test/<family>.test.js`), `AlexanderGrooff/mermaid-ascii` | Inputs + render-smoke only; their byte-level output assertions are theirs. |
-| oracle library | `mermaid-ast` (already a dependency) | A parsing differential (`<Family>.parse(...).toAST()`), not a semantics oracle — it does not resolve values. |
-
-Fetch raw files from the `develop` branch
-(`https://raw.githubusercontent.com/mermaid-js/mermaid/develop/<path>`), record
-the fetch date in the bench README, and **check the license before vendoring**
-(mermaid and both ASCII forks are MIT — attribute in the README; a repo with
-no license file must not be vendored, only summarized).
-
-## The method
-
-1. **Read both spec files end to end** before extracting anything. Count the
-   `it(`/`it.each` blocks; every one must land in cases.json, exclusions.json,
-   or the README's not-portable list.
-2. **Classify each test**: `parse` (structural fields), `schedule`/semantic
-   (resolved values), `error` (both sides reject), excluded (reason code), or
-   API-internal (not representable as diagram source — note it).
-3. **Normalize expectations, never inputs.** Inputs are vendored verbatim.
-   Their local-time `new Date(y, m, d)` tuples become UTC ISO strings; their
-   auto-synthesized ids (`task1`…) become index-based assertions; their
-   boolean tag flags become tag sets.
-4. **Run, and treat every failure as information.** A failing harvested case
-   is one of: a real bug in ours (fix it), a deliberate spec divergence (move
-   to exclusions with a reason + executable error code), or an upstream
-   behavior our spec should adopt (change ours — the gantt `tickInterval
-   1decade` case). Decide explicitly; never weaken a case to make it pass.
-5. **Gate it**: the runner is a normal `bun test` file; the docs-corpus floors
-   are evidence-based and regression-only, with a comment naming each entry
-   that holds the floor below 1.00 and why that is honest.
-6. **Re-run the search before each release** for new upstream tests (the
-   family's design doc should carry the watchlist of in-flight upstream
-   syntax, as `docs/design/families/gantt.md` does).
-
-## Exclusion reason codes
-
-Reuse these before inventing new ones, and document any new code in the bench
-README (the runner asserts every reason is documented):
-
-- `wall-clock-fallback` — upstream substitutes `new Date()` for missing or
-  unparseable inputs; our determinism contract mandates named errors. Always
-  executable (`oursErrorCode`).
-- `local-tz` — the upstream test only means something in a specific timezone
-  (they themselves gate the gantt DST test behind `TZ=America/Los_Angeles`).
-- `silent-ignore-vs-named-error` — upstream tolerates a token its own docs
-  call unsupported; we error by name per the family spec.
-- `exclude-boundary-model` (and siblings) — a real semantic difference,
-  precisely characterized. Where possible state the conservation law both
-  sides satisfy and exactly which inputs diverge.
-
-## Gotchas the gantt harvest hit (check for each of these)
-
-1. **Wall-clock expectations hide inside table tests** — scan for
-   `new Date()` with no arguments and `setHours(0, 0, 0, 0)` in expected
-   values, not just in implementation code.
-2. **TZ/DST-gated tests** can't run verbatim against a UTC-only engine; port
-   the input, assert our UTC behavior, ledger the difference.
-3. **Official docs contain tolerated junk** (`tickInterval 1decade`, a task
-   ending `1s   %% not yet official`). Docs examples are inputs users will
-   paste, so decide tolerate-vs-error consciously against the family spec and
-   put the decision in the ledger either way.
-4. **Boundary semantics can differ while conservation laws agree** — gantt's
-   exclude-walk counts `(start, end]` upstream vs our `[start, end)`. A
-   property test of the conservation law plus a ledger entry for the boundary
-   beats chasing instant-for-instant parity.
-5. **The harvest finds seams, not just bugs**: the very first harvested gantt
-   case exposed verify saying ok while render threw, which became the
-   `UNRESOLVABLE_SCHEDULE` warning. When a harvested input behaves
-   inconsistently across our own surfaces (parse vs verify vs render), that
-   inconsistency is the finding.
-6. **Upstream resolves more than you may assume** — their gantt resolver
-   handles forward references; we had documented the opposite. The harvest
-   corrects folklore about upstream as a side effect.
-
-## Definition of done
-
-- Every upstream test block accounted for (cases / exclusions / not-portable).
-- All cases green; all executable exclusions green; bench README has
-  provenance, fetch date, licenses, schema, and reason codes.
-- Docs-corpus family entries + floors wired (`build-corpus.ts`,
-  `agent-mermaid-corpus.test.ts`).
-- Divergences that changed our behavior are reflected in the family's design
-  doc and CHANGELOG.

package/docs/contributing/lessons-learned.md

@@ -1,276 +0,0 @@
-# Lessons learned
-
-Process lessons this repo has paid for, so they only have to be paid for once.
-Each entry names the incident that taught it. Add new lessons at the top with a
-date; do not delete old ones — supersede them in place.
-
-> **Scope.** This is the dated contributor process log. For the long-form
-> cumulative fork narrative (loops 1–22), see
-> [`../project/lessons-learned.md`](../project/lessons-learned.md).
-
-## 2026-07 — style coverage and typography semantics
-
-**A style transform is a semantic contract, not a blanket SVG rewrite.**
-The first style-coverage pass made typography expressive enough to expose an
-important boundary: class names, entity names, relationship labels, section
-labels, chart titles, and task labels are diagram labels; class members and ER
-attributes are schema/code-like literals. Uppercasing `Account` to `ACCOUNT`
-is a look. Uppercasing `displayName`, `createdAt`, `orderId`, or
-`closeAccount(reason: string)` destroys authored signal. Rule: label transforms
-apply to labels; syntax-like internals still participate in role-token paint
-and contrast audits, but keep authored casing unless a future explicit
-`member`/`attribute`/`syntaxText` policy says otherwise.
-
-**Measure the text the renderer will actually draw.** Aggressive typography is
-not layout-neutral: uppercase, weight, letter spacing, and compact labels all
-change measured width and row/axis/title budgets. The Gantt fix had to measure
-the transformed/tracked text, not the Mermaid source token, before rendering
-compact task labels and axes. Rule: any layout that reserves space for text
-must run the same transform path that the renderer uses, or the style will pass
-unit tests while visibly clipping in the editor.
-
-**Coverage evidence has to separate plumbing, readability, and taste.** The
-state-space diagram and galleries explain what the style catalog covers, but
-the durable gate is `style:audit`: every built-in family is rendered with
-sentinel role tokens, role propagation is checked, and contrast floors are
-enforced. Visual galleries answer "are these looks differentiated?"; the audit
-answers "does the style system reach the elements it claims to reach?" Keep
-both, and be explicit about the remaining gap: arbitrary user-authored
-style/palette stacks are not yet universally WCAG-proved.
-
-## 2026-07 — the layout-shift audit and look-control rework
-
-**User-initiated layout shift is CLS-exempt but still visible jank — diff
-positions, don't trust the metric.** A whole-site audit read CLS 0.000
-everywhere, yet clicking the home "Use with an agent" button slid its
-neighbours 83px, selecting a diagram style reflowed the wrapped mobile topbar
-by a full row (the theme dropdown jumped 284px), and the editor's "Copy agent
-prompt" slid 81px. All fired within 500ms of the click, so `hadRecentInput`
-flagged them out of the Core Web Vitals number. Rule: to audit click-induced
-shift, diff each anchor's bounding rect before/after the interaction and read
-the raw (unfiltered) `layout-shift` entries — CLS alone certifies nothing about
-what the user sees at the moment they click.
-
-**A width reservation is only correct once you check every breakpoint it
-crosses.** The Share button grew ~7px when its label became "Copied"; the
-obvious fix — a permanent inline `min-width` — would have overridden the
-≤760px `font-size:0` rule and broken the mobile icon-only square, because
-inline styles beat media queries. Reserving the label's width in `em` instead
-collapsed to 0 exactly when the mobile rule zeroed the font. Rule: prefer a
-unit/property the responsive rules can still override, and verify the
-reservation at each breakpoint it passes through before shipping it.
-
-**A layout invariant stated in a component's own copy is a test spec.** The
-seed-shuffle button's tooltip said "(never moves layout)" — true when clicked,
-false when it *appeared*, which is what reflowed the topbar. The existing
-style-switch test asserted "the chrome never moves" but only compared colours,
-so the regression passed straight through it. Rule: when a component claims a
-layout invariant (in a tooltip, a comment, or a test's own name), the guarding
-test must assert positions, not a proxy like colour.
-
-**Restructure by re-wrapping markup and re-scoping CSS; touch the JS only when
-an id or class contract actually changes.** Fusing the Style and Theme
-dropdowns into one split pill kept every button/wrap/menu id and the `.open`
-class the shared popup controller toggles, so selection, keyboard, and focus
-logic ran unchanged — the only rename was a CSS-only button class. Rule: when
-JS binds elements by id and toggles known classes, a visual restructure is a
-markup + CSS job; reading the id/class contracts first tells you whether the JS
-is even in scope.
-
-**Label from the code's own vocabulary, and check the word against its sibling
-controls.** "Theme" for the palette axis collided with the adjacent light/dark
-toggle and with Mermaid's `themeVariables`, and was category-muddy (internally
-a theme is a palette-only style) — while the style registry, CLI, and docs
-already called it a "palette." Relabelling to "Palette" was three visible
-strings with no code rename: there is no public `theme` render field, and
-renaming `state.theme` / `data-theme` / the localStorage key would have broken
-saved editor state and share links. Rule: audit where a term is actually used
-before putting it on a control; a user-facing label is not an API, and the two
-are allowed to differ.
-
-## 2026-07 — the website consolidation PR (#113)
-
-**A long-running branch that commits generated output collides catastrophically
-with a base that stops committing it — keep website changes source-only.** PR
-#113 committed the whole `website/public` bundle (100+ files) across nine
-commits. Meanwhile `main` (#110) had made `website/public` a gitignored build
-artifact, rebuilt by the test preload and at deploy. The result was a "dirty"
-PR whose merge was ~20 modify/delete conflicts on generated pages — the actual
-change (five source files) was buried under hundreds of artifact diffs.
-Resolution was to adopt the artifact model (`git rm -r website/public`, keep
-only `build.ts`, `source/pages`, the contract test, and `TODO.md`), which
-collapsed the PR from ~86 changed files to 5. Rule: never commit
-`website/public`; a website PR's diff is source only. A committed generated
-bundle turns every base change into a conflict and hides the real edit in noise.
-
-**Deterministic build + `website:check` can pass on wrong-but-deterministic
-output — assert content, not existence.** The sitemap (the PR's headline
-feature) shipped with only an `existsSync` gate. Because the build is
-deterministic and `website:check` only diffs regenerated-vs-committed output, a
-stale or malformed sitemap would regenerate identically and pass every gate —
-the wrong output is reproduced, not caught. A multi-agent audit flagged it; the
-fix asserts the sitemap lists exactly the live pages (no removed routes, no
-machine artifacts, one `<loc>` per page) and was verified red→green by injecting
-a removed route. Rule: for generated content, the test must *discriminate*
-correct from incorrect output, because determinism guarantees a wrong generator
-passes a same-vs-same check.
-
-**`bun test` green is not `tsc` green, and a piped exit code lies.** A new test
-passed `bun test` but failed strict `bun x tsc --noEmit` — a `matchAll` capture
-group is typed `string | undefined`. It nearly shipped because
-`bunx tsc … | tail` printed "exit: 0": the pipeline's status was `tail`'s, not
-tsc's, masking two real type errors. Rule: run the actual CI gate
-(`bun x tsc --noEmit`) after adding tests, and read `${PIPESTATUS[0]}` (or drop
-the pipe) so a tool's failure is never hidden behind a successful `tail`/`grep`.
-
-**Check what the platform already serves before adding a competing file.**
-Production serves Cloudflare's *managed* content-signals `robots.txt` at the
-edge; a repo `website/public/robots.txt` would likely have been shadowed and
-never delivered its `Sitemap:` line. A live `curl` settled it — the repo file
-was removed and the directive routed to the Cloudflare dashboard (TODO DEC-5).
-Corollary: for platform-managed surfaces (robots.txt, headers, redirects),
-verify the live response before shipping an asset that may never win. And a
-related cleanup that landed the same PR: hand-maintained parallel route lists
-drift (the `_redirects` list had silently dropped `/about/design`) — derive
-them from one source (here, the emitted-pages map) to delete the drift class.
-
-## 2026-07 — the brand-system and chrome-polish passes
-
-**Design intent and shipped hex drift apart; compute claims on what shipped.**
-The pine accent was chosen 28° of OkLCH hue from the semantic success green —
-in the design tool. The shipped hexes had converged to 15° apart (11° in dark
-mode): links and "Copied" confirmations read as one colour, worse for
-deuteranopes, and the review that picked pine had cited the design-intent
-number. The separation now lives as an executable claim
-(`chrome-token-lockstep.test.ts` asserts ≥ 20° on the shipped values). Rule:
-any colour-relationship claim is computed on the committed hex, and if the
-relationship matters, it becomes a test.
-
-**A "keep in lockstep" comment is a hope; a test is a guarantee.** Three files
-carried the shared chrome tokens (site stylesheet, editor stylesheet, and the
-editor's `chromeThemeColors()` in JS), synchronized only by comments — and a
-12% vs 13% hairline drift had already shipped that way. The lockstep test now
-extracts the triplet, brand chip, functional hues (both polarities), radii,
-motion tokens, and the hairline mix from all three sources and asserts
-equality. Corollary: the first draft of that test was itself rejected by the
-repo's test-quality lint (`toBeTruthy`) — new guard code has to pass the
-house's existing guards.
-
-**A rebrand includes the assets nobody opens.** Months of chrome work shipped
-while `og-image.png` still read "Beautiful Mermaid — by the team at Craft":
-the upstream project's card, wrong name, pre-fork palette, posted on every
-social share of the site. The CSS was audited to the percent; the PNG was
-never looked at. Rule: a brand change enumerates its raster/social surfaces —
-og-image, touch icons, favicon, README-rendered artifacts, repo social
-preview — and someone *views* each one.
-
-**Breakpoint boundaries hide unreachable controls; probe them mechanically.**
-Between 761 and ~1000px the editor topbar clipped with no scroll path — Copy
-agent prompt and Export Image were simply unreachable on an iPad portrait,
-8px above the mobile breakpoint. Nothing failed: no overflow, no console
-error, desktop and phone both fine. The check that catches it is mechanical
-(every interactive element's bounding rect inside `innerWidth`, sampled just
-above each breakpoint), and the fix is a policy, not a tweak: toolbars either
-wrap or scroll; they never assume they fit.
-
-**When one value moves, its coupled values move with it.** The iOS input-zoom
-fix (16px fields under coarse pointers) would have silently desynced the
-line-number gutter, which shares the textarea's font metrics row-for-row; the
-`forced-colors` block predated the new functional tokens and left them
-unmapped under Windows High Contrast. Both were caught only by asking "what
-else derives from or aligns with this?" before shipping. Same failure shape
-in both: a correct local change, an unenumerated dependency.
-
-**Verify a suspected gap exists before fixing it.** A review flagged popover
-keyboard handling (Escape, focus restore) as unaudited. The audit found a
-shared `createPopupController` already covering all seven popovers, including
-roving tabindex in the theme listbox. "Audited, no change needed" is a
-result worth reporting; patching per-component without looking for the shared
-mechanism would have added the inconsistency it meant to prevent.
-
-**Consistency work starts with a census, not a scroll-through.** Grep every
-value class and count occurrences (radii, durations, easings, font sizes,
-press scales, icon strokes, z-indexes, gaps) — the count-one entries are the
-findings. This surfaced 58 untokenized transition durations, three press
-scales where the system wanted one, five icon stroke weights where two were
-deliberate, and seven magic z-indexes with an accidental popover-above-popover
-ordering. Eyeballing pages finds none of these reliably.
-
-## 2026-07 — the label-overlap audit and remediation
-
-**A metric you never measure is a defect class you ship.** No gate measured
-label-label or label-box occlusion in any family until the 2026-07 audit — and
-the curated, human-reviewed corpus itself carried collisions in five families
-(architecture edge-label pairs, quadrant point labels, gantt compact rows,
-state reciprocal pills, flowchart feedback pills). The blind spot had even been
-*seen* and deferred (issue #42's review explicitly carved out "a separate
-label-lane/self-loop policy") — deferral without an owner issue is how a known
-gap becomes an ambient defect. Rule: every deferral gets a filed issue at
-deferral time (see the closure-hygiene lesson below).
-
-**Detector first, then the fix, then the detector becomes the gate.** The
-remediation sequence that worked: build the overlap auditor → calibrate it on
-the curated corpus (which also separates auditor bugs from real defects — two
-of the initial finding classes were the auditor's own rotation and region-
-border mistakes) → fix family by family with the detector red first → land the
-detector as a permanent gate (`label-overlap-gate.test.ts`: corpus at zero,
-per-family fuzz ratchets). A fix without the standing gate would regress
-silently; a gate calibrated before the corpus was clean would have been
-disabled as noisy.
-
-**"Generator noise" is a hypothesis, not a verdict.** The deep-fuzz
-`offOutlineEndpoints` hits were dismissed as duplicate-parallel-edge generator
-artifacts — but duplicate parallel edges are *valid Mermaid*, and that same
-input class turned out to break certificate completeness (#83) and stack labels
-(70% of fuzzed state diagrams). When a fuzz class is excused, the excuse needs
-the same evidence bar as a fix: either the input is genuinely invalid, or the
-class gets an owner issue.
-
-**Fixing one flaky suite does not fix the policy.** Hours after the
-route-contracts seeds were pinned (#86), a *different* property file
-(`property-mermaid-source-and-parser.test.ts`) failed CI on a rolled seed — its
-generator emitted grammar-ambiguous ids (`s---Py3` reads as the link
-`s --- Py3`, in this engine and in Mermaid) that only rare seeds produce. Two
-sub-lessons: property generators must be constrained to inputs whose expected
-behavior is actually unambiguous, and a determinism policy has to be applied as
-a sweep (every fast-check suite), not incident-by-incident.
-
-**An invariant enforced by a random property is a lottery, not a gate.**
-Certificate completeness was guarded only by an unpinned fast-check property —
-it fired roughly one CI run in seven, which reads as "flaky CI" rather than
-"real bug" and trains people to re-run. Invariants get deterministic gates
-(enumerated corpus + pinned seeds); randomness is for *finding* new
-counterexamples (deep fuzz lanes), not for *holding* known ground.
-
-**A dead quality signal is worse than no signal.** Every CI run printed "the
-mutation score is the adequacy signal" while the nightly mutation lane had been
-timing out (cancelled) for over a week — the signal's *existence* was asserted
-by docs while its *output* was absent, and nothing alarmed. If a scheduled
-gate's failure/cancellation isn't itself surfaced (a required check, a badge, a
-notification), the gate will die quietly exactly when it matters.
-
-## 2026-07 — tracker archaeology (issues 1–83)
-
-**Closure needs receipts on the issue, at closure time.** The audit found
-issues closed with zero receipts (#29, #34, #36, #41), an issue closed against
-its own last comment (#32), and closures that predated their fix (#37, #38's
-first close). Each needed a later archaeology pass to reconstruct. The rule
-this repo now follows: an issue closes with a comment naming the receipts
-(tests, docs, PRs, measurements) — and if part of the scope is deferred, the
-follow-up issue is filed *in the same action* (#87–#90 are the back-fill for
-past deferrals).
-
-**A pass that mutates geometry owns the consequences of the mutation.** Three
-post-freeze repairs re-routed edges and dropped their certificates without
-re-issuing them (#83); the shove pass moved nodes and left overlaps behind
-(#81). The doctrine that fixed both: any pass that mutates layout state must
-hand every invariant on — re-anchor the edges it moves, re-certify the routes
-it rewrites, re-separate the boxes it displaces. "A later pass will catch it"
-is how symptom-repair whack-a-mole starts.
-
-**Fix the invariant upstream, keep the net downstream.** The #81 degenerate
-class (18 fuzz signatures) collapsed to zero by restoring one upstream
-invariant (no node overlaps after a shove) — after a session of fixing
-individual routing symptoms had removed only one sub-class. The post-freeze
-nets stay as insurance, but they are gated on violations that should never
-occur, not used as the primary mechanism.

package/docs/contributing/releasing.md

@@ -1,71 +0,0 @@
-# Releasing `agentic-mermaid` to npm
-
-The package is published by [`.github/workflows/publish.yml`](../../.github/workflows/publish.yml),
-which triggers on a **published GitHub Release**. The workflow reproduces CI's
-deterministic gate (tests, `tsc`, `hero:check`, `website:check`, golden-drift,
-incremental mutation), fuzzes the built bundle + packed tarball under Node,
-builds with `tsup`, and runs `npm publish --access public`. There is no manual
-`npm publish` step.
-
-Publishing uses **npm OIDC trusted publishing** — no `NPM_TOKEN` secret. The
-workflow mints a short-lived OIDC id-token (`permissions: id-token: write`), npm
-verifies it against the trusted-publisher config, and **provenance is generated
-automatically** (no `--provenance` flag).
-
-## Preconditions (one-time, before the first release)
-
-- **Register the trusted publisher on npmjs.com.** On the (first-time: create the
-  placeholder package, or use the org's package settings) package's
-  Settings → Publishing access → "Add trusted publisher" → GitHub Actions, set:
-  organization/user `adewale`, repository `agentic-mermaid`, workflow filename
-  `publish.yml` (leave environment blank). This must be done before the first
-  `npm publish` or it fails with an auth error.
-- **The GitHub repo must be public.** Provenance writes to a public transparency
-  log and is **not** generated for private repos. If the repo must stay private,
-  publishing works but without provenance.
-- **Three-way repository match.** The OIDC token's repo, the npmjs.com
-  trusted-publisher config, and `package.json#repository.url`
-  (`git+https://github.com/adewale/agentic-mermaid.git`) must all agree — they do.
-- **Account 2FA** on the publishing account (WebAuthn/FIDO; TOTP is being
-  deprecated).
-- `npm view agentic-mermaid version` — confirm the version isn't already
-  published (first release: expect a 404).
-
-The workflow pins Node 22 and upgrades to the latest npm (trusted publishing
-needs npm ≥ 11.5.1 / Node ≥ 22.14).
-
-## Cutting a release
-
-1. **Land everything on `main` green.** Releases are cut from `main`, whose CI
-   has already run; `publish.yml` re-runs the deterministic gate + artifact fuzz
-   as a backstop.
-2. **Bump `version`** in `package.json` (first release is `0.1.0`). `llms.txt` /
-   `am capabilities` derive the version from `package.json`, so no manual edit.
-3. **Roll the changelog.** Retitle `## Unreleased` in
-   [`CHANGELOG.md`](../../CHANGELOG.md) to `## <version> — <YYYY-MM-DD>` and open a
-   fresh empty `## Unreleased` above it.
-4. **Flip the "published" copy** (see below), commit via PR, and merge to `main`.
-5. **Create the GitHub Release** on the merge commit (tag `v<version>`). Its
-   publication fires `publish.yml`, which gates, builds, and publishes.
-6. **Verify:** `npm view agentic-mermaid version` shows the new version;
-   `npm install agentic-mermaid` into a scratch project resolves and its bins run.
-7. **After the first publish,** set the package on npmjs.com to
-   "Require two-factor authentication and disallow tokens" — trusted publishing
-   keeps working, and token-based publishing is locked out.
-
-## The "published" flip
-
-Before the first npm publish, the repo deliberately said *"not yet published;
-install from source"*. The 0.1.0 release-prep PR flips these surfaces to the
-published copy:
-
-- **Website** — the install card is generated by [`website/build.ts`](../../website/build.ts)
-  (run via `bun run website`, deployed to Cloudflare Workers with `wrangler` via
-  [`.github/workflows/deploy-cloudflare.yml`](../../.github/workflows/deploy-cloudflare.yml)).
-  The default release build shows `npm i agentic-mermaid`; use
-  `SITE_NPM_STATUS=source` or `SITE_NPM_PUBLISHED=0` only for pre-publish source
-  install previews.
-- **README** — npm-install-first [Installation](../../README.md#installation)
-  copy and the `Published on npm as agentic-mermaid` status line.
-- **`docs/getting-started.md`** — `npm install agentic-mermaid` is the primary
-  Install block.

package/docs/contributing/visual-review-evidence.md

@@ -1,53 +0,0 @@
-# Visual review evidence
-
-Agentic Mermaid layout changes need evidence that is reproducible from source,
-not hand-edited screenshots. Use the smallest artifact that matches the change.
-
-## Required evidence by change type
-
-| Change type | Required evidence |
-|---|---|
-| Route contracts, ports, shape anchors, or contact geometry | `bun test src/__tests__/route-contracts.test.ts src/__tests__/contact-sheet.test.ts`; regenerate/review `docs/pr-assets/contact-sheet.png` when scenarios or geometry intentionally change. |
-| Duplicate / parallel edges (a multigraph — the same directed pair written more than once) | `bun test src/__tests__/route-contracts.test.ts`; review the duplicate/parallel cases on the contact sheet (`AP`–`AR`) and the crossing ratchet in `layout-rubric.test.ts`. A duplicate-specific before/after lives at `docs/pr-assets/issue-62-duplicate-edge-lanes-before-after.png` (regenerate with `bun run scripts/pr-assets/issue-62-evidence.ts`). |
-| ASCII/Unicode routing or region metadata | Exact goldens/tests: `bun run goldens:ascii:check` plus relevant `src/__tests__/ascii*.test.ts` / `agent-ascii-meta.test.ts`. |
-| Family renderer/layout changes | Family parser/layout/renderer tests, SVG snapshot where available, and `agent-family-layouts.test.ts`. |
-| Broad layout heuristics | `bun run rubric:visual` and/or `eval/layout-compare` before/after output attached to the PR. Commit only small canonical assets; attach large HTML reports as artifacts. |
-| Website/editor visual changes | `bun test e2e/browser.test.ts`; inspect captured screenshots when baselines or UI structure change. |
-| Region/action metadata only | Prefer JSON/SVG metadata assertions over raster screenshots; include one representative fixture proving stable `data-region`/sidecar IDs. |
-
-## Artifact meanings
-
-- `docs/pr-assets/contact-sheet.png` is the committed reviewer contact sheet for route/port geometry. The byte-match test ensures it reflects the current renderer. Scenarios `AP`–`AR` cover duplicate/parallel edges: duplicates must render as evenly-separated, nested (non-crossing) parallel lanes — never a collapsed single line or a crossed pair.
-- The duplicate-edge crossing ratchet (`layout-rubric.test.ts`) counts duplicate-pair crossings over the random-flowchart generator and holds the count at or below its pinned baseline. Duplicate edges share both endpoints, so a crossing between them is never logically required; the baseline is a regression ceiling whose target is zero — lower it when the count drops.
-- `eval/visual-rubric` produces deterministic scored galleries. Its scores are a gate for obvious regressions, not a replacement for human review.
-- `eval/layout-compare` compares before/after layout faithfulness and quality over a corpus. “0 regressions” means no configured metric/faithfulness regression, not a claim of pixel parity with Mermaid.js.
-- Browser screenshots prove the shipped site/editor still renders and remains usable. Pixel-diff is only active when dependencies are available, so reviewer inspection still matters.
-
-## Golden-snapshot drift gate (`[approve-goldens]`)
-
-Committed goldens under `src/__tests__/testdata/` are a **hard CI gate**, not an
-ignorable warning. The `ci.yml` "Golden snapshot drift" step fails the build if:
-
-- running the suite leaves **uncommitted** changes under `testdata/` (regenerate
-  and commit them), or
-- the PR's HEAD commit **modifies** committed goldens **without** an approval
-  line starting with `[approve-goldens]`.
-
-So when a renderer change legitimately moves goldens: regenerate them, **review
-the diff** (this is the human decision the gate enforces), commit the result,
-and **start a commit-message line** with `[approve-goldens]`. The token only
-counts at the start of a line — merely mentioning it mid-sentence (as this doc
-does) is not approval, so prose about the gate can't trip it. A standalone
-`[approve-goldens]` line on a commit that changes no goldens also fails, to keep
-the token meaningful. The gate logic lives in `scripts/ci/golden-drift.ts` and is
-unit-tested; the PR template restates it as a checklist item.
-
-## Reviewer checklist
-
-1. Does the PR say which visual command was run?
-2. Are generated artifacts reproducible from committed source/fixtures?
-3. If a committed PNG/snapshot changed, is the change explained in the PR body?
-4. If a visual check is skipped, is there a reason and an alternate structural test?
-5. Are large generated reports linked/attached rather than committed?
-6. For peer fan-in/fan-out screenshots, is the hub centered over the peer group?
-7. Does the review wrapper match the rendered diagram background, or use a neutral surface, so it does not create false label/background contrast?