agentic-mermaid 0.4.1 → 0.5.3

package/docs/theming.md

@@ -21,6 +21,23 @@ const svg = renderMermaidSVG(source, {
 
 From those colors the renderer derives contrast-aware node fills, labels, edges, and accents. This is the safest default for agents: pick readable foreground/background colors and let the renderer complete the palette.
 
+Automatic card and boundary outlines adjust the palette's `border` candidate
+to reach at least 3:1 contrast against a known opaque diagram background. This
+shared rule also applies when a look and palette are stacked. Authored strokes
+and `roles.node.borderColor` / `roles.group.borderColor` keep their exact paint,
+including intentionally hidden or zero-width outlines.
+
+Opaque literal background and foreground colors (hex, RGB, HSL and named
+colors) share concrete contrast resolution for outlines, text and connectors.
+Palette tokens and host-controlled CSS variable references remain authored.
+
+This background comparison does not certify contrast against nested custom
+fills or an arbitrary host behind a transparent SVG. Unresolved CSS colors and
+translucent outline/background colors retain their supplied values; choose and
+check those paints against the actual embedding surface.
+The ratio compares source paint colors. Check thin outlines at the intended
+PNG size, since antialiasing changes individual pixels.
+
 ## Enriched mode
 
 Use extra slots when your product already has semantic tokens:
@@ -127,23 +144,25 @@ For per-element emphasis, keep using Mermaid-native directives such as `classDef
 
 ## Security and fonts
 
-Default SVG output can include Google Fonts `@import` rules. The selected font
-gets one only when it is a single plain family name; class and ER diagrams can
-also import JetBrains Mono for monospace labels. CSS-variable references and
-font stacks do not produce an import for the selected family. For offline,
-strict, or agent-generated artifacts, use either:
+Default SVG output makes no font requests. Google Fonts `@import` rules are
+opt-in via `embedFontImport: true`; the selected font then gets one only when it
+is a single plain family name, and class and ER diagrams can also import
+JetBrains Mono for monospace labels. CSS-variable references and font stacks do
+not produce an import for the selected family.
 
 ```ts
-renderMermaidSVG(source, { embedFontImport: false })
+renderMermaidSVG(source, { embedFontImport: true })
 ```
 
-or strict mode:
+For untrusted diagrams, use strict mode:
 
 ```ts
 renderMermaidSVG(source, { security: 'strict' })
 ```
 
-`security: 'strict'` disables external-fetch references and is the recommended default for untrusted diagrams.
+`security: 'strict'` disables external-fetch references, including font imports
+requested with `embedFontImport: true`, and is the recommended default for
+untrusted diagrams.
 
 For custom Style font selection, browser faces, PNG `fontDirs`, fallbacks, and
 output-surface differences, see [Fonts in custom styles](./custom-fonts.md).

package/examples/styles/readme-hero.md

@@ -0,0 +1,25 @@
+# README hero: login with MFA
+
+The hero is a direct Agentic Mermaid PNG render of
+[`readme-hero.mmd`](readme-hero.mmd). The source includes credential validation,
+an MFA decision and two labeled retry paths to sign-in. Its authored classes
+color the MFA check and the successful session path.
+
+The style stack is `hand-drawn`, `nord-light`, then
+[`readme-hero.style.json`](readme-hero.style.json), which increases node and edge
+label sizes. The drawing seed is 11. No other artwork or text is added to the
+renderer output.
+
+From a source checkout with dependencies installed, generate the PNG directly:
+
+```sh
+bun run bin/am.ts render examples/styles/readme-hero.mmd --format png \
+  --style hand-drawn,nord-light,examples/styles/readme-hero.style.json \
+  --seed 11 --fit-width 1600 --security strict --output assets/hero.png
+```
+
+`bun run hero` uses the same source and options through `renderMermaidPNG` and
+updates the existing SVG freshness record. `bun run hero:check` checks that
+record against fresh renderer output; inspect the PNG after regeneration.
+
+This is an illustrative login flow, not a complete authentication design.

package/examples/styles/readme-hero.mmd

@@ -0,0 +1,13 @@
+flowchart LR
+  User([User]) --> Login[Sign in]
+  Login --> Credentials{Valid?}
+  Credentials -->|no| Login
+  Credentials -->|yes| MFA{MFA passed?}
+  MFA -->|no| Login
+  MFA -->|yes| Session[Create session]
+  Session --> Dashboard([Dashboard])
+
+  classDef challenge fill:#ebcb8b,stroke:#5e81ac,color:#2e3440
+  classDef success fill:#a3be8c,stroke:#4c566a,color:#2e3440
+  class MFA challenge
+  class Session,Dashboard success

package/examples/styles/readme-hero.style.json

@@ -0,0 +1,7 @@
+{
+  "formatVersion": 1,
+  "roles": {
+    "node": { "fontSize": 20, "paddingX": 18, "paddingY": 12 },
+    "edge": { "fontSize": 16, "lineWidth": 1.8, "bendRadius": 8 }
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-mermaid",
   "mcpName": "io.github.adewale/agentic-mermaid",
-  "version": "0.4.1",
+  "version": "0.5.3",
   "license": "MIT",
   "description": "Agentic Mermaid: render, verify, and safely edit Mermaid diagrams as ASCII, PNG, SVG, or structured agent workflows — with composable styles (hand-drawn, excalidraw, watercolor, or your own as JSON).",
   "type": "module",
@@ -24,23 +24,45 @@
       "default": "./dist/agent-core.js"
     },
     "./browser": "./dist/browser.global.js",
+    "./svg": {
+      "types": "./dist/svg.d.ts",
+      "import": "./dist/svg.js",
+      "default": "./dist/svg.js"
+    },
+    "./svg/styles": {
+      "types": "./dist/svg-styles.d.ts",
+      "import": "./dist/svg-styles.js",
+      "default": "./dist/svg-styles.js"
+    },
     "./browser/lazy": {
       "types": "./dist/browser-lazy/index.d.ts",
       "import": "./dist/browser-lazy/index.js",
       "default": "./dist/browser-lazy/index.js"
     },
     "./style-spec.schema.json": "./docs/schemas/style-spec.schema.json",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./zenuml": {
+      "types": "./dist/zenuml.d.ts",
+      "import": "./dist/zenuml.js",
+      "default": "./dist/zenuml.js"
+    }
   },
   "unpkg": "./dist/browser.global.js",
   "jsdelivr": "./dist/browser.global.js",
+  "imports": {
+    "#elk-constructor": {
+      "node": "./dist/elk-constructor.node.js",
+      "default": "./dist/elk-constructor.js"
+    }
+  },
   "bin": {
     "am": "dist/am.js",
     "agentic-mermaid": "dist/am.js",
     "agentic-mermaid-mcp": "dist/agentic-mermaid-mcp.js"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22",
+    "bun": ">=1.4.0"
   },
   "publishConfig": {
     "access": "public",
@@ -80,6 +102,14 @@
     "mindmap",
     "git-graph",
     "radar-chart",
+    "sankey-diagram",
+    "c4-diagram",
+    "packet-diagram",
+    "kanban",
+    "requirement-diagram",
+    "treemap",
+    "ishikawa",
+    "block-diagram",
     "visualization",
     "theming",
     "styles",
@@ -95,6 +125,7 @@
     "assets/fonts/",
     "assets/hero.png",
     "docs/*.md",
+    "!docs/community-benchmark-ranking.md",
     "docs/schemas/style-spec.schema.json",
     "examples/styles/",
     "skills/",
@@ -111,61 +142,57 @@
     "!dist/metafile-esm.json"
   ],
   "scripts": {
-    "test": "bun test --coverage --timeout 30000 src/__tests__/",
+    "test": "bun test --timeout 30000 src/__tests__/ eval/family-usage/count.test.ts eval/endpoint-marker/architecture-metrics.test.ts",
+    "test:coverage": "bun run test -- --coverage",
     "typecheck": "bun run typecheck:core && bun run typecheck:repo",
     "typecheck:core": "tsc --noEmit -p tsconfig.json",
-    "typecheck:repo": "tsc --noEmit -p tsconfig.repo.json",
+    "typecheck:repo": "bun eval/trident/prepare.ts && tsc --noEmit -p tsconfig.repo.json",
     "quality:check": "bun run scripts/ci/quality-gates.ts",
-    "evidence:check": "bun run scripts/ci/quality-gates.ts --evidence-only",
+    "generate": "bun run generate:sdk && bun run generate:browser-families && bun run doc-blocks && bun run agent-doc-artifacts && bun run style-spec-artifacts",
     "format": "biome format --write .",
     "format:changed": "biome format --write --changed",
     "test:browser": "bun run e2e/run-browser-contracts.ts",
     "editor": "bun run scripts/site/editor.ts",
     "dev": "bun run website:dev",
-    "bench": "bun run eval/benchmark/sample-bench.ts",
-    "benchmark:palette": "bun run eval/palette-performance/run.ts --record",
-    "benchmark:palette:check": "bun run eval/palette-performance/run.ts --check",
+    "bench": "bun eval/benchmark/commands.ts bench",
+    "bench:samples": "bun eval/benchmark/commands.ts bench:samples",
+    "bench:dave": "bun eval/benchmark/commands.ts bench:dave",
+    "bench:micro": "bun eval/benchmark/commands.ts bench:micro",
+    "bench:experiments": "bun eval/benchmark/commands.ts bench:experiments",
+    "bench:pipeline": "bun eval/benchmark/commands.ts bench:pipeline",
+    "bench:peers": "bun eval/benchmark/commands.ts bench:peers",
+    "bench:peers:qualify": "bun eval/benchmark/commands.ts bench:peers:qualify",
+    "bench:release": "bun eval/benchmark/commands.ts bench:release",
+    "bench:release:browser": "bun eval/benchmark/commands.ts bench:release:browser",
     "harvest:upstream": "bun run eval/mermaid-upstream-suite-bench/harvest.ts",
     "harvest:upstream:refresh-check": "bun run eval/mermaid-upstream-suite-bench/refresh-check.ts",
-    "build": "tsup && bun run build:browser && bun run build:browser:lazy",
+    "build": "bun run generate:sdk && tsup && bun run build:browser && bun run build:browser:lazy && bun run build:zenuml",
     "build:browser": "tsup --config tsup.browser.config.ts",
-    "build:browser:lazy": "bun run scripts/build/clean-browser-lazy.ts && bun run generate:browser-families && tsup --config tsup.browser-lazy.config.ts && bun run check:browser-lazy",
+    "build:browser:lazy": "bun run scripts/build/clean-browser-lazy.ts && bun run generate:browser-families && tsup --config tsup.browser-lazy.config.ts",
     "check:browser-lazy": "bun run scripts/build/browser-lazy-report.ts",
+    "generate:sdk": "bun run scripts/build/generate-sdk-declarations.ts",
     "generate:browser-families": "bun run scripts/build/generate-browser-family-catalog.ts",
     "check:browser-families": "bun run scripts/build/generate-browser-family-catalog.ts --check",
+    "check:output-identity": "bun eval/benchmark/commands.ts check:output-identity",
     "build:binary": "bun build ./bin/am.ts --compile --outfile dist/am",
-    "website": "bun run website/build.ts",
+    "website": "bun run generate:sdk && bun run website/build.ts",
     "website:check": "bun run website/build.ts --check",
-    "website:payload:write": "bun run scripts/site/website-payload-report.ts --write",
     "website:payload:check": "bun run scripts/site/website-payload-report.ts --check",
     "website:dev": "cd website && WRANGLER_SEND_METRICS=false ../node_modules/.bin/wrangler dev --local --host 127.0.0.1 --port 9095 --ip 127.0.0.1",
     "deploy": "gh workflow run deploy-cloudflare.yml --ref main",
     "prepublishOnly": "npm run build",
     "goldens:ascii": "bun run scripts/update-ascii-goldens.ts",
-    "goldens:ascii:check": "bun run scripts/update-ascii-goldens.ts --check",
     "hero": "bun run scripts/site/hero.ts",
     "hero:check": "bun run scripts/site/hero.ts --check",
-    "style:audit": "bun test src/__tests__/style-role-audit.test.ts",
+    "style:audit": "bun test --timeout 60000 src/__tests__/style-options.test.ts src/__tests__/styled-output.test.ts",
     "sketch:check": "bun test scripts/sketch-prototype/styles.test.ts && bun run scripts/sketch-prototype/contrast-audit.ts",
-    "characterization:check": "bun run scripts/characterization/contact-sheet.ts --check && bun run scripts/characterization/contact-sheet-families.ts --check && bun run scripts/characterization/visual-quality.ts --check",
+    "doc-blocks": "bun run scripts/generate-doc-blocks.ts",
     "agent-doc-artifacts": "bun run scripts/generate-agent-doc-artifacts.ts",
-    "agent-doc-artifacts:check": "bun run scripts/generate-agent-doc-artifacts.ts --check",
-    "section-a-report": "bun run scripts/generate-section-a-capability-report.ts",
-    "section-a-report:check": "bun run scripts/generate-section-a-capability-report.ts --check",
-    "section-b-report": "bun run scripts/generate-section-b-capability-report.ts",
-    "section-b-report:check": "bun run scripts/generate-section-b-capability-report.ts --check",
-    "render-options-docs": "bun run scripts/generate-render-options-docs.ts",
-    "render-options-docs:check": "bun run scripts/generate-render-options-docs.ts --check",
     "style-spec-artifacts": "bun run scripts/generate-style-spec-artifacts.ts",
-    "style-spec-artifacts:check": "bun run scripts/generate-style-spec-artifacts.ts --check",
-    "upstream-manifest": "bun run scripts/generate-upstream-mermaid-manifest.ts",
-    "upstream-manifest:check": "bun run scripts/generate-upstream-mermaid-manifest.ts --check",
-    "mutation-test": "bun run scripts/quality/mutation-profile.ts",
-    "sabotage:routes": "bun run eval/sabotage/route-regressions.ts",
-    "test:family-elevation-reverts": "bun run scripts/quality/family-elevation-revert-probes.ts",
-    "lint": "bun run lint:biome && bun run lint:contracts",
+    "upstream-family-index": "bun run scripts/generate-upstream-family-index.ts",
+    "lint": "bun run lint:biome",
     "lint:biome": "biome lint .",
-    "lint:contracts": "bun test src/__tests__/agent-substrate-lint.test.ts src/__tests__/test-quality-lint.test.ts",
+    "lint:package": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints ./browser",
     "eval:agent-live": "bun run eval/agent-usage/live.ts",
     "eval:agent-subagent": "bun run eval/agent-usage/capture-subagent-prompt-eval.ts",
     "eval:mcp-conformance": "bun run scripts/ci/mcp-conformance.ts",
@@ -176,69 +203,99 @@
     "eval:skill:bundle-evidence": "bun run scripts/eval/bundle-skill-evidence.ts",
     "eval:skill:materialize-codex-output": "bun run scripts/eval/materialize-codex-output.ts",
     "eval:skill:summarize-evidence": "bun run scripts/eval/summarize-skill-evidence.ts",
-    "eval:skill:sabotage": "bun run scripts/ci/skill-eval-sabotage.ts",
     "eval:family-portfolio": "bun run eval/mermaid-family-portfolio/build.ts",
-    "eval:family-portfolio:check": "bun run eval/mermaid-family-portfolio/build.ts --check",
+    "eval:mermaid-assertions": "bun run eval/mermaid-upstream-assertions/run.ts",
+    "eval:mermaid-modern": "bun run eval/mermaid-modern-compat/run.ts",
+    "eval:mermaid-grammar": "bun run eval/mermaid-modern-compat/grammar-run.ts",
+    "reference:mermaid": "bash scripts/setup-mermaid-reference.sh",
+    "test:mermaid-modern": "bun test --timeout 30000 eval/mermaid-modern-compat/semantic.test.ts eval/mermaid-modern-compat/native-operations.test.ts eval/mermaid-modern-compat/grammar-regressions.test.ts",
     "eval:degenerate-routes": "bun run eval/degenerate-etn/enumerate.ts",
     "rubric:visual": "bun run eval/visual-rubric/run.ts",
     "contact:sheet": "bun run eval/visual-rubric/contact-sheet.ts",
-    "contact:sheet:test-portfolio": "bun run scripts/pr-assets/test-portfolio-contact-sheet.ts",
-    "contact:sheet:test-portfolio:review": "bun run scripts/ci/test-portfolio-visual-review.ts",
     "gallery:custom-styles": "bun run scripts/docs/custom-style-cookbook.ts",
-    "gallery:custom-styles:check": "bun run scripts/docs/custom-style-cookbook.ts --check",
     "gallery:linkrank-feedback-packing": "bun run scripts/pr-assets/linkrank-feedback-packing-evidence.ts",
-    "gallery:linkrank-feedback-packing:check": "bun run scripts/pr-assets/linkrank-feedback-packing-evidence.ts --check",
     "gallery:mindmap-gitgraph": "bun run scripts/pr-assets/mindmap-gitgraph-content-gallery.ts",
-    "gallery:mindmap-gitgraph:check": "bun run scripts/pr-assets/mindmap-gitgraph-content-gallery.ts --check",
     "gallery:mermaid-docs": "bun run scripts/pr-assets/mermaid-doc-showcase-gallery.ts",
-    "gallery:mermaid-docs:check": "bun run scripts/pr-assets/mermaid-doc-showcase-gallery.ts --check",
     "gallery:style-switch": "bun run scripts/pr-assets/style-switch-contact-sheet.ts",
-    "gallery:style-switch:check": "bun run scripts/pr-assets/style-switch-contact-sheet.ts --check",
     "gallery:pie-highlight": "bun run scripts/pr-assets/pie-highlightslice-evidence.ts",
-    "gallery:pie-highlight:check": "bun run scripts/pr-assets/pie-highlightslice-evidence.ts --check",
-    "gallery:palette-rollout:baseline": "bun run scripts/pr-assets/palette-rollout-evidence.ts --record-baseline",
-    "gallery:palette-rollout": "bun run scripts/pr-assets/palette-rollout-evidence.ts",
-    "gallery:palette-rollout:check": "bun run scripts/pr-assets/palette-rollout-evidence.ts --check",
-    "gallery:palette-harmony": "bun run scripts/pr-assets/palette-harmony-experiment.ts",
-    "gallery:palette-harmony:check": "bun run scripts/pr-assets/palette-harmony-experiment.ts --check",
+    "gallery:sankey-comparison": "bun run scripts/pr-assets/sankey-mermaid-comparison.ts",
     "gallery:section-b": "bun run scripts/pr-assets/section-b-brand-evidence.ts",
-    "gallery:section-b:check": "bun run scripts/pr-assets/section-b-brand-evidence.ts --check",
     "track": "bun run eval/heuristic-tracker/run.ts",
     "audit:ugly": "bun run eval/ugly-detector/audit.ts",
-    "audit:dependencies": "bun audit --audit-level=high"
+    "audit:dependencies": "bun audit --audit-level=high",
+    "bench:all": "bun eval/benchmark/commands.ts bench:all",
+    "bench:families": "bun eval/benchmark/commands.ts bench:families",
+    "bench:invocations": "bun eval/benchmark/commands.ts bench:invocations",
+    "bench:community": "bun eval/benchmark/commands.ts bench:community",
+    "bench:pinned-mermaid": "bun eval/benchmark/commands.ts bench:pinned-mermaid",
+    "bench:prs": "bun eval/benchmark/commands.ts bench:prs",
+    "bench:test": "bun eval/benchmark/commands.ts bench:test",
+    "bench:typecheck": "bun eval/benchmark/commands.ts bench:typecheck",
+    "bench:lint": "bun eval/benchmark/commands.ts bench:lint",
+    "bench:community:update": "bun run eval/trident/run.ts community:update",
+    "bench:portable": "bun run eval/trident/run.ts portable",
+    "bench:portable:build": "bun run eval/trident/run.ts build",
+    "bench:performance-profile": "bun eval/benchmark/commands.ts bench:performance-profile",
+    "bench:endpoint-marker": "bun eval/benchmark/commands.ts bench:endpoint-marker",
+    "bench:modern-summary": "bun eval/benchmark/commands.ts bench:modern-summary",
+    "bench:corpus:export": "bun eval/benchmark/commands.ts corpus:export",
+    "bench:results": "bun eval/trident/run.ts results:publish",
+    "build:zenuml": "tsup --config tsup.zenuml.config.ts"
   },
   "dependencies": {
     "@resvg/resvg-js": "2.6.2",
     "acorn": "8.16.0",
-    "elkjs": "^0.11.0",
+    "d3-format": "3.1.0",
+    "d3-sankey": "0.12.3",
+    "elkjs": "0.11.1",
     "entities": "^7.0.1",
     "yaml": "^2.8.3"
   },
   "overrides": {
-    "brace-expansion": "5.0.8",
+    "@hono/node-server": "1.19.17",
+    "body-parser": "2.4.0",
+    "brace-expansion": "5.0.9",
+    "browserslist": "4.28.9",
+    "dompurify": "3.4.17",
     "esbuild": "0.28.1",
-    "fast-uri": "3.1.4",
+    "fast-uri": "3.1.8",
+    "ip-address": "10.7.1",
+    "hono": "4.13.13",
+    "katex": "0.18.2",
     "lodash-es": "4.18.1",
     "picomatch": "4.0.5",
-    "qs": "6.15.3"
+    "qs": "6.16.1",
+    "proxy-addr": "2.0.8",
+    "sharp": "0.35.5",
+    "undici": "7.30.1",
+    "zod": "4.6.6"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
     "@biomejs/biome": "2.5.5",
-    "@modelcontextprotocol/sdk": "1.29.0",
+    "@mermaid-js/mermaid-zenuml": "1.0.1",
+    "@modelcontextprotocol/sdk": "1.32.1",
     "@resvg/resvg-wasm": "2.6.2",
-    "@stryker-mutator/core": "^9.6.1",
+    "@swc/core": "1.15.8",
     "@types/bun": "^1.3.9",
+    "@types/d3-format": "3.0.4",
+    "@types/d3-sankey": "^0.12.5",
+    "@zenuml/core": "3.47.9",
     "beautiful-mermaid": "1.1.3",
     "fast-check": "^4.6.0",
-    "mermaid": "11.16.0",
+    "jsdom": "26.1.0",
+    "mermaid": "12.2.0",
     "mermaid-ast": "0.8.2",
-    "playwright": "^1.58.2",
     "perfect-freehand": "1.2.3",
+    "playwright": "^1.58.2",
+    "publint": "0.3.24",
     "roughjs": "4.6.6",
+    "saxes": "6.0.0",
     "shiki": "^3.19.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "upng-js": "^2.1.0",
-    "wrangler": "4.114.0"
+    "vitest": "4.1.11",
+    "wrangler": "4.149.0"
   }
 }

package/server.json

@@ -7,13 +7,13 @@
     "url": "https://github.com/adewale/agentic-mermaid",
     "source": "github"
   },
-  "version": "0.4.1",
+  "version": "0.5.3",
   "websiteUrl": "https://agentic-mermaid.dev/",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "agentic-mermaid",
-      "version": "0.4.1",
+      "version": "0.5.3",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {

package/skills/agentic-mermaid-diagram-workflow/SKILL.md

@@ -12,7 +12,7 @@ An agent-agnostic typed editing surface for Mermaid. New diagrams can be authore
 - `agentic-mermaid-mcp` connected → **Code Mode** (`references/code-mode.md`). Multi-step edits in one round-trip.
 - Can run JS/TS with imports → **library** (`agentic-mermaid/agent`). Same SDK.
 - Shell only → **CLI** (`references/cli.md`).
-- No local install, network only → **hosted MCP** at `https://agentic-mermaid.dev/mcp` (stateless Streamable HTTP JSON-RPC; `execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, and `build` tools — 64 KB input cap). Read `references/hosted-mcp.md` before composing a hosted request. Use the named direct tool and its exact argument object; do not substitute library APIs or local Code Mode for a hosted direct-tool task.
+- No local install, network only → **hosted MCP** at `https://agentic-mermaid.dev/mcp` (stateless Streamable HTTP JSON-RPC; <!-- BEGIN GENERATED: hosted-mcp-tools -->`execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, and `build`<!-- END GENERATED: hosted-mcp-tools --> tools — 64 KB input cap). Read `references/hosted-mcp.md` before composing a hosted request. Use the named direct tool and its exact argument object; do not substitute library APIs or local Code Mode for a hosted direct-tool task.
 
 For hosted MCP, choose the least-powerful tool that completes the task:
 
@@ -51,10 +51,9 @@ fenced block and recheck every op `kind` and field against this skill or
 
 Run `am capabilities --json` (or call the equivalent SDK capability API) before
 choosing a family or mutation. Its registry-derived family entries expose the
-current narrower, operation schema, edit policy, output support, and minimal
-source example; the generated Section A matrix supplies explicit native,
-source-preserved, diagnosed, and absent states. This skill intentionally does
-not maintain a second family or operation table.
+current narrower, operation schema, edit policy, output support, per-family
+conformance, and minimal source example. This skill intentionally does not
+maintain a second family or operation table.
 
 On hosted MCP, inspect the connected server's `tools/list` for its tool surface
 and call `describe_sdk({ family, detail: 'fields' })` for mutation fields. There
@@ -68,9 +67,20 @@ Gantt diagrams are segment-preserving: `asGantt` keeps title/section/task ops li
 
 `references/upstream/` documents Mermaid syntax for many more families than this renderer accepts; it is authoring reference only. `am capabilities --json` is the authoritative list of renderable families.
 
+## Choosing a family
+
+Choose the family from the reader's task; the family is the result of that decision, not the starting point. The full task router, with per-family anti-patterns and the verify codes that check each choice, is `docs/choosing-a-diagram.md`. The routes agents most often miss:
+
+- Steps and decisions toward an outcome: flowchart. A system moving between modes in response to events: state.
+- Ordered messages between actors: sequence. A flowchart arrow reads as causality, not time.
+- Dated work with durations and dependencies: gantt. Undated eras: timeline. One person's scored experience of a process: journey.
+- Quantities that must balance across stages: sankey. Parts of one whole at one moment: pie. Measured series across categories or time: xychart.
+
+Renderability and edit policy still come from `am capabilities --json`, not from this routing.
+
 ## Workflow
 
-For new diagrams, author Mermaid source directly, then `parseRegisteredMermaid` / `verifyMermaid` / render. For existing modeled diagrams:
+<!-- BEGIN GENERATED: new-diagram-policy -->New diagrams: author Mermaid source directly, then parse → verify → render or return it. `buildMermaid(kind, ops)` / `createMermaid(kind)` build a diagram from typed ops when you are generating one programmatically (for example, from data).<!-- END GENERATED: new-diagram-policy --> For existing modeled diagrams:
 
 1. `parseRegisteredMermaid(source)` → `ValidDiagram`.
 2. Use the family entry's advertised narrower (for example `asFlowchart(d)` or
@@ -136,12 +146,20 @@ Output artifact pattern:
 const verify = verifyMermaid(cur)
 if (!verify.ok) return { phase: 'verify', warnings: verify.warnings }
 const svg = renderMermaidSVG(cur, { security: 'strict' })
-const png = renderMermaidPNG(cur, { fitTo: { width: 1200 }, background: '#fff' })
+const png = renderMermaidPNG(cur, {
+  fitTo: { width: 1200 },
+  background: '#fff',
+  minLabelPx: 9,
+  onWarning: warning => console.warn(warning.code, warning.message),
+})
 const ascii = renderMermaidASCII(cur, { useAscii: true })
 const unicode = renderMermaidASCII(cur, { useAscii: false })
 const layout = verify.layout
 ```
 
-CLI PNG: `am render diagram.mmd --format png --output diagram.png`.
+CLI PNG: `am render diagram.mmd --format png --output diagram.png
+--min-label-px 9`. `BELOW_READABLE_SIZE` is a bounded shrinkage warning, not
+proof of readability; choose a task-specific floor when viewing conditions are
+known, or pass `0` to disable it.
 
 See `references/flowchart.md`, `references/sequence.md`, `references/timeline.md`, `references/upstream/gantt.md`, and the repository cookbook at `docs/agent-api-cookbook.md`.

package/skills/agentic-mermaid-diagram-workflow/references/cli.md

@@ -2,9 +2,10 @@
 
 Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout through the CLI.
 
+<!-- complete: cli-verbs -->
 ```text
 am render <file|-> --format svg|ascii|unicode|layout
-am render <file> --format png --output file.png  # one-shot only; no watch/multi-input
+am render <file> --format png --output file.png [--fit-width PX|--fit-height PX] [--min-label-px PX]
 am preview <file|-> [--output preview.html] [--open] [--json] [--security strict]  # strict standalone HTML
 am verify <file|->            structured JSON warnings (exit 3 if not ok)
 am parse <file|->             ValidDiagram JSON
@@ -14,6 +15,7 @@ am mutate <file|-> --ops JSON|file  many MutationOps → verify → new source
 am format <file|->            idempotent reformat
 am describe <file|->          prose summary, --format json AX tree, or --format facts semantic facts
 am capabilities --json        families, editPolicy, mutationOps, warning codes, formats
+am styles [--json]            registered styles, looks, and palette-only themes
 am batch --jsonl              JSONL stdin → JSONL envelopes (render/verify/parse/serialize/mutate)
 am render-markdown <file.md> [--ascii]  render fenced Mermaid blocks
 am llms-txt                   agent discovery digest
@@ -25,7 +27,10 @@ am <cmd> --help               per-command help
 `am verify` always emits JSON. `am mutate` dispatches across the live mutable
 family roster reported by `am capabilities --json`; opaque fallback bodies
 return a structured `UNSUPPORTED_FAMILY` error. `am mutate` verifies before emitting source; verify
-failure exits 3 and omits `source`. Use direct Mermaid source authoring plus
+failure exits 3 and omits `source`. A verify whose errors are all `INTERNAL_ERROR`
+(an Agentic Mermaid defect, not the diagram) exits 4 instead; report it with the source.
+An edit is still emitted when its only errors are `INTERNAL_ERROR` defects the input
+already had (same reason and `defaultRender`). Use direct Mermaid source authoring plus
 `am verify`/`am render` for brand-new diagrams; reserve `am mutate` for
 existing structured diagrams. `am parse | am serialize` round-trips through JSON.
 
@@ -40,4 +45,9 @@ am mutate flow.mmd --op '{"kind":"rename_node","from":"X","to":"Y"}'
 am mutate seq.mmd --op '{"kind":"add_message","from":"A","to":"B","text":"Hi"}'
 ```
 
-Exit codes: 0 ok, 2 arg/parse/mutation error, 3 verify failed, 4 internal.
+Exit codes: 0 ok, 2 arg/parse/mutation error, 3 verify failed, 4 internal (including a verify whose errors are all `INTERNAL_ERROR`).
+
+PNG emits `BELOW_READABLE_SIZE` when the smallest measurable configured text
+lands below `--min-label-px` after final raster sizing. The provisional default
+is 9px; pass `0` to disable it. Treat the warning as evidence of one bounded
+shrinkage condition, not proof that the whole image is or is not readable.

package/skills/agentic-mermaid-diagram-workflow/references/code-mode.md

@@ -1,5 +1,6 @@
 # Code Mode (structured edit channel)
 
+<!-- complete: local-mcp-tools -->
 `agentic-mermaid-mcp` exposes a primary Code Mode tool, `execute(code)`, plus
 narrow `describe_sdk`, `render_png`, and `describe` helpers. The initial
 `execute` declaration contains only the core SDK. Call
@@ -29,7 +30,7 @@ mermaid.renderMermaidASCII(input, { useAscii?: boolean, ganttToday?: string, mer
 mermaid.renderMermaidSVG(input, { security?: 'default'|'strict', idPrefix?, ganttToday?: string, mermaidConfig?: MermaidRuntimeConfig }): string
 ```
 
-Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout. In Code Mode, render SVG and text through `mermaid.*`: `renderMermaidASCII(input, { useAscii: true })` returns ASCII and `useAscii: false` returns Unicode box-drawing text. Use the narrow MCP `render_png` helper or host/library code for PNG binary output; JSON layout is available on `verifyMermaid(...).layout` and through the CLI/library layout APIs. `MermaidRuntimeConfig` matches the runtime config surface: arbitrary Mermaid config keys plus `theme`, `fontFamily`, `themeVariables`, `timeline`, `xyChart`, `gantt`, `mindmap`, `gitGraph`, `useMaxWidth`, `useWidth`, and `themeCSS`. `ganttToday` is a render option, not a clock read; pass it when a Gantt `todayMarker` should render.
+Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout. In Code Mode, render SVG and text through `mermaid.*`: `renderMermaidASCII(input, { useAscii: true })` returns ASCII and `useAscii: false` returns Unicode box-drawing text. Use the narrow MCP `render_png` helper or host/library code for PNG binary output; JSON layout is available on `verifyMermaid(...).layout` and through the CLI/library layout APIs. `MermaidRuntimeConfig` matches the runtime config surface: arbitrary Mermaid config keys plus `theme`, `fontFamily`, `themeVariables`, `timeline`, `xyChart`, `gantt`, `mindmap`, `gitGraph`, `useMaxWidth`, and `useWidth`, plus the other per-family sections the SDK declaration lists. Raw `themeCSS` is rejected by the public renderers in default security mode; style with `style` (a Look, Palette, inline spec, or stack) instead. `ganttToday` is a render option, not a clock read; pass it when a Gantt `todayMarker` should render.
 
 All SDK methods are synchronous and pure. Code Mode does not support `async`/`await`, Promise jobs, or dynamic import. Layout is deterministic; there is no layout seed (the render option `seed` only re-rolls ink of styled looks — `style: name | record | stack` — and never moves geometry).
 

package/skills/agentic-mermaid-diagram-workflow/references/flowchart.md

@@ -8,10 +8,13 @@ Shapes: `[rect]` `(round)` `([stadium])` `[[subroutine]]` `[(cylinder)]`
 
 Edges: `-->` `---` `-.->` `==>` `--o` `--x` `<-->` `-->|label|`.
 
-MutationOps (6): add_node, remove_node, rename_node, set_label, add_edge,
-remove_edge. remove_node cascades to incident edges; add_edge implicit-declares
-missing endpoints.
+MutationOps: the live list and field shapes come from `am capabilities --json`
+(`families[].mutationOps` / `opFields`) or `describeOps('flowchart')` — node,
+edge, shape, direction, subgraph, and class/style ops. remove_node cascades to
+incident edges; add_edge implicit-declares missing endpoints.
 
-Verify Tier 1: EMPTY_DIAGRAM, EDGE_MISANCHORED, OFF_CANVAS, GROUP_BREACH,
-UNKNOWN_SHAPE, LABEL_OVERFLOW (char-cap, default 40).
-Tier 2: NODE_OVERLAP, ROUTE_SELF_CROSS, ROUTE_HITCH, ROUTE_UNEXPLAINED_BEND, ROUTE_LABEL_ON_SHARED_TRUNK, ROUTE_CONTAINER_MISANCHOR, ROUTE_SHAPE_MISANCHOR, ROUTE_STALE_AFTER_NODE_MOVE.
+Verify: every Tier 1 code except the Gantt-only UNRESOLVABLE_SCHEDULE can fire
+on a flowchart (LABEL_OVERFLOW caps a label line at 40 characters by default),
+and so can every Tier 2 geometric code. `am capabilities --json` lists the codes
+by tier (`warningCodes`); each code's page under
+https://agentic-mermaid.dev/warnings/ says what triggers it and how to clear it.

package/skills/agentic-mermaid-diagram-workflow/references/hosted-mcp.md

@@ -44,6 +44,7 @@ synonym is still an invalid call.
 
 ## Direct tools
 
+<!-- complete: hosted-mcp-tools -->
 - `verify({ source })` returns structural `ok`, detected `family`, `summary`,
   `warnings`, and layout counts. Confirm the family as well as `ok`.
 - `describe({ source, format })` uses `text` for prose, `json` for an AX tree,

package/skills/agentic-mermaid-diagram-workflow/references/sequence.md

@@ -26,8 +26,9 @@ participant and top-level message ops remain live. Only an un-segmentable
 diagram (a stray `end`, an unclosed block) falls back to a whole-body OPAQUE
 body. Either way the parser never silently drops constructs.
 
-Verify Tier 1 only (no layout engine): EMPTY_DIAGRAM, EDGE_MISANCHORED
-(message references missing participant), LABEL_OVERFLOW (participant label or
-message text over char cap).
+Verify: Tier 1 EMPTY_DIAGRAM, EDGE_MISANCHORED (message references missing
+participant), LABEL_OVERFLOW (participant label or message text over char cap);
+layout-geometry checks on the sequence layout (OFF_CANVAS, GROUP_BREACH,
+NODE_OVERLAP); and UNSUPPORTED_SYNTAX naming verbatim segments.
 
 Upstream: https://mermaid.js.org/syntax/sequenceDiagram.html

package/skills/agentic-mermaid-diagram-workflow/references/timeline.md

@@ -14,16 +14,17 @@ Lines: `title <text>`, `section <label>`, `<period-label> : <event>`
 (multi-event via `: <event2> : <event3>`), and continuation `: <event>`
 that adds an event to the previous period.
 
-MutationOps (10): set_title (pass `null` to clear), add_section,
-remove_section, set_section_label, add_period, remove_period,
-set_period_label, add_event, remove_event, set_event_text.
+MutationOps: the live list and field shapes come from `am capabilities --json`
+or `describeOps('timeline')` — title, section, period, and event add/remove/
+relabel ops, move ops (order is the chronology), and accessibility title/
+description. `set_title` takes `null` to clear.
 
 Sections/periods/events are referenced by integer index. Indices shift
 after a remove — re-parse if you batch deletes.
 
-Fidelity fallback: a timeline with unmodeled syntax (anything beyond
-title/section/period/event/continuation) falls back to opaque body
-(`asTimeline` returns null). Round-trips losslessly via preserved `body.source`.
+Fidelity fallback: a timeline with syntax the parser does not model falls back
+to an opaque body (`asTimeline` returns null; `accTitle`/`accDescr` are
+modeled). Round-trips losslessly via preserved `body.source`.
 
 Verify Tier 1: EMPTY_DIAGRAM (no title + no periods), LABEL_OVERFLOW on
 title / section / period / event over the char cap.