agentic-mermaid 0.1.0 → 0.1.2

package/examples/agent-improve-auth-flow.ts

@@ -1,206 +0,0 @@
-// Runnable agent-improvement example:
-//   1. create a non-trivial Auth Flow via MCP Code Mode mutations;
-//   2. assess it and spot label-overflow warnings;
-//   3. improve it through another mutation batch;
-//   4. reassess the impact;
-//   5. write final Mermaid, SVG, ASCII, PNG, and assessment files.
-//
-// Run:
-//   bun run examples/agent-improve-auth-flow.ts
-//   bun run examples/agent-improve-auth-flow.ts --out-dir /tmp/auth-flow-improved
-
-import { Buffer } from 'node:buffer'
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { spawnSync } from 'node:child_process'
-import { handleRequest } from '../src/mcp/server.ts'
-
-const REPO = join(import.meta.dir, '..')
-
-function argValue(name: string): string | undefined {
-  const idx = process.argv.indexOf(name)
-  return idx >= 0 ? process.argv[idx + 1] : undefined
-}
-
-// Render the final source to PNG in a *fresh* process via `am render`. The
-// native PNG renderer (resvg) must not be loaded in this process: after MCP
-// Code Mode runs agent code in a `node:vm` sandbox, loading the native binding
-// here panics Bun (`panic: unreachable` on dlopen-after-vm). Shelling out to
-// the CLI keeps the dlopen in a clean process — same pattern as the MCP/CLI
-// parity example.
-function renderPngOutOfProcess(source: string, outPath: string): void {
-  const srcPath = `${outPath}.src.mmd`
-  writeFileSync(srcPath, source)
-  try {
-    const r = spawnSync(
-      'bun',
-      ['run', join(REPO, 'bin/am.ts'), 'render', srcPath, '--format', 'png', '--output', outPath],
-      { cwd: REPO, encoding: 'utf8' },
-    )
-    if (r.status !== 0) throw new Error(`am render --format png failed (${r.status})\nstderr: ${r.stderr}`)
-  } finally {
-    rmSync(srcPath, { force: true })
-  }
-}
-
-const outDir = resolve(argValue('--out-dir') ?? mkdtempSync(join(tmpdir(), 'am-agent-improve-')))
-const useTestPngPlaceholder = process.argv.includes('--test-png-placeholder')
-mkdirSync(outDir, { recursive: true })
-
-const AGENT_CODE = `
-const parsed = mermaid.parseMermaid('---\\ntitle: Auth Flow Draft\\n---\\nflowchart LR\\n')
-if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
-
-const flow = mermaid.asFlowchart(parsed.value)
-if (!flow) return { phase: 'narrow', error: 'not-flowchart' }
-
-let current = flow
-const createOps = [
-  { kind: 'add_node', id: 'A', label: 'User' },
-  { kind: 'add_node', id: 'B', label: 'Login Page' },
-  { kind: 'add_node', id: 'C', label: 'Are the supplied credentials valid?', shape: 'diamond' },
-  { kind: 'add_node', id: 'D', label: 'Does this user require multi-factor authentication?', shape: 'diamond' },
-  { kind: 'add_node', id: 'E', label: 'Enter MFA Code' },
-  { kind: 'add_node', id: 'F', label: 'Is the entered multi-factor code valid?', shape: 'diamond' },
-  { kind: 'add_node', id: 'G', label: 'Create Session' },
-  { kind: 'add_node', id: 'H', label: 'Dashboard' },
-  { kind: 'add_edge', from: 'A', to: 'B' },
-  { kind: 'add_edge', from: 'B', to: 'C' },
-  { kind: 'add_edge', from: 'C', to: 'B', label: 'No' },
-  { kind: 'add_edge', from: 'C', to: 'D', label: 'Yes' },
-  { kind: 'add_edge', from: 'D', to: 'E', label: 'Yes' },
-  { kind: 'add_edge', from: 'E', to: 'F' },
-  { kind: 'add_edge', from: 'F', to: 'E', label: 'No' },
-  { kind: 'add_edge', from: 'D', to: 'G', label: 'No' },
-  { kind: 'add_edge', from: 'F', to: 'G', label: 'Yes' },
-  { kind: 'add_edge', from: 'G', to: 'H' },
-]
-for (const op of createOps) {
-  const next = mermaid.mutate(current, op)
-  if (!next.ok) return { phase: 'create', op, error: next.error }
-  current = next.value
-}
-
-const assess = (diagram) => {
-  const verify = mermaid.verifyMermaid(diagram, { labelCharCap: 28 })
-  const source = mermaid.serializeMermaid(diagram)
-  const labels = Array.from(source.matchAll(/[\\[{]([^\\]\\}]+)[\\]\\}]/g)).map(m => m[1])
-  const longestLabel = labels.reduce((max, label) => Math.max(max, label.length), 0)
-  return {
-    ok: verify.ok,
-    warningCount: verify.warnings.length,
-    warnings: verify.warnings.map(w => ({ code: w.code, target: w.target, charCount: w.charCount, limit: w.limit })),
-    longestLabel,
-    bounds: verify.layout.bounds,
-    source,
-  }
-}
-
-const before = assess(current)
-const problems = []
-if (before.warnings.some(w => w.code === 'LABEL_OVERFLOW')) {
-  problems.push('Decision labels are too long for compact rendering and screenshots.')
-}
-if (before.bounds.w > 1600) {
-  problems.push('The left-to-right diagram is wide enough to be awkward in docs.')
-}
-
-const improveOps = [
-  { kind: 'set_label', target: 'C', label: 'Valid Credentials?' },
-  { kind: 'set_label', target: 'D', label: 'MFA Enabled?' },
-  { kind: 'set_label', target: 'F', label: 'Code Valid?' },
-]
-for (const op of improveOps) {
-  const next = mermaid.mutate(current, op)
-  if (!next.ok) return { phase: 'improve', op, error: next.error }
-  current = next.value
-}
-
-const after = assess(current)
-const svg = mermaid.renderMermaidSVG(current, { security: 'strict' })
-const ascii = mermaid.renderMermaidASCII(current, { useAscii: true })
-
-return {
-  createOps: createOps.length,
-  improveOps: improveOps.length,
-  problems,
-  impact: {
-    warningsBefore: before.warningCount,
-    warningsAfter: after.warningCount,
-    longestLabelBefore: before.longestLabel,
-    longestLabelAfter: after.longestLabel,
-    boundsBefore: before.bounds,
-    boundsAfter: after.bounds,
-  },
-  beforeSource: before.source,
-  source: after.source,
-  svg,
-  ascii,
-}
-`
-
-const response = await handleRequest({
-  jsonrpc: '2.0',
-  id: 1,
-  method: 'tools/call',
-  params: { name: 'execute', arguments: { code: AGENT_CODE } },
-})
-
-const text = (response?.result as { content?: Array<{ text?: string }> } | undefined)?.content?.[0]?.text
-if (typeof text !== 'string') throw new Error(`bad MCP response: ${JSON.stringify(response)}`)
-const executed = JSON.parse(text) as { ok: boolean; value?: unknown; error?: string }
-if (!executed.ok) throw new Error(`agent execute failed: ${executed.error ?? text}`)
-
-const result = executed.value as {
-  createOps: number
-  improveOps: number
-  problems: string[]
-  impact: Record<string, unknown>
-  beforeSource: string
-  source: string
-  svg: string
-  ascii: string
-}
-
-const files = {
-  before: join(outDir, 'auth-flow-before.mmd'),
-  source: join(outDir, 'auth-flow-improved.mmd'),
-  svg: join(outDir, 'auth-flow-improved.svg'),
-  ascii: join(outDir, 'auth-flow-improved.txt'),
-  png: join(outDir, 'auth-flow-improved.png'),
-  assessment: join(outDir, 'assessment.json'),
-}
-
-writeFileSync(files.before, result.beforeSource)
-writeFileSync(files.source, result.source)
-writeFileSync(files.svg, result.svg)
-writeFileSync(files.ascii, result.ascii)
-// PNG is binary, so the host renders it from the verified final source. The
-// default path renders the real PNG out-of-process (see renderPngOutOfProcess);
-// `--test-png-placeholder` writes a tiny stand-in to skip native rendering on
-// environments without the resvg binding.
-if (useTestPngPlaceholder) {
-  writeFileSync(files.png, Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+/p9sAAAAASUVORK5CYII=', 'base64'))
-} else {
-  renderPngOutOfProcess(result.source, files.png)
-}
-writeFileSync(files.assessment, JSON.stringify({
-  createOps: result.createOps,
-  improveOps: result.improveOps,
-  problems: result.problems,
-  impact: result.impact,
-}, null, 2) + '\n')
-
-writeFileSync(1, JSON.stringify({
-  ok: true,
-  outDir,
-  files,
-  problems: result.problems,
-  impact: result.impact,
-}, null, 2) + '\n')
-
-// This example is often run from test subprocesses. Exit explicitly after the
-// output is synchronously flushed so platform-specific native/font handles
-// cannot keep the process open after the example has completed.
-process.exit(0)

package/examples/agent-loop.ts

@@ -1,53 +0,0 @@
-// Runnable example: the agent verify-before-commit loop.
-//   bun run examples/agent-loop.ts
-//
-// Demonstrates parse → narrow → mutate (flowchart + sequence) → verify →
-// serialize, plus the opaque fallback for constructs we don't structurally model.
-
-import {
-  parseMermaid, asFlowchart, asSequence, mutate, verifyMermaid, serializeMermaid,
-} from '../src/agent/index.ts'
-
-function line(s: string) { process.stdout.write(s + '\n') }
-
-// 1. Flowchart: insert a Cache between API and DB.
-{
-  const d0 = parseMermaid('flowchart TD\n  API --> DB')
-  if (!d0.ok) throw new Error('parse failed')
-  const flow = asFlowchart(d0.value)!
-  const a = mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })
-  if (!a.ok) throw new Error(a.error.message)
-  const b = mutate(a.value, { kind: 'add_edge', from: 'API', to: 'Cache' })
-  if (!b.ok) throw new Error(b.error.message)
-  const c = mutate(b.value, { kind: 'add_edge', from: 'Cache', to: 'DB' })
-  if (!c.ok) throw new Error(c.error.message)
-  const v = verifyMermaid(c.value)
-  if (!v.ok) throw new Error('verify failed')
-  line('--- flowchart ---')
-  line(`verify ok: ${v.ok}  warnings: ${v.warnings.length}`)
-  line(serializeMermaid(c.value))
-}
-
-// 2. Sequence: add a reply.
-{
-  const d0 = parseMermaid('sequenceDiagram\n  Alice->>Bob: Hi')
-  if (!d0.ok) throw new Error('parse failed')
-  const seq = asSequence(d0.value)!
-  const a = mutate(seq, { kind: 'add_message', from: 'Bob', to: 'Alice', text: 'Hello', style: 'reply' })
-  if (!a.ok) throw new Error(a.error.message)
-  const v = verifyMermaid(a.value)
-  if (!v.ok) throw new Error('verify failed')
-  line('--- sequence ---')
-  line(`verify ok: ${v.ok}  warnings: ${v.warnings.length}`)
-  line(serializeMermaid(a.value))
-}
-
-// 3. Opaque fallback: a sequence diagram with a Note isn't structurally
-//    mutable, but it round-trips losslessly via preserved body.source.
-{
-  const d0 = parseMermaid('sequenceDiagram\n  Alice->>Bob: Hi\n  Note over Bob: thinking')
-  if (!d0.ok) throw new Error('parse failed')
-  line('--- opaque sequence (has a Note) ---')
-  line(`asSequence is null (not mutable): ${asSequence(d0.value) === null}`)
-  line(`round-trips losslessly: ${serializeMermaid(d0.value).includes('Note over Bob')}`)
-}

package/examples/mcp-vs-cli-complex-diagrams.ts

@@ -1,133 +0,0 @@
-// Runnable parity example: build complicated diagrams via MCP Code Mode and
-// via the `am` CLI, then assert the serialized Mermaid source is identical.
-//   bun run examples/mcp-vs-cli-complex-diagrams.ts
-//
-// This intentionally uses MCP `execute` for composition. The non-Code-Mode
-// path is the CLI, not a parallel render-tool-per-format MCP surface.
-
-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { spawnSync } from 'node:child_process'
-import { handleRequest } from '../src/mcp/server.ts'
-import type { AnyMutationOp } from '../src/agent/types.ts'
-
-const REPO = join(import.meta.dir, '..')
-
-const CASES: Array<{ id: string; initialSource: string; ops: AnyMutationOp[] }> = [
-  {
-    id: 'auth-flow',
-    initialSource: `---
-title: Auth Flow
----
-flowchart LR
-`,
-    ops: [
-      { kind: 'add_node', id: 'A', label: 'User' },
-      { kind: 'add_node', id: 'B', label: 'Login Page' },
-      { kind: 'add_node', id: 'C', label: 'Valid Credentials?', shape: 'diamond' },
-      { kind: 'add_node', id: 'D', label: 'MFA Enabled?', shape: 'diamond' },
-      { kind: 'add_node', id: 'E', label: 'Enter MFA Code' },
-      { kind: 'add_node', id: 'F', label: 'Code Valid?', shape: 'diamond' },
-      { kind: 'add_node', id: 'G', label: 'Create Session' },
-      { kind: 'add_node', id: 'H', label: 'Dashboard' },
-      { kind: 'add_edge', from: 'A', to: 'B' },
-      { kind: 'add_edge', from: 'B', to: 'C' },
-      { kind: 'add_edge', from: 'C', to: 'B', label: 'No' },
-      { kind: 'add_edge', from: 'C', to: 'D', label: 'Yes' },
-      { kind: 'add_edge', from: 'D', to: 'E', label: 'Yes' },
-      { kind: 'add_edge', from: 'E', to: 'F' },
-      { kind: 'add_edge', from: 'F', to: 'E', label: 'No' },
-      { kind: 'add_edge', from: 'D', to: 'G', label: 'No' },
-      { kind: 'add_edge', from: 'F', to: 'G', label: 'Yes' },
-      { kind: 'add_edge', from: 'G', to: 'H' },
-    ],
-  },
-  {
-    id: 'order-domain-er',
-    initialSource: `---
-title: Order Domain
----
-erDiagram
-`,
-    ops: [
-      { kind: 'add_entity', id: 'CUSTOMER', attributes: ['string id', 'string email'] },
-      { kind: 'add_entity', id: 'ORDER', attributes: ['string id', 'date placed_at', 'string status'] },
-      { kind: 'add_entity', id: 'LINE_ITEM', attributes: ['string id', 'int quantity'] },
-      { kind: 'add_entity', id: 'PRODUCT', attributes: ['string sku', 'string name'] },
-      { kind: 'add_relation', from: 'CUSTOMER', to: 'ORDER', leftCard: 'one-only', rightCard: 'zero-or-many', label: 'places' },
-      { kind: 'add_relation', from: 'ORDER', to: 'LINE_ITEM', leftCard: 'one-only', rightCard: 'one-or-many', label: 'contains' },
-      { kind: 'add_relation', from: 'PRODUCT', to: 'LINE_ITEM', leftCard: 'one-only', rightCard: 'zero-or-many', label: 'appears_in' },
-    ],
-  },
-]
-
-async function buildViaMcpCodeMode(c: typeof CASES[number]): Promise<string> {
-  const code = `
-    const parsed = mermaid.parseMermaid(${JSON.stringify(c.initialSource)})
-    if (!parsed.ok) return { error: parsed.error }
-    const narrow = parsed.value.kind === 'er' ? mermaid.asEr(parsed.value) : mermaid.asFlowchart(parsed.value)
-    if (!narrow) return { error: 'unsupported-family', family: parsed.value.kind }
-    let current = narrow
-    const ops = ${JSON.stringify(c.ops)}
-    for (const op of ops) {
-      const next = mermaid.mutate(current, op)
-      if (!next.ok) return { error: next.error, op }
-      current = next.value
-    }
-    const verify = mermaid.verifyMermaid(current)
-    if (!verify.ok) return { error: 'verify', warnings: verify.warnings }
-    return { source: mermaid.serializeMermaid(current) }
-  `
-
-  const response = await handleRequest({
-    jsonrpc: '2.0',
-    id: c.id,
-    method: 'tools/call',
-    params: { name: 'execute', arguments: { code } },
-  })
-  const payload = parseMcpTextPayload(response)
-  if (!payload.ok) throw new Error(`MCP execute failed for ${c.id}: ${payload.error}`)
-  const value = payload.value as { source?: unknown }
-  if (typeof value.source !== 'string') throw new Error(`MCP returned no source for ${c.id}: ${JSON.stringify(value)}`)
-  return value.source
-}
-
-function buildViaCli(c: typeof CASES[number]): string {
-  const dir = mkdtempSync(join(tmpdir(), `am-${c.id}-`))
-  try {
-    const input = join(dir, `${c.id}.mmd`)
-    const ops = join(dir, 'ops.json')
-    writeFileSync(input, c.initialSource)
-    writeFileSync(ops, JSON.stringify(c.ops, null, 2))
-    const r = spawnSync('bun', ['run', join(REPO, 'bin/am.ts'), 'mutate', input, '--ops', ops, '--json'], {
-      cwd: REPO,
-      encoding: 'utf8',
-    })
-    if (r.status !== 0) throw new Error(`CLI failed for ${c.id} (${r.status})\nstdout: ${r.stdout}\nstderr: ${r.stderr}`)
-    const payload = JSON.parse(r.stdout) as { ok: boolean; source?: unknown; error?: unknown }
-    if (!payload.ok || typeof payload.source !== 'string') throw new Error(`CLI returned no source for ${c.id}: ${r.stdout}`)
-    return payload.source
-  } finally {
-    rmSync(dir, { recursive: true, force: true })
-  }
-}
-
-function parseMcpTextPayload(response: Awaited<ReturnType<typeof handleRequest>>): { ok: boolean; value?: unknown; error?: string } {
-  const text = (response?.result as { content?: Array<{ text?: string }> } | undefined)?.content?.[0]?.text
-  if (typeof text !== 'string') return { ok: false, error: `bad MCP response: ${JSON.stringify(response)}` }
-  const executeResult = JSON.parse(text) as { ok: boolean; value?: unknown; error?: string }
-  return executeResult.ok ? { ok: true, value: executeResult.value } : { ok: false, error: executeResult.error ?? text }
-}
-
-const sources: Record<string, string> = {}
-for (const c of CASES) {
-  const mcpSource = await buildViaMcpCodeMode(c)
-  const cliSource = buildViaCli(c)
-  if (mcpSource !== cliSource) {
-    throw new Error(`${c.id}: MCP and CLI produced different source\n--- MCP ---\n${mcpSource}\n--- CLI ---\n${cliSource}`)
-  }
-  sources[c.id] = mcpSource
-}
-
-console.log(JSON.stringify({ ok: true, channelA: 'mcp.execute', channelB: 'am mutate --ops', cases: Object.keys(sources), sources }, null, 2))

package/llms.txt

@@ -1,104 +0,0 @@
-# Agentic Mermaid
-
-> Agent-native Mermaid runtime: parse, verify, mutate, and round-trip
-> Mermaid diagrams with a typed IR. Deterministic ASCII / PNG / SVG. No
-> browser required. CLI + MCP + library.
-
-Version: 0.1.0
-
-## What it does
-
-A typed editing surface over Mermaid for AI agents. Parse a diagram to a
-ValidDiagram, mutate it with typed ops, verify structurally (no pixels),
-serialize back to canonical source. Layout is deterministic (verified
-cross-process and same-machine cross-runtime on x86_64/ARM64).
-
-## The agent loop
-
-New diagrams: author Mermaid source → parse → verify → render/return.
-Existing structured diagrams: parse → narrow → mutate → verify → serialize.
-Run verify at every commit point. Never serialize a diagram whose verify result
-you haven't inspected.
-
-## CLI verbs (`am <verb>`)
-
-- render --format svg, ascii, unicode, json [--security strict] — render a diagram
-- render --format png --output file.png — render one input to PNG (no PNG bytes on stdout, no multi-input/watch)
-- render --style <names|file.json> --seed N — styled svg/png; comma-separate to stack (--style hand-drawn,dracula)
-- styles [--json] — list registered styles (default + full looks + palette-only themes)
-- parse — diagram → ValidDiagram JSON
-- verify — structural validation (exit 3 if invalid)
-- mutate --op '<json>' / --ops '<json array|file>' — apply typed mutation(s), verify, then emit source
-- preview [--output file.html] [--open] — standalone strict-mode HTML preview for user inspection
-- format — normalize / canonicalize source
-- describe [--format text|json|facts] — natural-language, AX-tree, or semantic facts summary
-- capabilities --json — machine-readable capability envelope incl. editPolicy + mutationOps
-- batch --jsonl — bulk render/verify/parse/serialize/mutate ops, one JSON envelope per line
-- render-markdown <file.md> [--ascii] — render fenced mermaid blocks, skip invalid ones
-- llms-txt — this document
-- init-agent [--dir .] [--force] — write AGENTS.md section, root skills/ bundle, and .mcp.json sample
-
-Exit codes: 0 ok, 2 arg error, 3 verify-failed, 4 internal.
-
-## MCP tools
-
-Code Mode `execute(code)` (JavaScript in a node:vm sandbox with a typed
-mermaid.* SDK declaration) plus narrow helper tools: render_png and describe.
-render_png is offline.
-
-## Output formats
-
-Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout. Full capability list: svg, ascii, unicode, png, json. SVG strict mode (security: 'strict') emits zero external-fetch
-references — safe for untrusted/agent-generated diagrams. See SECURITY.md.
-
-## Diagram families
-
-All families parse, verify, render, round-trip: flowchart, state, sequence, timeline, class, er, journey, architecture, xychart, pie, quadrant, gantt.
-Structured mutation (structured-when-narrowed): flowchart, state, sequence, timeline, class, er, journey, architecture, xychart, pie, quadrant, gantt.
-Narrowers: asFlowchart, asState, asSequence, asTimeline, asClass, asEr, asJourney, asArchitecture, asXyChart, asPie, asQuadrant, asGantt.
-State diagrams own a dedicated body (BUILD-19): narrow with asState; state-shaped ops apply (asFlowchart returns null on them).
-Source-level-only: none — every renderable family ships structured mutation.
-Opaque-fallback bodies (unmodeled syntax) round-trip losslessly via preserved source (never silently dropped) and stay source-level only.
-
-## Warning codes
-
-EMPTY_DIAGRAM (structural/error), UNRESOLVABLE_SCHEDULE (structural/error), RENDER_FAILED (structural/error), EDGE_MISANCHORED (structural/error), OFF_CANVAS (structural/error), GROUP_BREACH (structural/error), UNKNOWN_SHAPE (structural/warning), LABEL_OVERFLOW (structural/warning), NODE_OVERLAP (geometric/warning), ROUTE_SELF_CROSS (geometric/warning), ROUTE_HITCH (geometric/warning), ROUTE_UNEXPLAINED_BEND (geometric/warning), ROUTE_LABEL_ON_SHARED_TRUNK (geometric/warning), ROUTE_CONTAINER_MISANCHOR (geometric/warning), ROUTE_SHAPE_MISANCHOR (geometric/warning), ROUTE_STALE_AFTER_NODE_MOVE (geometric/warning), DUPLICATE_EDGE (lint/warning), UNREACHABLE_NODE (lint/warning), DECISION_BRANCH_UNLABELED (lint/warning), COMMENT_DROPPED (lint/warning), UNSUPPORTED_SYNTAX (lint/warning), CONTENT_DROPPED_ON_ROUNDTRIP (lint/warning)
-
-## Library
-
-`import { parseMermaid, mutate, verifyMermaid, analyzeMermaid,
-analyzeMermaidSource, serializeMermaid, renderMermaidASCII,
-renderMermaidPNG, renderMermaidSVG, renderMermaidASCIIWithMeta,
-describeMermaid, asciiToMermaid, verifyNoExternalRefs,
-registerStyle, knownStyles, validateStyleSpec } from 'agentic-mermaid/agent'`
-
-## Styles
-
-Every render call accepts style: a name ('hand-drawn', 'excalidraw',
-'pen-and-ink', 'freehand', 'watercolor', 'blueprint', 'tufte', or any theme
-name — a theme is a palette-only style), an inline JSON spec, or a stack
-merged left → right ({ style: ['hand-drawn', 'dracula'] }). seed re-rolls
-ink wobble, never layout — (source, style, seed) reproduces an image
-exactly. Custom styles are data: validateStyleSpec(json) checks untrusted
-records, registerStyle({ name, … }) makes them addressable by name.
-Authoring guide + quality rubric: docs/style-authoring.md.
-
-## Docs
-
-- docs/README.md — documentation index and structure
-- Instructions_for_agents.md — canonical agent-use guide
-- AGENT_NATIVE.md — architecture/spec rationale
-- docs/features.md — current capability inventory
-- docs/api.md — library/CLI/MCP API reference, including SVG/PNG/ASCII output
-- docs/diagram-families.md — family examples and edit policy
-- docs/theming.md — themes, CSS variables, and Shiki compatibility
-- docs/style-authoring.md — styles: the composable look system (a theme is a palette-only style; stack names/specs; author custom styles as data records with the quality rubric)
-- docs/quality.md — determinism + "good looking" rubric
-- TODO.md — only active backlog
-- SECURITY.md — threat model + strict-mode guarantee
-- docs/agent-mutation-policy.md — structured-vs-source-level policy
-- docs/agent-api-cookbook.md — copy-pasteable library/CLI/MCP recipes
-- docs/mcp-code-mode-rationale.md — MCP surface rationale
-- docs/agent-workflow-examples.md — runnable MCP/CLI + agent-improvement examples
-- skills/ — agent-agnostic SKILL.md bundles for diagram workflow and live-editor development
-- skill-evals/ — skill-eval-harness manifest, fixtures, and benchmark instructions

package/skill-evals/README.md

@@ -1,77 +0,0 @@
-# Skill evals
-
-This directory contains the `skill-eval-harness` manifest for the repository’s agent-agnostic skills under [`../skills/`](../skills/).
-
-## Coverage matrix
-
-The public tune split now includes:
-
-- Diagram families: flowchart, state, sequence, timeline, class, ER, journey,
-  architecture, xychart, pie, quadrant, gantt.
-- Channels: library, CLI, and MCP Code Mode.
-- Negative/no-trigger rows for unrelated work.
-- Adversarial rows for source concatenation, skipping verify, editing generated `editor.html`, and using `type` instead of `kind`.
-- Fixture-backed artifact rows under [`fixtures/`](./fixtures/) that require changed Mermaid/source plus `verifyMermaid` evidence.
-
-The manifest also contains private `prompt_ref` stubs for `holdout` and `holdback`. Those paths are intentionally under ignored `skill-evals/private/`; keep real hidden prompts and answer keys out of public commits.
-
-## Harness
-
-Install/run with:
-
-```bash
-uvx --from git+https://github.com/adewale/skill-eval-harness.git@v0.1.1 skill-benchmark --help
-```
-
-Validate and audit the public manifest:
-
-```bash
-skill-benchmark validate skill-evals/shared-benchmark.json
-skill-benchmark audit-manifest skill-evals/shared-benchmark.json --format markdown --out /tmp/agentic-mermaid-skill-audit.md
-```
-
-Use strict hidden-prompt validation only in a private eval workspace where `skill-evals/private/...` exists:
-
-```bash
-skill-benchmark validate skill-evals/shared-benchmark.json --strict-holdback
-```
-
-Prepare visible tune tasks with repeated runs:
-
-```bash
-skill-benchmark prepare skill-evals/shared-benchmark.json \
-  --split tune \
-  --runs-per-variant 5 \
-  --out /tmp/agentic-mermaid-skill-tasks.jsonl
-```
-
-Use 3 runs per variant for cheap iteration; use 5 for pre-merge/release evidence. Fixture-backed artifact cases require a runner that preserves generated `outputs/...` files inside each run directory so `file_exists` assertions can grade them.
-
-Run autonomous trigger/no-trigger checks separately:
-
-```bash
-skill-pi-trigger-eval skill-evals/shared-benchmark.json \
-  --split tune \
-  --runs-per-query 5 \
-  --out /tmp/agentic-mermaid-trigger-report.json
-```
-
-After running the prepared tasks with a coding-agent runner, grade with:
-
-```bash
-skill-benchmark benchmark skill-evals/shared-benchmark.json \
-  --runs /tmp/agentic-mermaid-skill-runs \
-  --split tune \
-  --out /tmp/agentic-mermaid-skill-benchmark.json
-```
-
-## Latest smoke result
-
-Runner: Pi CLI, one run per variant, tune split only, model reported by Pi as `gpt-5.5` / `openai-codex`.
-
-| Variant | Cases | Runs | Mean objective pass rate |
-|---|---:|---:|---:|
-| `with_skill` | 2 | 2 | 1.00 |
-| `without_skill` | 2 | 2 | 0.00 |
-
-That older result was a positive smoke signal. It is superseded as a coverage target by the expanded manifest above and should be rerun with 3–5 runs per variant before claiming benchmark-level evidence.

package/skill-evals/fixtures/architecture-cache/input.mmd

@@ -1,5 +0,0 @@
-architecture-beta
-  group app(cloud)[Application]
-  service api(server)[API] in app
-  service db(database)[Database] in app
-  api:R -- L:db

package/skill-evals/fixtures/class-payment/input.mmd

@@ -1,4 +0,0 @@
-classDiagram
-  class PaymentService
-  class Invoice
-  PaymentService --> Invoice : creates

package/skill-evals/fixtures/er-orders/input.mmd

@@ -1,10 +0,0 @@
-erDiagram
-  CUSTOMER {
-    string id PK
-    string email
-  }
-  ORDER {
-    string id PK
-    string customer_id FK
-  }
-  CUSTOMER ||--o{ ORDER : places

package/skill-evals/fixtures/flowchart-cache/input.mmd

@@ -1,3 +0,0 @@
-flowchart TD
-  Client[Client] --> API[API]
-  API --> DB[(Database)]

package/skill-evals/fixtures/gantt-release/input.mmd

@@ -1,7 +0,0 @@
-gantt
-  title Release train
-  dateFormat YYYY-MM-DD
-  section Build
-    Build renderer :build, 2024-01-08, 3d
-  section Ship
-    Release        :milestone, rel, after build, 0d

package/skill-evals/fixtures/journey-checkout/input.mmd

@@ -1,6 +0,0 @@
-journey
-  title Checkout
-  section Browse
-    Find item: 4: Customer
-  section Pay
-    Enter payment: 3: Customer

package/skill-evals/fixtures/pie-exports/input.mmd

@@ -1,5 +0,0 @@
-pie showData
-  title Export requests
-  "SVG" : 42
-  "PNG" : 28
-  "ASCII" : 18

package/skill-evals/fixtures/quadrant-priorities/input.mmd

@@ -1,11 +0,0 @@
-quadrantChart
-  title Feature priorities
-  x-axis Low impact --> High impact
-  y-axis Low effort --> High effort
-  quadrant-1 Plan carefully
-  quadrant-2 Big bets
-  quadrant-3 Defer
-  quadrant-4 Quick wins
-  SVG export: [0.78, 0.28]
-  MCP setup: [0.62, 0.72]
-  Theme polish: [0.35, 0.24]

package/skill-evals/fixtures/sequence-retry/input.mmd

@@ -1,8 +0,0 @@
-sequenceDiagram
-  participant Client
-  participant API
-  participant DB
-  Client->>API: Request
-  API->>DB: Query
-  DB-->>API: Result
-  API-->>Client: Response

package/skill-evals/fixtures/state-lifecycle/input.mmd

@@ -1,5 +0,0 @@
-stateDiagram-v2
-  [*] --> Idle
-  Idle --> Processing: start
-  Processing --> Complete: done
-  Complete --> [*]

package/skill-evals/fixtures/timeline-release/input.mmd

@@ -1,6 +0,0 @@
-timeline
-  title Agentic Mermaid Release
-  section Plan
-    Design : API surface
-  section Build
-    Implement : Renderer