@stacksjs/defaults 0.74.41 → 0.74.42

package/ai/skills/stacks-cms/SKILL.md

@@ -183,10 +183,10 @@ cms.comments.deleteComment(id: number): Promise<void>
   title: 'Stacks Blog',
   description: 'The official Stacks.js blog',
   postsPerPage: 10,
-  enableComments: true,
-  enableRss: true,
-  enableSitemap: true,
-  enableSearch: true,
+  enableComments: true,   // declared, NOT yet honoured by the static builder
+  enableRss: true,        // generates feed.xml
+  enableSitemap: true,    // generates sitemap.xml
+  enableSearch: true,     // declared, NOT yet honoured by the static builder
   social: { twitter: '@stacksjs', github: 'stacksjs/stacks' },
   theme: { primaryColor: '#3451b2', logo: '/images/logos/logo-transparent.svg' },
 }

package/ai/skills/stacks-config/SKILL.md

@@ -110,7 +110,7 @@ they name: `defineEvents` and `defineListener` from `@stacksjs/events`,
 ### Features
 | File | Type | Key Settings |
 |------|------|-------------|
-| `blog.ts` | BlogConfig | subdomain, postsPerPage, enableComments/RSS/sitemap |
+| `blog.ts` | BlogConfig | subdomain, postsPerPage, enableRss/enableSitemap (enableComments and enableSearch are declared but not yet honoured) |
 | `cms.ts` | CmsConfig | content management settings |
 | `saas.ts` | SaasConfig | plans (Hobby/Pro/Lifetime with pricing), webhook, currencies |
 | `ui.ts` | HeadwindOptions | content, output, minify |

package/ai/skills/stacks-technical-diagrams/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2026 tt-a1i (Archify)
-Copyright (c) 2025 Cocoon AI (original "architecture-diagram-generator")
+Copyright (c) 2025 Cocoon AI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/ai/skills/stacks-technical-diagrams/SKILL.md

@@ -1,259 +1,285 @@
 ---
 name: stacks-technical-diagrams
-description: Create polished, dependency-free architecture, workflow, sequence, data-flow, and lifecycle diagrams for Stacks applications as standalone HTML with inline SVG, dark/light themes, and PNG, JPEG, WebP, and SVG export. Use for system or cloud architecture, security boundaries, network topology, technical workflows, CI/CD, runbooks, API call sequences, request lifecycles, data pipelines, lineage, PII boundaries, state machines, status transitions, or converting Mermaid into a purpose-built diagram.
+description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle diagrams for Stacks applications as explorable standalone HTML with inline SVG, dark/light themes, four visual presets, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accepts plain-language requirements or pasted Mermaid; reads repository evidence when the diagram must reflect real code; compares two architecture snapshots as a Before/Delta/After review. Use for system or cloud architecture, security boundaries, network topology, technical workflows, CI/CD, runbooks, API call sequences, request lifecycles, data pipelines, lineage, PII boundaries, state machines, status transitions, or converting Mermaid into a purpose-built diagram.
 license: MIT
 metadata:
   source: tt-a1i/archify
-  source_version: "2.10.0"
-  source_commit: 73f769d2e97c7fb54b74bebb276c1987db278c3f
+  source_version: "2.17.0-dev.1"
+  source_commit: 18911058008f17dc065af23a2cdc9bfeff6d3f7a
   based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)
 ---
 
 # Technical Diagrams for Stacks
 
-Create professional technical diagrams as self-contained HTML files with inline SVG, a theme toggle, and a built-in image/SVG export menu.
+Turn a small typed JSON specification into one self-contained, interactive HTML diagram. Static
+output is the default; motion is opt-in.
 
-Every diagram ships with a **dark/light theme toggle** (persists in `localStorage`, respects `prefers-color-scheme`), an **export menu** (copy PNG to clipboard; download PNG/JPEG/WebP rasterized natively at up to 4× resolution; download a **dual-theme SVG** that follows the embedding host's `prefers-color-scheme` - ideal for GitHub READMEs), and a **CSS-variable color system** that keeps both themes consistent.
+Every delivered artifact carries a theme toggle (persists in `localStorage`, respects
+`prefers-color-scheme`), pan/zoom, node search, focus with authored upstream/downstream reach, route
+probing, a semantic lens, an overview radar, presentation mode, guided stories, and an export menu
+(clipboard PNG; PNG/JPEG/WebP raster at up to 4x; dual-theme SVG; WebM for motion; 1200x630 share
+cards). Those are reader capabilities that already exist in the output, not authoring work.
 
 ## Attribution
 
-This skill ports the renderer and visual system from [Archify](https://github.com/tt-a1i/archify) 2.10.0 by tt-a1i under the MIT license. Archify is itself a fork and rewrite of Cocoon AI's `architecture-diagram-generator` 1.0. Preserve `LICENSE` when redistributing this skill or substantial portions of its source.
+This skill ports the renderer, validator, and viewer from
+[Archify](https://github.com/tt-a1i/archify) 2.17.0-dev.1 by tt-a1i under the MIT license. Archify is
+itself a fork and rewrite of Cocoon AI's `architecture-diagram-generator` 1.0. Preserve `LICENSE` and
+`THIRD_PARTY_NOTICES.md` when redistributing this skill or substantial portions of its source.
 
-## Dependency-free contract
+## Running the CLI
 
-Do not install packages or fetch runtime assets. Use Bun and the bundled source only. Standalone validators for all five JSON schemas are checked in, the renderer uses Bun's built-in Node compatibility modules, and generated HTML uses system font fallbacks with no network requests.
+Every command below is one launcher invocation from the Stacks project root:
 
-Run `bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs doctor` from the Stacks project root to verify the skill. Run `bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs demo [output-directory]` to generate a ready-to-open example before creating the first custom diagram.
-
-## Stacks repository workflow
-
-1. Inspect the implementation before drawing. Treat `app/` as overrides and `storage/framework/defaults/app/` as fallbacks. Follow registrations in `app/Routes.ts`, route files, actions, jobs, listeners, middleware, models, config, resources, and framework entry points that matter to the requested view.
-2. Read the relevant Stacks domain skill before mapping an unfamiliar subsystem. Common companions include `stacks-router`, `stacks-actions`, `stacks-models`, `stacks-database`, `stacks-jobs`, `stacks-events`, `stacks-realtime`, and `stacks-cloud`.
-3. Draw one question per diagram. For a runtime overview, prefer browser or client -> stx/router -> action or service -> model/query -> database, then add only the external systems and trust boundaries needed for that story.
-4. Write output to the user's requested path. When no path is given, use `docs/public/diagrams/<descriptive-name>/index.html` and keep the source JSON beside it. That path matters: BunPress only renders `docs/**/*.md` and copies `docs/public/**`, so a diagram written anywhere else under `docs/` never reaches the built site. The directory-plus-`index.html` shape is what the deployed docs host serves at the clean URL `/docs/diagrams/<descriptive-name>` - a bare `<name>.html` is redirected to an extensionless path that does not exist. Link to it from a docs page as `/diagrams/<descriptive-name>` (BunPress adds the `/docs` base).
-
-If Bun cannot run, fall back to architecture mode: copy `assets/template.html`, hand-place SVG using the design system below, and run the self-review checklist before delivering.
-
-## Choosing a Diagram Type
-
-| Type | Use for | How |
-|------|---------|-----|
-| `architecture` | System components, cloud resources, services, security boundaries, infrastructure | `renderers/architecture/render-architecture.mjs` + JSON (or hand-place SVG when renderers can't run) |
-| `workflow` | Technical flows, approval gates, tool calls, runbooks, CI/CD, incident response | `renderers/workflow/render-workflow.mjs` + JSON |
-| `sequence` | API call chains, request lifecycles, cache fallback, async traces, return paths | `renderers/sequence/render-sequence.mjs` + JSON |
-| `dataflow` | Pipelines, ETL/ELT, PII isolation, lineage, warehouse sync, consumers | `renderers/dataflow/render-dataflow.mjs` + JSON |
-| `lifecycle` | State machines, status transitions, wait states, retries, terminal states | `renderers/lifecycle/render-lifecycle.mjs` + JSON |
-
-Trigger phrases: "architecture/system/cloud diagram" → `architecture` (unless clearly process-oriented). "workflow/flow/process/runbook/approval/CI-CD/incident" → `workflow`. "sequence/interaction/call chain/who calls whom" → `sequence`. "data flow/pipeline/ETL/lineage/PII/governance" → `dataflow`. "state/status/lifecycle/state machine/retry/terminal" → `lifecycle`.
-
-## Mermaid as an Input Dialect
-
-When the user pastes Mermaid code, do NOT try to render or parse it mechanically. Read it for structure and **lay out from scratch** in the matching diagram mode:
-
-| Mermaid | Diagram mode | Mapping |
-|---------|--------------|---------|
-| `flowchart` / `graph` | `workflow` (or `architecture` if it's a component map) | `subgraph` → lane or region boundary; node shape `{}` (diamond) → decision/security node; `-->` labels → edge labels (use sparingly); `classDef`/`style` → nearest semantic type |
-| `sequenceDiagram` | `sequence` | `participant` → participants (pick semantic `type` from the name); `->>` → message, `-->>` → `return` variant; `Note` → message `note`; `rect` blocks → segments |
-| `stateDiagram` | `lifecycle` | states → states (pick `start`/`active`/`waiting`/`success`/`failure` from names); `[*]` start/end → `start` type / `terminal` lane; transition labels → event-like labels |
-
-Drop Mermaid styling; keep only the topology and meaning. You choose grouping, lane order, and what deserves emphasis - that judgment is the product.
-
-## Layout principles (read before placing)
-
-The renderer's readability comes from **spatial narrative**, not from drawing every dependency as an arrow. Before you write coordinates or edge lists, plan one clear story:
-
-1. **One main path** - left → right (architecture) or lane → column (workflow). The reader should trace the happy path without crossing lines.
-2. **Few labeled edges** - label only cross-boundary or non-obvious transitions on the main path. Adjacent steps stay unlabeled.
-3. **Short side branches** - permissions, storage, bots, CI: connect **up or down** from the nearest node on the main path. Never route a secondary edge diagonally across unrelated components.
-4. **Cards for detail** - policies, tech stack notes, and "also connects to X" belong in summary cards, not as extra arrows.
-5. **Mode fit** - process / approval / tool-call stories → `workflow` or `sequence`. Component maps with ≤12 nodes → `architecture`. If the diagram needs 20+ edges, remove edges until the main path is obvious.
-
-Use the complete examples in `examples/` as the starting point for each renderer mode.
-
-When validation fails on label overlap, read the **Suggested fix** lines (coordinates / `labelAt` / `labelDy`) and apply them directly - do not guess offsets blindly.
+```bash
+.claude/skills/stacks-technical-diagrams/bin/diagrams doctor
+```
 
-## Renderer Modes (architecture / workflow / sequence / dataflow / lifecycle)
+The launcher runs Bun against the skill's own empty `bunfig.toml` with `--no-env-file`, so a diagram
+render never inherits the application's `preload` chain or its `.env`. Never call the renderers with
+a bare `bun`; use the launcher (or `bun --config=<skill>/bunfig.toml --no-env-file
+<skill>/bin/technical-diagrams.mjs` if you need the explicit form).
+
+Commands: `render`, `validate`, `deliver`, `compare`, `preview`, `visual-check`, `check`, `inspect`,
+`migrate`, `guide`, `brands`, `examples`, `doctor`, `demo`. Run `diagrams` with no arguments for the
+full usage block.
+
+## Fast authoring path
+
+Use this bounded path for ordinary generation.
+
+1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question. When
+   ambiguous, run `diagrams guide "<scenario>" --json`.
+2. Read one matching schema in `schemas/`, plus `schemas/common.schema.json`, plus one matching JSON
+   example in `examples/`. Read only those files. Use the example for field shape, never for facts.
+   New workflow sources use `schema_version: 2`; keep `schema_version: 1` only when preserving an
+   existing workflow's fixed geometry.
+3. Artifact first: the next tool action writes the candidate JSON. Do not plan exact coordinates in
+   prose and do not read renderer internals before the first candidate. Start with one clear main
+   path, short side branches, sparse labels, and at most 12 primary nodes. Set
+   `meta.quality_profile: "showcase"` unless the user explicitly wants a dense `standard` map. Start
+   with automatic routes and labels; do not add `via`, `channelX`, `channelY`, or `labelAt` before a
+   diagnostic asks for one, and apply at most one diagnosed geometry control per repair.
+4. Validate after every candidate edit and immediately before handoff:
+
+   ```bash
+   .claude/skills/stacks-technical-diagrams/bin/diagrams validate <type> <candidate.json> --quality showcase --json
+   ```
+
+   A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase
+   pass reports all 9 artifact checks with 0 composition errors and 0 warnings. For a workflow v2
+   geometry diagnosis, run `validate workflow <candidate.json> --layout-json` and read the stable
+   compiler receipt; solver internals are not authoring controls. A passing final validation freezes
+   the candidate: do not edit it afterward.
+5. Deliver once, as the final acceptance step:
+
+   ```bash
+   .claude/skills/stacks-technical-diagrams/bin/diagrams deliver <type> <candidate.json> <output.html> --quality showcase --json
+   ```
+
+   A non-zero exit is never success. On failure, change only the diagnosed `subject`, verify
+   `evidence`, choose from `supportedFixes`, and rerun. Keep correcting while the objective error
+   count reaches a new minimum; if two consecutive rounds do not improve that best count, stop and
+   report the unresolved diagnostics truthfully.
+
+Inspect renderer or validator source only after an unsupported internal diagnostic or two failed
+focused repairs.
 
-All five modes follow the same loop:
+## Stacks repository workflow
 
-1. **Read first**: the schema (`schemas/<type>.schema.json`) and the complete worked example (`examples/*.{architecture,workflow,sequence,dataflow,lifecycle}.json`) - copy its patterns instead of guessing field shapes.
-2. Write `<name>.<type>.json`.
-3. Render: `bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs render <type> <input>.json <output>.html`.
-4. Validate the generated artifact: `bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs validate <type> <input>.json --json`, or check an existing HTML file with `bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs check <output>.html`. This catches malformed SVG output, non-finite SVG values, two-point diagonal arrows, and arrows crossing the legend.
-5. If either step fails, the error names the JSON path or the fix (thresholds, valid ranges, which knob to change). Fix the JSON and re-run; never edit the renderer.
+1. Inspect the implementation before drawing. Treat `app/` as overrides and
+   `storage/framework/defaults/app/` as fallbacks. Follow registrations in `app/Routes.ts`, route
+   files, actions, jobs, listeners, middleware, models, config, resources, and the framework entry
+   points that matter to the requested view.
+2. Read the relevant Stacks domain skill before mapping an unfamiliar subsystem. Common companions
+   are `stacks-router`, `stacks-actions`, `stacks-models`, `stacks-database`, `stacks-jobs`,
+   `stacks-events`, `stacks-realtime`, and `stacks-cloud`.
+3. Draw one question per diagram. For a runtime overview, prefer browser or client -> stx/router ->
+   action or service -> model/query -> database, then add only the external systems and trust
+   boundaries that story needs.
+4. Write output to the user's requested path. When no path is given, use
+   `docs/public/diagrams/<descriptive-name>/index.html` and keep the source JSON beside it. That
+   path matters: BunPress only renders `docs/**/*.md` and copies `docs/public/**`, so a diagram
+   written anywhere else under `docs/` never reaches the built site. The directory-plus-`index.html`
+   shape is what the deployed docs host serves at the clean URL
+   `/docs/diagrams/<descriptive-name>`; a bare `<name>.html` is redirected to an extensionless path
+   that does not exist. Link to it from a docs page as `/diagrams/<descriptive-name>` (BunPress adds
+   the `/docs` base).
+
+To pin architecture nodes to real code, pass `--repo-root .` and author `meta.repository`; nodes then
+mark themselves `SRC n` and open Git-verified files and line ranges at one pinned commit. See
+`references/authoring-contract.md`.
+
+## Type router
+
+| Type | Use for |
+|---|---|
+| `architecture` | Components, services, cloud/security boundaries, infrastructure |
+| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD, incident response |
+| `sequence` | API call chains, request lifecycles, cache fallback, async traces, returns |
+| `dataflow` | Pipelines, ETL/ELT, lineage, PII and governance boundaries, consumers |
+| `lifecycle` | State/status transitions, retries, waiting and terminal states |
+
+Trigger phrases: "architecture/system/cloud diagram" -> `architecture` (unless clearly
+process-oriented). "workflow/flow/process/runbook/approval/CI-CD/incident" -> `workflow`.
+"sequence/interaction/call chain/who calls whom" -> `sequence`. "data
+flow/pipeline/ETL/lineage/PII/governance" -> `dataflow`. "state/status/lifecycle/state
+machine/retry/terminal" -> `lifecycle`.
+
+## Mermaid input
+
+Read Mermaid for topology and meaning, then author fresh JSON. Do not parse or re-render Mermaid
+styling.
+
+- `flowchart` / `graph` -> `workflow`, or `architecture` for a component map. `subgraph` becomes a
+  lane or a boundary; a diamond node becomes a decision or security node.
+- `sequenceDiagram` -> `sequence`. `participant` becomes a semantic participant, `->>` a message,
+  `-->>` a `return` variant, `Note` a message note, `rect` a segment.
+- `stateDiagram` -> `lifecycle`. `[*]` becomes the `start` type or the `terminal` lane; transition
+  labels stay event-like.
+
+Drop Mermaid styling and keep only topology and meaning. Grouping, lane order, and emphasis are your
+judgment, and that judgment is the product.
+
+## Authoring invariants
+
+- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges
+  before adding routing controls. If a diagram needs 20+ edges, remove edges until the main path is
+  obvious.
+- Detail belongs in summary `cards`, not in extra arrows.
+- Omit `meta.visual_preset` by default so every diagram opens in `classic`. Color mode and visual
+  preset are independent: switching light/dark preserves the preset. Set `signal-flow`, `blueprint`,
+  or `editorial` only when the user asks for that style.
+- Omit `meta.subtitle` by default. Never invent one that restates the title, nodes, or cards.
+- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden`
+  and renderer-supported `entries.<kind>.label|visible`. Labels never change semantics.
+- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`,
+  `external`. Variants are `default`, `emphasis`, `security`, `dashed`.
+- Relationship labels are semantic data. When one collides, move the label, adjust the route or
+  spacing, then shorten the wording while preserving meaning. Delete wording only when both endpoints
+  fully imply it and it carries no protocol, action, direction, sync/async behavior, or
+  cross-boundary mechanism. Deleting a meaningful label is not a geometry repair.
+- Spacing means clear gap, not center distance. A label's clear gap must exceed its measured mask
+  width.
+- Automatic routes own their endpoint sides: the first and final segment leave and enter
+  perpendicular to that side. Automatic Port Spread is default behavior for architecture, workflow,
+  dataflow, and lifecycle; it stands down for explicit `via`, `channelX`, `channelY`, `labelAt`, or a
+  non-`auto` route.
+- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a label
+  masking another route.
+- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set `"spread"` when a
+  wide viewBox leaves unused horizontal space or meaningful participant labels do not fit; do not
+  shorten semantic labels first.
+- Lifecycle phase columns `0..4` occupy the main rail; an event or terminal column `N` in `0..2`
+  aligns beneath main column `N + 2`. A recoverable state uses `type: "failure"` plus a real
+  transition back to the active state.
+- Omit `meta.engineering_profile` by default. Enable `deployment-ownership` only when the user
+  explicitly asks for production deployment topology, ownership handoff, or a fail-closed deployment
+  review, and the facts are known. It fails closed on missing owners, region placement, private
+  database scope, or named crossings; repair the facts rather than removing the profile.
+- Set `meta.animation: "trace"` only for a demo or presentation view. It respects
+  `prefers-reduced-motion` and leaves static output unchanged.
+- `meta.views` is optional: at most five curated chapters built from stable node IDs.
+- `meta.locale` (`en` or `zh-CN`) localizes renderer-owned viewer UI only, never authored content.
+  For any other language, omit it and say plainly that the fixed viewer UI and `<html lang>` fall
+  back to English.
+- Treat the artifact as a first-screen desktop composition. One responsive artifact serves laptops
+  and external displays; never emit device-specific HTML or alternate topology. Before handoff the
+  page must not scroll horizontally or vertically at 1440x900, 1600x1000, and 1920x1080 (plus
+  2048x1320 for a large-display composition). Repair overflow by removing genuinely redundant content
+  or compacting spacing before shrinking nodes or labels. Never counterfeit a pass with
+  `overflow: hidden`, clipping, an internal scroller, a stretched SVG, or smaller typography.
+
+Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair
+rules, repository evidence, or mode-specific placement.
+
+## Delivery evidence
+
+`deliver` freezes the specification bytes into a private same-directory snapshot, renders and checks
+that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both
+specification and artifact. It proves deterministic artifact checks; it does not exercise the viewer
+in a browser.
 
-Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, workflow edges crossing unrelated nodes, and legends outside the viewBox. CJK text is measured at double width automatically.
+```bash
+.claude/skills/stacks-technical-diagrams/bin/diagrams visual-check <output.html> --json
+```
 
-Set `meta.animation: "trace"` only when the user asks for motion or a presentation/demo view. It adds lightweight SVG/CSS trace animation to renderer-marked arrows and nodes, respects `prefers-reduced-motion`, and leaves the default static output unchanged.
+`visual-check` drives a system Chrome over the DevTools Protocol against the exact delivered HTML,
+without rerendering it, and writes screenshots plus a machine-readable receipt. It exits 2 (skipped)
+when no Chrome is installed. Keep three claims separate: `deliver` proves artifact checks,
+`visual-check` proves bounded browser behavior, and perceptual review requires a human or an
+image-capable reviewer. Never run `visual-check` after a failed delivery: it would inspect the stale
+last-good artifact.
 
-### Workflow
+For an active authoring loop, `preview` watches one JSON file on a random loopback port and reloads
+only after a candidate passes every gate, keeping the last verified diagram visible through failures:
 
-```json
-{
-  "schema_version": 1,
-  "diagram_type": "workflow",
-  "meta": { "title": "Release Workflow", "subtitle": "PR to production", "output": "release.html" },
-  "lanes": [ { "id": "dev", "label": "Developer" }, { "id": "ci", "label": "CI" }, { "id": "exceptions", "label": "Exception Handling", "variant": "exception" } ],
-  "phases": [ { "id": "intake", "label": "Intake", "fromCol": 0, "toCol": 1 } ],
-  "groups": [ { "id": "checks", "label": "Parallel checks", "lane": "ci", "fromCol": 1, "toCol": 3, "variant": "emphasis" } ],
-  "mainPath": ["pr", "build"],
-  "nodes": [
-    { "id": "pr", "lane": "dev", "col": 0, "type": "frontend", "label": "Open PR", "sublabel": "feature branch" },
-    { "id": "build", "lane": "ci", "col": 1, "type": "backend", "label": "Build", "sublabel": "lint + test", "tag": "blocking" }
-  ],
-  "edges": [
-    { "from": "pr", "to": "build", "label": "webhook", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" }
-  ],
-  "cards": []
-}
+```bash
+.claude/skills/stacks-technical-diagrams/bin/diagrams preview <type> <input>.json <output>.html --quality showcase
 ```
 
-**Layout budget**: 6 columns (`col` 0-5) at fixed x positions `[88, 220, 300, 430, 500, 625]` - columns 1↔2 and 3↔4 are only 70-80px apart, so default-width (92px) nodes in those adjacent columns of the same lane overlap; skip a column or shrink `width`. Lane content width is 640px. Omit `meta.viewBox` - the renderer sizes height to the lane count automatically. Use `phases` for top-of-diagram story beats, `groups` to frame parallel work or a branch inside one lane, and `lane.variant: "exception"` for error/retry/fallback lanes. `mainPath` is optional but recommended: list the happy-path node ids in order so the renderer can catch missing edges or accidental backward movement. Edge routes: `straight`, `drop` (bend between lanes; `bias` 0-1 picks where), `outside-right`, `return-left`, `bottom-channel`, `up-channel`, or explicit `via` points. Keep adjacent-step edges unlabeled; reserve labels for cross-lane transitions, approvals, async traces, and returns.
-
-### Sequence
-
-```json
-{
-  "schema_version": 1,
-  "diagram_type": "sequence",
-  "meta": { "title": "Cache Miss Request", "subtitle": "auth and cache fallback", "output": "cache-miss.html" },
-  "participants": [
-    { "id": "web", "type": "frontend", "label": "Web App", "sublabel": "React UI" },
-    { "id": "api", "type": "backend", "label": "API", "sublabel": "handler" }
-  ],
-  "segments": [ { "from": 160, "to": 320, "label": "01 / AUTH" } ],
-  "messages": [
-    { "from": "web", "to": "api", "y": 200, "label": "GET /data", "variant": "emphasis" },
-    { "from": "api", "to": "web", "y": 290, "label": "200 JSON", "variant": "return" }
-  ],
-  "activations": [ { "participant": "api", "from": 190, "to": 300, "type": "backend" } ],
-  "cards": []
-}
-```
+Never start `preview` by default. `deliver --open` is an opt-in one-shot handoff after commit. Full
+receipt fields, coverage, sidecars, and exit behavior: `references/delivery-contract.md`.
 
-**Layout budget**: participants sit at x = 62 + index×108, so a 920-wide viewBox fits at most 8. Message `y` must stay within `[160, viewBox_height − 83]`; messages that share horizontal space need ≥28px vertical separation; arrows need ≥60px horizontal span. `segments[].from/to` and `activations[].from/to` are **y pixel coordinates**, not participant ids. A taller `meta.viewBox` (default `[920, 760]`) buys more timeline room. Keep labels short: "GET /path", "verify JWT", "cache miss", "200 JSON".
-
-### Dataflow
-
-```json
-{
-  "schema_version": 1,
-  "diagram_type": "dataflow",
-  "meta": { "title": "Product Analytics", "subtitle": "events to consumers", "output": "analytics.html" },
-  "stages": [ { "label": "Sources" }, { "label": "Ingest" }, { "label": "Store" } ],
-  "nodes": [
-    { "id": "web", "type": "frontend", "label": "Web App", "stage": 0, "row": 0, "sublabel": "clickstream" },
-    { "id": "kafka", "type": "messagebus", "label": "Kafka", "stage": 1, "row": 0, "tag": "accepted events" }
-  ],
-  "flows": [
-    { "from": "web", "to": "kafka", "label": "events", "classification": "PII touch", "variant": "emphasis" }
-  ],
-  "cards": []
-}
-```
+## Architecture Delta
 
-**Layout budget**: 2-5 stages at x = 100 + stage×215; 5 rows (`row` 0-4) at y `[128, 242, 356, 470, 584]`; default node 112×58. Default viewBox `[940, 720]`. Flow labels are mandatory and asset-like ("clickstream", "identity map", "feature vectors"); put sensitivity in `classification` ("PII touch", "approved only", "non-PII"). Variants: `emphasis` = primary path, `security` = PII/policy/consent, `dashed` = async/batch.
-
-### Lifecycle
-
-```json
-{
-  "schema_version": 1,
-  "diagram_type": "lifecycle",
-  "meta": { "title": "Agent Run Lifecycle", "subtitle": "states and terminal outcomes", "output": "agent-run.html" },
-  "lanes": [
-    { "id": "main", "label": "Lifecycle phases" },
-    { "id": "waiting", "label": "Interruptions" },
-    { "id": "terminal", "label": "Terminal exits" }
-  ],
-  "states": [
-    { "id": "queued", "type": "start", "label": "Queued", "lane": "main", "col": 0, "step": "01" },
-    { "id": "running", "type": "active", "label": "Executing", "lane": "main", "col": 2, "step": "02" },
-    { "id": "approval", "type": "waiting", "label": "Needs Approval", "lane": "waiting", "col": 0 },
-    { "id": "done", "type": "success", "label": "Completed", "lane": "terminal", "col": 2 }
-  ],
-  "transitions": [
-    { "from": "queued", "to": "running", "variant": "emphasis" },
-    { "from": "running", "to": "approval", "label": "needs approval", "variant": "security", "fromSide": "bottom", "toSide": "right" },
-    { "from": "running", "to": "done", "label": "success", "variant": "emphasis", "fromSide": "bottom", "toSide": "top" }
-  ],
-  "cards": []
-}
-```
+For design or PR review, compare two validated architecture snapshots as Before / Delta / After with
+a machine receipt of exactly what was added, removed, changed, moved, and rerouted:
 
-**Layout budget - lane ids are semantic and reserved**: `main` is required and maps to the top phase band (cols 0-4); `terminal` maps to the bottom outcome band (cols 0-2); **every other lane id shares the single middle event band** (cols 0-2) - separate same-band states with different `col` or `yOffset`. Band headers render from your lane labels. Default viewBox `[980, 660]`. Keep transition labels event-like and sparse ("retry", "timeout", "cancel"); prefer state `tag`s, `step` numbers, and summary cards over label-heavy arrows. Put terminal states in the `terminal` lane so endings are unambiguous.
-
-### Per-mode deep guidance
-
-Each renderer has a README with its full design language (route presets, semantic types, story guidance): `renderers/workflow/README.md`, `renderers/sequence/README.md`, `renderers/dataflow/README.md`, `renderers/lifecycle/README.md`. Read the matching one before your first diagram of that mode in a session.
-
-## Architecture Mode
-
-Architecture has the same read-schema-then-render loop as the other modes - prefer it. Hand-placed SVG is the fallback for when renderers can't run.
-
-```json
-{
-  "schema_version": 1,
-  "diagram_type": "architecture",
-  "meta": { "title": "Sample Web App", "subtitle": "3-tier SaaS on AWS", "output": "web-app.html" },
-  "components": [
-    { "id": "users", "type": "external", "label": "Users", "sublabel": "Browser", "pos": [40, 300] },
-    { "id": "api", "type": "backend", "label": "API Server", "sublabel": "FastAPI :8000", "pos": [460, 300] },
-    { "id": "db", "type": "database", "label": "PostgreSQL", "sublabel": ":5432", "pos": [680, 300] }
-  ],
-  "boundaries": [
-    { "kind": "region", "label": "AWS us-west-2", "wraps": ["api", "db"] }
-  ],
-  "connections": [
-    { "from": "users", "to": "api", "label": "HTTPS", "variant": "emphasis" },
-    { "from": "api", "to": "db", "label": "SQL" }
-  ],
-  "cards": []
-}
+```bash
+.claude/skills/stacks-technical-diagrams/bin/diagrams compare architecture base.json head.json delta.html --receipt delta.receipt.json --json
 ```
 
-Render: `bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs render architecture <input>.json <output>.html`.
+Component identity is `components[].id`, relationship identity is `connections[].id` (required for
+compare), and boundary identity is derived from `kind` + `label`. The delta reports authored facts
+only; it infers no impact, risk, or merge safety.
 
-**Free placement** - `pos: [x, y]` is the component's top-left; `size: [w, h]` defaults to `[120, 60]`. Unlike typed modes there is no lane/stage grid - asymmetric placement is yours to choose. `meta.viewBox` is optional (auto-fitted).
+## Brand marks
 
-**Grid placement (#8)** - when manual coordinates are painful, set semantic cells instead of doing arithmetic:
+Brand identity is optional and explicit. When a node names a real product, look up a canonical
+built-in ID from the bundled catalogue of 107 marks:
 
-```json
-{
-  "layout": { "mode": "grid", "cols": 7, "origin": [40, 100], "gapX": 24, "gapY": 48, "cellW": 120, "cellH": 60 },
-  "components": [
-    { "id": "agents", "type": "frontend", "label": "Agent Hosts", "row": 1, "col": 1 },
-    { "id": "ir", "type": "messagebus", "label": "JSON IR", "row": 1, "col": 2 }
-  ]
-}
+```bash
+.claude/skills/stacks-technical-diagrams/bin/diagrams brands "postgres" --json
 ```
 
-`pos` still wins when present and overrides one cell. This is **not** auto-layout. Spacing is fixed cell math.
+Never infer a brand from a vague role such as "database", and never let a badge replace the semantic
+`type`, label, or relationship facts. `brands capture <url>` is the one command in this skill that
+makes a network request: it is user-initiated, it pins the result by SHA-256, and `render`,
+`validate`, `deliver`, and `compare` never perform an unpinned capture. See
+`references/brand-marks.md`.
 
-**Inspect layout (#9)** - after editing JSON, dump computed boxes without opening HTML:
+## Dependency-free and offline contract
 
-```bash
-bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs inspect architecture my.architecture.json
-# or: bun --config=storage/framework/defaults/ai/skills/stacks-technical-diagrams/bunfig.toml --no-env-file storage/framework/defaults/ai/skills/stacks-technical-diagrams/bin/technical-diagrams.mjs validate architecture my.architecture.json --layout-json
-```
+Do not install packages or fetch runtime assets. Standalone validators for all five schemas are
+checked in, the renderers use Bun's Node compatibility modules, and delivered HTML embeds its own
+subsetted JetBrains Mono, so a page renders with no network access. Upstream's update-notifier
+scripts are deliberately not vendored: this port is pinned by `metadata.source_commit` and is updated
+by re-porting, never by a runtime download.
 
-Output includes component rects, boundaries, connection point paths, and label positions.
+Verify the install with `diagrams doctor`, and generate a ready-to-open example with
+`diagrams demo <output-directory>` before the first custom diagram.
 
-**The renderer does the mechanical work that used to be hand-tuned**, so you only choose coordinates and meaning:
+## Deeper references
 
-- **Free coordinates** - `pos: [x, y]` is the component's top-left; `size: [w, h]` defaults to `[120, 60]`. Unlike the typed modes there is no lane/stage grid - asymmetric placement is yours to choose. `meta.viewBox` is optional (auto-fitted to your components + a legend row).
-- **Grid placement** - optional `layout.mode: "grid"` with `row`/`col` per component (see above). Not dagre; fixed cell spacing only.
-- **Boundaries from `wraps`** - list the component ids a `region` (dashed amber) or `security-group` (dashed rose) encloses; the renderer computes the box with correct 30/50 padding automatically. Never hand-arithmetic a boundary again.
-- **Connections** route like edges (`variant`, `fromSide`/`toSide`, `route: straight|orthogonal-h|orthogonal-v|auto`, `via`, `labelDx/labelDy/labelAt`). For a vertical labeled connection, push the label into the gap with `labelDy` (the validator will tell you if it lands on a box).
-- The renderer auto-emits the two-rect `c-mask` pattern, draws arrows before boxes (z-order), builds the legend from the component types you used, and **fails fast on component overlap, off-canvas components/boundaries, unknown wraps/connection ids, label-vs-component collisions, and non-finite coordinates** - the same reliability the other four modes already had.
+Read one of these only when the fast path calls for it.
 
-### Hand-placed fallback (no renderer available)
+| Need | Read |
+|---|---|
+| Field enums, spacing math, geometry repair, repository evidence, placement | `references/authoring-contract.md` |
+| Receipt fields, coverage, sidecars, exit behavior, preview, export receipts | `references/delivery-contract.md` |
+| Share cards, route/reach cards, motion, stories, deep links, presentation | `references/viewer-runtime.md` |
+| Brand catalogue rules and capture | `references/brand-marks.md`, `brand-marks/README.md` |
+| Per-mode layout budgets, route presets, semantic types | `renderers/<mode>/README.md` |
+| IR overview across all five modes | `schemas/README.md` |
 
-When Bun cannot run, copy `assets/template.html` and place SVG by hand. Study the worked diagram inside the template for coordinate idioms, follow the design system below, and run the self-review checklist before delivering.
+## Hand-placed fallback (no Bun available)
 
-### The Cardinal Rule: CSS classes, not inline colors
+When the CLI cannot run, copy `assets/template.html`, place SVG by hand using the design system
+below, and run the self-review checklist before delivering.
 
-The theme toggle works by switching CSS custom properties. Hardcoded `fill="rgba(...)"` or `stroke="#22d3ee"` will NOT update on theme change. Always use the class system:
+**The cardinal rule: CSS classes, not inline colors.** The theme toggle switches CSS custom
+properties, so `fill="rgba(...)"` or `stroke="#22d3ee"` will not follow the theme.
 
 ```svg
 <rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>
@@ -262,29 +288,31 @@ The theme toggle works by switching CSS custom properties. Hardcoded `fill="rgba
 <text x="CX" y="CY+16" class="t-muted" font-size="9" text-anchor="middle">FastAPI :8000</text>
 ```
 
-### Design system
-
-Component fills `c-frontend` (clients/UI), `c-backend` (services/APIs), `c-database` (stores/caches), `c-cloud` (managed infra), `c-security` (auth/secrets), `c-messagebus` (Kafka/queues), `c-external` (3rd parties); text accents `t-<same>` plus neutrals `t-primary` / `t-muted` / `t-dim`. Arrows `a-default`, `a-emphasis` (hot path), `a-security` (dashed), `a-dashed` (async) - always set `stroke-width` and pair `marker-end="url(#arrowhead[-variant])"` with the matching class. Boundaries: `c-security-group` (dashed rose), `c-region` (dashed amber), `c-lane` (swimlane).
-
-Typography inherits JetBrains Mono from the SVG root. Sizes: 11-12px component names, 9px sublabels, 8px annotations, 7px tiny labels.
-
-### Hard layout rules
+Component fills `c-frontend`, `c-backend`, `c-database`, `c-cloud`, `c-security`, `c-messagebus`,
+`c-external`; text accents `t-<same>` plus `t-primary` / `t-muted` / `t-dim`. Arrows `a-default`,
+`a-emphasis` (hot path), `a-security` (dashed), `a-dashed` (async), each with an explicit
+`stroke-width` and a matching `marker-end="url(#arrowhead[-variant])"`. Boundaries:
+`c-security-group` (dashed rose), `c-region` (dashed amber), `c-lane`. Typography inherits JetBrains
+Mono from the SVG root: 11-12px component names, 9px sublabels, 8px annotations, 7px tiny labels.
 
-- **Two-rect pattern everywhere**: opaque `c-mask` rect first, styled `c-<type>` rect on top - semi-transparent fills otherwise let arrows bleed through.
-- **Arrows before components** in document order (SVG paints in order; arrows must sit behind boxes).
-- **Vertical stacking**: ≥40px gap between components; inline connectors (message buses, 20px tall) live inside the gap, never overlapping boxes.
-- **Boundary padding**: boundary `y` = inner `y` − 30, boundary `height` = inner `height` + 50, label baseline 18px below the boundary top.
-- **Legend placement**: outside ALL boundary boxes, ≥20px below the lowest one; grow the viewBox if needed.
+Hard layout rules: an opaque `c-mask` rect immediately before every styled `c-<type>` rect; all
+arrows before all component rects in document order; at least 40px vertical gap between components;
+boundary `y` = inner `y` - 30 and boundary `height` = inner `height` + 50 with the label baseline 18px
+below the boundary top; the legend outside every boundary and at least 20px below the lowest one.
 
-### Self-review checklist (run before delivering)
+Self-review before delivering:
 
-1. `grep -E 'fill="(#|rgb)|stroke="(#|rgb)' out.html` inside the SVG returns nothing except the template's own defs (Cardinal Rule).
+1. `grep -E 'fill="(#|rgb)|stroke="(#|rgb)' out.html` inside the SVG returns nothing but the
+   template's own defs.
 2. Every `c-<type>` rect has an identical-geometry `c-mask` rect immediately before it.
-3. All `<line>`/`<path>` arrows appear before all component rects in document order.
-4. Compute max(y + height) over all SVG elements: viewBox height must exceed it by ≥20px; same for x/width.
+3. All arrows appear before all component rects in document order.
+4. max(y + height) over all SVG elements is at least 20px inside the viewBox height; same for x.
 5. Legend y is below every boundary's y + height.
-6. The `.toolbar`, `<script>` blocks, and `:root` / `[data-theme]` CSS are untouched - they ARE the theme toggle and export menu.
+6. The `.toolbar`, `<script>` blocks, and `:root` / `[data-theme]` CSS are untouched. They are the
+   theme toggle, viewer, and export menu.
 
 ## Output
 
-A single self-contained `.html`: embedded CSS with local system font fallbacks, inline SVG, and embedded theme and export JavaScript. It renders directly in any modern browser without network access. Raster exports render natively at up to 4× the viewBox, with large diagrams stepping down to stay within canvas limits. SVG downloads are dual-theme, self-contained, and follow the host's `prefers-color-scheme` with an optional `svg[data-theme="..."]` override.
+Report the checked HTML path, the diagram type, the validation summary, the specification and
+artifact receipt, the browser-evidence status, and a truthful visual-review status. Never claim
+success for a non-zero command, and never claim a visual inspection you did not perform.