{"id":"98610c22-0386-4786-98e0-f42d98b71b73","entityType":"agent","slug":"clawhub-leostehlik-visual-architecture","name":"Visual Architecture Clawhub V180","canonicalUrl":"https://www.xpersona.co/agent/clawhub-leostehlik-visual-architecture","canonicalPath":"/agent/clawhub-leostehlik-visual-architecture","generatedAt":"2026-10-10T17:35:40.913Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T14:27:02.393Z","emptyReason":null},"description":"Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite. Skill: Visual Architecture Clawhub V180 Owner: leostehlik Summary: Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite. Tags: agent:1.6.0, architecture:1.6.0, artifact-engine:1.6.0, diagram:1.6.0, diagrams:1.3.0, latest:1.8.0, openclaw:1.6.0, pr-delta:1.6.0, source-eviden","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s1754kcncc002avbhpwjnqgcr98728et:visual-architecture","sourceUrl":"https://clawhub.ai/leostehlik/visual-architecture","homepage":"https://clawhub.ai/leostehlik/skills/visual-architecture","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/leostehlik/visual-architecture","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/leostehlik/skills/visual-architecture","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:27:02.393Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:27:02.393Z","emptyReason":null},"stars":null,"forks":null,"downloads":1388,"packageName":null,"latestVersion":"1.8.0","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T14:27:02.392Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T14:27:02.393Z","lastCrawledAt":"2026-10-10T14:27:02.392Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T14:27:02.392Z","lastVerifiedAt":null,"highlights":[{"version":"1.8.0","createdAt":"2026-09-01T00:47:05.918Z","changelog":"v1.8.0 public case-study conversion: sanitized TypeScript monorepo case study, generated artifacts, README quick-start, gallery entry, and proof-loop evidence.","fileCount":125,"zipByteSize":199420},{"version":"1.6.0","createdAt":"2026-08-28T00:06:29.557Z","changelog":"v1.6.0: extraction quality release. Adds language-aware repo extraction, confidence-scored source evidence, source-backed validation metrics, PR delta concern grouping, gallery evidence drilldown, and refreshed generated case-study artifacts.","fileCount":118,"zipByteSize":183125},{"version":"1.5.1","createdAt":"2026-08-27T23:40:43.297Z","changelog":"v1.5.1: repo-aware extraction and layout release. Adds extract-repo, deterministic layout, extract-pr, artifact bundling with quality gates, generated source-backed examples, gallery narrative, and artifact rail polish.","fileCount":118,"zipByteSize":173535},{"version":"1.4.0","createdAt":"2026-08-27T23:08:24.155Z","changelog":"v1.4.0: Archify-standard visual quality slice with renderer v2 mode backdrops, receipt quality scoring, story/evidence gallery, source-backed case study, share-card links, and harness proof demos.","fileCount":105,"zipByteSize":147978},{"version":"1.3.0","createdAt":"2026-08-27T22:39:20.535Z","changelog":"Redesigns the generated Pages gallery as an interactive artifact browser with rail, stage, details, and generated links.","fileCount":98,"zipByteSize":121666},{"version":"1.2.0","createdAt":"2026-08-27T22:26:28.817Z","changelog":"Adds a GitHub Pages visual gallery, removes README artifact tables, and makes the README point to the navigable site instead of raw GitHub file views.","fileCount":98,"zipByteSize":116403},{"version":"1.1.1","createdAt":"2026-08-27T22:09:40.579Z","changelog":"Repairs package metadata for the v1.1 README showcase release so ClawHub latest is inspectable and installable.","fileCount":97,"zipByteSize":110667},{"version":"1.1.0","createdAt":"2026-08-27T22:05:16.015Z","changelog":"Adds generated README showcase visuals, a dark showcase render theme, and an SVG bounds fix for routed via-points.","fileCount":97,"zipByteSize":110634}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1754kcncc002avbhpwjnqgcr98728et:visual-architecture","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T17:35:40.908Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-leostehlik-visual-architecture/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T14:27:02.393Z","emptyReason":null},"readme":"Skill: Visual Architecture Clawhub V180\n\nOwner: leostehlik\n\nSummary: Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite.\n\nTags: agent:1.6.0, architecture:1.6.0, artifact-engine:1.6.0, diagram:1.6.0, diagrams:1.3.0, latest:1.8.0, openclaw:1.6.0, pr-delta:1.6.0, source-evidence:1.6.0, svg:1.6.0, visualization:1.6.0\n\nVersion history:\n\nv1.8.0 | 2026-09-01T00:47:05.918Z | user\n\nv1.8.0 public case-study conversion: sanitized TypeScript monorepo case study, generated artifacts, README quick-start, gallery entry, and proof-loop evidence.\n\nv1.6.0 | 2026-08-28T00:06:29.557Z | user\n\nv1.6.0: extraction quality release. Adds language-aware repo extraction, confidence-scored source evidence, source-backed validation metrics, PR delta concern grouping, gallery evidence drilldown, and refreshed generated case-study artifacts.\n\nv1.5.1 | 2026-08-27T23:40:43.297Z | user\n\nv1.5.1: repo-aware extraction and layout release. Adds extract-repo, deterministic layout, extract-pr, artifact bundling with quality gates, generated source-backed examples, gallery narrative, and artifact rail polish.\n\nv1.4.0 | 2026-08-27T23:08:24.155Z | user\n\nv1.4.0: Archify-standard visual quality slice with renderer v2 mode backdrops, receipt quality scoring, story/evidence gallery, source-backed case study, share-card links, and harness proof demos.\n\nv1.3.0 | 2026-08-27T22:39:20.535Z | user\n\nRedesigns the generated Pages gallery as an interactive artifact browser with rail, stage, details, and generated links.\n\nv1.2.0 | 2026-08-27T22:26:28.817Z | user\n\nAdds a GitHub Pages visual gallery, removes README artifact tables, and makes the README point to the navigable site instead of raw GitHub file views.\n\nv1.1.1 | 2026-08-27T22:09:40.579Z | user\n\nRepairs package metadata for the v1.1 README showcase release so ClawHub latest is inspectable and installable.\n\nv1.1.0 | 2026-08-27T22:05:16.015Z | user\n\nAdds generated README showcase visuals, a dark showcase render theme, and an SVG bounds fix for routed via-points.\n\nv1.0.2 | 2026-08-27T21:46:11.624Z | user\n\nRelease metadata repair for the final v1 artifact-engine state: schemas, mode-aware validation, delivery receipts, source evidence badges, PR delta compare, share cards, proof gallery, harness docs, and GitHub release sync.\n\nv1.0.1 | 2026-08-27T21:43:06.907Z | user\n\nRelease-hygiene follow-up for the v1 artifact-engine state: schemas, mode-aware validation, delivery receipts, source evidence badges, PR delta compare, share cards, proof gallery, harness docs, and GitHub release sync.\n\nv1.0.0 | 2026-08-27T21:40:02.046Z | user\n\ntest\n\nv0.2.5 | 2026-05-24T13:46:34.911Z | user\n\nRestore the concise diagram-focused workflow and original renderer behaviour.\n\nv0.2.4 | 2026-05-24T12:52:02.398Z | user\n\nEnforce Visual Architecture renderer file boundaries: inputs/outputs are limited to project or temp paths and existing outputs require --force.\n\nv0.2.3 | 2026-05-24T12:43:32.705Z | user\n\nTighten Visual Architecture security-review wording around architecture confidentiality/topology rather than copyright/ownership.\n\nv0.2.2 | 2026-05-24T11:26:57.495Z | user\n\nDocument the Visual Architecture dual-use boundary: deterministic local JSON-to-SVG rendering, human-owned content decisions, and security review focused on concrete tool behaviour.\n\nv0.2.1 | 2026-05-24T10:00:16.013Z | user\n\nClarify explicit architecture-diagram activation, input/output file boundaries, overwrite caution, review before publishing, and no elevated or generic file-writing use.\n\nv0.2.0 | 2026-05-22T17:04:56.924Z | user\n\nSanitize public example, add README and license, add version metadata, and keep renderer packaging deterministic.\n\nv0.1.0 | 2026-05-21T10:59:00.318Z | user\n\nInitial public Visual Architecture skill.\n\nArchive index:\n\nArchive v1.8.0: 125 files, 199420 bytes\n\nFiles: CHANGELOG.md (5437b), docs/clawhub-sync.md (833b), docs/diagnostics.md (2698b), docs/gallery.html (36134b), docs/harness-demos.md (1158b), docs/harnesses.md (1301b), docs/public-typescript-monorepo-case-study.md (1879b), docs/repo-aware-generation.md (2345b), examples/agent-runtime.html (11268b), examples/agent-runtime.html.receipt.json (1719b), examples/agent-runtime.json (1925b), examples/agent-runtime.share-card.svg (1567b), examples/agent-runtime.svg (8548b), examples/agent-runtime.svg.receipt.json (1716b), examples/dataflow-analytics.html (11863b), examples/dataflow-analytics.html.receipt.json (1543b), examples/dataflow-analytics.json (1420b), examples/dataflow-analytics.share-card.svg (1566b), examples/dataflow-analytics.svg (9114b), examples/dataflow-analytics.svg.receipt.json (1540b), examples/lifecycle-agent-task.html (13144b), examples/lifecycle-agent-task.html.receipt.json (1542b), examples/lifecycle-agent-task.json (1538b), examples/lifecycle-agent-task.share-card.svg (1559b), examples/lifecycle-agent-task.svg (10355b), examples/lifecycle-agent-task.svg.receipt.json (1540b), examples/pr-delta-before.html (7075b), examples/pr-delta-before.html.receipt.json (1129b), examples/pr-delta-before.json (567b), examples/pr-delta-before.share-card.svg (1492b), examples/pr-delta-before.svg (4564b), examples/pr-delta-before.svg.receipt.json (1127b), examples/pr-delta-extracted.html (16842b), examples/pr-delta-extracted.html.receipt.json (1182b), examples/pr-delta-extracted.json (13347b), examples/pr-delta-extracted.share-card.svg (1595b), examples/pr-delta-extracted.svg (13866b), examples/pr-delta-extracted.svg.receipt.json (1180b), examples/pr-delta-generated.html (12084b), examples/pr-delta-generated.html.receipt.json (2208b), examples/pr-delta-generated.json (2103b), examples/pr-delta-generated.share-card.svg (1499b), examples/pr-delta-generated.svg (9358b), examples/pr-delta-generated.svg.receipt.json (1530b), examples/pr-delta-head.html (8437b), examples/pr-delta-head.html.receipt.json (1144b), examples/pr-delta-head.json (855b), examples/pr-delta-head.share-card.svg (1497b), examples/pr-delta-head.svg (5861b), examples/pr-delta-head.svg.receipt.json (1142b), examples/pr-delta-review.html (12632b), examples/pr-delta-review.html.receipt.json (1527b), examples/pr-delta-review.json (2301b), examples/pr-delta-review.share-card.svg (1543b), examples/pr-delta-review.svg (9882b), examples/pr-delta-review.svg.receipt.json (1524b), examples/repo-evidence-map.html (13450b), examples/repo-evidence-map.html.receipt.json (1542b), examples/repo-evidence-map.json (2760b), examples/repo-evidence-map.share-card.svg (1575b), examples/repo-evidence-map.svg (10636b), examples/repo-evidence-map.svg.receipt.json (1540b), examples/sequence-cache-miss.html (11584b), examples/sequence-cache-miss.html.receipt.json (1317b), examples/sequence-cache-miss.json (1391b), examples/sequence-cache-miss.share-card.svg (1560b), examples/sequence-cache-miss.svg (8865b), examples/sequence-cache-miss.svg.receipt.json (1314b), examples/service-map.html (10989b), examples/service-map.html.receipt.json (1542b), examples/service-map.json (1745b), examples/service-map.share-card.svg (1467b), examples/service-map.svg (8347b), examples/service-map.svg.receipt.json (1539b), examples/showcase-artifact-engine.html (12076b), examples/showcase-artifact-engine.html.receipt.json (1193b), examples/showcase-artifact-engine.json (2270b), examples/showcase-artifact-engine.share-card.svg (1595b), examples/showcase-artifact-engine.svg (9286b), examples/showcase-artifact-engine.svg.receipt.json (1190b)\n\nFile v1.8.0:SKILL.md\n\n---\nname: visual-architecture\ndescription: \"Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite.\"\nmetadata:\n  version: \"1.8.0\"\n---\n# Visual Architecture\n\nCreate architecture artifacts with the bundled Python renderer instead of hand-writing SVG. v1.8 adds a public TypeScript-monorepo case study path on top of the v1.7 extraction engine: source-backed case-study docs, generated artifacts, README quick-starts, and gallery conversion proof.\n\nUse this when the user needs a trustworthy system map, agent workflow, sequence, data-flow, lifecycle/state diagram, repo-evidence diagram, or PR delta review sketch that should stay local, deterministic, and reviewable.\n\n## Workflow\n\n1. Either extract a TypeScript-aware starter spec from a repo or create a JSON file with `mode`, `title`, `nodes`, and `edges`.\n   - Supported modes: `architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`, `pr-delta`.\n   - Supported themes: `classic` for documentation, `showcase` for README/release proof images.\n2. Snap intended node positions to the renderer grid mentally before writing them:\n   - horizontal grid: 120px\n   - vertical grid: 80px\n3. For repo-aware drafts, extract and layout first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py extract-repo . --output repo-map.json --title \"Generated Repo Map\"\npython3 skills/visual-architecture/scripts/render_architecture.py layout repo-map.json repo-map.layout.json --mode architecture\n```\n\n4. Validate first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py validate input.json --json\n```\n\n5. Deliver the final artifact with a receipt:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py deliver input.json output.html --json\n```\n\nUse `.svg` for a static docs artifact or `.html` for a self-contained presentation artifact.\n\nFor PR delta review, either extract a PR concern map from git refs or compare two specs:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py extract-pr --base origin/master --head HEAD --output pr-delta.json\npython3 skills/visual-architecture/scripts/render_architecture.py compare base.json head.json pr-delta.html --spec pr-delta.json --json\n```\n\n6. If `rsvg-convert` is available and you need a bitmap preview, run:\n\n```bash\nrsvg-convert -o output.png output.svg\n```\n\n## JSON Input Structure\n\n```json\n{\n  \"title\": \"Service Map\",\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\n## Node Kinds\n\n- `service`: rounded rectangle\n- `llm`: double-border rounded rectangle\n- `agent`: hexagon\n- `memory`: cylinder\n\nEach node requires:\n- `id`: unique string\n- `label`: primary title\n- `kind`: one of the node kinds above\n- `x`, `y`: grid-aligned center coordinates\n\nOptional:\n- `subtitle`: smaller secondary label\n- `show_grid`: set true to display the editing grid in the exported SVG\n- `theme`: set `showcase` on the top-level spec for dark public-facing artifacts\n- `evidence`: object or list with `source`, optional `line`/`lines`, `commit`, `confidence`, and `note`\n\n## Edge Kinds\n\n- `primary-data`: blue solid arrow\n- `memory-write`: green dashed arrow\n- `control`: slate dashed arrow\n\nEach edge requires:\n- `from`: source node id\n- `to`: target node id\n\nOptional:\n- `label`: rendered on the route with a shielding background rect\n- `source_side`, `target_side`: force edge anchors (`left`, `right`, `top`, `bottom`)\n- `via`: array of orthogonal turn points, each with `x` and `y`\n- `label_segment`: zero-based segment index to place the label on\n- `label_offset`: `[dx, dy]` shift for fine label placement\n\n## Renderer Guarantees\n\n- Validate rejects unsupported node/edge kinds and unknown edge endpoints before rendering\n- Deliver writes the artifact atomically and emits a JSON receipt with SHA-256 hashes\n- Validation receipts include a quality score for spacing, density, route crossings, and visual overlap\n- `extract-repo`, `layout`, `extract-pr`, and `bundle` turn repo evidence into checked artifacts without hand-placing every node\n- `--min-quality` can fail delivery or bundle export when the artifact is not presentation-grade\n- The generated gallery can load spec/receipt JSON and show story steps plus source evidence\n- Evidence badges render as `SRC n` on nodes with source-backed evidence\n- PR delta compare writes added/removed node and edge facts into the receipt\n- Route arrows orthogonally only\n- Render in this order: background, arrows, nodes, labels\n- Keep label shields behind arrow text for readability\n- Stay restrained: clean strokes, no decorative effects, and hide the editing grid unless explicitly requested\n\n## Usage Notes\n\n- Prefer this skill when the user wants architecture diagrams, routing maps, or system relationship visuals.\n- Choose semantic kinds first, then place nodes on the grid, then add only the edges needed to explain flow.\n- Keep diagrams sparse. If a diagram feels crowded, split it into two files instead of forcing a dense composite.\n- Prefer `deliver` for handoff. A passing render without a receipt is a draft.\n- Do not claim repository evidence unless the spec names source files, commits, or confidence explicitly.\n\n## Example\n\nUse `examples/service-map.json` as a generic architecture starting point. Use `examples/agent-runtime.json`, `examples/sequence-cache-miss.json`, `examples/dataflow-analytics.json`, and `examples/lifecycle-agent-task.json` for the non-architecture modes. Use `examples/repo-evidence-map.json` for source-pinned evidence, and `examples/pr-delta-before.json` plus `examples/pr-delta-head.json` for generated PR deltas.\n\nFile v1.8.0:README.md\n\n# visual-architecture\n\n[![Validate](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml/badge.svg)](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml)\n\n**Deterministic, local-first architecture artifacts for agents.**\n\nvisual-architecture turns local repo evidence or typed JSON specs into SVG, self-contained HTML, share cards, receipts, and a generated Pages showcase. The v1.8 contract is stronger: agents can extract TypeScript monorepo structure, infer app/package/backend/frontend surfaces, attach confidence-scored evidence, lay it out deterministically, validate evidence quality, and publish a reviewable artifact bundle.\n\nThe wedge against Archify is local-first proof: architecture artifacts that look intentional, cite their sources, explain PR deltas, and remain reproducible from a repo scan or checked JSON.\n\n![Visual Architecture artifact engine](examples/showcase-artifact-engine.svg)\n\n## Visual Gallery\n\nOpen the generated artifact site: **https://leostehlik.github.io/visual-architecture/**\n\nThe gallery is the browsing surface: artifact rail, large diagram stage, story path, receipt quality, share cards, source evidence drilldown, and a public TypeScript-monorepo case study. The README stays as the product brief; the repo keeps the JSON specs, SVG/HTML artifacts, and receipts for audit.\n\n\n## Public Case Study\n\nThe current conversion artifact is a sanitized TypeScript monorepo map: client app, server app, editor extension, shared packages, backend modules, realtime gateway, database layer, and proof bundle.\n\nOpen it in the gallery or inspect the checked files directly:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/showcase-typescript-monorepo-case-study.json /tmp/typescript-monorepo-case-study.html --json\npython3 scripts/render_architecture.py bundle examples/showcase-typescript-monorepo-case-study.json /tmp/typescript-monorepo-case-study --min-quality good\n```\n\n- Case-study notes: [`docs/public-typescript-monorepo-case-study.md`](docs/public-typescript-monorepo-case-study.md)\n- Spec: [`examples/showcase-typescript-monorepo-case-study.json`](examples/showcase-typescript-monorepo-case-study.json)\n- SVG: [`examples/showcase-typescript-monorepo-case-study.svg`](examples/showcase-typescript-monorepo-case-study.svg)\n- Receipt: [`examples/showcase-typescript-monorepo-case-study.html.receipt.json`](examples/showcase-typescript-monorepo-case-study.html.receipt.json)\n\n## Why It Exists\n\nAgents are good at inventing diagrams and bad at proving what they just drew. visual-architecture gives them a narrow, deterministic path:\n\n1. Author a compact JSON spec.\n2. Validate supported modes, node kinds, edge kinds, endpoints, evidence fields, grid placement, and obvious route hazards.\n3. Deliver SVG or HTML atomically.\n4. Emit a JSON receipt with input/output SHA-256, byte counts, metrics, warnings, and validation result.\n\nThe output stays local and deterministic, but no longer uses one generic box-arrow treatment for every artifact. Architecture, workflow, sequence, data-flow, lifecycle, and PR delta modes now get distinct visual scaffolding.\n\n## Install\n\n### OpenClaw / ClawHub\n\n```bash\nopenclaw skills install visual-architecture\n```\n\n### Manual\n\n```bash\ngit clone https://github.com/LeoStehlik/visual-architecture.git ~/.openclaw/workspace/skills/visual-architecture\n```\n\nFor Codex, Claude Code, OpenCode, or another agent harness, copy this repo or the `SKILL.md` plus `scripts/` and `examples/` into the harness skill directory.\n\n## Quick Start\n\nValidate a spec:\n\n```bash\npython3 scripts/render_architecture.py validate examples/service-map.json --json\n```\n\nRender a static SVG:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/service-map.json examples/service-map.svg --json\n```\n\nDeliver a self-contained HTML artifact:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/agent-runtime.json examples/agent-runtime.html --json\n```\n\nCompare base/head specs for a PR delta artifact:\n\n```bash\npython3 scripts/render_architecture.py compare examples/pr-delta-before.json examples/pr-delta-head.json examples/pr-delta-generated.html --spec examples/pr-delta-generated.json --json\n```\n\nExtract TypeScript-aware repo evidence, apply layout, generate a bundle, or build the gallery:\n\n```bash\npython3 scripts/render_architecture.py extract-repo . --output examples/visual-architecture-auto.json --title \"Generated TypeScript-Aware Repo Map\"\npython3 scripts/render_architecture.py layout examples/visual-architecture-auto.json /tmp/laid-out.json --mode architecture\npython3 scripts/render_architecture.py bundle examples/visual-architecture-auto.json /tmp/visual-architecture-bundle --min-quality good\npython3 scripts/render_architecture.py gallery index.html\n```\n\nThe legacy v0.2 command still works:\n\n```bash\npython3 scripts/render_architecture.py examples/service-map.json examples/service-map.svg\n```\n\n## Checked Artifacts\n\nThe checked examples cover service maps, agent workflows, repo evidence, PR deltas, sequence, data-flow, lifecycle, and the dark showcase theme. Browse them through the generated site instead of raw GitHub file views:\n\n- Gallery: https://leostehlik.github.io/visual-architecture/\n- Hero spec: [`examples/showcase-artifact-engine.json`](examples/showcase-artifact-engine.json)\n- Hero receipt: [`examples/showcase-artifact-engine.html.receipt.json`](examples/showcase-artifact-engine.html.receipt.json)\n\nShare-card SVGs are generated beside each example as `*.share-card.svg`.\n\nRun the same local proof gate as CI:\n\n```bash\nmake validate\n```\n\nRegenerate all examples:\n\n```bash\nmake examples\n```\n\n## JSON Model\n\n```json\n{\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"title\": \"Service Map\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\nNode kinds:\n\n- `service` - rounded rectangle\n- `llm` - double-border rounded rectangle\n- `agent` - hexagon\n- `memory` - cylinder\n\nEdge kinds:\n\n- `primary-data` - blue solid arrow\n- `memory-write` - green dashed arrow\n- `control` - slate dashed arrow\n\nSupported modes:\n\n- `architecture` - component maps, services, stores, boundaries\n- `workflow` - agent/tool/process/runbook paths\n- `sequence` - request/API/call lifecycles\n- `dataflow` - pipelines, lineage, stores, sensitive boundaries\n- `lifecycle` - states, retries, waits, terminal outcomes\n- `pr-delta` - review artifacts for base/head architecture changes\n\nThemes:\n\n- `classic` - light documentation artifact, used by default\n- `showcase` - dark README/release artifact for first-screen proof images\n\nEvidence fields can be added to nodes or edges:\n\n```json\n{\n  \"source\": \"services/fraud/client.ts\",\n  \"line\": 42,\n  \"commit\": \"abc1234\",\n  \"confidence\": \"medium\",\n  \"note\": \"Fraud scoring client introduced by this PR.\"\n}\n```\n\nNodes with evidence render a compact `SRC n` badge. Receipts count evidence items and keep PR delta facts separate from ordinary artifact validation.\n\n## Receipt Contract\n\n`deliver` writes `<artifact>.receipt.json` by default. A receipt includes:\n\n- tool/version\n- artifact kind: `svg` or `html`\n- input path, SHA-256, and byte count\n- output path, SHA-256, and byte count\n- validation status, errors, warnings, and metrics\n\nValidation currently checks the shape of the spec, supported modes and semantic kinds, unknown endpoints, evidence field shape, duplicate/shared grid positions, route crossings through unrelated nodes, edge crossings, density, visual overlap, and long labels that are likely to crowd the diagram. Receipts include a quality score so ugly artifacts are visible as defects, not treated as successful output.\n\nStable diagnostic codes are documented in [`docs/diagnostics.md`](docs/diagnostics.md).\n\n## Roadmap\n\nCompleted v1.0 ladder:\n\n- v0.3: public foundation, examples, HTML wrapper, release hygiene\n- v0.4: schemas, validate/deliver receipts, CI proof\n- v0.5: workflow, sequence, data-flow, and lifecycle modes\n- v0.6: source evidence fields, evidence validation, `SRC n` badges, evidence metrics\n- v0.7: base/head PR delta compare command with review receipt\n- v1.0: proof gallery, share-card artifacts, harness notes, GitHub release surface\n\nHarness install/use notes are in [`docs/harnesses.md`](docs/harnesses.md), and short proof demos for OpenClaw, Codex, Claude Code, and OpenCode are in [`docs/harness-demos.md`](docs/harness-demos.md). ClawHub sync checks are in [`docs/clawhub-sync.md`](docs/clawhub-sync.md).\n\nNext high-value work:\n\n- deeper automatic layout per mode, especially sequence/data-flow/lifecycle\n- stronger label clearance and route-quality diagnostics\n- route, config, call graph, and cross-package dependency extraction beyond the current public case-study surface\n- PNG export when a portable raster dependency is available\n\n## Repository\n\n```text\nvisual-architecture/\n├── SKILL.md\n├── examples/\n│   ├── *.json\n│   ├── *.svg\n│   ├── *.html\n│   ├── *.receipt.json\n│   └── *.share-card.svg\n├── schemas/\n│   └── *.schema.json\n├── docs/\n│   └── gallery.html\n├── scripts/\n│   └── render_architecture.py\n├── .github/workflows/\n│   └── validate.yml\n├── Makefile\n└── README.md\n```\n\n## Status\n\nv1.8.0 public case-study conversion: deterministic renderer, TypeScript-aware extraction, schemas, mode-aware validation, delivery receipts, HTML/SVG/share-card artifacts, source evidence badges, PR delta compare, gallery, and a sanitized TypeScript monorepo case study.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nFile v1.8.0:_meta.json\n\n{\n  \"ownerId\": \"kn7d3r58cdxk8k0xg6jq6k65gs873c0c\",\n  \"slug\": \"visual-architecture\",\n  \"version\": \"1.8.0\",\n  \"publishedAt\": 1788223625918\n}\n\nFile v1.8.0:CHANGELOG.md\n\n# Changelog\n\n## v1.8.0\n\n- Add a public TypeScript-monorepo case study that converts clone/API curiosity into a human-readable artifact path.\n- Add sanitized case-study notes covering client, server, editor extension, shared packages, backend modules, realtime gateway, database layer, and proof bundle surfaces.\n- Add checked generated case-study SVG, HTML, share card, receipts, and gallery/index entries.\n- Add README case-study quick-start commands for `deliver` and `bundle`.\n- Bump renderer and skill metadata to `1.8.0`.\n\n## v1.7.0\n\n- Ignore junk/build directories during repo extraction by default.\n- Prevent generated extractor edges from targeting missing nodes.\n- Detect workspace package/app surfaces from monorepo package metadata.\n- Add TS/TSX import scanning and per-package import summaries.\n- Detect client app, server app, editor extension, backend modules, realtime gateways, database layer, API client, and frontend feature surfaces.\n- Refresh generated public examples with the v1.7 extractor.\n- Validate the extractor against a private TypeScript monorepo without publishing private artifacts.\n\n## v1.6.0\n\n- Add language-aware repo extraction for Python, package metadata, workflows, schemas, examples, docs, and generated site files.\n- Add confidence-scored extraction metadata and source confidence metrics to validation receipts.\n- Improve PR delta extraction by grouping changed files into architecture concerns rather than raw filename buckets.\n- Tighten source-backed validation so generated evidence artifacts require evidence on every node and edge.\n- Upgrade the gallery evidence panel into an evidence drilldown that shows source type, confidence, and extraction rule.\n- Refresh generated repo and PR examples from the v1.6 extractor.\n\n## v1.5.1\n\n- Polish the generated Pages gallery artifact rail so the public showcase no longer exposes a native horizontal scrollbar.\n\n## v1.5.0\n\n- Add `extract-repo` to create a first source-backed architecture spec from local repository structure.\n- Add `layout` for deterministic mode-aware node placement without hand-authored coordinates.\n- Add `extract-pr` to group changed files into a generated PR delta review spec.\n- Add `bundle` to export HTML, SVG, share card, receipt, and bundle manifest together.\n- Add `--min-quality` gates for `deliver` and `bundle`.\n- Add generated repo evidence and PR delta examples to the public gallery.\n\n## v1.4.0\n\n- Add renderer v2 foundations: mode-specific backdrops for architecture, workflow, sequence, data-flow, lifecycle, and PR delta artifacts.\n- Add visual quality scoring to validation receipts for overlap, density, route crossings, spacing, and route complexity.\n- Add story-aware gallery data and an interactive evidence panel that loads checked spec/receipt JSON on GitHub Pages.\n- Add a real visual-architecture case-study artifact with source evidence pointing at the renderer, Makefile, README, and examples.\n- Tighten README/SKILL positioning around Archify-standard presentation, local proof, and source-backed case studies.\n\n## v1.3.0\n\n- Redesign the generated gallery into an interactive artifact viewer.\n- Put the diagram stage, artifact rail, details panel, and source links into one generated Pages surface.\n- Keep the gallery generated from checked JSON examples rather than hand-authored showcase markup.\n\n## v1.2.0\n\n- Add a generated GitHub Pages gallery site as the visual browsing surface.\n- Remove the README gallery tables that pushed visitors into raw GitHub file views.\n- Generate both root `index.html` and `docs/gallery.html` from the local examples.\n\n## v1.1.1\n\n- Repair package metadata after the v1.1.0 ClawHub publish became non-inspectable.\n\n## v1.1.0\n\n- Add a dark `showcase` render theme for README and release artifacts.\n- Add three checked showcase examples for the artifact workflow, repo evidence map, and PR delta review surface.\n- Replace the README first-screen diagram with generated showcase artifacts.\n\n## v1.0.2\n\n- Release metadata repair so GitHub and ClawHub package versions both report the final v1 artifact-engine state cleanly.\n\n## v1.0.0\n\n- Complete the planned product ladder from foundation renderer to artifact engine.\n- Add schema files for architecture, workflow, sequence, data-flow, lifecycle, PR delta, and shared evidence primitives.\n- Add mode-aware validation metrics and examples for all supported diagram modes.\n- Add source evidence fields on nodes/edges with validation and visible `SRC n` node badges.\n- Add `compare` command for base/head PR delta artifacts and receipts.\n- Add static share-card SVG generation and generated proof gallery.\n- Expand CI validation to schemas, every example, generated gallery, and PR delta compare smoke.\n\n## v0.3.0\n\n- Reposition visual-architecture as a local-first architecture artifact engine for agents.\n- Add `validate`, `render`, and `deliver` commands while preserving the old two-argument render command.\n- Add delivery receipts with input/output SHA-256 hashes, byte counts, validation result, warnings, and metrics.\n- Add self-contained HTML output in addition to SVG.\n- Add checked proof examples for service maps, agent runtimes, repo-evidence maps, and PR delta review maps.\n- Expand `make validate` so CI validates every example and proves committed SVGs regenerate byte-for-byte.\n- Update the roadmap toward schema diagnostics, multi-diagram modes, source evidence, PR deltas, and share/export artifacts.\n\nFile v1.8.0:docs/clawhub-sync.md\n\n# ClawHub Sync Checklist\n\nPublish to ClawHub only after the public repo state is green and the installable package is clean.\n\n## Required Checks\n\n```bash\nmake validate\ngrep -RInE \"private-path|private-host|token-placeholder|client-name-placeholder\" README.md SKILL.md CHANGELOG.md docs examples scripts schemas\n```\n\nInstall smoke after publish must confirm:\n\n- `SKILL.md` reports the expected version\n- examples are present\n- `python3 scripts/render_architecture.py validate examples/service-map.json --json` exits 0\n- no generated docs expose private local paths, private hosts, credentials, or internal runtime state\n\n## Current State\n\nGitHub `v1.0.0` is the target public release for the full product ladder. ClawHub sync is allowed only if the publish bundle passes the checks above and the registry accepts the package cleanly.\n\nFile v1.8.0:docs/diagnostics.md\n\n# Diagnostics\n\n`visual-architecture validate --json` and `deliver --json` return stable diagnostic codes. The validator is intentionally local and conservative: it checks authored JSON facts and renderer-safe geometry, not live infrastructure.\n\n## Spec Codes\n\n- `spec.type` - input is not a JSON object\n- `mode.unsupported` - `mode` is not one of the supported diagram modes\n- `title.required` - title is missing or empty\n- `nodes.required` - nodes are missing or empty\n- `edges.type` - edges exists but is not a list\n\n## Node Codes\n\n- `node.type` - node is not an object\n- `node.id.required` - node id is missing or empty\n- `node.id.duplicate` - node id repeats\n- `node.label.required` - node label is missing or empty\n- `node.kind.unsupported` - node kind is not renderer-supported\n- `node.x.required` / `node.y.required` - coordinate is missing or non-numeric\n- `node.x.snapped` / `node.y.snapped` - coordinate will snap to the renderer grid\n- `node.position.shared` - two nodes share one grid position\n\n## Edge Codes\n\n- `edge.type` - edge is not an object\n- `edge.from.unknown` / `edge.to.unknown` - endpoint id does not exist\n- `edge.kind.unsupported` - edge kind is not renderer-supported\n- `edge.label.long` - label may crowd the route\n- `edge.via.type` - via point is not an object\n- `edge.via.x.required` / `edge.via.y.required` - via coordinate is missing or non-numeric\n- `edge.via.x.snapped` / `edge.via.y.snapped` - via coordinate will snap to the renderer grid\n- `edge.route.crosses-node` - an edge route crosses an unrelated node box\n\n## Evidence Codes\n\n- `evidence.type` - evidence is not an object or list\n- `evidence.item.type` - evidence list item is not an object\n- `evidence.source.required` - evidence source is missing\n- `evidence.line.type` - evidence line is not an integer\n- `evidence.lines.type` - evidence lines are not `[start, end]` integers\n- `evidence.commit.type` - evidence commit is not a string\n- `evidence.confidence.unknown` - confidence is not `high`, `medium`, or `low`\n\n## Visual Quality Diagnostics\n\n- `quality.node.overlap` - rendered node boxes overlap or sit too close to be presentation-grade.\n- `quality.node.spacing` - node centers are too close for a clean artifact.\n- `quality.route.crossings` - unrelated edge routes cross and should be rerouted with `via` points.\n- `quality.route.complex` - an edge route has enough turns to become visually noisy.\n- `quality.density.high` - the artifact is dense enough that it should probably be split or narrated as a smaller story.\n\nReceipts expose `validation.metrics.quality.score` and `validation.metrics.quality.rating`. Treat `needs-work` and `poor` as visual defects even when the JSON shape is valid.\n\nFile v1.8.0:docs/harness-demos.md\n\n# Harness Demos\n\nEach harness should prove the same thing: a local JSON spec becomes a checked artifact plus a receipt. Keep the demo small enough to paste into an agent task.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\npython3 ~/.openclaw/workspace/skills/visual-architecture/scripts/render_architecture.py deliver \\\n  ~/.openclaw/workspace/skills/visual-architecture/examples/showcase-visual-architecture-case-study.json \\\n  /tmp/visual-architecture-case-study.html --json\n```\n\n## Codex\n\n```text\nUse the visual-architecture skill. Validate examples/showcase-visual-architecture-case-study.json, deliver HTML, then report the receipt quality score and evidence count.\n```\n\n## Claude Code\n\n```text\nRead SKILL.md, run the validate command against examples/showcase-pr-delta.json, then deliver examples/showcase-pr-delta.html with a receipt.\n```\n\n## OpenCode\n\n```text\nInstall or copy this repo as a local skill, then run make examples and make validate before citing any generated artifact.\n```\n\nA harness demo is not accepted unless it reports the generated receipt path, input/output SHA-256 hashes, quality rating, and evidence count.\n\nFile v1.8.0:docs/harnesses.md\n\n# Harness Notes\n\nvisual-architecture is a plain local skill: JSON in, SVG/HTML/receipt out. It does not need a hosted renderer.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\n```\n\nAsk Francis or another OpenClaw agent to use `visual-architecture` for a bounded architecture, workflow, sequence, data-flow, lifecycle, repo-evidence, or PR delta artifact.\n\n## Codex\n\nCopy this repo into the Codex skill directory or keep it in the target repo and point Codex at `SKILL.md`.\n\nUseful prompt:\n\n```text\nUse visual-architecture to create a source-evidence architecture map for this repo.\nValidate the JSON, deliver HTML, and return the receipt path.\n```\n\n## Claude Code\n\nCopy the skill folder into Claude's local skills directory and keep generated artifacts inside the project. Prefer `deliver` over `render` so Claude has a receipt to cite.\n\n## OpenCode\n\nPlace the repo or skill folder where OpenCode can read `SKILL.md`. Use the same command contract:\n\n```bash\npython3 scripts/render_architecture.py validate input.json --json\npython3 scripts/render_architecture.py deliver input.json output.html --json\n```\n\n## Review Rule\n\nFor public artifacts, scan generated files for private paths, hostnames, tokens, internal context, and accidental client details before release or ClawHub sync.\n\nFile v1.8.0:docs/public-typescript-monorepo-case-study.md\n\n# Public TypeScript Monorepo Case Study\n\nThis case study is intentionally generic. It is modeled on the shape of a serious private TypeScript monorepo without publishing private repo names, file paths, client data, or deployment details.\n\n## Scenario\n\nA product repo contains a web client, API server, editor extension, shared packages, backend modules, realtime gateway, API client, and database layer. A human reviewer wants the agent to explain the architecture without inventing systems or leaking private details.\n\n## Surfaces\n\n- Client app: routes, feature modules, hooks, and UI state.\n- Server app: HTTP entrypoint, controllers, services, and background jobs.\n- Editor extension: local command surface that calls the product API.\n- Shared packages: types, API client, validation helpers, and config.\n- Backend modules: domain services, auth/session rules, import/export jobs, and queue workers.\n- Realtime gateway: websocket or event bridge for collaborative state.\n- Database layer: migrations, repositories, and persistence boundaries.\n- Proof bundle: generated SVG/HTML, receipt JSON, share card, and source-evidence drilldown.\n\n## Extraction Claims\n\nVisual Architecture should identify these surfaces as a reviewable starter map, not as a final omniscient diagram. The value is a deterministic artifact the reviewer can correct: nodes, edges, evidence, confidence, and receipt quality are all visible.\n\n## Review Path\n\n1. Extract a repo map.\n2. Inspect evidence and confidence.\n3. Run layout for a readable first pass.\n4. Bundle the artifact.\n5. Use the gallery to review the map and receipts.\n6. Correct the JSON spec when the tool is wrong.\n\n## Public Boundary\n\nThe public artifact uses generic names and source descriptions only. It does not publish private application names, internal hostnames, customer names, environment values, or proprietary code structure.\n\nFile v1.8.0:docs/repo-aware-generation.md\n\n# Repo-Aware Generation\n\n`visual-architecture` can now create a first useful architecture draft from a local repository. The extractor is deliberately conservative: it looks for repo surfaces that are easy to defend with file evidence, then emits a normal JSON spec that can be reviewed and edited.\n\n```bash\npython3 scripts/render_architecture.py extract-repo . --output examples/visual-architecture-auto.json\npython3 scripts/render_architecture.py deliver examples/visual-architecture-auto.json examples/visual-architecture-auto.html --min-quality good --json\n```\n\nFor pull requests, generate a changed-file review surface:\n\n```bash\npython3 scripts/render_architecture.py extract-pr --base origin/master --head HEAD --output examples/pr-delta-extracted.json\n```\n\nFor hand-authored specs, apply deterministic layout before delivery:\n\n```bash\npython3 scripts/render_architecture.py layout input.json output.json --mode architecture --theme showcase\n```\n\nFor release assets, bundle everything together:\n\n```bash\npython3 scripts/render_architecture.py bundle examples/visual-architecture-auto.json /tmp/visual-architecture-bundle --min-quality good\n```\n\nA generated artifact is still a draft. The receipt quality rating, warnings, and evidence list are the review surface.\n\n\n## v1.6 Extraction Quality\n\nThe v1.6 extractor is language-aware rather than only filename-aware. It classifies Python runtime files, package metadata, GitHub Actions workflows, JSON schemas, checked examples, generated gallery files, and product docs. Generated source-backed artifacts carry extraction rules, source type, confidence, and file/line evidence on every node and edge. PR delta extraction groups changed files into architecture concerns so the review artifact says what surface changed, not just which files changed.\n\n\n## v1.7 TypeScript Monorepo Extraction\n\nThe v1.7 extractor skips common generated and dependency directories by default, then detects workspaces from package metadata. It creates package/app nodes for client, server, and editor-extension style workspaces, scans TS/TSX imports for per-package dependency summaries, and detects backend modules, realtime gateways, database/migration layers, frontend entries, API clients, config boundaries, and feature folders. Extracted edges are filtered so generated specs cannot point at missing nodes.\n\nFile v1.8.0:skill-card.md\n\n## Description:\n\nCreate deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[leostehlik](https://clawhub.ai/user/leostehlik)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and engineers use this skill to create local, deterministic architecture, workflow, sequence, data-flow, lifecycle, repo-evidence, and PR delta artifacts that can be validated, rendered, and reviewed with receipts.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Generated HTML/SVG artifacts can run injected browser scripts if diagram JSON is untrusted.\n\nMitigation: Use trusted local JSON, review or fix HTML/SVG escaping before untrusted use, and avoid opening or deploying generated HTML/SVG from unreviewed contributions.\n\nRisk: Generated artifacts can expose private paths, repository details, hostnames, tokens, or internal context when shared publicly.\n\nMitigation: Review generated artifacts, receipts, and galleries for private details before sharing, release, or ClawHub sync.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/leostehlik/skills/visual-architecture)\n- [Generated Artifact Gallery](https://leostehlik.github.io/visual-architecture/)\n- [Diagnostics](docs/diagnostics.md)\n- [Repo-Aware Generation](docs/repo-aware-generation.md)\n- [Harness Notes](docs/harnesses.md)\n- [Public TypeScript Monorepo Case Study](docs/public-typescript-monorepo-case-study.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance, Files]\n\n**Output Format:** [Markdown guidance with JSON specs, shell commands, generated SVG/HTML artifacts, JSON receipts, share cards, and bundles]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Local-first output; deliver and bundle commands emit receipts with hashes, validation status, warnings, metrics, and quality ratings.]\n\n## Skill Version(s):\n\n1.8.0 (source: SKILL.md metadata, CHANGELOG, server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.8.0:examples/agent-runtime.html.receipt.json\n\n{\n  \"artifactKind\": \"html\",\n  \"generatedAt\": \"2026-09-01T00:41:50.340917+00:00\",\n  \"input\": {\n    \"bytes\": 1925,\n    \"path\": \"examples/agent-runtime.json\",\n    \"sha256\": \"4adc883c50030740dc1416d2fe999302f42c303acc255225babf7376721450d5\"\n  },\n  \"mode\": \"workflow\",\n  \"output\": {\n    \"bytes\": 11268,\n    \"path\": \"examples/agent-runtime.html\",\n    \"sha256\": \"08f3319b20b6b89626c9fa4b0fe7c52278c240a125d0c50d89d055c3dee9dc3b\"\n  },\n  \"tool\": \"visual-architecture\",\n  \"validation\": {\n    \"errors\": [],\n    \"metrics\": {\n      \"edgeKinds\": [\n        \"control\",\n        \"memory-write\",\n        \"primary-data\"\n      ],\n      \"edges\": 5,\n      \"evidenceItems\": 0,\n      \"mode\": \"workflow\",\n      \"nodeKinds\": [\n        \"agent\",\n        \"memory\",\n        \"service\"\n      ],\n      \"nodes\": 6,\n      \"quality\": {\n        \"checks\": [\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"brief\",\n              \"lessons\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"builder\",\n              \"receipt\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"artifact\",\n              \"validator\"\n            ]\n          }\n        ],\n        \"rating\": \"good\",\n        \"routeCrossings\": 0,\n        \"score\": 76\n      },\n      \"sourceBacked\": false,\n      \"sourceConfidence\": {\n        \"high\": 0,\n        \"low\": 0,\n        \"medium\": 0,\n        \"unspecified\": 0\n      },\n      \"theme\": \"classic\"\n    },\n    \"ok\": true,\n    \"warnings\": []\n  },\n  \"version\": \"1.8.0\"\n}\n\nArchive v1.6.0: 118 files, 183125 bytes\n\nFiles: CHANGELOG.md (4334b), docs/clawhub-sync.md (833b), docs/diagnostics.md (2698b), docs/gallery.html (34280b), docs/harness-demos.md (1158b), docs/harnesses.md (1301b), docs/repo-aware-generation.md (1803b), examples/agent-runtime.html (11268b), examples/agent-runtime.html.receipt.json (1719b), examples/agent-runtime.json (1925b), examples/agent-runtime.share-card.svg (1567b), examples/agent-runtime.svg (8548b), examples/agent-runtime.svg.receipt.json (1716b), examples/dataflow-analytics.html (11863b), examples/dataflow-analytics.html.receipt.json (1543b), examples/dataflow-analytics.json (1420b), examples/dataflow-analytics.share-card.svg (1566b), examples/dataflow-analytics.svg (9114b), examples/dataflow-analytics.svg.receipt.json (1540b), examples/lifecycle-agent-task.html (13144b), examples/lifecycle-agent-task.html.receipt.json (1542b), examples/lifecycle-agent-task.json (1538b), examples/lifecycle-agent-task.share-card.svg (1559b), examples/lifecycle-agent-task.svg (10355b), examples/lifecycle-agent-task.svg.receipt.json (1540b), examples/pr-delta-before.html (7075b), examples/pr-delta-before.html.receipt.json (1129b), examples/pr-delta-before.json (567b), examples/pr-delta-before.share-card.svg (1492b), examples/pr-delta-before.svg (4564b), examples/pr-delta-before.svg.receipt.json (1127b), examples/pr-delta-extracted.html (16842b), examples/pr-delta-extracted.html.receipt.json (1182b), examples/pr-delta-extracted.json (16795b), examples/pr-delta-extracted.share-card.svg (1595b), examples/pr-delta-extracted.svg (13866b), examples/pr-delta-extracted.svg.receipt.json (1180b), examples/pr-delta-generated.html (12084b), examples/pr-delta-generated.html.receipt.json (2208b), examples/pr-delta-generated.json (2103b), examples/pr-delta-generated.share-card.svg (1499b), examples/pr-delta-generated.svg (9358b), examples/pr-delta-generated.svg.receipt.json (1530b), examples/pr-delta-head.html (8437b), examples/pr-delta-head.html.receipt.json (1144b), examples/pr-delta-head.json (855b), examples/pr-delta-head.share-card.svg (1497b), examples/pr-delta-head.svg (5861b), examples/pr-delta-head.svg.receipt.json (1142b), examples/pr-delta-review.html (12632b), examples/pr-delta-review.html.receipt.json (1527b), examples/pr-delta-review.json (2301b), examples/pr-delta-review.share-card.svg (1543b), examples/pr-delta-review.svg (9882b), examples/pr-delta-review.svg.receipt.json (1524b), examples/repo-evidence-map.html (13450b), examples/repo-evidence-map.html.receipt.json (1542b), examples/repo-evidence-map.json (2760b), examples/repo-evidence-map.share-card.svg (1575b), examples/repo-evidence-map.svg (10636b), examples/repo-evidence-map.svg.receipt.json (1540b), examples/sequence-cache-miss.html (11584b), examples/sequence-cache-miss.html.receipt.json (1317b), examples/sequence-cache-miss.json (1391b), examples/sequence-cache-miss.share-card.svg (1560b), examples/sequence-cache-miss.svg (8865b), examples/sequence-cache-miss.svg.receipt.json (1314b), examples/service-map.html (10989b), examples/service-map.html.receipt.json (1542b), examples/service-map.json (1745b), examples/service-map.share-card.svg (1467b), examples/service-map.svg (8347b), examples/service-map.svg.receipt.json (1539b), examples/showcase-artifact-engine.html (12076b), examples/showcase-artifact-engine.html.receipt.json (1193b), examples/showcase-artifact-engine.json (2270b), examples/showcase-artifact-engine.share-card.svg (1595b), examples/showcase-artifact-engine.svg (9286b), examples/showcase-artifact-engine.svg.receipt.json (1190b), examples/showcase-pr-delta.html (13668b)\n\nFile v1.6.0:SKILL.md\n\n---\nname: visual-architecture\ndescription: \"Create deterministic, local-first architecture artifacts from typed JSON or language-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite.\"\nmetadata:\n  version: \"1.6.0\"\n---\n# Visual Architecture\n\nCreate architecture artifacts with the bundled Python renderer instead of hand-writing SVG. v1.6 adds language-aware repo extraction, confidence-scored evidence, deterministic auto-layout, PR delta concern extraction, artifact bundles, quality fail gates, and evidence drilldown in the gallery.\n\nUse this when the user needs a trustworthy system map, agent workflow, sequence, data-flow, lifecycle/state diagram, repo-evidence diagram, or PR delta review sketch that should stay local, deterministic, and reviewable.\n\n## Workflow\n\n1. Either extract a language-aware starter spec from a repo or create a JSON file with `mode`, `title`, `nodes`, and `edges`.\n   - Supported modes: `architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`, `pr-delta`.\n   - Supported themes: `classic` for documentation, `showcase` for README/release proof images.\n2. Snap intended node positions to the renderer grid mentally before writing them:\n   - horizontal grid: 120px\n   - vertical grid: 80px\n3. For repo-aware drafts, extract and layout first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py extract-repo . --output repo-map.json --title \"Generated Repo Map\"\npython3 skills/visual-architecture/scripts/render_architecture.py layout repo-map.json repo-map.layout.json --mode architecture\n```\n\n4. Validate first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py validate input.json --json\n```\n\n5. Deliver the final artifact with a receipt:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py deliver input.json output.html --json\n```\n\nUse `.svg` for a static docs artifact or `.html` for a self-contained presentation artifact.\n\nFor PR delta review, either extract a PR concern map from git refs or compare two specs:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py extract-pr --base origin/master --head HEAD --output pr-delta.json\npython3 skills/visual-architecture/scripts/render_architecture.py compare base.json head.json pr-delta.html --spec pr-delta.json --json\n```\n\n6. If `rsvg-convert` is available and you need a bitmap preview, run:\n\n```bash\nrsvg-convert -o output.png output.svg\n```\n\n## JSON Input Structure\n\n```json\n{\n  \"title\": \"Service Map\",\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\n## Node Kinds\n\n- `service`: rounded rectangle\n- `llm`: double-border rounded rectangle\n- `agent`: hexagon\n- `memory`: cylinder\n\nEach node requires:\n- `id`: unique string\n- `label`: primary title\n- `kind`: one of the node kinds above\n- `x`, `y`: grid-aligned center coordinates\n\nOptional:\n- `subtitle`: smaller secondary label\n- `show_grid`: set true to display the editing grid in the exported SVG\n- `theme`: set `showcase` on the top-level spec for dark public-facing artifacts\n- `evidence`: object or list with `source`, optional `line`/`lines`, `commit`, `confidence`, and `note`\n\n## Edge Kinds\n\n- `primary-data`: blue solid arrow\n- `memory-write`: green dashed arrow\n- `control`: slate dashed arrow\n\nEach edge requires:\n- `from`: source node id\n- `to`: target node id\n\nOptional:\n- `label`: rendered on the route with a shielding background rect\n- `source_side`, `target_side`: force edge anchors (`left`, `right`, `top`, `bottom`)\n- `via`: array of orthogonal turn points, each with `x` and `y`\n- `label_segment`: zero-based segment index to place the label on\n- `label_offset`: `[dx, dy]` shift for fine label placement\n\n## Renderer Guarantees\n\n- Validate rejects unsupported node/edge kinds and unknown edge endpoints before rendering\n- Deliver writes the artifact atomically and emits a JSON receipt with SHA-256 hashes\n- Validation receipts include a quality score for spacing, density, route crossings, and visual overlap\n- `extract-repo`, `layout`, `extract-pr`, and `bundle` turn repo evidence into checked artifacts without hand-placing every node\n- `--min-quality` can fail delivery or bundle export when the artifact is not presentation-grade\n- The generated gallery can load spec/receipt JSON and show story steps plus source evidence\n- Evidence badges render as `SRC n` on nodes with source-backed evidence\n- PR delta compare writes added/removed node and edge facts into the receipt\n- Route arrows orthogonally only\n- Render in this order: background, arrows, nodes, labels\n- Keep label shields behind arrow text for readability\n- Stay restrained: clean strokes, no decorative effects, and hide the editing grid unless explicitly requested\n\n## Usage Notes\n\n- Prefer this skill when the user wants architecture diagrams, routing maps, or system relationship visuals.\n- Choose semantic kinds first, then place nodes on the grid, then add only the edges needed to explain flow.\n- Keep diagrams sparse. If a diagram feels crowded, split it into two files instead of forcing a dense composite.\n- Prefer `deliver` for handoff. A passing render without a receipt is a draft.\n- Do not claim repository evidence unless the spec names source files, commits, or confidence explicitly.\n\n## Example\n\nUse `examples/service-map.json` as a generic architecture starting point. Use `examples/agent-runtime.json`, `examples/sequence-cache-miss.json`, `examples/dataflow-analytics.json`, and `examples/lifecycle-agent-task.json` for the non-architecture modes. Use `examples/repo-evidence-map.json` for source-pinned evidence, and `examples/pr-delta-before.json` plus `examples/pr-delta-head.json` for generated PR deltas.\n\nFile v1.6.0:README.md\n\n# visual-architecture\n\n[![Validate](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml/badge.svg)](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml)\n\n**Deterministic, local-first architecture artifacts for agents.**\n\nvisual-architecture turns local repo evidence or typed JSON specs into SVG, self-contained HTML, share cards, receipts, and a generated Pages showcase. The v1.6 contract is stronger: agents can extract a language-aware, confidence-scored spec from a repository, infer architecture concerns, lay it out deterministically, validate evidence quality, and publish a reviewable artifact bundle.\n\nThe wedge against Archify is local-first proof: architecture artifacts that look intentional, cite their sources, explain PR deltas, and remain reproducible from a repo scan or checked JSON.\n\n![Visual Architecture artifact engine](examples/showcase-artifact-engine.svg)\n\n## Visual Gallery\n\nOpen the generated artifact site: **https://leostehlik.github.io/visual-architecture/**\n\nThe gallery is the browsing surface: artifact rail, large diagram stage, story path, receipt quality, share cards, and source evidence drilldown. The README stays as the product brief; the repo keeps the JSON specs, SVG/HTML artifacts, and receipts for audit.\n\n## Why It Exists\n\nAgents are good at inventing diagrams and bad at proving what they just drew. visual-architecture gives them a narrow, deterministic path:\n\n1. Author a compact JSON spec.\n2. Validate supported modes, node kinds, edge kinds, endpoints, evidence fields, grid placement, and obvious route hazards.\n3. Deliver SVG or HTML atomically.\n4. Emit a JSON receipt with input/output SHA-256, byte counts, metrics, warnings, and validation result.\n\nThe output stays local and deterministic, but no longer uses one generic box-arrow treatment for every artifact. Architecture, workflow, sequence, data-flow, lifecycle, and PR delta modes now get distinct visual scaffolding.\n\n## Install\n\n### OpenClaw / ClawHub\n\n```bash\nopenclaw skills install visual-architecture\n```\n\n### Manual\n\n```bash\ngit clone https://github.com/LeoStehlik/visual-architecture.git ~/.openclaw/workspace/skills/visual-architecture\n```\n\nFor Codex, Claude Code, OpenCode, or another agent harness, copy this repo or the `SKILL.md` plus `scripts/` and `examples/` into the harness skill directory.\n\n## Quick Start\n\nValidate a spec:\n\n```bash\npython3 scripts/render_architecture.py validate examples/service-map.json --json\n```\n\nRender a static SVG:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/service-map.json examples/service-map.svg --json\n```\n\nDeliver a self-contained HTML artifact:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/agent-runtime.json examples/agent-runtime.html --json\n```\n\nCompare base/head specs for a PR delta artifact:\n\n```bash\npython3 scripts/render_architecture.py compare examples/pr-delta-before.json examples/pr-delta-head.json examples/pr-delta-generated.html --spec examples/pr-delta-generated.json --json\n```\n\nExtract language-aware repo evidence, apply layout, generate a bundle, or build the gallery:\n\n```bash\npython3 scripts/render_architecture.py extract-repo . --output examples/visual-architecture-auto.json --title \"Generated Language-Aware Repo Map\"\npython3 scripts/render_architecture.py layout examples/visual-architecture-auto.json /tmp/laid-out.json --mode architecture\npython3 scripts/render_architecture.py bundle examples/visual-architecture-auto.json /tmp/visual-architecture-bundle --min-quality good\npython3 scripts/render_architecture.py gallery index.html\n```\n\nThe legacy v0.2 command still works:\n\n```bash\npython3 scripts/render_architecture.py examples/service-map.json examples/service-map.svg\n```\n\n## Checked Artifacts\n\nThe checked examples cover service maps, agent workflows, repo evidence, PR deltas, sequence, data-flow, lifecycle, and the dark showcase theme. Browse them through the generated site instead of raw GitHub file views:\n\n- Gallery: https://leostehlik.github.io/visual-architecture/\n- Hero spec: [`examples/showcase-artifact-engine.json`](examples/showcase-artifact-engine.json)\n- Hero receipt: [`examples/showcase-artifact-engine.html.receipt.json`](examples/showcase-artifact-engine.html.receipt.json)\n\nShare-card SVGs are generated beside each example as `*.share-card.svg`.\n\nRun the same local proof gate as CI:\n\n```bash\nmake validate\n```\n\nRegenerate all examples:\n\n```bash\nmake examples\n```\n\n## JSON Model\n\n```json\n{\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"title\": \"Service Map\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\nNode kinds:\n\n- `service` - rounded rectangle\n- `llm` - double-border rounded rectangle\n- `agent` - hexagon\n- `memory` - cylinder\n\nEdge kinds:\n\n- `primary-data` - blue solid arrow\n- `memory-write` - green dashed arrow\n- `control` - slate dashed arrow\n\nSupported modes:\n\n- `architecture` - component maps, services, stores, boundaries\n- `workflow` - agent/tool/process/runbook paths\n- `sequence` - request/API/call lifecycles\n- `dataflow` - pipelines, lineage, stores, sensitive boundaries\n- `lifecycle` - states, retries, waits, terminal outcomes\n- `pr-delta` - review artifacts for base/head architecture changes\n\nThemes:\n\n- `classic` - light documentation artifact, used by default\n- `showcase` - dark README/release artifact for first-screen proof images\n\nEvidence fields can be added to nodes or edges:\n\n```json\n{\n  \"source\": \"services/fraud/client.ts\",\n  \"line\": 42,\n  \"commit\": \"abc1234\",\n  \"confidence\": \"medium\",\n  \"note\": \"Fraud scoring client introduced by this PR.\"\n}\n```\n\nNodes with evidence render a compact `SRC n` badge. Receipts count evidence items and keep PR delta facts separate from ordinary artifact validation.\n\n## Receipt Contract\n\n`deliver` writes `<artifact>.receipt.json` by default. A receipt includes:\n\n- tool/version\n- artifact kind: `svg` or `html`\n- input path, SHA-256, and byte count\n- output path, SHA-256, and byte count\n- validation status, errors, warnings, and metrics\n\nValidation currently checks the shape of the spec, supported modes and semantic kinds, unknown endpoints, evidence field shape, duplicate/shared grid positions, route crossings through unrelated nodes, edge crossings, density, visual overlap, and long labels that are likely to crowd the diagram. Receipts include a quality score so ugly artifacts are visible as defects, not treated as successful output.\n\nStable diagnostic codes are documented in [`docs/diagnostics.md`](docs/diagnostics.md).\n\n## Roadmap\n\nCompleted v1.0 ladder:\n\n- v0.3: public foundation, examples, HTML wrapper, release hygiene\n- v0.4: schemas, validate/deliver receipts, CI proof\n- v0.5: workflow, sequence, data-flow, and lifecycle modes\n- v0.6: source evidence fields, evidence validation, `SRC n` badges, evidence metrics\n- v0.7: base/head PR delta compare command with review receipt\n- v1.0: proof gallery, share-card artifacts, harness notes, GitHub release surface\n\nHarness install/use notes are in [`docs/harnesses.md`](docs/harnesses.md), and short proof demos for OpenClaw, Codex, Claude Code, and OpenCode are in [`docs/harness-demos.md`](docs/harness-demos.md). ClawHub sync checks are in [`docs/clawhub-sync.md`](docs/clawhub-sync.md).\n\nNext high-value work:\n\n- deeper automatic layout per mode, especially sequence/data-flow/lifecycle\n- stronger label clearance and route-quality diagnostics\n- richer language-aware extraction for imports/routes/configuration boundaries\n- PNG export when a portable raster dependency is available\n\n## Repository\n\n```text\nvisual-architecture/\n├── SKILL.md\n├── examples/\n│   ├── *.json\n│   ├── *.svg\n│   ├── *.html\n│   ├── *.receipt.json\n│   └── *.share-card.svg\n├── schemas/\n│   └── *.schema.json\n├── docs/\n│   └── gallery.html\n├── scripts/\n│   └── render_architecture.py\n├── .github/workflows/\n│   └── validate.yml\n├── Makefile\n└── README.md\n```\n\n## Status\n\nv1.0.0 artifact engine foundation: deterministic renderer, schemas, mode-aware validation, delivery receipts, HTML artifacts, source evidence badges, PR delta compare, share cards, gallery, and checked examples.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nFile v1.6.0:_meta.json\n\n{\n  \"ownerId\": \"kn7d3r58cdxk8k0xg6jq6k65gs873c0c\",\n  \"slug\": \"visual-architecture\",\n  \"version\": \"1.6.0\",\n  \"publishedAt\": 1787875589557\n}\n\nFile v1.6.0:CHANGELOG.md\n\n# Changelog\n\n## v1.6.0\n\n- Add language-aware repo extraction for Python, package metadata, workflows, schemas, examples, docs, and generated site files.\n- Add confidence-scored extraction metadata and source confidence metrics to validation receipts.\n- Improve PR delta extraction by grouping changed files into architecture concerns rather than raw filename buckets.\n- Tighten source-backed validation so generated evidence artifacts require evidence on every node and edge.\n- Upgrade the gallery evidence panel into an evidence drilldown that shows source type, confidence, and extraction rule.\n- Refresh generated repo and PR examples from the v1.6 extractor.\n\n## v1.5.1\n\n- Polish the generated Pages gallery artifact rail so the public showcase no longer exposes a native horizontal scrollbar.\n\n## v1.5.0\n\n- Add `extract-repo` to create a first source-backed architecture spec from local repository structure.\n- Add `layout` for deterministic mode-aware node placement without hand-authored coordinates.\n- Add `extract-pr` to group changed files into a generated PR delta review spec.\n- Add `bundle` to export HTML, SVG, share card, receipt, and bundle manifest together.\n- Add `--min-quality` gates for `deliver` and `bundle`.\n- Add generated repo evidence and PR delta examples to the public gallery.\n\n## v1.4.0\n\n- Add renderer v2 foundations: mode-specific backdrops for architecture, workflow, sequence, data-flow, lifecycle, and PR delta artifacts.\n- Add visual quality scoring to validation receipts for overlap, density, route crossings, spacing, and route complexity.\n- Add story-aware gallery data and an interactive evidence panel that loads checked spec/receipt JSON on GitHub Pages.\n- Add a real visual-architecture case-study artifact with source evidence pointing at the renderer, Makefile, README, and examples.\n- Tighten README/SKILL positioning around Archify-standard presentation, local proof, and source-backed case studies.\n\n## v1.3.0\n\n- Redesign the generated gallery into an interactive artifact viewer.\n- Put the diagram stage, artifact rail, details panel, and source links into one generated Pages surface.\n- Keep the gallery generated from checked JSON examples rather than hand-authored showcase markup.\n\n## v1.2.0\n\n- Add a generated GitHub Pages gallery site as the visual browsing surface.\n- Remove the README gallery tables that pushed visitors into raw GitHub file views.\n- Generate both root `index.html` and `docs/gallery.html` from the local examples.\n\n## v1.1.1\n\n- Repair package metadata after the v1.1.0 ClawHub publish became non-inspectable.\n\n## v1.1.0\n\n- Add a dark `showcase` render theme for README and release artifacts.\n- Add three checked showcase examples for the artifact workflow, repo evidence map, and PR delta review surface.\n- Replace the README first-screen diagram with generated showcase artifacts.\n\n## v1.0.2\n\n- Release metadata repair so GitHub and ClawHub package versions both report the final v1 artifact-engine state cleanly.\n\n## v1.0.0\n\n- Complete the planned product ladder from foundation renderer to artifact engine.\n- Add schema files for architecture, workflow, sequence, data-flow, lifecycle, PR delta, and shared evidence primitives.\n- Add mode-aware validation metrics and examples for all supported diagram modes.\n- Add source evidence fields on nodes/edges with validation and visible `SRC n` node badges.\n- Add `compare` command for base/head PR delta artifacts and receipts.\n- Add static share-card SVG generation and generated proof gallery.\n- Expand CI validation to schemas, every example, generated gallery, and PR delta compare smoke.\n\n## v0.3.0\n\n- Reposition visual-architecture as a local-first architecture artifact engine for agents.\n- Add `validate`, `render`, and `deliver` commands while preserving the old two-argument render command.\n- Add delivery receipts with input/output SHA-256 hashes, byte counts, validation result, warnings, and metrics.\n- Add self-contained HTML output in addition to SVG.\n- Add checked proof examples for service maps, agent runtimes, repo-evidence maps, and PR delta review maps.\n- Expand `make validate` so CI validates every example and proves committed SVGs regenerate byte-for-byte.\n- Update the roadmap toward schema diagnostics, multi-diagram modes, source evidence, PR deltas, and share/export artifacts.\n\nFile v1.6.0:docs/clawhub-sync.md\n\n# ClawHub Sync Checklist\n\nPublish to ClawHub only after the public repo state is green and the installable package is clean.\n\n## Required Checks\n\n```bash\nmake validate\ngrep -RInE \"private-path|private-host|token-placeholder|client-name-placeholder\" README.md SKILL.md CHANGELOG.md docs examples scripts schemas\n```\n\nInstall smoke after publish must confirm:\n\n- `SKILL.md` reports the expected version\n- examples are present\n- `python3 scripts/render_architecture.py validate examples/service-map.json --json` exits 0\n- no generated docs expose private local paths, private hosts, credentials, or internal runtime state\n\n## Current State\n\nGitHub `v1.0.0` is the target public release for the full product ladder. ClawHub sync is allowed only if the publish bundle passes the checks above and the registry accepts the package cleanly.\n\nFile v1.6.0:docs/diagnostics.md\n\n# Diagnostics\n\n`visual-architecture validate --json` and `deliver --json` return stable diagnostic codes. The validator is intentionally local and conservative: it checks authored JSON facts and renderer-safe geometry, not live infrastructure.\n\n## Spec Codes\n\n- `spec.type` - input is not a JSON object\n- `mode.unsupported` - `mode` is not one of the supported diagram modes\n- `title.required` - title is missing or empty\n- `nodes.required` - nodes are missing or empty\n- `edges.type` - edges exists but is not a list\n\n## Node Codes\n\n- `node.type` - node is not an object\n- `node.id.required` - node id is missing or empty\n- `node.id.duplicate` - node id repeats\n- `node.label.required` - node label is missing or empty\n- `node.kind.unsupported` - node kind is not renderer-supported\n- `node.x.required` / `node.y.required` - coordinate is missing or non-numeric\n- `node.x.snapped` / `node.y.snapped` - coordinate will snap to the renderer grid\n- `node.position.shared` - two nodes share one grid position\n\n## Edge Codes\n\n- `edge.type` - edge is not an object\n- `edge.from.unknown` / `edge.to.unknown` - endpoint id does not exist\n- `edge.kind.unsupported` - edge kind is not renderer-supported\n- `edge.label.long` - label may crowd the route\n- `edge.via.type` - via point is not an object\n- `edge.via.x.required` / `edge.via.y.required` - via coordinate is missing or non-numeric\n- `edge.via.x.snapped` / `edge.via.y.snapped` - via coordinate will snap to the renderer grid\n- `edge.route.crosses-node` - an edge route crosses an unrelated node box\n\n## Evidence Codes\n\n- `evidence.type` - evidence is not an object or list\n- `evidence.item.type` - evidence list item is not an object\n- `evidence.source.required` - evidence source is missing\n- `evidence.line.type` - evidence line is not an integer\n- `evidence.lines.type` - evidence lines are not `[start, end]` integers\n- `evidence.commit.type` - evidence commit is not a string\n- `evidence.confidence.unknown` - confidence is not `high`, `medium`, or `low`\n\n## Visual Quality Diagnostics\n\n- `quality.node.overlap` - rendered node boxes overlap or sit too close to be presentation-grade.\n- `quality.node.spacing` - node centers are too close for a clean artifact.\n- `quality.route.crossings` - unrelated edge routes cross and should be rerouted with `via` points.\n- `quality.route.complex` - an edge route has enough turns to become visually noisy.\n- `quality.density.high` - the artifact is dense enough that it should probably be split or narrated as a smaller story.\n\nReceipts expose `validation.metrics.quality.score` and `validation.metrics.quality.rating`. Treat `needs-work` and `poor` as visual defects even when the JSON shape is valid.\n\nFile v1.6.0:docs/harness-demos.md\n\n# Harness Demos\n\nEach harness should prove the same thing: a local JSON spec becomes a checked artifact plus a receipt. Keep the demo small enough to paste into an agent task.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\npython3 ~/.openclaw/workspace/skills/visual-architecture/scripts/render_architecture.py deliver \\\n  ~/.openclaw/workspace/skills/visual-architecture/examples/showcase-visual-architecture-case-study.json \\\n  /tmp/visual-architecture-case-study.html --json\n```\n\n## Codex\n\n```text\nUse the visual-architecture skill. Validate examples/showcase-visual-architecture-case-study.json, deliver HTML, then report the receipt quality score and evidence count.\n```\n\n## Claude Code\n\n```text\nRead SKILL.md, run the validate command against examples/showcase-pr-delta.json, then deliver examples/showcase-pr-delta.html with a receipt.\n```\n\n## OpenCode\n\n```text\nInstall or copy this repo as a local skill, then run make examples and make validate before citing any generated artifact.\n```\n\nA harness demo is not accepted unless it reports the generated receipt path, input/output SHA-256 hashes, quality rating, and evidence count.\n\nFile v1.6.0:docs/harnesses.md\n\n# Harness Notes\n\nvisual-architecture is a plain local skill: JSON in, SVG/HTML/receipt out. It does not need a hosted renderer.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\n```\n\nAsk Francis or another OpenClaw agent to use `visual-architecture` for a bounded architecture, workflow, sequence, data-flow, lifecycle, repo-evidence, or PR delta artifact.\n\n## Codex\n\nCopy this repo into the Codex skill directory or keep it in the target repo and point Codex at `SKILL.md`.\n\nUseful prompt:\n\n```text\nUse visual-architecture to create a source-evidence architecture map for this repo.\nValidate the JSON, deliver HTML, and return the receipt path.\n```\n\n## Claude Code\n\nCopy the skill folder into Claude's local skills directory and keep generated artifacts inside the project. Prefer `deliver` over `render` so Claude has a receipt to cite.\n\n## OpenCode\n\nPlace the repo or skill folder where OpenCode can read `SKILL.md`. Use the same command contract:\n\n```bash\npython3 scripts/render_architecture.py validate input.json --json\npython3 scripts/render_architecture.py deliver input.json output.html --json\n```\n\n## Review Rule\n\nFor public artifacts, scan generated files for private paths, hostnames, tokens, internal context, and accidental client details before release or ClawHub sync.\n\nFile v1.6.0:docs/repo-aware-generation.md\n\n# Repo-Aware Generation\n\n`visual-architecture` can now create a first useful architecture draft from a local repository. The extractor is deliberately conservative: it looks for repo surfaces that are easy to defend with file evidence, then emits a normal JSON spec that can be reviewed and edited.\n\n```bash\npython3 scripts/render_architecture.py extract-repo . --output examples/visual-architecture-auto.json\npython3 scripts/render_architecture.py deliver examples/visual-architecture-auto.json examples/visual-architecture-auto.html --min-quality good --json\n```\n\nFor pull requests, generate a changed-file review surface:\n\n```bash\npython3 scripts/render_architecture.py extract-pr --base origin/master --head HEAD --output examples/pr-delta-extracted.json\n```\n\nFor hand-authored specs, apply deterministic layout before delivery:\n\n```bash\npython3 scripts/render_architecture.py layout input.json output.json --mode architecture --theme showcase\n```\n\nFor release assets, bundle everything together:\n\n```bash\npython3 scripts/render_architecture.py bundle examples/visual-architecture-auto.json /tmp/visual-architecture-bundle --min-quality good\n```\n\nA generated artifact is still a draft. The receipt quality rating, warnings, and evidence list are the review surface.\n\n\n## v1.6 Extraction Quality\n\nThe v1.6 extractor is language-aware rather than only filename-aware. It classifies Python runtime files, package metadata, GitHub Actions workflows, JSON schemas, checked examples, generated gallery files, and product docs. Generated source-backed artifacts carry extraction rules, source type, confidence, and file/line evidence on every node and edge. PR delta extraction groups changed files into architecture concerns so the review artifact says what surface changed, not just which files changed.\n\nFile v1.6.0:skill-card.md\n\n## Description:\n\nCreate deterministic, local-first architecture artifacts from typed JSON or language-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[leostehlik](https://clawhub.ai/user/leostehlik)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and engineers use this skill to create reviewable system maps, agent workflows, sequence diagrams, data-flow diagrams, lifecycle diagrams, repository evidence maps, and PR delta review sketches from local JSON specs or repository extraction.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill asks an agent to run a bundled local Python renderer, read repository files, run git diff for PR maps, and write diagram and receipt files.\n\nMitigation: Install only when that local access is acceptable for the target project, and run it in a workspace where generated files and repository reads are expected.\n\nRisk: Generated diagrams may be mistaken for source-backed architecture evidence when receipts show incomplete or false source backing.\n\nMitigation: Review generated receipts before citing artifacts, especially examples where sourceBacked is false or node and edge evidence is incomplete.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/leostehlik/skills/visual-architecture)\n- [Visual Architecture gallery](https://leostehlik.github.io/visual-architecture/)\n- [README](README.md)\n- [Diagnostics](docs/diagnostics.md)\n- [Repo-Aware Generation](docs/repo-aware-generation.md)\n- [Harness Notes](docs/harnesses.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with JSON specs and shell command blocks; generated artifacts may include SVG, self-contained HTML, share-card SVG, and JSON receipts.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Outputs are local and deterministic when produced through the bundled renderer; receipts include hashes, validation status, metrics, warnings, and evidence quality signals.]\n\n## Skill Version(s):\n\n1.6.0 (source: SKILL.md frontmatter, CHANGELOG, server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.6.0:examples/agent-runtime.html.receipt.json\n\n{\n  \"artifactKind\": \"html\",\n  \"generatedAt\": \"2026-08-28T00:01:33.196496+00:00\",\n  \"input\": {\n    \"bytes\": 1925,\n    \"path\": \"examples/agent-runtime.json\",\n    \"sha256\": \"4adc883c50030740dc1416d2fe999302f42c303acc255225babf7376721450d5\"\n  },\n  \"mode\": \"workflow\",\n  \"output\": {\n    \"bytes\": 11268,\n    \"path\": \"examples/agent-runtime.html\",\n    \"sha256\": \"08f3319b20b6b89626c9fa4b0fe7c52278c240a125d0c50d89d055c3dee9dc3b\"\n  },\n  \"tool\": \"visual-architecture\",\n  \"validation\": {\n    \"errors\": [],\n    \"metrics\": {\n      \"edgeKinds\": [\n        \"control\",\n        \"memory-write\",\n        \"primary-data\"\n      ],\n      \"edges\": 5,\n      \"evidenceItems\": 0,\n      \"mode\": \"workflow\",\n      \"nodeKinds\": [\n        \"agent\",\n        \"memory\",\n        \"service\"\n      ],\n      \"nodes\": 6,\n      \"quality\": {\n        \"checks\": [\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"brief\",\n              \"lessons\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"builder\",\n              \"receipt\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"artifact\",\n              \"validator\"\n            ]\n          }\n        ],\n        \"rating\": \"good\",\n        \"routeCrossings\": 0,\n        \"score\": 76\n      },\n      \"sourceBacked\": false,\n      \"sourceConfidence\": {\n        \"high\": 0,\n        \"low\": 0,\n        \"medium\": 0,\n        \"unspecified\": 0\n      },\n      \"theme\": \"classic\"\n    },\n    \"ok\": true,\n    \"warnings\": []\n  },\n  \"version\": \"1.6.0\"\n}\n\nFile v1.6.0:examples/agent-runtime.json\n\n{\n  \"mode\": \"workflow\",\n  \"title\": \"Agent Runtime Proof Loop\",\n  \"summary\": \"A local agent turns a task brief into a checked artifact with verifier feedback and durable lessons.\",\n  \"show_grid\": false,\n  \"nodes\": [\n    {\n      \"id\": \"brief\",\n      \"label\": \"Task Brief\",\n      \"subtitle\": \"Scoped ACs\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"builder\",\n      \"label\": \"Builder Agent\",\n      \"subtitle\": \"Implements slice\",\n      \"kind\": \"agent\",\n      \"x\": 360,\n      \"y\": 160\n    },\n    {\n      \"id\": \"artifact\",\n      \"label\": \"Artifact\",\n      \"subtitle\": \"SVG or HTML\",\n      \"kind\": \"service\",\n      \"x\": 600,\n      \"y\": 160\n    },\n    {\n      \"id\": \"validator\",\n      \"label\": \"Validator\",\n      \"subtitle\": \"Checks contract\",\n      \"kind\": \"agent\",\n      \"x\": 600,\n      \"y\": 320\n    },\n    {\n      \"id\": \"receipt\",\n      \"label\": \"Receipt\",\n      \"subtitle\": \"Hashes + metrics\",\n      \"kind\": \"memory\",\n      \"x\": 360,\n      \"y\": 320\n    },\n    {\n      \"id\": \"lessons\",\n      \"label\": \"Lessons\",\n      \"subtitle\": \"Future corrections\",\n      \"kind\": \"memory\",\n      \"x\": 120,\n      \"y\": 320\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"brief\",\n      \"to\": \"builder\",\n      \"kind\": \"control\",\n      \"label\": \"execute\",\n      \"label_offset\": [0, -28]\n    },\n    {\n      \"from\": \"builder\",\n      \"to\": \"artifact\",\n      \"kind\": \"primary-data\",\n      \"label\": \"deliver\",\n      \"label_offset\": [0, -28]\n    },\n    {\n      \"from\": \"artifact\",\n      \"to\": \"validator\",\n      \"kind\": \"control\",\n      \"label\": \"validate\"\n    },\n    {\n      \"from\": \"validator\",\n      \"to\": \"receipt\",\n      \"kind\": \"memory-write\",\n      \"label\": \"proof\",\n      \"source_side\": \"left\",\n      \"target_side\": \"right\"\n    },\n    {\n      \"from\": \"receipt\",\n      \"to\": \"lessons\",\n      \"kind\": \"memory-write\",\n      \"label\": \"capture\",\n      \"source_side\": \"left\",\n      \"target_side\": \"right\"\n    }\n  ]\n}\n\nArchive v1.5.1: 118 files, 173535 bytes\n\nFiles: CHANGELOG.md (3683b), docs/clawhub-sync.md (833b), docs/diagnostics.md (2698b), docs/gallery.html (33772b), docs/harness-demos.md (1158b), docs/harnesses.md (1301b), docs/repo-aware-generation.md (1270b), examples/agent-runtime.html (10841b), examples/agent-runtime.html.receipt.json (1570b), examples/agent-runtime.json (1925b), examples/agent-runtime.share-card.svg (1567b), examples/agent-runtime.svg (8193b), examples/agent-runtime.svg.receipt.json (1567b), examples/dataflow-analytics.html (11437b), examples/dataflow-analytics.html.receipt.json (1394b), examples/dataflow-analytics.json (1420b), examples/dataflow-analytics.share-card.svg (1566b), examples/dataflow-analytics.svg (8760b), examples/dataflow-analytics.svg.receipt.json (1391b), examples/lifecycle-agent-task.html (12724b), examples/lifecycle-agent-task.html.receipt.json (1393b), examples/lifecycle-agent-task.json (1538b), examples/lifecycle-agent-task.share-card.svg (1559b), examples/lifecycle-agent-task.svg (10007b), examples/lifecycle-agent-task.svg.receipt.json (1391b), examples/pr-delta-before.html (6875b), examples/pr-delta-before.html.receipt.json (980b), examples/pr-delta-before.json (567b), examples/pr-delta-before.share-card.svg (1492b), examples/pr-delta-before.svg (4400b), examples/pr-delta-before.svg.receipt.json (978b), examples/pr-delta-extracted.html (14890b), examples/pr-delta-extracted.html.receipt.json (1032b), examples/pr-delta-extracted.json (7739b), examples/pr-delta-extracted.share-card.svg (1565b), examples/pr-delta-extracted.svg (12076b), examples/pr-delta-extracted.svg.receipt.json (1030b), examples/pr-delta-generated.html (11668b), examples/pr-delta-generated.html.receipt.json (2059b), examples/pr-delta-generated.json (2103b), examples/pr-delta-generated.share-card.svg (1499b), examples/pr-delta-generated.svg (9014b), examples/pr-delta-generated.svg.receipt.json (1381b), examples/pr-delta-head.html (8168b), examples/pr-delta-head.html.receipt.json (995b), examples/pr-delta-head.json (855b), examples/pr-delta-head.share-card.svg (1497b), examples/pr-delta-head.svg (5640b), examples/pr-delta-head.svg.receipt.json (993b), examples/pr-delta-review.html (12217b), examples/pr-delta-review.html.receipt.json (1378b), examples/pr-delta-review.json (2301b), examples/pr-delta-review.share-card.svg (1543b), examples/pr-delta-review.svg (9539b), examples/pr-delta-review.svg.receipt.json (1375b), examples/repo-evidence-map.html (13032b), examples/repo-evidence-map.html.receipt.json (1393b), examples/repo-evidence-map.json (2760b), examples/repo-evidence-map.share-card.svg (1575b), examples/repo-evidence-map.svg (10290b), examples/repo-evidence-map.svg.receipt.json (1391b), examples/sequence-cache-miss.html (11239b), examples/sequence-cache-miss.html.receipt.json (1168b), examples/sequence-cache-miss.json (1391b), examples/sequence-cache-miss.share-card.svg (1560b), examples/sequence-cache-miss.svg (8580b), examples/sequence-cache-miss.svg.receipt.json (1165b), examples/service-map.html (10643b), examples/service-map.html.receipt.json (1393b), examples/service-map.json (1745b), examples/service-map.share-card.svg (1467b), examples/service-map.svg (8061b), examples/service-map.svg.receipt.json (1390b), examples/showcase-artifact-engine.html (11653b), examples/showcase-artifact-engine.html.receipt.json (1044b), examples/showcase-artifact-engine.json (2270b), examples/showcase-artifact-engine.share-card.svg (1595b), examples/showcase-artifact-engine.svg (8935b), examples/showcase-artifact-engine.svg.receipt.json (1041b), examples/showcase-pr-delta.html (13252b)\n\nFile v1.5.1:SKILL.md\n\n---\nname: visual-architecture\ndescription: \"Create deterministic, local-first architecture artifacts from typed JSON: validate specs, render restrained SVG/HTML diagrams, and emit receipts agents can cite.\"\nmetadata:\n  version: \"1.5.1\"\n---\n# Visual Architecture\n\nCreate architecture artifacts with the bundled Python renderer instead of hand-writing SVG. v1.5 adds repo extraction, deterministic auto-layout, PR delta extraction, artifact bundles, quality fail gates, and evidence-backed gallery stories.\n\nUse this when the user needs a trustworthy system map, agent workflow, sequence, data-flow, lifecycle/state diagram, repo-evidence diagram, or PR delta review sketch that should stay local, deterministic, and reviewable.\n\n## Workflow\n\n1. Either extract a starter spec from a repo or create a JSON file with `mode`, `title`, `nodes`, and `edges`.\n   - Supported modes: `architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`, `pr-delta`.\n   - Supported themes: `classic` for documentation, `showcase` for README/release proof images.\n2. Snap intended node positions to the renderer grid mentally before writing them:\n   - horizontal grid: 120px\n   - vertical grid: 80px\n3. For repo-aware drafts, extract and layout first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py extract-repo . --output repo-map.json\npython3 skills/visual-architecture/scripts/render_architecture.py layout repo-map.json repo-map.layout.json --mode architecture\n```\n\n4. Validate first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py validate input.json --json\n```\n\n5. Deliver the final artifact with a receipt:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py deliver input.json output.html --json\n```\n\nUse `.svg` for a static docs artifact or `.html` for a self-contained presentation artifact.\n\nFor PR delta review, compare two specs:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py compare base.json head.json pr-delta.html --spec pr-delta.json --json\n```\n\n6. If `rsvg-convert` is available and you need a bitmap preview, run:\n\n```bash\nrsvg-convert -o output.png output.svg\n```\n\n## JSON Input Structure\n\n```json\n{\n  \"title\": \"Service Map\",\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\n## Node Kinds\n\n- `service`: rounded rectangle\n- `llm`: double-border rounded rectangle\n- `agent`: hexagon\n- `memory`: cylinder\n\nEach node requires:\n- `id`: unique string\n- `label`: primary title\n- `kind`: one of the node kinds above\n- `x`, `y`: grid-aligned center coordinates\n\nOptional:\n- `subtitle`: smaller secondary label\n- `show_grid`: set true to display the editing grid in the exported SVG\n- `theme`: set `showcase` on the top-level spec for dark public-facing artifacts\n- `evidence`: object or list with `source`, optional `line`/`lines`, `commit`, `confidence`, and `note`\n\n## Edge Kinds\n\n- `primary-data`: blue solid arrow\n- `memory-write`: green dashed arrow\n- `control`: slate dashed arrow\n\nEach edge requires:\n- `from`: source node id\n- `to`: target node id\n\nOptional:\n- `label`: rendered on the route with a shielding background rect\n- `source_side`, `target_side`: force edge anchors (`left`, `right`, `top`, `bottom`)\n- `via`: array of orthogonal turn points, each with `x` and `y`\n- `label_segment`: zero-based segment index to place the label on\n- `label_offset`: `[dx, dy]` shift for fine label placement\n\n## Renderer Guarantees\n\n- Validate rejects unsupported node/edge kinds and unknown edge endpoints before rendering\n- Deliver writes the artifact atomically and emits a JSON receipt with SHA-256 hashes\n- Validation receipts include a quality score for spacing, density, route crossings, and visual overlap\n- `extract-repo`, `layout`, `extract-pr`, and `bundle` turn repo evidence into checked artifacts without hand-placing every node\n- `--min-quality` can fail delivery or bundle export when the artifact is not presentation-grade\n- The generated gallery can load spec/receipt JSON and show story steps plus source evidence\n- Evidence badges render as `SRC n` on nodes with source-backed evidence\n- PR delta compare writes added/removed node and edge facts into the receipt\n- Route arrows orthogonally only\n- Render in this order: background, arrows, nodes, labels\n- Keep label shields behind arrow text for readability\n- Stay restrained: clean strokes, no decorative effects, and hide the editing grid unless explicitly requested\n\n## Usage Notes\n\n- Prefer this skill when the user wants architecture diagrams, routing maps, or system relationship visuals.\n- Choose semantic kinds first, then place nodes on the grid, then add only the edges needed to explain flow.\n- Keep diagrams sparse. If a diagram feels crowded, split it into two files instead of forcing a dense composite.\n- Prefer `deliver` for handoff. A passing render without a receipt is a draft.\n- Do not claim repository evidence unless the spec names source files, commits, or confidence explicitly.\n\n## Example\n\nUse `examples/service-map.json` as a generic architecture starting point. Use `examples/agent-runtime.json`, `examples/sequence-cache-miss.json`, `examples/dataflow-analytics.json`, and `examples/lifecycle-agent-task.json` for the non-architecture modes. Use `examples/repo-evidence-map.json` for source-pinned evidence, and `examples/pr-delta-before.json` plus `examples/pr-delta-head.json` for generated PR deltas.\n\nFile v1.5.1:README.md\n\n# visual-architecture\n\n[![Validate](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml/badge.svg)](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml)\n\n**Deterministic, local-first architecture artifacts for agents.**\n\nvisual-architecture turns local repo evidence or typed JSON specs into SVG, self-contained HTML, share cards, receipts, and a generated Pages showcase. The v1.5 contract is stronger: agents can extract a first source-backed spec from a repository, lay it out deterministically, validate quality, and publish a reviewable artifact bundle.\n\nThe wedge against Archify is local-first proof: architecture artifacts that look intentional, cite their sources, explain PR deltas, and remain reproducible from a repo scan or checked JSON.\n\n![Visual Architecture artifact engine](examples/showcase-artifact-engine.svg)\n\n## Visual Gallery\n\nOpen the generated artifact site: **https://leostehlik.github.io/visual-architecture/**\n\nThe gallery is the browsing surface: artifact rail, large diagram stage, story path, receipt quality, share cards, and source evidence viewer. The README stays as the product brief; the repo keeps the JSON specs, SVG/HTML artifacts, and receipts for audit.\n\n## Why It Exists\n\nAgents are good at inventing diagrams and bad at proving what they just drew. visual-architecture gives them a narrow, deterministic path:\n\n1. Author a compact JSON spec.\n2. Validate supported modes, node kinds, edge kinds, endpoints, evidence fields, grid placement, and obvious route hazards.\n3. Deliver SVG or HTML atomically.\n4. Emit a JSON receipt with input/output SHA-256, byte counts, metrics, warnings, and validation result.\n\nThe output stays local and deterministic, but no longer uses one generic box-arrow treatment for every artifact. Architecture, workflow, sequence, data-flow, lifecycle, and PR delta modes now get distinct visual scaffolding.\n\n## Install\n\n### OpenClaw / ClawHub\n\n```bash\nopenclaw skills install visual-architecture\n```\n\n### Manual\n\n```bash\ngit clone https://github.com/LeoStehlik/visual-architecture.git ~/.openclaw/workspace/skills/visual-architecture\n```\n\nFor Codex, Claude Code, OpenCode, or another agent harness, copy this repo or the `SKILL.md` plus `scripts/` and `examples/` into the harness skill directory.\n\n## Quick Start\n\nValidate a spec:\n\n```bash\npython3 scripts/render_architecture.py validate examples/service-map.json --json\n```\n\nRender a static SVG:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/service-map.json examples/service-map.svg --json\n```\n\nDeliver a self-contained HTML artifact:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/agent-runtime.json examples/agent-runtime.html --json\n```\n\nCompare base/head specs for a PR delta artifact:\n\n```bash\npython3 scripts/render_architecture.py compare examples/pr-delta-before.json examples/pr-delta-head.json examples/pr-delta-generated.html --spec examples/pr-delta-generated.json --json\n```\n\nExtract repo evidence, apply layout, generate a bundle, or build the gallery:\n\n```bash\npython3 scripts/render_architecture.py extract-repo . --output examples/visual-architecture-auto.json\npython3 scripts/render_architecture.py layout examples/visual-architecture-auto.json /tmp/laid-out.json --mode architecture\npython3 scripts/render_architecture.py bundle examples/visual-architecture-auto.json /tmp/visual-architecture-bundle --min-quality good\npython3 scripts/render_architecture.py gallery index.html\n```\n\nThe legacy v0.2 command still works:\n\n```bash\npython3 scripts/render_architecture.py examples/service-map.json examples/service-map.svg\n```\n\n## Checked Artifacts\n\nThe checked examples cover service maps, agent workflows, repo evidence, PR deltas, sequence, data-flow, lifecycle, and the dark showcase theme. Browse them through the generated site instead of raw GitHub file views:\n\n- Gallery: https://leostehlik.github.io/visual-architecture/\n- Hero spec: [`examples/showcase-artifact-engine.json`](examples/showcase-artifact-engine.json)\n- Hero receipt: [`examples/showcase-artifact-engine.html.receipt.json`](examples/showcase-artifact-engine.html.receipt.json)\n\nShare-card SVGs are generated beside each example as `*.share-card.svg`.\n\nRun the same local proof gate as CI:\n\n```bash\nmake validate\n```\n\nRegenerate all examples:\n\n```bash\nmake examples\n```\n\n## JSON Model\n\n```json\n{\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"title\": \"Service Map\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\nNode kinds:\n\n- `service` - rounded rectangle\n- `llm` - double-border rounded rectangle\n- `agent` - hexagon\n- `memory` - cylinder\n\nEdge kinds:\n\n- `primary-data` - blue solid arrow\n- `memory-write` - green dashed arrow\n- `control` - slate dashed arrow\n\nSupported modes:\n\n- `architecture` - component maps, services, stores, boundaries\n- `workflow` - agent/tool/process/runbook paths\n- `sequence` - request/API/call lifecycles\n- `dataflow` - pipelines, lineage, stores, sensitive boundaries\n- `lifecycle` - states, retries, waits, terminal outcomes\n- `pr-delta` - review artifacts for base/head architecture changes\n\nThemes:\n\n- `classic` - light documentation artifact, used by default\n- `showcase` - dark README/release artifact for first-screen proof images\n\nEvidence fields can be added to nodes or edges:\n\n```json\n{\n  \"source\": \"services/fraud/client.ts\",\n  \"line\": 42,\n  \"commit\": \"abc1234\",\n  \"confidence\": \"medium\",\n  \"note\": \"Fraud scoring client introduced by this PR.\"\n}\n```\n\nNodes with evidence render a compact `SRC n` badge. Receipts count evidence items and keep PR delta facts separate from ordinary artifact validation.\n\n## Receipt Contract\n\n`deliver` writes `<artifact>.receipt.json` by default. A receipt includes:\n\n- tool/version\n- artifact kind: `svg` or `html`\n- input path, SHA-256, and byte count\n- output path, SHA-256, and byte count\n- validation status, errors, warnings, and metrics\n\nValidation currently checks the shape of the spec, supported modes and semantic kinds, unknown endpoints, evidence field shape, duplicate/shared grid positions, route crossings through unrelated nodes, edge crossings, density, visual overlap, and long labels that are likely to crowd the diagram. Receipts include a quality score so ugly artifacts are visible as defects, not treated as successful output.\n\nStable diagnostic codes are documented in [`docs/diagnostics.md`](docs/diagnostics.md).\n\n## Roadmap\n\nCompleted v1.0 ladder:\n\n- v0.3: public foundation, examples, HTML wrapper, release hygiene\n- v0.4: schemas, validate/deliver receipts, CI proof\n- v0.5: workflow, sequence, data-flow, and lifecycle modes\n- v0.6: source evidence fields, evidence validation, `SRC n` badges, evidence metrics\n- v0.7: base/head PR delta compare command with review receipt\n- v1.0: proof gallery, share-card artifacts, harness notes, GitHub release surface\n\nHarness install/use notes are in [`docs/harnesses.md`](docs/harnesses.md), and short proof demos for OpenClaw, Codex, Claude Code, and OpenCode are in [`docs/harness-demos.md`](docs/harness-demos.md). ClawHub sync checks are in [`docs/clawhub-sync.md`](docs/clawhub-sync.md).\n\nNext high-value work:\n\n- deeper automatic layout per mode, especially sequence/data-flow/lifecycle\n- stronger label clearance and route-quality diagnostics\n- richer language-aware extraction for imports/routes/configuration boundaries\n- PNG export when a portable raster dependency is available\n\n## Repository\n\n```text\nvisual-architecture/\n├── SKILL.md\n├── examples/\n│   ├── *.json\n│   ├── *.svg\n│   ├── *.html\n│   ├── *.receipt.json\n│   └── *.share-card.svg\n├── schemas/\n│   └── *.schema.json\n├── docs/\n│   └── gallery.html\n├── scripts/\n│   └── render_architecture.py\n├── .github/workflows/\n│   └── validate.yml\n├── Makefile\n└── README.md\n```\n\n## Status\n\nv1.0.0 artifact engine foundation: deterministic renderer, schemas, mode-aware validation, delivery receipts, HTML artifacts, source evidence badges, PR delta compare, share cards, gallery, and checked examples.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nFile v1.5.1:_meta.json\n\n{\n  \"ownerId\": \"kn7d3r58cdxk8k0xg6jq6k65gs873c0c\",\n  \"slug\": \"visual-architecture\",\n  \"version\": \"1.5.1\",\n  \"publishedAt\": 1787874043297\n}\n\nFile v1.5.1:CHANGELOG.md\n\n# Changelog\n\n## v1.5.1\n\n- Polish the generated Pages gallery artifact rail so the public showcase no longer exposes a native horizontal scrollbar.\n\n## v1.5.0\n\n- Add `extract-repo` to create a first source-backed architecture spec from local repository structure.\n- Add `layout` for deterministic mode-aware node placement without hand-authored coordinates.\n- Add `extract-pr` to group changed files into a generated PR delta review spec.\n- Add `bundle` to export HTML, SVG, share card, receipt, and bundle manifest together.\n- Add `--min-quality` gates for `deliver` and `bundle`.\n- Add generated repo evidence and PR delta examples to the public gallery.\n\n## v1.4.0\n\n- Add renderer v2 foundations: mode-specific backdrops for architecture, workflow, sequence, data-flow, lifecycle, and PR delta artifacts.\n- Add visual quality scoring to validation receipts for overlap, density, route crossings, spacing, and route complexity.\n- Add story-aware gallery data and an interactive evidence panel that loads checked spec/receipt JSON on GitHub Pages.\n- Add a real visual-architecture case-study artifact with source evidence pointing at the renderer, Makefile, README, and examples.\n- Tighten README/SKILL positioning around Archify-standard presentation, local proof, and source-backed case studies.\n\n## v1.3.0\n\n- Redesign the generated gallery into an interactive artifact viewer.\n- Put the diagram stage, artifact rail, details panel, and source links into one generated Pages surface.\n- Keep the gallery generated from checked JSON examples rather than hand-authored showcase markup.\n\n## v1.2.0\n\n- Add a generated GitHub Pages gallery site as the visual browsing surface.\n- Remove the README gallery tables that pushed visitors into raw GitHub file views.\n- Generate both root `index.html` and `docs/gallery.html` from the local examples.\n\n## v1.1.1\n\n- Repair package metadata after the v1.1.0 ClawHub publish became non-inspectable.\n\n## v1.1.0\n\n- Add a dark `showcase` render theme for README and release artifacts.\n- Add three checked showcase examples for the artifact workflow, repo evidence map, and PR delta review surface.\n- Replace the README first-screen diagram with generated showcase artifacts.\n\n## v1.0.2\n\n- Release metadata repair so GitHub and ClawHub package versions both report the final v1 artifact-engine state cleanly.\n\n## v1.0.0\n\n- Complete the planned product ladder from foundation renderer to artifact engine.\n- Add schema files for architecture, workflow, sequence, data-flow, lifecycle, PR delta, and shared evidence primitives.\n- Add mode-aware validation metrics and examples for all supported diagram modes.\n- Add source evidence fields on nodes/edges with validation and visible `SRC n` node badges.\n- Add `compare` command for base/head PR delta artifacts and receipts.\n- Add static share-card SVG generation and generated proof gallery.\n- Expand CI validation to schemas, every example, generated gallery, and PR delta compare smoke.\n\n## v0.3.0\n\n- Reposition visual-architecture as a local-first architecture artifact engine for agents.\n- Add `validate`, `render`, and `deliver` commands while preserving the old two-argument render command.\n- Add delivery receipts with input/output SHA-256 hashes, byte counts, validation result, warnings, and metrics.\n- Add self-contained HTML output in addition to SVG.\n- Add checked proof examples for service maps, agent runtimes, repo-evidence maps, and PR delta review maps.\n- Expand `make validate` so CI validates every example and proves committed SVGs regenerate byte-for-byte.\n- Update the roadmap toward schema diagnostics, multi-diagram modes, source evidence, PR deltas, and share/export artifacts.\n\nFile v1.5.1:docs/clawhub-sync.md\n\n# ClawHub Sync Checklist\n\nPublish to ClawHub only after the public repo state is green and the installable package is clean.\n\n## Required Checks\n\n```bash\nmake validate\ngrep -RInE \"private-path|private-host|token-placeholder|client-name-placeholder\" README.md SKILL.md CHANGELOG.md docs examples scripts schemas\n```\n\nInstall smoke after publish must confirm:\n\n- `SKILL.md` reports the expected version\n- examples are present\n- `python3 scripts/render_architecture.py validate examples/service-map.json --json` exits 0\n- no generated docs expose private local paths, private hosts, credentials, or internal runtime state\n\n## Current State\n\nGitHub `v1.0.0` is the target public release for the full product ladder. ClawHub sync is allowed only if the publish bundle passes the checks above and the registry accepts the package cleanly.\n\nFile v1.5.1:docs/diagnostics.md\n\n# Diagnostics\n\n`visual-architecture validate --json` and `deliver --json` return stable diagnostic codes. The validator is intentionally local and conservative: it checks authored JSON facts and renderer-safe geometry, not live infrastructure.\n\n## Spec Codes\n\n- `spec.type` - input is not a JSON object\n- `mode.unsupported` - `mode` is not one of the supported diagram modes\n- `title.required` - title is missing or empty\n- `nodes.required` - nodes are missing or empty\n- `edges.type` - edges exists but is not a list\n\n## Node Codes\n\n- `node.type` - node is not an object\n- `node.id.required` - node id is missing or empty\n- `node.id.duplicate` - node id repeats\n- `node.label.required` - node label is missing or empty\n- `node.kind.unsupported` - node kind is not renderer-supported\n- `node.x.required` / `node.y.required` - coordinate is missing or non-numeric\n- `node.x.snapped` / `node.y.snapped` - coordinate will snap to the renderer grid\n- `node.position.shared` - two nodes share one grid position\n\n## Edge Codes\n\n- `edge.type` - edge is not an object\n- `edge.from.unknown` / `edge.to.unknown` - endpoint id does not exist\n- `edge.kind.unsupported` - edge kind is not renderer-supported\n- `edge.label.long` - label may crowd the route\n- `edge.via.type` - via point is not an object\n- `edge.via.x.required` / `edge.via.y.required` - via coordinate is missing or non-numeric\n- `edge.via.x.snapped` / `edge.via.y.snapped` - via coordinate will snap to the renderer grid\n- `edge.route.crosses-node` - an edge route crosses an unrelated node box\n\n## Evidence Codes\n\n- `evidence.type` - evidence is not an object or list\n- `evidence.item.type` - evidence list item is not an object\n- `evidence.source.required` - evidence source is missing\n- `evidence.line.type` - evidence line is not an integer\n- `evidence.lines.type` - evidence lines are not `[start, end]` integers\n- `evidence.commit.type` - evidence commit is not a string\n- `evidence.confidence.unknown` - confidence is not `high`, `medium`, or `low`\n\n## Visual Quality Diagnostics\n\n- `quality.node.overlap` - rendered node boxes overlap or sit too close to be presentation-grade.\n- `quality.node.spacing` - node centers are too close for a clean artifact.\n- `quality.route.crossings` - unrelated edge routes cross and should be rerouted with `via` points.\n- `quality.route.complex` - an edge route has enough turns to become visually noisy.\n- `quality.density.high` - the artifact is dense enough that it should probably be split or narrated as a smaller story.\n\nReceipts expose `validation.metrics.quality.score` and `validation.metrics.quality.rating`. Treat `needs-work` and `poor` as visual defects even when the JSON shape is valid.\n\nFile v1.5.1:docs/harness-demos.md\n\n# Harness Demos\n\nEach harness should prove the same thing: a local JSON spec becomes a checked artifact plus a receipt. Keep the demo small enough to paste into an agent task.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\npython3 ~/.openclaw/workspace/skills/visual-architecture/scripts/render_architecture.py deliver \\\n  ~/.openclaw/workspace/skills/visual-architecture/examples/showcase-visual-architecture-case-study.json \\\n  /tmp/visual-architecture-case-study.html --json\n```\n\n## Codex\n\n```text\nUse the visual-architecture skill. Validate examples/showcase-visual-architecture-case-study.json, deliver HTML, then report the receipt quality score and evidence count.\n```\n\n## Claude Code\n\n```text\nRead SKILL.md, run the validate command against examples/showcase-pr-delta.json, then deliver examples/showcase-pr-delta.html with a receipt.\n```\n\n## OpenCode\n\n```text\nInstall or copy this repo as a local skill, then run make examples and make validate before citing any generated artifact.\n```\n\nA harness demo is not accepted unless it reports the generated receipt path, input/output SHA-256 hashes, quality rating, and evidence count.\n\nFile v1.5.1:docs/harnesses.md\n\n# Harness Notes\n\nvisual-architecture is a plain local skill: JSON in, SVG/HTML/receipt out. It does not need a hosted renderer.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\n```\n\nAsk Francis or another OpenClaw agent to use `visual-architecture` for a bounded architecture, workflow, sequence, data-flow, lifecycle, repo-evidence, or PR delta artifact.\n\n## Codex\n\nCopy this repo into the Codex skill directory or keep it in the target repo and point Codex at `SKILL.md`.\n\nUseful prompt:\n\n```text\nUse visual-architecture to create a source-evidence architecture map for this repo.\nValidate the JSON, deliver HTML, and return the receipt path.\n```\n\n## Claude Code\n\nCopy the skill folder into Claude's local skills directory and keep generated artifacts inside the project. Prefer `deliver` over `render` so Claude has a receipt to cite.\n\n## OpenCode\n\nPlace the repo or skill folder where OpenCode can read `SKILL.md`. Use the same command contract:\n\n```bash\npython3 scripts/render_architecture.py validate input.json --json\npython3 scripts/render_architecture.py deliver input.json output.html --json\n```\n\n## Review Rule\n\nFor public artifacts, scan generated files for private paths, hostnames, tokens, internal context, and accidental client details before release or ClawHub sync.\n\nFile v1.5.1:docs/repo-aware-generation.md\n\n# Repo-Aware Generation\n\n`visual-architecture` can now create a first useful architecture draft from a local repository. The extractor is deliberately conservative: it looks for repo surfaces that are easy to defend with file evidence, then emits a normal JSON spec that can be reviewed and edited.\n\n```bash\npython3 scripts/render_architecture.py extract-repo . --output examples/visual-architecture-auto.json\npython3 scripts/render_architecture.py deliver examples/visual-architecture-auto.json examples/visual-architecture-auto.html --min-quality good --json\n```\n\nFor pull requests, generate a changed-file review surface:\n\n```bash\npython3 scripts/render_architecture.py extract-pr --base origin/master --head HEAD --output examples/pr-delta-extracted.json\n```\n\nFor hand-authored specs, apply deterministic layout before delivery:\n\n```bash\npython3 scripts/render_architecture.py layout input.json output.json --mode architecture --theme showcase\n```\n\nFor release assets, bundle everything together:\n\n```bash\npython3 scripts/render_architecture.py bundle examples/visual-architecture-auto.json /tmp/visual-architecture-bundle --min-quality good\n```\n\nA generated artifact is still a draft. The receipt quality rating, warnings, and evidence list are the review surface.\n\nFile v1.5.1:skill-card.md\n\n## Description:\n\nCreate deterministic, local-first architecture artifacts from typed JSON or language-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[leostehlik](https://clawhub.ai/user/leostehlik)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use this skill to turn local repository evidence or typed JSON specs into reviewable architecture diagrams, PR delta views, workflow maps, sequence diagrams, data-flow diagrams, lifecycle diagrams, and evidence-backed artifact bundles.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Generated HTML, SVG, JSON specs, or receipts may expose private file paths, internal hostnames, client names, or sensitive change metadata.\n\nMitigation: Review generated artifacts before publication and run repo or PR extraction only against repositories intended for summary.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/leostehlik/skills/visual-architecture)\n- [Generated visual gallery](https://leostehlik.github.io/visual-architecture/)\n- [Harness notes](docs/harnesses.md)\n- [Harness demos](docs/harness-demos.md)\n- [Diagnostics](docs/diagnostics.md)\n- [Repo-aware generation](docs/repo-aware-generation.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with JSON specs, shell commands, and generated SVG, HTML, JSON receipt, and bundle file paths]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Produces local deterministic artifacts and receipts; supports validation, delivery, repo extraction, PR delta comparison, bundling, and gallery generation.]\n\n## Skill Version(s):\n\n1.5.1 (source: server release metadata, skill metadata, and changelog)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.5.1:examples/agent-runtime.html.receipt.json\n\n{\n  \"artifactKind\": \"html\",\n  \"generatedAt\": \"2026-08-27T23:37:32.416558+00:00\",\n  \"input\": {\n    \"bytes\": 1925,\n    \"path\": \"examples/agent-runtime.json\",\n    \"sha256\": \"4adc883c50030740dc1416d2fe999302f42c303acc255225babf7376721450d5\"\n  },\n  \"mode\": \"workflow\",\n  \"output\": {\n    \"bytes\": 10841,\n    \"path\": \"examples/agent-runtime.html\",\n    \"sha256\": \"0d614a214b4bda1e196d2306720a089b65c1b48e8dde32125061032f0467e547\"\n  },\n  \"tool\": \"visual-architecture\",\n  \"validation\": {\n    \"errors\": [],\n    \"metrics\": {\n      \"edgeKinds\": [\n        \"control\",\n        \"memory-write\",\n        \"primary-data\"\n      ],\n      \"edges\": 5,\n      \"evidenceItems\": 0,\n      \"mode\": \"workflow\",\n      \"nodeKinds\": [\n        \"agent\",\n        \"memory\",\n        \"service\"\n      ],\n      \"nodes\": 6,\n      \"quality\": {\n        \"checks\": [\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"brief\",\n              \"lessons\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"builder\",\n              \"receipt\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"artifact\",\n              \"validator\"\n            ]\n          }\n        ],\n        \"rating\": \"good\",\n        \"routeCrossings\": 0,\n        \"score\": 76\n      },\n      \"theme\": \"classic\"\n    },\n    \"ok\": true,\n    \"warnings\": []\n  },\n  \"version\": \"1.5.1\"\n}\n\nFile v1.5.1:examples/agent-runtime.json\n\n{\n  \"mode\": \"workflow\",\n  \"title\": \"Agent Runtime Proof Loop\",\n  \"summary\": \"A local agent turns a task brief into a checked artifact with verifier feedback and durable lessons.\",\n  \"show_grid\": false,\n  \"nodes\": [\n    {\n      \"id\": \"brief\",\n      \"label\": \"Task Brief\",\n      \"subtitle\": \"Scoped ACs\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"builder\",\n      \"label\": \"Builder Agent\",\n      \"subtitle\": \"Implements slice\",\n      \"kind\": \"agent\",\n      \"x\": 360,\n      \"y\": 160\n    },\n    {\n      \"id\": \"artifact\",\n      \"label\": \"Artifact\",\n      \"subtitle\": \"SVG or HTML\",\n      \"kind\": \"service\",\n      \"x\": 600,\n      \"y\": 160\n    },\n    {\n      \"id\": \"validator\",\n      \"label\": \"Validator\",\n      \"subtitle\": \"Checks contract\",\n      \"kind\": \"agent\",\n      \"x\": 600,\n      \"y\": 320\n    },\n    {\n      \"id\": \"receipt\",\n      \"label\": \"Receipt\",\n      \"subtitle\": \"Hashes + metrics\",\n      \"kind\": \"memory\",\n      \"x\": 360,\n      \"y\": 320\n    },\n    {\n      \"id\": \"lessons\",\n      \"label\": \"Lessons\",\n      \"subtitle\": \"Future corrections\",\n      \"kind\": \"memory\",\n      \"x\": 120,\n      \"y\": 320\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"brief\",\n      \"to\": \"builder\",\n      \"kind\": \"control\",\n      \"label\": \"execute\",\n      \"label_offset\": [0, -28]\n    },\n    {\n      \"from\": \"builder\",\n      \"to\": \"artifact\",\n      \"kind\": \"primary-data\",\n      \"label\": \"deliver\",\n      \"label_offset\": [0, -28]\n    },\n    {\n      \"from\": \"artifact\",\n      \"to\": \"validator\",\n      \"kind\": \"control\",\n      \"label\": \"validate\"\n    },\n    {\n      \"from\": \"validator\",\n      \"to\": \"receipt\",\n      \"kind\": \"memory-write\",\n      \"label\": \"proof\",\n      \"source_side\": \"left\",\n      \"target_side\": \"right\"\n    },\n    {\n      \"from\": \"receipt\",\n      \"to\": \"lessons\",\n      \"kind\": \"memory-write\",\n      \"label\": \"capture\",\n      \"source_side\": \"left\",\n      \"target_side\": \"right\"\n    }\n  ]\n}\n\nArchive v1.4.0: 105 files, 147978 bytes\n\nFiles: CHANGELOG.md (3039b), docs/clawhub-sync.md (833b), docs/diagnostics.md (2698b), docs/gallery.html (29487b), docs/harness-demos.md (1158b), docs/harnesses.md (1301b), examples/agent-runtime.html (10841b), examples/agent-runtime.html.receipt.json (1570b), examples/agent-runtime.json (1925b), examples/agent-runtime.share-card.svg (1567b), examples/agent-runtime.svg (8193b), examples/agent-runtime.svg.receipt.json (1567b), examples/dataflow-analytics.html (11437b), examples/dataflow-analytics.html.receipt.json (1394b), examples/dataflow-analytics.json (1420b), examples/dataflow-analytics.share-card.svg (1566b), examples/dataflow-analytics.svg (8760b), examples/dataflow-analytics.svg.receipt.json (1391b), examples/lifecycle-agent-task.html (12724b), examples/lifecycle-agent-task.html.receipt.json (1393b), examples/lifecycle-agent-task.json (1538b), examples/lifecycle-agent-task.share-card.svg (1559b), examples/lifecycle-agent-task.svg (10007b), examples/lifecycle-agent-task.svg.receipt.json (1391b), examples/pr-delta-before.html (6875b), examples/pr-delta-before.html.receipt.json (980b), examples/pr-delta-before.json (567b), examples/pr-delta-before.share-card.svg (1492b), examples/pr-delta-before.svg (4400b), examples/pr-delta-before.svg.receipt.json (978b), examples/pr-delta-generated.html (11668b), examples/pr-delta-generated.html.receipt.json (2059b), examples/pr-delta-generated.json (2103b), examples/pr-delta-generated.share-card.svg (1499b), examples/pr-delta-generated.svg (9014b), examples/pr-delta-generated.svg.receipt.json (1381b), examples/pr-delta-head.html (8168b), examples/pr-delta-head.html.receipt.json (995b), examples/pr-delta-head.json (855b), examples/pr-delta-head.share-card.svg (1497b), examples/pr-delta-head.svg (5640b), examples/pr-delta-head.svg.receipt.json (993b), examples/pr-delta-review.html (12217b), examples/pr-delta-review.html.receipt.json (1378b), examples/pr-delta-review.json (2301b), examples/pr-delta-review.share-card.svg (1543b), examples/pr-delta-review.svg (9539b), examples/pr-delta-review.svg.receipt.json (1375b), examples/repo-evidence-map.html (13032b), examples/repo-evidence-map.html.receipt.json (1393b), examples/repo-evidence-map.json (2760b), examples/repo-evidence-map.share-card.svg (1575b), examples/repo-evidence-map.svg (10290b), examples/repo-evidence-map.svg.receipt.json (1391b), examples/sequence-cache-miss.html (11239b), examples/sequence-cache-miss.html.receipt.json (1168b), examples/sequence-cache-miss.json (1391b), examples/sequence-cache-miss.share-card.svg (1560b), examples/sequence-cache-miss.svg (8580b), examples/sequence-cache-miss.svg.receipt.json (1165b), examples/service-map.html (10643b), examples/service-map.html.receipt.json (1393b), examples/service-map.json (1745b), examples/service-map.share-card.svg (1467b), examples/service-map.svg (8061b), examples/service-map.svg.receipt.json (1390b), examples/showcase-artifact-engine.html (11653b), examples/showcase-artifact-engine.html.receipt.json (1044b), examples/showcase-artifact-engine.json (2270b), examples/showcase-artifact-engine.share-card.svg (1595b), examples/showcase-artifact-engine.svg (8935b), examples/showcase-artifact-engine.svg.receipt.json (1041b), examples/showcase-pr-delta.html (13252b), examples/showcase-pr-delta.html.receipt.json (1396b), examples/showcase-pr-delta.json (2427b), examples/showcase-pr-delta.share-card.svg (1587b), examples/showcase-pr-delta.svg (10476b), examples/showcase-pr-delta.svg.receipt.json (1394b), examples/showcase-repo-evidence.html (13341b), examples/showcase-repo-evidence.html.receipt.json (1048b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: visual-architecture\ndescription: \"Create deterministic, local-first architecture artifacts from typed JSON: validate specs, render restrained SVG/HTML diagrams, and emit receipts agents can cite.\"\nmetadata:\n  version: \"1.4.0\"\n---\n# Visual Architecture\n\nCreate architecture artifacts with the bundled Python renderer instead of hand-writing SVG. v1.4 adds mode-specific visual grammar, quality scoring, story-aware galleries, and an evidence viewer for public case studies.\n\nUse this when the user needs a trustworthy system map, agent workflow, sequence, data-flow, lifecycle/state diagram, repo-evidence diagram, or PR delta review sketch that should stay local, deterministic, and reviewable.\n\n## Workflow\n\n1. Create a JSON file with `mode`, `title`, `nodes`, and `edges`.\n   - Supported modes: `architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`, `pr-delta`.\n   - Supported themes: `classic` for documentation, `showcase` for README/release proof images.\n2. Snap intended node positions to the renderer grid mentally before writing them:\n   - horizontal grid: 120px\n   - vertical grid: 80px\n3. Validate first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py validate input.json --json\n```\n\n4. Deliver the final artifact with a receipt:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py deliver input.json output.html --json\n```\n\nUse `.svg` for a static docs artifact or `.html` for a self-contained presentation artifact.\n\nFor PR delta review, compare two specs:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py compare base.json head.json pr-delta.html --spec pr-delta.json --json\n```\n\n5. If `rsvg-convert` is available and you need a bitmap preview, run:\n\n```bash\nrsvg-convert -o output.png output.svg\n```\n\n## JSON Input Structure\n\n```json\n{\n  \"title\": \"Service Map\",\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\n## Node Kinds\n\n- `service`: rounded rectangle\n- `llm`: double-border rounded rectangle\n- `agent`: hexagon\n- `memory`: cylinder\n\nEach node requires:\n- `id`: unique string\n- `label`: primary title\n- `kind`: one of the node kinds above\n- `x`, `y`: grid-aligned center coordinates\n\nOptional:\n- `subtitle`: smaller secondary label\n- `show_grid`: set true to display the editing grid in the exported SVG\n- `theme`: set `showcase` on the top-level spec for dark public-facing artifacts\n- `evidence`: object or list with `source`, optional `line`/`lines`, `commit`, `confidence`, and `note`\n\n## Edge Kinds\n\n- `primary-data`: blue solid arrow\n- `memory-write`: green dashed arrow\n- `control`: slate dashed arrow\n\nEach edge requires:\n- `from`: source node id\n- `to`: target node id\n\nOptional:\n- `label`: rendered on the route with a shielding background rect\n- `source_side`, `target_side`: force edge anchors (`left`, `right`, `top`, `bottom`)\n- `via`: array of orthogonal turn points, each with `x` and `y`\n- `label_segment`: zero-based segment index to place the label on\n- `label_offset`: `[dx, dy]` shift for fine label placement\n\n## Renderer Guarantees\n\n- Validate rejects unsupported node/edge kinds and unknown edge endpoints before rendering\n- Deliver writes the artifact atomically and emits a JSON receipt with SHA-256 hashes\n- Validation receipts include a quality score for spacing, density, route crossings, and visual overlap\n- The generated gallery can load spec/receipt JSON and show story steps plus source evidence\n- Evidence badges render as `SRC n` on nodes with source-backed evidence\n- PR delta compare writes added/removed node and edge facts into the receipt\n- Route arrows orthogonally only\n- Render in this order: background, arrows, nodes, labels\n- Keep label shields behind arrow text for readability\n- Stay restrained: clean strokes, no decorative effects, and hide the editing grid unless explicitly requested\n\n## Usage Notes\n\n- Prefer this skill when the user wants architecture diagrams, routing maps, or system relationship visuals.\n- Choose semantic kinds first, then place nodes on the grid, then add only the edges needed to explain flow.\n- Keep diagrams sparse. If a diagram feels crowded, split it into two files instead of forcing a dense composite.\n- Prefer `deliver` for handoff. A passing render without a receipt is a draft.\n- Do not claim repository evidence unless the spec names source files, commits, or confidence explicitly.\n\n## Example\n\nUse `examples/service-map.json` as a generic architecture starting point. Use `examples/agent-runtime.json`, `examples/sequence-cache-miss.json`, `examples/dataflow-analytics.json`, and `examples/lifecycle-agent-task.json` for the non-architecture modes. Use `examples/repo-evidence-map.json` for source-pinned evidence, and `examples/pr-delta-before.json` plus `examples/pr-delta-head.json` for generated PR deltas.\n\nFile v1.4.0:README.md\n\n# visual-architecture\n\n[![Validate](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml/badge.svg)](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml)\n\n**Deterministic, local-first architecture artifacts for agents.**\n\nvisual-architecture turns small typed JSON specs into SVG, self-contained HTML, share cards, receipts, and a generated Pages showcase. The v1.4 contract is stronger: each mode gets its own visual grammar, validation scores readability, and the gallery can show story steps, receipts, and source evidence instead of dumping visitors into raw files.\n\nThe wedge against Archify is local-first proof: architecture artifacts that look intentional, cite their sources, explain PR deltas, and remain reproducible from checked JSON.\n\n![Visual Architecture artifact engine](examples/showcase-artifact-engine.svg)\n\n## Visual Gallery\n\nOpen the generated artifact site: **https://leostehlik.github.io/visual-architecture/**\n\nThe gallery is the browsing surface: artifact rail, large diagram stage, story path, receipt quality, share cards, and source evidence viewer. The README stays as the product brief; the repo keeps the JSON specs, SVG/HTML artifacts, and receipts for audit.\n\n## Why It Exists\n\nAgents are good at inventing diagrams and bad at proving what they just drew. visual-architecture gives them a narrow, deterministic path:\n\n1. Author a compact JSON spec.\n2. Validate supported modes, node kinds, edge kinds, endpoints, evidence fields, grid placement, and obvious route hazards.\n3. Deliver SVG or HTML atomically.\n4. Emit a JSON receipt with input/output SHA-256, byte counts, metrics, warnings, and validation result.\n\nThe output stays local and deterministic, but no longer uses one generic box-arrow treatment for every artifact. Architecture, workflow, sequence, data-flow, lifecycle, and PR delta modes now get distinct visual scaffolding.\n\n## Install\n\n### OpenClaw / ClawHub\n\n```bash\nopenclaw skills install visual-architecture\n```\n\n### Manual\n\n```bash\ngit clone https://github.com/LeoStehlik/visual-architecture.git ~/.openclaw/workspace/skills/visual-architecture\n```\n\nFor Codex, Claude Code, OpenCode, or another agent harness, copy this repo or the `SKILL.md` plus `scripts/` and `examples/` into the harness skill directory.\n\n## Quick Start\n\nValidate a spec:\n\n```bash\npython3 scripts/render_architecture.py validate examples/service-map.json --json\n```\n\nRender a static SVG:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/service-map.json examples/service-map.svg --json\n```\n\nDeliver a self-contained HTML artifact:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/agent-runtime.json examples/agent-runtime.html --json\n```\n\nCompare base/head specs for a PR delta artifact:\n\n```bash\npython3 scripts/render_architecture.py compare examples/pr-delta-before.json examples/pr-delta-head.json examples/pr-delta-generated.html --spec examples/pr-delta-generated.json --json\n```\n\nGenerate a static share card or gallery site:\n\n```bash\npython3 scripts/render_architecture.py share-card examples/repo-evidence-map.json examples/repo-evidence-map.share-card.svg\npython3 scripts/render_architecture.py gallery index.html\n```\n\nThe legacy v0.2 command still works:\n\n```bash\npython3 scripts/render_architecture.py examples/service-map.json examples/service-map.svg\n```\n\n## Checked Artifacts\n\nThe checked examples cover service maps, agent workflows, repo evidence, PR deltas, sequence, data-flow, lifecycle, and the dark showcase theme. Browse them through the generated site instead of raw GitHub file views:\n\n- Gallery: https://leostehlik.github.io/visual-architecture/\n- Hero spec: [`examples/showcase-artifact-engine.json`](examples/showcase-artifact-engine.json)\n- Hero receipt: [`examples/showcase-artifact-engine.html.receipt.json`](examples/showcase-artifact-engine.html.receipt.json)\n\nShare-card SVGs are generated beside each example as `*.share-card.svg`.\n\nRun the same local proof gate as CI:\n\n```bash\nmake validate\n```\n\nRegenerate all examples:\n\n```bash\nmake examples\n```\n\n## JSON Model\n\n```json\n{\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"title\": \"Service Map\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\nNode kinds:\n\n- `service` - rounded rectangle\n- `llm` - double-border rounded rectangle\n- `agent` - hexagon\n- `memory` - cylinder\n\nEdge kinds:\n\n- `primary-data` - blue solid arrow\n- `memory-write` - green dashed arrow\n- `control` - slate dashed arrow\n\nSupported modes:\n\n- `architecture` - component maps, services, stores, boundaries\n- `workflow` - agent/tool/process/runbook paths\n- `sequence` - request/API/call lifecycles\n- `dataflow` - pipelines, lineage, stores, sensitive boundaries\n- `lifecycle` - states, retries, waits, terminal outcomes\n- `pr-delta` - review artifacts for base/head architecture changes\n\nThemes:\n\n- `classic` - light documentation artifact, used by default\n- `showcase` - dark README/release artifact for first-screen proof images\n\nEvidence fields can be added to nodes or edges:\n\n```json\n{\n  \"source\": \"services/fraud/client.ts\",\n  \"line\": 42,\n  \"commit\": \"abc1234\",\n  \"confidence\": \"medium\",\n  \"note\": \"Fraud scoring client introduced by this PR.\"\n}\n```\n\nNodes with evidence render a compact `SRC n` badge. Receipts count evidence items and keep PR delta facts separate from ordinary artifact validation.\n\n## Receipt Contract\n\n`deliver` writes `<artifact>.receipt.json` by default. A receipt includes:\n\n- tool/version\n- artifact kind: `svg` or `html`\n- input path, SHA-256, and byte count\n- output path, SHA-256, and byte count\n- validation status, errors, warnings, and metrics\n\nValidation currently checks the shape of the spec, supported modes and semantic kinds, unknown endpoints, evidence field shape, duplicate/shared grid positions, route crossings through unrelated nodes, edge crossings, density, visual overlap, and long labels that are likely to crowd the diagram. Receipts include a quality score so ugly artifacts are visible as defects, not treated as successful output.\n\nStable diagnostic codes are documented in [`docs/diagnostics.md`](docs/diagnostics.md).\n\n## Roadmap\n\nCompleted v1.0 ladder:\n\n- v0.3: public foundation, examples, HTML wrapper, release hygiene\n- v0.4: schemas, validate/deliver receipts, CI proof\n- v0.5: workflow, sequence, data-flow, and lifecycle modes\n- v0.6: source evidence fields, evidence validation, `SRC n` badges, evidence metrics\n- v0.7: base/head PR delta compare command with review receipt\n- v1.0: proof gallery, share-card artifacts, harness notes, GitHub release surface\n\nHarness install/use notes are in [`docs/harnesses.md`](docs/harnesses.md), and short proof demos for OpenClaw, Codex, Claude Code, and OpenCode are in [`docs/harness-demos.md`](docs/harness-demos.md). ClawHub sync checks are in [`docs/clawhub-sync.md`](docs/clawhub-sync.md).\n\nNext high-value work:\n\n- deeper automatic layout per mode, especially sequence/data-flow/lifecycle\n- stronger label clearance and route-quality diagnostics\n- extractor-assisted source evidence instead of hand-authored file/line evidence\n- PNG export when a portable raster dependency is available\n\n## Repository\n\n```text\nvisual-architecture/\n├── SKILL.md\n├── examples/\n│   ├── *.json\n│   ├── *.svg\n│   ├── *.html\n│   ├── *.receipt.json\n│   └── *.share-card.svg\n├── schemas/\n│   └── *.schema.json\n├── docs/\n│   └── gallery.html\n├── scripts/\n│   └── render_architecture.py\n├── .github/workflows/\n│   └── validate.yml\n├── Makefile\n└── README.md\n```\n\n## Status\n\nv1.0.0 artifact engine foundation: deterministic renderer, schemas, mode-aware validation, delivery receipts, HTML artifacts, source evidence badges, PR delta compare, share cards, gallery, and checked examples.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n\nFile v1.4.0:_meta.json\n\n{\n  \"ownerId\": \"kn7d3r58cdxk8k0xg6jq6k65gs873c0c\",\n  \"slug\": \"visual-architecture\",\n  \"version\": \"1.4.0\",\n  \"publishedAt\": 1787872104155\n}\n\nFile v1.4.0:CHANGELOG.md\n\n# Changelog\n\n## v1.4.0\n\n- Add renderer v2 foundations: mode-specific backdrops for architecture, workflow, sequence, data-flow, lifecycle, and PR delta artifacts.\n- Add visual quality scoring to validation receipts for overlap, density, route crossings, spacing, and route complexity.\n- Add story-aware gallery data and an interactive evidence panel that loads checked spec/receipt JSON on GitHub Pages.\n- Add a real visual-architecture case-study artifact with source evidence pointing at the renderer, Makefile, README, and examples.\n- Tighten README/SKILL positioning around Archify-standard presentation, local proof, and source-backed case studies.\n\n## v1.3.0\n\n- Redesign the generated gallery into an interactive artifact viewer.\n- Put the diagram stage, artifact rail, details panel, and source links into one generated Pages surface.\n- Keep the gallery generated from checked JSON examples rather than hand-authored showcase markup.\n\n## v1.2.0\n\n- Add a generated GitHub Pages gallery site as the visual browsing surface.\n- Remove the README gallery tables that pushed visitors into raw GitHub file views.\n- Generate both root `index.html` and `docs/gallery.html` from the local examples.\n\n## v1.1.1\n\n- Repair package metadata after the v1.1.0 ClawHub publish became non-inspectable.\n\n## v1.1.0\n\n- Add a dark `showcase` render theme for README and release artifacts.\n- Add three checked showcase examples for the artifact workflow, repo evidence map, and PR delta review surface.\n- Replace the README first-screen diagram with generated showcase artifacts.\n\n## v1.0.2\n\n- Release metadata repair so GitHub and ClawHub package versions both report the final v1 artifact-engine state cleanly.\n\n## v1.0.0\n\n- Complete the planned product ladder from foundation renderer to artifact engine.\n- Add schema files for architecture, workflow, sequence, data-flow, lifecycle, PR delta, and shared evidence primitives.\n- Add mode-aware validation metrics and examples for all supported diagram modes.\n- Add source evidence fields on nodes/edges with validation and visible `SRC n` node badges.\n- Add `compare` command for base/head PR delta artifacts and receipts.\n- Add static share-card SVG generation and generated proof gallery.\n- Expand CI validation to schemas, every example, generated gallery, and PR delta compare smoke.\n\n## v0.3.0\n\n- Reposition visual-architecture as a local-first architecture artifact engine for agents.\n- Add `validate`, `render`, and `deliver` commands while preserving the old two-argument render command.\n- Add delivery receipts with input/output SHA-256 hashes, byte counts, validation result, warnings, and metrics.\n- Add self-contained HTML output in addition to SVG.\n- Add checked proof examples for service maps, agent runtimes, repo-evidence maps, and PR delta review maps.\n- Expand `make validate` so CI validates every example and proves committed SVGs regenerate byte-for-byte.\n- Update the roadmap toward schema diagnostics, multi-diagram modes, source evidence, PR deltas, and share/export artifacts.\n\nFile v1.4.0:docs/clawhub-sync.md\n\n# ClawHub Sync Checklist\n\nPublish to ClawHub only after the public repo state is green and the installable package is clean.\n\n## Required Checks\n\n```bash\nmake validate\ngrep -RInE \"private-path|private-host|token-placeholder|client-name-placeholder\" README.md SKILL.md CHANGELOG.md docs examples scripts schemas\n```\n\nInstall smoke after publish must confirm:\n\n- `SKILL.md` reports the expected version\n- examples are present\n- `python3 scripts/render_architecture.py validate examples/service-map.json --json` exits 0\n- no generated docs expose private local paths, private hosts, credentials, or internal runtime state\n\n## Current State\n\nGitHub `v1.0.0` is the target public release for the full product ladder. ClawHub sync is allowed only if the publish bundle passes the checks above and the registry accepts the package cleanly.\n\nFile v1.4.0:docs/diagnostics.md\n\n# Diagnostics\n\n`visual-architecture validate --json` and `deliver --json` return stable diagnostic codes. The validator is intentionally local and conservative: it checks authored JSON facts and renderer-safe geometry, not live infrastructure.\n\n## Spec Codes\n\n- `spec.type` - input is not a JSON object\n- `mode.unsupported` - `mode` is not one of the supported diagram modes\n- `title.required` - title is missing or empty\n- `nodes.required` - nodes are missing or empty\n- `edges.type` - edges exists but is not a list\n\n## Node Codes\n\n- `node.type` - node is not an object\n- `node.id.required` - node id is missing or empty\n- `node.id.duplicate` - node id repeats\n- `node.label.required` - node label is missing or empty\n- `node.kind.unsupported` - node kind is not renderer-supported\n- `node.x.required` / `node.y.required` - coordinate is missing or non-numeric\n- `node.x.snapped` / `node.y.snapped` - coordinate will snap to the renderer grid\n- `node.position.shared` - two nodes share one grid position\n\n## Edge Codes\n\n- `edge.type` - edge is not an object\n- `edge.from.unknown` / `edge.to.unknown` - endpoint id does not exist\n- `edge.kind.unsupported` - edge kind is not renderer-supported\n- `edge.label.long` - label may crowd the route\n- `edge.via.type` - via point is not an object\n- `edge.via.x.required` / `edge.via.y.required` - via coordinate is missing or non-numeric\n- `edge.via.x.snapped` / `edge.via.y.snapped` - via coordinate will snap to the renderer grid\n- `edge.route.crosses-node` - an edge route crosses an unrelated node box\n\n## Evidence Codes\n\n- `evidence.type` - evidence is not an object or list\n- `evidence.item.type` - evidence list item is not an object\n- `evidence.source.required` - evidence source is missing\n- `evidence.line.type` - evidence line is not an integer\n- `evidence.lines.type` - evidence lines are not `[start, end]` integers\n- `evidence.commit.type` - evidence commit is not a string\n- `evidence.confidence.unknown` - confidence is not `high`, `medium`, or `low`\n\n## Visual Quality Diagnostics\n\n- `quality.node.overlap` - rendered node boxes overlap or sit too close to be presentation-grade.\n- `quality.node.spacing` - node centers are too close for a clean artifact.\n- `quality.route.crossings` - unrelated edge routes cross and should be rerouted with `via` points.\n- `quality.route.complex` - an edge route has enough turns to become visually noisy.\n- `quality.density.high` - the artifact is dense enough that it should probably be split or narrated as a smaller story.\n\nReceipts expose `validation.metrics.quality.score` and `validation.metrics.quality.rating`. Treat `needs-work` and `poor` as visual defects even when the JSON shape is valid.\n\nFile v1.4.0:docs/harness-demos.md\n\n# Harness Demos\n\nEach harness should prove the same thing: a local JSON spec becomes a checked artifact plus a receipt. Keep the demo small enough to paste into an agent task.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\npython3 ~/.openclaw/workspace/skills/visual-architecture/scripts/render_architecture.py deliver \\\n  ~/.openclaw/workspace/skills/visual-architecture/examples/showcase-visual-architecture-case-study.json \\\n  /tmp/visual-architecture-case-study.html --json\n```\n\n## Codex\n\n```text\nUse the visual-architecture skill. Validate examples/showcase-visual-architecture-case-study.json, deliver HTML, then report the receipt quality score and evidence count.\n```\n\n## Claude Code\n\n```text\nRead SKILL.md, run the validate command against examples/showcase-pr-delta.json, then deliver examples/showcase-pr-delta.html with a receipt.\n```\n\n## OpenCode\n\n```text\nInstall or copy this repo as a local skill, then run make examples and make validate before citing any generated artifact.\n```\n\nA harness demo is not accepted unless it reports the generated receipt path, input/output SHA-256 hashes, quality rating, and evidence count.\n\nFile v1.4.0:docs/harnesses.md\n\n# Harness Notes\n\nvisual-architecture is a plain local skill: JSON in, SVG/HTML/receipt out. It does not need a hosted renderer.\n\n## OpenClaw\n\n```bash\nopenclaw skills install visual-architecture\n```\n\nAsk Francis or another OpenClaw agent to use `visual-architecture` for a bounded architecture, workflow, sequence, data-flow, lifecycle, repo-evidence, or PR delta artifact.\n\n## Codex\n\nCopy this repo into the Codex skill directory or keep it in the target repo and point Codex at `SKILL.md`.\n\nUseful prompt:\n\n```text\nUse visual-architecture to create a source-evidence architecture map for this repo.\nValidate the JSON, deliver HTML, and return the receipt path.\n```\n\n## Claude Code\n\nCopy the skill folder into Claude's local skills directory and keep generated artifacts inside the project. Prefer `deliver` over `render` so Claude has a receipt to cite.\n\n## OpenCode\n\nPlace the repo or skill folder where OpenCode can read `SKILL.md`. Use the same command contract:\n\n```bash\npython3 scripts/render_architecture.py validate input.json --json\npython3 scripts/render_architecture.py deliver input.json output.html --json\n```\n\n## Review Rule\n\nFor public artifacts, scan generated files for private paths, hostnames, tokens, internal context, and accidental client details before release or ClawHub sync.\n\nFile v1.4.0:skill-card.md\n\n## Description:\n\nCreate deterministic, local-first architecture artifacts from typed JSON: validate specs, render restrained SVG/HTML diagrams, and emit receipts agents can cite.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[leostehlik](https://clawhub.ai/user/leostehlik)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers and engineers use this skill to turn typed JSON specs into local, deterministic architecture, workflow, sequence, data-flow, lifecycle, repo-evidence, and PR delta artifacts with receipts that agents can cite.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Generated architecture artifacts and receipts may expose private paths, hostnames, client names, or other sensitive project details if the input spec includes them.\n\nMitigation: Review specs, evidence fields, rendered artifacts, and receipt JSON before publishing or sharing externally.\n\n## Reference(s):\n\n- [ClawHub Skill Page](https://clawhub.ai/leostehlik/skills/visual-architecture)\n- [Generated Visual Gallery](https://leostehlik.github.io/visual-architecture/)\n- [GitHub Repository](https://github.com/LeoStehlik/visual-architecture.git)\n- [Diagnostics](docs/diagnostics.md)\n- [Harness Notes](docs/harnesses.md)\n- [Harness Demos](docs/harness-demos.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with JSON specs and shell command examples; the bundled renderer produces SVG, self-contained HTML, share-card SVG, and JSON receipt files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Local deterministic rendering; validates typed JSON specs and emits SHA-256 receipt metadata for delivered artifacts.]\n\n## Skill Version(s):\n\n1.4.0 (source: frontmatter, changelog, release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.4.0:examples/agent-runtime.html.receipt.json\n\n{\n  \"artifactKind\": \"html\",\n  \"generatedAt\": \"2026-08-27T23:03:17.555340+00:00\",\n  \"input\": {\n    \"bytes\": 1925,\n    \"path\": \"examples/agent-runtime.json\",\n    \"sha256\": \"4adc883c50030740dc1416d2fe999302f42c303acc255225babf7376721450d5\"\n  },\n  \"mode\": \"workflow\",\n  \"output\": {\n    \"bytes\": 10841,\n    \"path\": \"examples/agent-runtime.html\",\n    \"sha256\": \"0d614a214b4bda1e196d2306720a089b65c1b48e8dde32125061032f0467e547\"\n  },\n  \"tool\": \"visual-architecture\",\n  \"validation\": {\n    \"errors\": [],\n    \"metrics\": {\n      \"edgeKinds\": [\n        \"control\",\n        \"memory-write\",\n        \"primary-data\"\n      ],\n      \"edges\": 5,\n      \"evidenceItems\": 0,\n      \"mode\": \"workflow\",\n      \"nodeKinds\": [\n        \"agent\",\n        \"memory\",\n        \"service\"\n      ],\n      \"nodes\": 6,\n      \"quality\": {\n        \"checks\": [\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"brief\",\n              \"lessons\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"builder\",\n              \"receipt\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"artifact\",\n              \"validator\"\n            ]\n          }\n        ],\n        \"rating\": \"good\",\n        \"routeCrossings\": 0,\n        \"score\": 76\n      },\n      \"theme\": \"classic\"\n    },\n    \"ok\": true,\n    \"warnings\": []\n  },\n  \"version\": \"1.4.0\"\n}\n\nFile v1.4.0:examples/agent-runtime.json\n\n{\n  \"mode\": \"workflow\",\n  \"title\": \"Agent Runtime Proof Loop\",\n  \"summary\": \"A local agent turns a task brief into a checked artifact with verifier feedback and durable lessons.\",\n  \"show_grid\": false,\n  \"nodes\": [\n    {\n      \"id\": \"brief\",\n      \"label\": \"Task Brief\",\n      \"subtitle\": \"Scoped ACs\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"builder\",\n      \"label\": \"Builder Agent\",\n      \"subtitle\": \"Implements slice\",\n      \"kind\": \"agent\",\n      \"x\": 360,\n      \"y\": 160\n    },\n    {\n      \"id\": \"artifact\",\n      \"label\": \"Artifact\",\n      \"subtitle\": \"SVG or HTML\",\n      \"kind\": \"service\",\n      \"x\": 600,\n      \"y\": 160\n    },\n    {\n      \"id\": \"validator\",\n      \"label\": \"Validator\",\n      \"subtitle\": \"Checks contract\",\n      \"kind\": \"agent\",\n      \"x\": 600,\n      \"y\": 320\n    },\n    {\n      \"id\": \"receipt\",\n      \"label\": \"Receipt\",\n      \"subtitle\": \"Hashes + metrics\",\n      \"kind\": \"memory\",\n      \"x\": 360,\n      \"y\": 320\n    },\n    {\n      \"id\": \"lessons\",\n      \"label\": \"Lessons\",\n      \"subtitle\": \"Future corrections\",\n      \"kind\": \"memory\",\n      \"x\": 120,\n      \"y\": 320\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"brief\",\n      \"to\": \"builder\",\n      \"kind\": \"control\",\n      \"label\": \"execute\",\n      \"label_offset\": [0, -28]\n    },\n    {\n      \"from\": \"builder\",\n      \"to\": \"artifact\",\n      \"kind\": \"primary-data\",\n      \"label\": \"deliver\",\n      \"label_offset\": [0, -28]\n    },\n    {\n      \"from\": \"artifact\",\n      \"to\": \"validator\",\n      \"kind\": \"control\",\n      \"label\": \"validate\"\n    },\n    {\n      \"from\": \"validator\",\n      \"to\": \"receipt\",\n      \"kind\": \"memory-write\",\n      \"label\": \"proof\",\n      \"source_side\": \"left\",\n      \"target_side\": \"right\"\n    },\n    {\n      \"from\": \"receipt\",\n      \"to\": \"lessons\",\n      \"kind\": \"memory-write\",\n      \"label\": \"capture\",\n      \"source_side\": \"left\",\n      \"target_side\": \"right\"\n    }\n  ]\n}\n\nFile v1.4.0:examples/agent-runtime.svg.receipt.json\n\n{\n  \"artifactKind\": \"svg\",\n  \"generatedAt\": \"2026-08-27T23:03:17.513317+00:00\",\n  \"input\": {\n    \"bytes\": 1925,\n    \"path\": \"examples/agent-runtime.json\",\n    \"sha256\": \"4adc883c50030740dc1416d2fe999302f42c303acc255225babf7376721450d5\"\n  },\n  \"mode\": \"workflow\",\n  \"output\": {\n    \"bytes\": 8193,\n    \"path\": \"examples/agent-runtime.svg\",\n    \"sha256\": \"3deea21deb53bf411b13cc1c963f8c4588c4b838e9792b86b8346aaf6d42bedd\"\n  },\n  \"tool\": \"visual-architecture\",\n  \"validation\": {\n    \"errors\": [],\n    \"metrics\": {\n      \"edgeKinds\": [\n        \"control\",\n        \"memory-write\",\n        \"primary-data\"\n      ],\n      \"edges\": 5,\n      \"evidenceItems\": 0,\n      \"mode\": \"workflow\",\n      \"nodeKinds\": [\n        \"agent\",\n        \"memory\",\n        \"service\"\n      ],\n      \"nodes\": 6,\n      \"quality\": {\n        \"checks\": [\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"brief\",\n              \"lessons\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"builder\",\n              \"receipt\"\n            ]\n          },\n          {\n            \"code\": \"quality.node.spacing\",\n            \"level\": \"warn\",\n            \"subjects\": [\n              \"artifact\",\n              \"validator\"\n            ]\n          }\n        ],\n        \"rating\": \"good\",\n        \"routeCrossings\": 0,\n        \"score\": 76\n      },\n      \"theme\": \"classic\"\n    },\n    \"ok\": true,\n    \"warnings\": []\n  },\n  \"version\": \"1.4.0\"\n}\n\nArchive v1.3.0: 98 files, 121666 bytes\n\nFiles: CHANGELOG.md (2397b), docs/clawhub-sync.md (833b), docs/diagnostics.md (2010b), docs/gallery.html (21253b), docs/harnesses.md (1301b), examples/agent-runtime.html (9862b), examples/agent-runtime.html.receipt.json (874b), examples/agent-runtime.json (1925b), examples/agent-runtime.share-card.svg (1567b), examples/agent-runtime.svg (7262b), examples/agent-runtime.svg.receipt.json (872b), examples/dataflow-analytics.html (9829b), examples/dataflow-analytics.html.receipt.json (884b), examples/dataflow-analytics.json (1420b), examples/dataflow-analytics.share-card.svg (1566b), examples/dataflow-analytics.svg (7230b), examples/dataflow-analytics.svg.receipt.json (882b), examples/lifecycle-agent-task.html (10460b), examples/lifecycle-agent-task.html.receipt.json (891b), examples/lifecycle-agent-task.json (1538b), examples/lifecycle-agent-task.share-card.svg (1559b), examples/lifecycle-agent-task.svg (7845b), examples/lifecycle-agent-task.svg.receipt.json (888b), examples/pr-delta-before.html (5271b), examples/pr-delta-before.html.receipt.json (849b), examples/pr-delta-before.json (567b), examples/pr-delta-before.share-card.svg (1492b), examples/pr-delta-before.svg (2874b), examples/pr-delta-before.svg.receipt.json (847b), examples/pr-delta-generated.html (10070b), examples/pr-delta-generated.html.receipt.json (1560b), examples/pr-delta-generated.json (2103b), examples/pr-delta-generated.share-card.svg (1499b), examples/pr-delta-generated.svg (7494b), examples/pr-delta-generated.svg.receipt.json (882b), examples/pr-delta-head.html (6564b), examples/pr-delta-head.html.receipt.json (864b), examples/pr-delta-head.json (855b), examples/pr-delta-head.share-card.svg (1497b), examples/pr-delta-head.svg (4114b), examples/pr-delta-head.svg.receipt.json (862b), examples/pr-delta-review.html (10618b), examples/pr-delta-review.html.receipt.json (879b), examples/pr-delta-review.json (2301b), examples/pr-delta-review.share-card.svg (1543b), examples/pr-delta-review.svg (8018b), examples/pr-delta-review.svg.receipt.json (876b), examples/repo-evidence-map.html (11428b), examples/repo-evidence-map.html.receipt.json (891b), examples/repo-evidence-map.json (2760b), examples/repo-evidence-map.share-card.svg (1575b), examples/repo-evidence-map.svg (8764b), examples/repo-evidence-map.svg.receipt.json (888b), examples/sequence-cache-miss.html (9150b), examples/sequence-cache-miss.html.receipt.json (845b), examples/sequence-cache-miss.json (1391b), examples/sequence-cache-miss.share-card.svg (1560b), examples/sequence-cache-miss.svg (6575b), examples/sequence-cache-miss.svg.receipt.json (843b), examples/service-map.html (9038b), examples/service-map.html.receipt.json (893b), examples/service-map.json (1745b), examples/service-map.share-card.svg (1467b), examples/service-map.svg (6534b), examples/service-map.svg.receipt.json (891b), examples/showcase-artifact-engine.html (10644b), examples/showcase-artifact-engine.html.receipt.json (913b), examples/showcase-artifact-engine.json (1839b), examples/showcase-artifact-engine.share-card.svg (1595b), examples/showcase-artifact-engine.svg (7974b), examples/showcase-artifact-engine.svg.receipt.json (910b), examples/showcase-pr-delta.html (11653b), examples/showcase-pr-delta.html.receipt.json (899b), examples/showcase-pr-delta.json (2052b), examples/showcase-pr-delta.share-card.svg (1587b), examples/showcase-pr-delta.svg (8955b), examples/showcase-pr-delta.svg.receipt.json (896b), examples/showcase-repo-evidence.html (11735b), examples/showcase-repo-evidence.html.receipt.json (917b), examples/showcase-repo-evidence.json (2510b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: visual-architecture\ndescription: \"Create deterministic, local-first architecture artifacts from typed JSON: validate specs, render restrained SVG/HTML diagrams, and emit receipts agents can cite.\"\nmetadata:\n  version: \"1.3.0\"\n---\n# Visual Architecture\n\nCreate architecture artifacts with the bundled Python renderer instead of hand-writing SVG.\n\nUse this when the user needs a trustworthy system map, agent workflow, sequence, data-flow, lifecycle/state diagram, repo-evidence diagram, or PR delta review sketch that should stay local, deterministic, and reviewable.\n\n## Workflow\n\n1. Create a JSON file with `mode`, `title`, `nodes`, and `edges`.\n   - Supported modes: `architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`, `pr-delta`.\n   - Supported themes: `classic` for documentation, `showcase` for README/release proof images.\n2. Snap intended node positions to the renderer grid mentally before writing them:\n   - horizontal grid: 120px\n   - vertical grid: 80px\n3. Validate first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py validate input.json --json\n```\n\n4. Deliver the final artifact with a receipt:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py deliver input.json output.html --json\n```\n\nUse `.svg` for a static docs artifact or `.html` for a self-contained presentation artifact.\n\nFor PR delta review, compare two specs:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py compare base.json head.json pr-delta.html --spec pr-delta.json --json\n```\n\n5. If `rsvg-convert` is available and you need a bitmap preview, run:\n\n```bash\nrsvg-convert -o output.png output.svg\n```\n\n## JSON Input Structure\n\n```json\n{\n  \"title\": \"Service Map\",\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}\n```\n\n## Node Kinds\n\n- `service`: rounded rectangle\n- `llm`: double-border rounded rectangle\n- `agent`: hexagon\n- `memory`: cylinder\n\nEach node requires:\n- `id`: unique string\n- `label`: primary title\n- `kind`: one of the node kinds above\n- `x`, `y`: grid-aligned center coordinates\n\nOptional:\n- `subtitle`: smaller secondary label\n- `show_grid`: set true to display the editing grid in the exported SVG\n- `theme`: set `showcase` on the top-level spec for dark public-facing artifacts\n- `evidence`: object or list with `source`, optional `line`/`lines`, `commit`, `confidence`, and `note`\n\n## Edge Kinds\n\n- `primary-data`: blue solid arrow\n- `memory-write`: green dashed arrow\n- `control`: slate dashed arrow\n\nEach edge requires:\n- `from`: source node id\n- `to`: target node id\n\nOptional:\n- `label`: rendered on the route with a shielding background rect\n- `source_side`, `target_side`: force edge anchors (`left`, `right`, `top`, `bottom`)\n- `via`: array of orthogonal turn points, each with `x` and `y`\n- `label_segment`: zero-based segment index to place the label on\n- `label_offset`: `[dx, dy]` shift for fine label placement\n\n## Renderer Guarantees\n\n- Validate rejects unsupported node/edge kinds and unknown edge endpoints before rendering\n- Deliver writes the artifact atomically and emits a JSON receipt with SHA-256 hashes\n- Evidence badges render as `SRC n` on nodes with source-backed evidence\n- PR delta compare writes added/removed node and edge facts into the receipt\n- Route arrows orthogonally only\n- Render in this order: background, arrows, nodes, labels\n- Keep label shields behind arrow text for readability\n- Stay restrained: clean strokes, no decorative effects, and hide the editing grid unless explicitly requested\n\n## Usage Notes\n\n- Prefer this skill when the user wants architecture diagrams, routing maps, or system relationship visuals.\n- Choose semantic kinds first, then place nodes on the grid, then add only the edges needed to explain flow.\n- Keep diagrams sparse. If a diagram feels crowded, split it into two files instead of forcing a dense composite.\n- Prefer `deliver` for handoff. A passing render without a receipt is a draft.\n- Do not claim repository evidence unless the spec names source files, commits, or confidence explicitly.\n\n## Example\n\nUse `examples/service-map.json` as a generic architecture starting point. Use `examples/agent-runtime.json`, `examples/sequence-cache-miss.json`, `examples/dataflow-analytics.json`, and `examples/lifecycle-agent-task.json` for the non-architecture modes. Use `examples/repo-evidence-map.json` for source-pinned evidence, and `examples/pr-delta-before.json` plus `examples/pr-delta-head.json` for generated PR deltas.\n\nFile v1.3.0:README.md\n\n# visual-architecture\n\n[![Validate](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml/badge.svg)](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml)\n\n**Deterministic, local-first architecture artifacts for agents.**\n\nvisual-architecture turns small typed JSON specs into restrained SVG or self-contained HTML system maps. The v1.0 contract is simple: validate the spec, render the artifact, write a receipt with hashes, and keep source evidence and PR deltas explicit en...","readmeExcerpt":"Skill: Visual Architecture Clawhub V180 Owner: leostehlik Summary: Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite. Tags: agent:1.6.0, architecture:1.6.0, artifact-engine:1.6.0, diagram:1.6.0, diagrams:1.3.0, latest:1.8.0, openclaw:1.6.0, pr-delta:1.6.0, source-eviden","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"python3 skills/visual-architecture/scripts/render_architecture.py extract-repo . --output repo-map.json --title \"Generated Repo Map\"\npython3 skills/visual-architecture/scripts/render_architecture.py layout repo-map.json repo-map.layout.json --mode architecture"},{"language":"bash","snippet":"python3 skills/visual-architecture/scripts/render_architecture.py validate input.json --json"},{"language":"bash","snippet":"python3 skills/visual-architecture/scripts/render_architecture.py deliver input.json output.html --json"},{"language":"bash","snippet":"python3 skills/visual-architecture/scripts/render_architecture.py extract-pr --base origin/master --head HEAD --output pr-delta.json\npython3 skills/visual-architecture/scripts/render_architecture.py compare base.json head.json pr-delta.html --spec pr-delta.json --json"},{"language":"bash","snippet":"rsvg-convert -o output.png output.svg"},{"language":"json","snippet":"{\n  \"title\": \"Service Map\",\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n    {\n      \"from\": \"web\",\n      \"to\": \"api\",\n      \"kind\": \"primary-data\",\n      \"label\": \"HTTP\"\n    }\n  ]\n}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: visual-architecture\ndescription: \"Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite.\"\nmetadata:\n  version: \"1.8.0\"\n---\n# Visual Architecture\n\nCreate architecture artifacts with the bundled Python renderer instead of hand-writing SVG. v1.8 adds a public TypeScript-monorepo case study path on top of the v1.7 extraction engine: source-backed case-study docs, generated artifacts, README quick-starts, and gallery conversion proof.\n\nUse this when the user needs a trustworthy system map, agent workflow, sequence, data-flow, lifecycle/state diagram, repo-evidence diagram, or PR delta review sketch that should stay local, deterministic, and reviewable.\n\n## Workflow\n\n1. Either extract a TypeScript-aware starter spec from a repo or create a JSON file with `mode`, `title`, `nodes`, and `edges`.\n   - Supported modes: `architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`, `pr-delta`.\n   - Supported themes: `classic` for documentation, `showcase` for README/release proof images.\n2. Snap intended node positions to the renderer grid mentally before writing them:\n   - horizontal grid: 120px\n   - vertical grid: 80px\n3. For repo-aware drafts, extract and layout first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py extract-repo . --output repo-map.json --title \"Generated Repo Map\"\npython3 skills/visual-architecture/scripts/render_architecture.py layout repo-map.json repo-map.layout.json --mode architecture\n```\n\n4. Validate first:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py validate input.json --json\n```\n\n5. Deliver the final artifact with a receipt:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py deliver input.json output.html --json\n```\n\nUse `.svg` for a static docs artifact or `.html` for a self-contained presentation artifact.\n\nFor PR delta review, either extract a PR concern map from git refs or compare two specs:\n\n```bash\npython3 skills/visual-architecture/scripts/render_architecture.py extract-pr --base origin/master --head HEAD --output pr-delta.json\npython3 skills/visual-architecture/scripts/render_architecture.py compare base.json head.json pr-delta.html --spec pr-delta.json --json\n```\n\n6. If `rsvg-convert` is available and you need a bitmap preview, run:\n\n```bash\nrsvg-convert -o output.png output.svg\n```\n\n## JSON Input Structure\n\n```json\n{\n  \"title\": \"Service Map\",\n  \"mode\": \"architecture\",\n  \"theme\": \"classic\",\n  \"summary\": \"One local request path with async work and model access.\",\n  \"nodes\": [\n    {\n      \"id\": \"web\",\n      \"label\": \"Web App\",\n      \"subtitle\": \"User interface\",\n      \"kind\": \"service\",\n      \"x\": 120,\n      \"y\": 160\n    },\n    {\n      \"id\": \"api\",\n      \"label\": \"API\",\n      \"subtitle\": \"Business logic\",\n      \"kind\": \"service\",\n      \"x\": 360,\n      \"y\": 160\n    }\n  ],\n  \"edges\": [\n  "},{"path":"README.md","content":"# visual-architecture\n\n[![Validate](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml/badge.svg)](https://github.com/LeoStehlik/visual-architecture/actions/workflows/validate.yml)\n\n**Deterministic, local-first architecture artifacts for agents.**\n\nvisual-architecture turns local repo evidence or typed JSON specs into SVG, self-contained HTML, share cards, receipts, and a generated Pages showcase. The v1.8 contract is stronger: agents can extract TypeScript monorepo structure, infer app/package/backend/frontend surfaces, attach confidence-scored evidence, lay it out deterministically, validate evidence quality, and publish a reviewable artifact bundle.\n\nThe wedge against Archify is local-first proof: architecture artifacts that look intentional, cite their sources, explain PR deltas, and remain reproducible from a repo scan or checked JSON.\n\n![Visual Architecture artifact engine](examples/showcase-artifact-engine.svg)\n\n## Visual Gallery\n\nOpen the generated artifact site: **https://leostehlik.github.io/visual-architecture/**\n\nThe gallery is the browsing surface: artifact rail, large diagram stage, story path, receipt quality, share cards, source evidence drilldown, and a public TypeScript-monorepo case study. The README stays as the product brief; the repo keeps the JSON specs, SVG/HTML artifacts, and receipts for audit.\n\n\n## Public Case Study\n\nThe current conversion artifact is a sanitized TypeScript monorepo map: client app, server app, editor extension, shared packages, backend modules, realtime gateway, database layer, and proof bundle.\n\nOpen it in the gallery or inspect the checked files directly:\n\n```bash\npython3 scripts/render_architecture.py deliver examples/showcase-typescript-monorepo-case-study.json /tmp/typescript-monorepo-case-study.html --json\npython3 scripts/render_architecture.py bundle examples/showcase-typescript-monorepo-case-study.json /tmp/typescript-monorepo-case-study --min-quality good\n```\n\n- Case-study notes: [`docs/public-typescript-monorepo-case-study.md`](docs/public-typescript-monorepo-case-study.md)\n- Spec: [`examples/showcase-typescript-monorepo-case-study.json`](examples/showcase-typescript-monorepo-case-study.json)\n- SVG: [`examples/showcase-typescript-monorepo-case-study.svg`](examples/showcase-typescript-monorepo-case-study.svg)\n- Receipt: [`examples/showcase-typescript-monorepo-case-study.html.receipt.json`](examples/showcase-typescript-monorepo-case-study.html.receipt.json)\n\n## Why It Exists\n\nAgents are good at inventing diagrams and bad at proving what they just drew. visual-architecture gives them a narrow, deterministic path:\n\n1. Author a compact JSON spec.\n2. Validate supported modes, node kinds, edge kinds, endpoints, evidence fields, grid placement, and obvious route hazards.\n3. Deliver SVG or HTML atomically.\n4. Emit a JSON receipt with input/output SHA-256, byte counts, metrics, warnings, and validation result.\n\nThe output stays local and deterministic, but no longer uses o"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7d3r58cdxk8k0xg6jq6k65gs873c0c\",\n  \"slug\": \"visual-architecture\",\n  \"version\": \"1.8.0\",\n  \"publishedAt\": 1788223625918\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\n## v1.8.0\n\n- Add a public TypeScript-monorepo case study that converts clone/API curiosity into a human-readable artifact path.\n- Add sanitized case-study notes covering client, server, editor extension, shared packages, backend modules, realtime gateway, database layer, and proof bundle surfaces.\n- Add checked generated case-study SVG, HTML, share card, receipts, and gallery/index entries.\n- Add README case-study quick-start commands for `deliver` and `bundle`.\n- Bump renderer and skill metadata to `1.8.0`.\n\n## v1.7.0\n\n- Ignore junk/build directories during repo extraction by default.\n- Prevent generated extractor edges from targeting missing nodes.\n- Detect workspace package/app surfaces from monorepo package metadata.\n- Add TS/TSX import scanning and per-package import summaries.\n- Detect client app, server app, editor extension, backend modules, realtime gateways, database layer, API client, and frontend feature surfaces.\n- Refresh generated public examples with the v1.7 extractor.\n- Validate the extractor against a private TypeScript monorepo without publishing private artifacts.\n\n## v1.6.0\n\n- Add language-aware repo extraction for Python, package metadata, workflows, schemas, examples, docs, and generated site files.\n- Add confidence-scored extraction metadata and source confidence metrics to validation receipts.\n- Improve PR delta extraction by grouping changed files into architecture concerns rather than raw filename buckets.\n- Tighten source-backed validation so generated evidence artifacts require evidence on every node and edge.\n- Upgrade the gallery evidence panel into an evidence drilldown that shows source type, confidence, and extraction rule.\n- Refresh generated repo and PR examples from the v1.6 extractor.\n\n## v1.5.1\n\n- Polish the generated Pages gallery artifact rail so the public showcase no longer exposes a native horizontal scrollbar.\n\n## v1.5.0\n\n- Add `extract-repo` to create a first source-backed architecture spec from local repository structure.\n- Add `layout` for deterministic mode-aware node placement without hand-authored coordinates.\n- Add `extract-pr` to group changed files into a generated PR delta review spec.\n- Add `bundle` to export HTML, SVG, share card, receipt, and bundle manifest together.\n- Add `--min-quality` gates for `deliver` and `bundle`.\n- Add generated repo evidence and PR delta examples to the public gallery.\n\n## v1.4.0\n\n- Add renderer v2 foundations: mode-specific backdrops for architecture, workflow, sequence, data-flow, lifecycle, and PR delta artifacts.\n- Add visual quality scoring to validation receipts for overlap, density, route crossings, spacing, and route complexity.\n- Add story-aware gallery data and an interactive evidence panel that loads checked spec/receipt JSON on GitHub Pages.\n- Add a real visual-architecture case-study artifact with source evidence pointing at the renderer, Makefile, README, and examples.\n- Tighten README/SKILL positioning around Archify-standard present"},{"path":"docs/clawhub-sync.md","content":"# ClawHub Sync Checklist\n\nPublish to ClawHub only after the public repo state is green and the installable package is clean.\n\n## Required Checks\n\n```bash\nmake validate\ngrep -RInE \"private-path|private-host|token-placeholder|client-name-placeholder\" README.md SKILL.md CHANGELOG.md docs examples scripts schemas\n```\n\nInstall smoke after publish must confirm:\n\n- `SKILL.md` reports the expected version\n- examples are present\n- `python3 scripts/render_architecture.py validate examples/service-map.json --json` exits 0\n- no generated docs expose private local paths, private hosts, credentials, or internal runtime state\n\n## Current State\n\nGitHub `v1.0.0` is the target public release for the full product ladder. ClawHub sync is allowed only if the publish bundle passes the checks above and the registry accepts the package cleanly."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite. Skill: Visual Architecture Clawhub V180 Owner: leostehlik Summary: Create deterministic, local-first architecture artifacts from typed JSON or TypeScript-aware repo extraction: validate specs, render SVG/HTML diagrams, and emit source-backed receipts agents can cite. Tags: agent:1.6.0, architecture:1.6.0, artifact-engine:1.6.0, diagram:1.6.0, diagrams:1.3.0, latest:1.8.0, openclaw:1.6.0, pr-delta:1.6.0, source-eviden","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":961,"uniquenessScore":50,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T14:27:02.393Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T14:27:02.393Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T17:35:40.913Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}