Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix: harden diagram authoring and delivery
tt-a1i3b5035f94760
diff --git a/archify.zip b/archify.zipindex 8fcda41e..be42159e 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 0451f221..31e7b355 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -1,6 +1,6 @@---name: archify-description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, semantic navigation, optional trace motion, an optional 1200×630 Share Card PNG, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, approval or CI/CD flows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid. Prefer typed JSON IR renderers and deterministic validation; deliver static output by default, enable motion only when requested, and use optional post-commit opening only for an interactive local handoff.+description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid.license: MITmetadata:version: "2.12"@@ -8,422 +8,96 @@ metadata:based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)----# Archify Skill+# Archify-Create professional technical diagrams as self-contained HTML files with inline SVG, a theme toggle, and a built-in image/SVG export menu.+Create a self-contained, interactive HTML diagram from a small typed JSON specification. Static output is the default; enable motion only when the user asks for a demo or presentation.## Fast authoring path-For an ordinary renderer-backed request with shell access, use this bounded path before reading the feature catalogue below:+Use this bounded path for ordinary generation. Do not read the optional Viewer Runtime reference unless the user asks about those features.-1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the user's question.-2. Read only one matching schema in `schemas/` and one matching JSON example in `examples/`. Use their field shapes, but author fresh domain facts, IDs, and layout.-3. Artifact first: after those reads finish, the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose, compare several layouts, inspect another example, or run CLI help first. Start with one clear main path, short side branches, 180–220 px horizontal spacing, 140–180 px branch spacing, sparse relationship labels, and at most 12 primary nodes; omit optional cards, views, and tags until validation passes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly asks for a dense `standard` engineering map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic explicitly calls for one; add at most one diagnosed geometry control per repair. Fresh authorship means new stable IDs, domain wording, and layout. When the requested roles naturally match an example, preserve the accurate topology instead of inventing a less accurate difference merely to look novel.- - Lifecycle only: phase columns `0..4` occupy the main rail; event and outcome columns `0..2` align under phase columns `2..4`. Put approval under execution at event column `0` and blocked-under-review at event column `1`. A recoverable state uses `type: "failure"` plus a real transition back to the active state; a card or view saying “retry” is not topology. Do not add reverse resume transitions for waiting states unless the requested lifecycle explicitly requires them.-4. Run `node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json` (or `standard` when the user explicitly wants a dense engineering map). Run it again after every candidate edit and immediately before handoff, even when an earlier iteration passed. A receipt with only 4 artifact checks is basic validation, never showcase acceptance; a showcase pass must report all 9 artifact checks with 0 composition errors and 0 warnings. If the candidate omits or misspells the exact `meta.quality_profile` field, fix that field before any geometry repair. A passing final validation freezes the candidate: never edit it afterward. When the requested output is a delivered HTML artifact, `deliver` is the final acceptance command: run `node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json` because it revalidates those frozen bytes before committing the output. A non-zero exit can never be described as success.-5. If validation fails, change only the diagnosed subject using its `supportedFixes`, then rerun. Continue focused correction while the objective error count reaches a new minimum. If two consecutive rounds do not improve that best count, or only trade a cleared error for a new one, stop and report the unresolved diagnostics truthfully.+1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.+2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts.+3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.+4. Validate after every candidate edit and immediately before handoff:-Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmark files before the first candidate. Inspect implementation only when validation returns an unsupported internal diagnostic or two focused repairs fail. Read the feature-specific sections below only when the user requests those capabilities; ordinary generation does not require understanding the viewer runtime.+ ```bash+ node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json+ ```-Every renderer-backed diagram ships with a factual Diagram Guide for discovering its current actions and shortcuts, deterministic semantic node hooks, a counted two-kind Semantic Lens with selective inline legend entrances, a fine-pointer/keyboard Intent Trace before committed focus, a two-endpoint Route Probe over authored directed relationships, a searchable Node Finder, keyboard-accessible one-hop focus with a renderer-owned Semantic Passport and copyable deep link, a live Semantic Radar overview, an optional Named Chapter Rail with static Chapter Delta Preview, a native Story Beat Navigator with Story Follow Camera, Story Director Strip, and Story Horizon, and stable Shareable Story Moment links, a reader-controlled Live/Still Motion Governor for trace artifacts, a viewer-only Share Chapter Cue for one-shot embeds, Presentation Stage, dependency-free pan/zoom, a **dark/light theme toggle** (persists in `localStorage`, respects `prefers-color-scheme`), an **export menu** (create, copy, or download a 1200×630 Share Card; copy full-diagram PNG to clipboard; download PNG/JPEG/WebP rasterized natively at up to 4× resolution; download a **dual-theme SVG**; record a trace-enabled diagram to WebM), and a **CSS-variable color system** that keeps both themes consistent. Temporary Diagram Guide, Semantic Lens, legend preview, Intent Trace, Route Probe, finder, focus, radar, Chapter Delta Preview, Story Trail overlays, Story Director Strip, Story Horizon, beat state, guided-view, playback, presentation, motion-owner, and viewport state never changes the canonical full-diagram export.+ A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase pass must report all 9 artifact checks with 0 composition errors and 0 warnings. If the candidate omits or misspells the exact `meta.quality_profile` field, fix it before geometry. A passing final validation freezes the candidate: never edit it afterward.+5. For a delivered HTML, `deliver` is the final acceptance command:-Offer the optional 1200×630 Share Card PNG when the user asks for a README, release, social, or launch preview. It uses the current theme and visual preset, contains the entire canonical diagram without cropping, and never claims validation; the checked HTML remains the source of any delivery receipt. When the browser supports image clipboard writes, Copy Share Card must reuse that same one-pass canonical PNG; unsupported readers retain the download action.+ ```bash+ node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json+ ```-Route Share Card is a reader-invoked optional export, never a default generation or delivery mode. When the user wants to share an incident path, request chain, dependency route, or PR explanation, offer the choice to resolve a Route Probe and use **Export → Route Share Card**; otherwise keep ordinary Share Card and canonical exports unchanged. The contextual Export item appears only after a real directed route resolves, reuses that exact ordered node and stable-edge snapshot without re-running pathfinding, preserves the full diagram as dimmed context, and downloads one 1200×630 PNG named `<diagram-base>-route-share-card.png`. It remains the shared Share Card seam (`Archify.exportMenu.shareCard({ variant: "route" })`) with `format=share-card` and `variant=route`; clear, unreachable, stale, or conflicting routes must fail closed. The isolated clone may use only static `data-share-route-*` decoration and must not include Journey position, animation overlays, camera, Focus, Lens, or Story state. Do not claim the route variant is canonical. This slice is download-only: do not promise Copy Route Share Card, a new format, schema, layout, dependency, URL, or storage surface.+ A non-zero exit can never be described as success. If validation fails, change only the diagnosed `subject`, verify `evidence`, choose from `supportedFixes`, and rerun. Continue focused correction 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.-Reach Share Card is the corresponding reader-invoked export for an active **authored reachability** query. When the user wants to explain what authored relationships lead into a component or continue from it, focus that node, choose `Upstream` or `Downstream`, then offer **Export → Reach Share Card**. The item must remain hidden unless a non-empty reach result is active. It consumes the already resolved node IDs, stable edge keys, minimum depths, origin, direction, and maximum hops without running BFS again; stale, duplicate, conflicting, empty, or tampered DOM state fails closed. The shared 1200×630 seam is `Archify.exportMenu.shareCard({ variant: "reach" })`, with `format=share-card`, `variant=reach`, `canonical=false`, and an independent reach-state-clean receipt. The clone may use only static `data-share-reach-*` decoration, keeps the complete diagram as dimmed context, labels the header `Authored upstream/downstream`, and downloads `<diagram-base>-<direction>-reach-share-card.png`. Never call the asset impact, blast radius, breakage, or runtime causality. This is download-only and adds no copy action, format, schema, parser, layout, dependency, URL, storage, hosted service, or mobile product surface.+Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for an unsupported internal diagnostic or after two focused repairs fail.-Reading Depth progressively reveals renderer-owned context and fine detail as the reader zooms, while semantic interactions reveal the exact local facts they need at any scale.+Lifecycle note: phase columns `0..4` occupy the main rail; event/outcome columns `0..2` align beneath later phases. A recoverable state uses `type: "failure"` plus a real transition back to the active state.-Direct Relationship Pin makes every unique compiled relationship directly operable without changing the authored line. Give important `connections`, `edges`, `messages`, `flows`, and `transitions` an optional author-controlled `id` using the normal identifier pattern; IDs must be unique within their relationship collection. The renderer keeps its numeric `data-edge-key` for runtime de-duplication and emits the author identity separately as `data-edge-id`. At runtime, reject conflicting source/target/label/ID metadata and clone only path/line/polyline geometry into one viewer-owned overlay below nodes. Use a transparent 24px non-scaling stroke for hit testing plus a separate dashed focus rail; keep exactly one relationship button at `tabindex="0"` and move roving focus with all Arrow keys, Home, and End. Fine-pointer hover and keyboard focus reuse exact Relationship Preview transiently. Click, tap, Enter, or Space opens the source Semantic Passport and pins the exact existing Lens row. When the relationship has an authored ID, the pin writes `#relation=<id>`, changes the action to `Copy relation`, and restores the same source, target, label, path, and bounded camera after reordering; stale IDs fail closed. An ID-less legacy relationship remains an in-page pin, keeps `Copy node`, and never exposes its numeric key. The same relationship, a true background activation, Clear, or Escape clears it. `aria-pressed` conveys the pin while the source/target/label name stays stable. Touch never waits for hover, nodes win near endpoints, panning never activates a relation, and stronger Focus, Story, Route, Semantic Lens, Chapter, and embed states take priority. Do not add another panel, toolbar action, dependency, storage, or authored geometry. Remove all hit, pin, preview, and pulse state from embed, print, and canonical export; preserve the authored `data-edge-id` as semantic SVG identity.+## Type router-## Setup+| Type | Use for |+|---|---|+| `architecture` | Components, services, cloud/security boundaries, infrastructure |+| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD |+| `sequence` | API call chains, request lifecycles, async traces, returns |+| `dataflow` | Pipelines, ETL/ELT, lineage, governance, consumers |+| `lifecycle` | State/status transitions, retries, waiting and terminal states |-No dependency installation is required. The distributed skill includes standalone validators compiled from all five JSON Schemas, so schema and layout validation work immediately after installation. The generated HTML and the renderer runtime are both dependency-free.+When ambiguous, run `node bin/archify.mjs guide "<scenario>" --json`. Scenario proof examples are structural references, not facts to copy.-Run `node bin/archify.mjs doctor` to verify an installation. Run `node bin/archify.mjs demo [output-directory]` to generate a ready-to-open example before creating the first custom diagram.+## Mermaid input-If you have no shell access at all (e.g. the skill was added as project knowledge), fall back to architecture mode for every request: hand-place SVG into `assets/template.html` following the Design System below, and run the self-review checklist before delivering.+Read Mermaid for topology and meaning, then author fresh Archify JSON; do not mechanically render Mermaid styling.-## Choosing a Diagram Type+- `flowchart` / `graph` → `workflow`, or `architecture` for a component map.+- `sequenceDiagram` → `sequence`; participants become semantic participants and arrows become messages.+- `stateDiagram` → `lifecycle`; states and transitions retain meaning, not Mermaid style.-When the request is ambiguous, run `node bin/archify.mjs guide "<the user's scenario>"` before choosing a renderer. The bundled zero-dependency guide selects one of 11 bounded scenario recipes and returns the question answered, when to use or avoid it, required evidence, presentation settings, and a copy-ready prompt. `--json` provides the same contract for automation, and `--lang en|zh` overrides language detection. Use the recommendation as a starting point, then verify it against the user's actual question and repository evidence.+## Authoring invariants-Every bundled scenario recipe is backed by a checked-in, validated example in `examples/` and a generated Proof Lab card. Use those examples as structural references rather than copying their domain facts. When changing a recipe or proof example in the repository, regenerate both `docs/guide.html` and `docs/gallery.html`; tests enforce that all 11 recipe proof IDs resolve and that each proof retains three named reader views.+- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.+- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.+- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; otherwise omit the label or move it deliberately.+- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.+- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn.+- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.-| 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 |+Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.-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`.+## Delivery-## Mermaid as an Input Dialect+Use `validate` during repair and `deliver` once for final acceptance. Delivery freezes the exact 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.-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 archify mode:--| Mermaid | Archify 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)--Archify'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.--Worked examples on this pattern: `examples/web-app.architecture.json` (bounded application map) and `examples/production-deployment.architecture.json` (larger ownership and trust-boundary map).--When validation fails on label overlap, read the **Suggested fix** lines (coordinates / `labelAt` / `labelDy`) and apply them directly — do not guess offsets blindly.--## Renderer Modes (architecture / workflow / sequence / dataflow / lifecycle)--All five modes follow the same loop:--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. Preflight while iterating: `node bin/archify.mjs validate <type> <input>.json --json`, explicitly adding `--quality standard` for dense engineering diagrams or `--quality showcase` for polished delivery. Success and failure both produce exactly one JSON object. On failure, consume `diagnostics[]`: use the stable `code`, change only the named `subject`, verify the measured `evidence`, and choose only from `supportedFixes`. Never infer an unsupported field or rewrite the whole graph from the free-text `error`. Use `render` plus `check` separately only when diagnosing a candidate.-4. When the user wants an active desktop authoring loop, offer the optional `node bin/archify.mjs preview <type> <input>.json <output>.html --quality <profile>` command. It opens one loopback-only status shell and watches that single explicit source; each stable content digest is bound to an immutable private snapshot, that snapshot runs through the existing verified delivery pipeline, and the named source digest is checked again immediately before atomic commit so only the latest fully passing candidate advances the browser revision. Invalid, half-written, deleted, or superseded input reports its real stage while the previous verified revision remains on screen and on disk. Identical source bytes do not rebuild, identical artifact bytes do not reload, and input/output aliases must fail before watching or commit. Preview is explicit and interactive: never start it by default for one-shot requests, CI, unattended agents, remote sharing, or mobile use; use `--no-open` only when the user will open the printed URL themselves or automation is testing the loop. Stop it with Ctrl-C before final handoff; shutdown may drain an active delivery only for a bounded grace period and must terminate a stuck child before removing private state. Its local server, generation state, diagnostics, source path, and port must never enter the generated artifact or any export.-5. Commit the final artifact with `node bin/archify.mjs deliver <type> <input>.json <output>.html --json` and the chosen `--quality`. Deliver renders a unique same-directory candidate, runs the complete artifact checker, computes the exact byte count and SHA-256 receipt, and only replaces the target after all artifact checks pass. Add `--open` only when the user wants an immediate local preview of that one-shot delivery: it runs after that atomic commit, uses one argument-array OS opener with a five-second bound, and records `open.status` without changing delivery success when opening fails or is unsupported. Keep it off for CI, unattended agents, and non-interactive environments. Renderer, checker, receipt, or commit failure returns non-zero, removes the candidate, preserves the previous target unchanged, and never invokes an opener.-6. If any step fails, the repair receipt names the JSON path or subject, rule code, measured evidence, and supported fix (thresholds, valid ranges, which knob to change). Apply one local repair and re-run; never edit the renderer, never treat an empty `supportedFixes` list as permission to guess, and never exceed the two focused correction rounds below.--Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. In JSON mode the same fact is a `schema/<keyword>` diagnostic. Input, repository-evidence, shared Clean Flow, composition, artifact-check, and delivery failures use the same additive `schemaVersion: 1` repair contract; an `internal/unclassified` diagnostic has no supported repair and must be reported rather than guessed through. The renderers additionally fail fast on established 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, and legends outside the viewBox. A relationship passing through an unrelated opaque semantic node is always a hard correctness failure, even when neither `meta.quality_profile` nor CLI `--quality` is present: paint order must never make one authored relationship look like a different topology. The shared Clean Flow Gate reports `clean-flow/edge-through-node`, the exact collection/index and optional relationship ID, obstacle ID, first intersecting segment, 2px clearance, and supported routing/placement knobs before output is written. Stricter composition preferences remain profile-aware. For new or edited work, choose `standard` or `showcase` explicitly; structural container-border rules apply to both explicit profiles, unrelated proper X crossings and unrelated collinear overlaps of at least 8px warn in `standard` and fail in `showcase`, and showcase also fails any sub-8px route segment and sub-16px interior turn while preserving ordinary 8–15px endpoint stubs. The Clean Label Gate measures each renderer's actual relationship-label mask against every other authored route: sub-2px clearance is a `standard` warning, while sub-4px clearance fails `showcase` before write and in the final artifact check. A label's own relationship fragments are exempt, but shared source/target fan-out is not; fix with `labelAt`, `labelDx`/`labelDy`, `labelSegment`, route/via/channel controls, or message `y` in sequence diagrams. Collinear corridors are not proper crossings; the separate `composition/ambiguous-corridor` rule exempts relationships with a shared semantic endpoint, point touches, and overlaps below 8px. Source/target boxes are endpoints; boundaries, lanes, stages, lifecycle bands, sequence segments/lifelines/activations, and other containers remain intentional pass-through geometry. CJK text is measured at double width automatically.--Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle diagrams. When two or more eligible automatic relationships share one node-side midpoint, assign deterministic, symmetric edge ports ordered by the opposite endpoint, while preserving a 16px corner gutter. It does not apply to sequence messages, a single relationship, or any relationship with explicit `via`, `channelX`, `channelY`, `labelAt`, or a non-`auto` route; authored geometry always wins. This is bounded endpoint separation, not a graph layout engine, and it must not change topology, schema, labels, presets, viewer state, or export behavior.--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 plus one explicit 44px `Live` / `Still` Motion Governor. Ambient scan, edge, and node motion must run one finite pass, permanently settle for that document generation, and restore every authored solid/security/async dash style; switching `Still` back to `Live` must not replay it. Story, Chapter, Route, Lens, Relationship Preview, Intent Trace, Focus, and Legend remain stronger semantic owners. `Still` must reset every effect to complete static meaning, pause active Story playback at its exact beat, persist the reader choice when storage is available, and never auto-resume playback. Dynamic `prefers-reduced-motion` and page hiding use the same stop path. Static artifacts must never start decorative motion or show the control; embed remains calm unless `?play=1` explicitly requests one bounded chapter. Route Probe uses one finite signal and then leaves the exact route static. Canonical SVG and raster exports remain still; only the isolated WebM clone may explicitly opt into the repeatable finite trace timeline. Motion ownership is viewer-only, tokenized for stale-safe cleanup, and never enters schema, IR, renderer layout, or authored geometry.--Use `meta.views` when one overview needs a short, curated reading sequence. Each view is a label plus a set of existing semantic node IDs; it never changes layout, geometry, or styling. Keep the collection intentionally small (maximum five):--```json-"views": [- {- "id": "request-path",- "label": "Request to result",- "focus": ["user", "api", "worker", "result"],- "note": "Follow the successful request through the system."- }-]-```--Generated HTML exposes Play/Pause, previous/next/overview controls, <kbd>P</kbd> playback, <kbd>[</kbd>/<kbd>]</kbd> manual chapter navigation, and shareable `#view=<id>` links. Before any chapter is active, use the existing `data-active-view="all"` state as Story Shelf: establish it before the panel is unhidden, keep the compact guided identity, Play, and every authored chapter visible with 44px targets, but hide Previous/Next, Copy moment, Show all, and the generic instructional note. Chapter activation, Play, or valid deep-link restoration must expand the full existing Director in the same task; Show all and the existing Escape unwind must return to the shelf. Do not add a disclosure control, second component, storage preference, query parameter, schema field, or playback owner. It also builds a Named Chapter Rail from the same `meta.views` array: every native button shows a two-digit authored position and the exact label. From overview, candidates show `=0 +focus.length −0`; after activation, the current button shows its stop count and every other candidate shows exact `=stay +enter −leave` focus membership. The rail must never own parallel selection state; it mirrors `activeIndex`, delegates activation to the existing guided-view path, and uses a single roving tab stop. Left/Right/Home/End move focus only and apply one static Chapter Delta Preview over existing stable-ID nodes; they must not change selection, camera, Story Trail/Beat, URL, contained scroll, `aria-current`, or `aria-pressed`. Native Enter/Space activates; Escape dismisses only the preview and preserves focus; touch activates on the first tap without a preview latch. Rail preview pauses playback and must not auto-restart it. Mark current, before, after, stay, enter, and leave with structural/text cues as well as color. On narrow screens use contained horizontal scroll/snap, at least 44px targets, and immediate centering of the active chapter without widening the page. Keep the entire rail out of embed and print output.--The ordered `focus` list becomes Story Beat Navigator. Render every resolved stop as a native button with its two-digit position, node label, at least a 24px desktop target and a 32px mobile target. Click, first tap, Enter, or Space pauses playback and pins exactly that beat; keyboard focus pauses at the existing playhead but must not select a different beat. Exactly one active stop carries `aria-current="step"`, and selecting it must not change `activeIndex`, chapter focus IDs, chapter-rail current state, URL/history, diagram/page scroll, layout, or authored data. Classify only the exact stable-ID relationship between the immediately previous and current stop: one previous→current edge is `forward` and renders `→`; one current→previous edge is `reverse` and renders `←`; no direct edge is `group` and renders `·`; more than one or bidirectional exact edge is `multiple` and renders `⇄`. Never infer a path from nonconsecutive internal edges, labels, geometry, proximity, kinds, or Story order. A manual forward/reverse beat may run one finite marker-free exact-edge signal in Live; group/multiple stay static, and Still/reduced motion keeps the complete static meaning. One generation-owned scheduler uses `max(1100ms, 3200ms / stopCount)` dwell, preserves elapsed dwell on pause, resumes the remaining dwell from the same beat, and starts the next chapter only after Shared Anchor Handoff settles. Replacement, hidden state, print, reduced motion, and teardown invalidate stale callbacks and pulses without corrupting the selected static beat. Choose a meaningful authored order even for thematic subgraphs.--Story Follow Camera reuses the existing Semantic Camera only after reader-started playback or deliberate beat activation. Frame current + next at the first stop, previous + current + next in the middle, and previous + current at the last stop; use exact stable IDs only, 64px padding, a 1.65× maximum scale, and one finite 320ms transaction. The camera must settle before the 1100ms minimum dwell expires. Pause, replacement, overview, manual pan/zoom, hidden/print state, and stale camera receipts clear follow ownership. `Still` and reduced motion disable automatic Story Play but keep manual beat inspection as an instant frame. Exact `#view=&beat=` restoration may defer one animation frame until the shared camera exists, then restores paused with no pulse or autoplay. Do not follow an ordinary embed unless `?play=1` explicitly requests playback. Keep follow attributes and transforms out of canonical export, and add no panel, schema, IR, renderer layout, dependency, storage, cloned foreground graph, or authored geometry.--Semantic Story Carrier reuses Relationship Preview's five compiled token kinds on Story Beat's existing finite 780ms exact-edge pulse. Before classifying a step, deduplicate SVG path and label fragments by stable `data-edge-key`, preferring the fragment that owns drawable path/line/polyline geometry; never let a label duplicate turn one authored relationship into `multiple`. Only one unambiguous forward/reverse edge may create the carrier, and it must follow that edge's real source-to-target geometry in a viewer-only overlay above authored edges and below semantic nodes. Reuse the current Story motion owner and a generation receipt so stale `animationend` callbacks cannot clear a newer beat. Ordinary desktop artifacts and explicit `?play=1` playback may animate; passive embeds, Still, reduced motion, hidden/print state, and canonical/raster export remain static. This is not a mobile product feature: narrow layouts receive containment only. Add no schema, IR, renderer branch, layout change, dependency, replay control, timer, authored geometry, or second animation system.--Story Director Strip narrates that frame outside the canonical SVG. For every active beat, show `NN / NN`, the exact previous/current node route, up to three distinct authored `data-edge-label` values, and the current node's existing responsibility/context. Reuse only Story Beat's `start / forward / reverse / multiple / group` result. A group must say `Grouped transition · no direct authored link`; reverse must name the real authored direction; missing labels may say only `Authored relationship`. Never infer a verb, transitive route, or relationship from geometry, proximity, kinds, or story order. Autoplay uses `aria-live="off"`; paused, manual, and exact-link states use `polite`. Live mode may use one 140ms caption entrance, while Still and reduced motion are immediate. On desktop Presentation playback, hide only the chapter rail, Story Trail, Copy moment, Show all, and redundant title/note; keep Previous, Next, Pause, position, route, and facts visible, then restore the complete controls on pause. Mobile keeps its two-line caption and 44px controls. Ordinary embed, print, and canonical export exclude the strip. Add no schema, IR, renderer layout, dependency, storage, authored geometry, or parallel story state.--Story Horizon completes that story state as `past / active / next / pending`. `next` means exactly `storyBeatIndex + 1`: at most one real next node and the exact already-resolved connector set owned by that next step. Forward and reverse preserve authored direction; multiple preserves every real connector; grouped previews only its real node and never invents a link. Use static opacity/saturation hierarchy (`active > past > next > pending`) without early camera movement, pulsing, cloned topology, or another live announcement. The final beat has no horizon. The Director Strip may name the next node only inside its existing desktop footprint; mobile adds no row. Rapid changes atomically replace state. Still and reduced motion preserve the same static meaning. Clear Horizon on overview, chapter replacement, takeover, teardown, print, and export. Add no schema, IR, renderer layout, dependency, storage, edge rewrite, or authored geometry.--Every active beat also enables one viewer-only **Copy moment** action. It produces `#view=<view-id>&beat=<stable-node-id>` from the current chapter and authored node identity; never use a numeric beat index, label, camera transform, layout coordinate, or serialized viewer state. Copying during playback first pauses at the visible beat and removes `play=1` from the copied URL. Static restoration activates the chapter, waits for the winning Shared Anchor Handoff, rechecks the current hash and generation, then selects the exact matching stop with no pulse, autoplay, focus move, or URL rewrite. A missing, stale, duplicate-context, or cross-chapter beat fails closed to the valid chapter. Manual beat activation and automatic playback do not mutate the URL. Expose only read-only `beatLink()` / `copyBeatLink()` receipts; add no storage, schema, IR, dependency, server, or canonical SVG state.--For a share-ready one-shot chapter, use `?play=1#view=<id>`: it plays only that named view once on the same readable per-beat cadence, never auto-advances, then stays still and readable. Add `&beat=<stable-node-id>` only to start at that exact authored stop and play the remaining beats once. In embed mode, a Share Chapter Cue names the view, derives its exact route from the same Story Trail stops, reports the current `Step NN / NN` plus Ready/Playing/Settled/Paused/Still state, and freezes its node, edge, and progress at the actual interruption point. A static `?embed=1#view=<id>&beat=<node-id>` reuses that same cue as a truthful `Pinned` receipt and never starts motion. It is an HTML viewer layer outside SVG geometry and canonical exports; narrow screens reserve a top band so it cannot cover nodes. With no hash it activates the first authored view. It does not run when `prefers-reduced-motion: reduce` matches. Both playback modes pause when the page is hidden and yield immediately when the reader explores a node, changes the view, zooms, or pans. Embed mode pauses ambient trace loops, so Proof Lab grids remain static unless a named one-shot chapter is requested. View IDs must be unique, focus lists cannot be empty or contain duplicates, and every focus ID must exist in that diagram's semantic collection (`components`, `nodes`, `participants`, or `states`).--For every real chapter-to-chapter change, compute continuity only from exact stable IDs shared by the outgoing and destination `focus` lists. Prefer the active Story Beat when it is shared; otherwise use the latest shared outgoing stop. Shared Anchor Handoff keeps that node's screen position fixed through a short orientation hold, shows one viewer-only `NN → NN · via <node>` receipt and ring, then settles the existing bounded Semantic Camera through one interruptible finite transaction. If no ID is shared, publish `no-anchor`, omit the ring, and retarget without guessing from labels, geometry, kinds, or relationships. New navigation replaces the current generation; manual pan/zoom samples the rendered position and takes over without a snap; Story dwell begins only after the winning transaction settles. Still, dynamic reduced motion, hidden pages, ordinary embeds, print, and canonical exports must synchronously reach a complete clean destination. Add no transition fields, cloned graph, layout motion, dependency, or canonical SVG state.--Compute Chapter Delta Preview and Shared Anchor Handoff from one normalized helper only: `stay` is the current focus in authored order intersected with the candidate, `leave` is the remaining current focus, and `enter` is the candidate focus in authored order absent from current. Only unique IDs present in the canonical SVG may count. Preview is instantaneous presentation state, not partial activation: it may write only the root candidate ID, node membership roles, candidate-button preview state, compact counts, and a tokenized static `chapter-preview` motion owner. Pointer and focus intents arbitrate independently with latest valid intent winning; a stronger Route, Lens, Legend, Relationship, or Intent owner defers preview without being cleared. Hidden/print/activation/Show All/hash/direct-node cleanup is atomic, export clones strip every preview attribute, and returning visibility or Live must never restore a stale preview. Never add an overlay, clone, edge diff, camera call, first-tap mobile preview, schema field, or model-change wording such as “nodes added/removed.”--The viewer also includes a zero-dependency Presentation Stage. Press <kbd>F</kbd> or use the Present toolbar action to make the live diagram fill the viewport while retaining theme, guided-story, focus, and pan/zoom controls. Use `?present=1&play=1#view=<id>` for a shareable live slide that demonstrates itself once and then becomes a stable reading surface. <kbd>Escape</kbd> clears an active guided view or semantic focus first, then exits the stage. This is an HTML viewing mode only: never change the typed input, SVG geometry, or canonical export to implement it.--Reading Depth is the shared viewer's progressive semantic-zoom contract. Renderers—not inferred pixel geometry—mark responsibility sublabels and relationship labels with `data-detail="context"`, mark authored tags, steps, notes, and classifications with `data-detail="fine"`, and leave primary labels always visible. The viewer reports `MAP` below 125%, `READ` from 125% to below 175%, and `FULL` from 175% upward. Committed focus, Semantic Lens, Intent Trace, Route Probe, Story Trail, and Relationship Preview must reveal the exact matched detail regardless of zoom. Print and canonical exports always contain complete detail, reduced-motion removes detail transitions, and this contract must never add schema or JSON IR fields.--Press <kbd>?</kbd> or use the question-mark control to open Diagram Guide. It must derive exact semantic node and relationship counts from stable compiled hooks and take guided-view count from the existing runtime. Its six primary rows—Find, Route, Radar, Lens, Story, and Presentation—delegate to those existing interactions; do not create a second command implementation. Disable Story honestly when no guided views exist. Arrow keys, Home, End, the named direct shortcuts, and Escape must work inside the panel. Opening the guide pauses story playback and closes overlapping Finder, Radar, Lens, and export panels without clearing focus or an in-progress route; narrow screens temporarily recede the Route receipt. Keep the guide out of embed, print, and canonical SVG export, and never add guide fields to JSON IR.--Press <kbd>/</kbd> or use the diagram's finder control to search any rendered node by label, responsibility sublabel, structural context, authored tag, semantic kind, or stable ID. Results report that same context plus relationship count; selecting one exits a guided view, resets the viewport, reveals the node on a contained mobile diagram, and enters the existing `#focus=<id>` one-hop view. While Route Probe is choosing an endpoint, the same control becomes a contextual route picker instead: source results include only nodes with a real authored outgoing route, destination results include only nodes reachable from the current source, and each destination previews its shortest directed hop count. Escape closes Finder while preserving the route question. Single-node focus opens Semantic Passport above Relationship Lens: it must show kind, sublabel, structural context, optional tag, and stable ID from renderer-owned SVG attributes, plus a dependency-free `Copy link` action for the existing focus URL. On narrow screens, keep the relationship list collapsed behind its exact count and place the compact Passport above or below the selected node; following a relationship collapses the next Passport again. Architecture context comes from authored boundary `wraps`; workflow context from lane/group/phase; sequence context from participant role; data-flow context from stage; lifecycle context from lane. Never infer scope from pixel proximity. Finder and Passport require no new input fields and must never be hand-authored as viewer markup in JSON IR.--Semantic Passport also exposes **Authored Reach** for its focused node. `Upstream` walks only incoming `data-edge-from` → `data-edge-to` relationships; `Downstream` walks only outgoing relationships. Use deterministic unweighted BFS in authored DOM edge order, deduplicate relationship fragments by stable edge key, assign minimum hop depth, terminate cycles, and report reachable node count, exact in-scope relationship count, and maximum hop depth. The result may be called upstream/downstream authored reachability, never blast radius, breakage, runtime causality, or repository impact. Keep the focused origin and every reachable authored node/relationship readable while unrelated topology recedes; do not move geometry, clone paths, or add motion. The two native buttons are keyboard-accessible, disabled honestly at zero reach, toggle off on repeated activation, and restore from `#focus=<id>&reach=upstream|downstream`; the existing Copy link includes the active direction. A new focus, clear, relation follow, route, lens, or story takeover removes the state deterministically. Classic, Signal Flow, Blueprint, dark, and light preserve the same semantics; Blueprint has no glow. Print and canonical SVG/raster/Share Card/WebM export remove all reach attributes. Add no schema, IR, renderer layout, parser, inferred edge, dependency, hosted runtime, permanent panel, toolbar control, or dedicated mobile surface.--Relationship Lens rows are the accessible target for exact-edge Relationship Preview. On one true fine-pointer entry or keyboard `focusin`, resolve exactly one stable `data-edge-key`, preserve authored source-to-target direction even for incoming rows, and clone only its path/line/polyline geometry into one marker-free, pointer-free, `aria-hidden` overlay with `pathLength="1"`. Play one 1.2-second pass and carry exactly one compact semantic token along the same geometry: security edge/endpoint evidence wins, then dashed/message-bus event evidence, database data evidence, waiting/success lifecycle state evidence, and otherwise a call cue. Use only compiled variants and renderer-owned stable kinds—never labels, product names, or geometry. Then remove the complete overlay while leaving the exact original edge plus source/target emphasis readable. A parked pointer or focus must not loop or restart from child bubbling; row re-entry or re-focus may replay. Narrow screens reuse the contained fallback and are not a dedicated product surface. Replacement, preview exit, Focus clear, Escape, stronger viewer ownership, page hiding, `animationend`, `animationcancel`, and a live switch to reduced motion must leave zero overlays. Classic, Signal Flow, and Blueprint may style the signal differently without changing timing or geometry; Blueprint has no glow. Never add replay controls, nested row actions, timers, schema/IR fields, renderer layout, dependencies, or motion to embed, print, canonical SVG, or raster export.--Press <kbd>M</kbd> or use the `MAP` control to open Semantic Radar. It must derive a simplified, type-colored overview from each rendered node's stable ID, `data-node-kind`, and runtime `getBBox()`; never clone the canonical SVG or add radar fields to JSON IR. Its viewport rectangle follows desktop transform zoom/pan and contained mobile horizontal scroll. Radar node click/Enter/Space delegates to the same semantic focus and camera, while background drag/click and Arrow keys recenter the current view. The open radar docks only while the diagram intersects the window, chooses the opposite horizontal side from the focused node, and searches for a vertical slot that avoids the node and visible Passport when space permits. On contained mobile diagrams, report the actual visible width rather than claiming a zoom percentage. Escape closes the radar before clearing focus. Keep the radar out of embed, print, static HTML SVG counts, and canonical exports by constructing its small SVG at runtime.--Inline legend interaction is selective, not automatic. Add `data-legend-bridge` and exact `data-legend-kind` rows only when one legend row means precisely one renderer-owned node kind: every dynamically used architecture component type; workflow frontend, backend, security, messagebus, and database rows; lifecycle active, waiting, success, and failure rows. Keep sequence edge-variant legends and data-flow mixed node/edge legends static. The viewer derives counts from the same compiled node facts as Semantic Lens, adds hit targets and badges only at runtime, exposes a roving toolbar/group for positive-count rows, and keeps zero-count rows visibly non-actionable. Fine-pointer hover or keyboard focus may softly preview exact nodes, touching authored relationships, and connected peers without flow animation; touch, click, Enter, and Space activate the existing Lens directly. Selected rows need a non-color cue. Active Lens, focus, route, story, presentation, Relationship Preview, and other stronger owners suppress the preview. Embed skips decoration; print and canonical export remove every runtime role, badge, hit target, selection, and preview marker. Never duplicate kind counts in a renderer or add legend schema, JSON IR, graph-copy, or dependency surface.--Press <kbd>L</kbd> or use the `LENS` control to compare compiled node kinds. Derive chips and exact counts only from stable `data-node-kind`; never hard-code a renderer-specific category list. Permit at most two selected kinds. One selected kind keeps its nodes and all touching relationships strong while connected peer endpoints remain contextual; two selected kinds keep only their direct authored cross-kind relationships strong and report both directions separately. Count nodes by stable ID and relationships once by stable edge key. After an explicit selection, Semantic Flow clones only the exact matched path/line/polyline geometry into a marker-free, pointer-free, `aria-hidden` runtime overlay: one-kind traffic distinguishes outgoing, incoming, and within-kind direction, while two-kind traffic distinguishes authored forward and reverse flow. Run one short pass, then leave the complete static Lens selection readable; passive pointer or keyboard focus must not create an infinite loop. Keep nodes, labels, camera, and original edges fixed; preserve preset identity, make reduced motion static, suppress flow above 24 matched edges, and omit the overlay in embed, print, and canonical export. Unrelated content must recede softly without being hidden, moved, rerouted, or removed from fitting. Closing the panel preserves the pinned state, `#lens=<kind>~<kind>` restores it, and Escape closes the panel before clearing the lens. Focus, Route Probe, and Story Trail clear Lens before taking ownership; active Lens suppresses Intent Trace. Matching renderer-owned Reading Depth detail remains visible. Add no schema, IR, renderer layout, graph-copy, or dependency surface.--Before a node is committed to focus, the shared viewer provides Intent Trace. Fine-pointer hover and keyboard focus must derive exactly the node's one-hop incoming, outgoing, and self-loop relationships from stable `data-edge-from`, `data-edge-to`, and `data-edge-key` hooks. Unrelated topology may recede, but authored edges, markers, dash patterns, labels, and geometry remain unchanged. The directional signal is a runtime-only clone of path/line/polyline geometry with markers and semantic attributes removed and `pathLength="1"` for a consistent rhythm. Touch skips the preview and retains one-tap focus. Active embed/story/focus/relationship-preview/pan state suppresses it, `prefers-reduced-motion` replaces movement with a static highlight, keyboard focus announces exact connection counts, and click/Enter/Space clears the temporary state before Semantic Passport takes ownership. Never add Intent Trace fields to JSON IR or include its overlay in canonical exports.--Press <kbd>R</kbd> or use `PATH` to open Route Probe. If one node is already focused it becomes the source; otherwise choose a source directly on the semantic SVG or through contextual Finder, then choose a highlighted reachable destination on-canvas or from the same search surface. Finder must omit dead-end sources, filter destinations by authored reachability, preview their shortest directed hop count, and keep the in-progress route when Finder closes. Traverse only `data-edge-from` → `data-edge-to`, ignore self-loops for two-endpoint routing, and use deterministic unweighted BFS in authored DOM edge order. The result must be the fewest real directed hops, keep exact ordered node and edge identity, frame only that route with Semantic Camera, and expose a compact node/hop receipt plus `#route=<source>~<target>` copy link. Never invent edge weights, fall back to an undirected path, mutate layout, or add route fields to JSON IR. Endpoint selection must work by pointer, Enter/Space, and Finder handoff. `prefers-reduced-motion` keeps the same static result; embed and print omit the control; canonical exports remove route state, step/candidate attributes, and cloned `pathLength="1"` signal geometry.--After Route Probe resolves, expose Route Journey over the existing ordered `activeNodeIds` and exact `activeEdges`; do not build a second graph. Render every receipt stop as a native button with one roving Tab stop and add Previous, Next, Journey/Pause/Replay, and Overview controls. The full route stays visible. Position zero owns the source and no incoming edge; position `i > 0` owns exactly `activeEdges[i - 1]`, which alone may emit one finite 780ms marker-free signal. Manual activation pauses playback, while arrows/Home/End move focus and Enter/Space selects. Playback must start only from deliberate Play activation, run one finite pass, preserve the remaining dwell when paused, and reject stale timers with a generation token. Manual pan/zoom, path focus, Diagram Guide, Motion Still, dynamic reduced motion, page hiding, and print pause it without auto-resume. Use Semantic Camera to frame previous/current/next; manual inspection remains available without motion. Escape layers as pause → Overview → clear. Keep `#route=<source>~<target>` endpoint-only and restore to Overview without autoplay. Mobile controls need 44px targets; embed, print, canonical export, schema, IR, layout, dependencies, storage, and authored SVG geometry remain unchanged.--Choose the authored `meta.visual_preset` with the user by audience, without changing diagram geometry: use `"signal-flow"` for a striking demo or motion-forward presentation; use `"blueprint"` for deployment maps, infrastructure handoffs, and drafting-style technical documentation; use `"editorial"` for warm publication-style design reviews, launch notes, and narrative documentation; omit it (or use `"classic"`) for the stable default visual language. If the user has no preference, keep Classic rather than guessing. In the generated artifact, `Style` opens a direct four-option picker for Classic, Flow, Blueprint, and Editorial over the exact same topology; <kbd>S</kbd> remains the fast cycle shortcut. This session-only choice updates the canonical SVG and therefore deliberate exports, but never rewrites source JSON, persists a preference, changes the URL, or runs in a passive embed. Every preset supports both themes. WebM export appears only for trace-enabled diagrams and records six seconds directly in a supporting browser.--For Architecture deployment reviews, choose `meta.engineering_profile: "deployment-ownership"` only after the user explicitly asks for a fail-closed deployment contract. Ordinary Architecture diagrams omit it. The profile requires every non-external component to name its owner in `tag` and belong to exactly one `region`; at least one `region` and one `security-group`; every `database` inside a security group; every security group contained within one shared region; and every connection that changes region/security-group membership to name its real boundary-crossing mechanism in `label`. It validates authored facts only. Never infer owners, regions, private placement, or crossing mechanisms, and never describe a passing profile as live-infrastructure or repository verification. `quality_profile` governs visual composition; `engineering_profile` governs this optional deployment contract.--Architecture Delta is also optional and never part of ordinary generation. Offer it when the user asks what changed between two existing Architecture snapshots, wants a design-review artifact, or wants authored architecture context for a PR. First ask the user to identify the exact base and head JSON files; do not choose a baseline silently. Explain that every `connection` on both sides needs a unique authored `id`, then run `node bin/archify.mjs compare architecture <base.json> <head.json> [output.html] --json`. Never add relationship IDs by matching labels or endpoints, and never interpret a changed ID as a rename. The command validates both snapshots independently, fails closed when they share no component ID or name different repositories, then produces deterministic Before / Delta / After HTML plus a sidecar receipt. The result opens as a static overview; each validated row can focus its exact authored component, relationship, or boundary ID, and the reader may deliberately start one finite Review pass. This navigator is viewer-only, never changes the receipt or URL, leaves manual navigation available under reduced motion, and disables itself when DOM identity is missing, duplicated, or conflicting. Describe the result as an authored snapshot comparison (or revision-pinned inputs only when repository evidence passed on both sides), never as blast radius, risk, safety, mergeability, or verified PR impact.--### Workflow--```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": [- { "id": "pr-to-build", "from": "pr", "to": "build", "label": "webhook", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" }- ],- "cards": []-}-```--**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": [- { "id": "request-data", "from": "web", "to": "api", "y": 200, "label": "GET /data", "variant": "emphasis" },- { "id": "return-data", "from": "api", "to": "web", "y": 290, "label": "200 JSON", "variant": "return" }- ],- "activations": [ { "participant": "api", "from": 190, "to": 300, "type": "backend" } ],- "cards": []-}-```--**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": [- { "id": "web-events", "from": "web", "to": "kafka", "label": "events", "classification": "PII touch", "variant": "emphasis" }- ],- "cards": []-}-```--**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": [- { "id": "start-running", "from": "queued", "to": "running", "variant": "emphasis" },- { "id": "approval-needed", "from": "running", "to": "approval", "label": "needs approval", "variant": "security", "fromSide": "bottom", "toSide": "right" },- { "id": "run-succeeded", "from": "running", "to": "done", "label": "success", "variant": "emphasis", "fromSide": "bottom", "toSide": "top" }- ],- "cards": []-}-```--**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": [- { "id": "users-to-api", "from": "users", "to": "api", "label": "HTTPS", "variant": "emphasis" },- { "id": "api-to-db", "from": "api", "to": "db", "label": "SQL" }- ],- "cards": []-}-```--Render: `node bin/archify.mjs render architecture <input>.json <output>.html`.--### Optional verified repository evidence--For a public-repository architecture map, offer one explicit choice before adding source evidence: **plain portable map (default)** or **revision-verified source links**. Do not enable evidence silently, infer paths, or add it to workflow/sequence/dataflow/lifecycle diagrams. If the user already asked for a source-linked or evidence-backed map, that is sufficient consent; do not ask twice.--Evidence is opt-in because repository paths become part of the standalone HTML. It is currently limited to public GitHub repositories and Architecture mode. Never use it for a private repository, never serialize an absolute local path, and never claim a path is verified unless the command below succeeds.--```json-{- "meta": {- "title": "Runtime Architecture",- "repository": {- "url": "https://github.com/example/project",- "revision": "0123456789abcdef0123456789abcdef01234567"- }- },- "components": [- {- "id": "router",- "type": "backend",- "label": "Command Router",- "sources": [- { "path": "src/router.ts", "line": 24, "end_line": 61, "label": "Dispatch entry" }- ]- }- ]-}-```--Use a full 40-character commit SHA. Each component may name one to three repo-relative POSIX paths, with an optional 1-based line or inclusive line range and reader-facing label. Then pass the repository top level explicitly:+Add `--open` only when the user wants an immediate local preview. For an active desktop authoring loop, the optional command is:```bash-node bin/archify.mjs deliver architecture map.architecture.json map.html \- --repo-root /absolute/path/to/project --quality showcase --json+node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase```-`render`, `validate`, and `preview` accept the same `--repo-root` option. Archify checks that the local `origin` matches the authored GitHub URL and that the exact commit, blobs, and requested lines exist. A failure preserves the previous delivered artifact. A success adds only verified links to the existing Semantic Passport and Node Finder; the evidence payload stays outside the SVG, so SVG/raster/Share Card/WebM exports remain free of repository paths.+Never start preview by default. Read `references/delivery-contract.md` when using preview, repository evidence, export receipts, visual review, or post-commit opening.-**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).+## Optional viewer capabilities-**Grid placement (#8)** — when manual coordinates are painful, set semantic cells instead of doing arithmetic:+Generated HTML already contains theme switching, pan/zoom, search, focus, relationship tracing, semantic views, presentation, and truthful exports. These are reader capabilities, not extra authoring work. `meta.animation: "trace"` is opt-in; `meta.views` is optional and should contain at most five curated chapters.-```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 }- ]-}-```+Read `references/viewer-runtime.md` only when the user explicitly asks for Share Cards, Route/Reach cards, motion, guided stories, deep links, presentation, search/focus, or another Viewer Runtime feature.-`pos` still wins when present (override one cell). This is **not** auto-layout — spacing is fixed cell math. The complete grid field shape is the snippet above; validate a candidate with `node bin/archify.mjs inspect architecture <file>`.+## Setup and fallback-**Inspect layout (#9)** — after editing JSON, dump computed boxes without opening HTML:+No install is required inside the skill package. Verify with:```bash-node bin/archify.mjs inspect architecture my.architecture.json-# or: node bin/archify.mjs validate architecture my.architecture.json --layout-json-```--Output includes component rects, boundaries, connection point paths, and label positions.--**The renderer does the mechanical work that used to be hand-tuned**, so you only choose coordinates and meaning:--- **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`). Architecture `auto` preserves the original H-V-H dogleg when it is clear and tries the complementary in-bounds V-H-V dogleg only when the first would cross an unrelated component; eligible shared automatic endpoints use the bounded Automatic Port Spread rule above, while explicit routing is never rewritten. 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.--### Hand-placed fallback (no renderer available)--When Node/ajv can't run, copy `assets/template.html` and place SVG by hand. Study the worked diagram inside the template and `examples/web-app-rendered.html` for coordinate idioms, follow the Design System below, and run the self-review checklist before delivering.--### The Cardinal Rule: CSS classes, not inline colors--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:--```svg-<rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>-<rect x="X" y="Y" width="W" height="H" rx="6" class="c-backend" stroke-width="1.5"/>-<text x="CX" y="CY" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">API Server</text>-<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).--Renderer-backed nodes automatically receive one small inline SVG Semantic Sigil derived from the existing role (`frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`, or lifecycle state type). Do not add vendor logos or duplicate the sigil by hand; put product identity in the label/sublabel and let the stable semantic category control color and the role stamp.--Typography inherits JetBrains Mono from the SVG root. Sizes: 11–12px component names, 9px sublabels, 8px annotations, 7px tiny labels.--### Hard layout rules--- **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).-- **Clean flow before delivery**: with or without a quality profile, a relationship may touch its own source/target boxes but must not pass through any unrelated semantic node. If both bounded architecture auto candidates are blocked, fix `clean-flow/edge-through-node` with `fromSide`/`toSide`, a route/channel, explicit `via`, or node placement; do not hide the defect with paint order. This semantic correctness rule is universal, while older profile-less schema-v1 inputs retain advisory handling for stricter composition preferences.-- **Choose a composition profile deliberately with the user**: `standard` keeps dense engineering topologies renderable and records route-rhythm, proper-X, unrelated ≥8px collinear-corridor, and sub-2px label-route clearance findings as warnings; `showcase` fails those findings and requires 4px label-route clearance. Both explicit profiles enforce structural border-run checks; universal Clean Flow applies before profile selection. Endpoint stubs from 8–15px, point touches, short corridor overlaps, and shared-endpoint fan-out/merge remain valid only where they do not pass under another relationship's label mask. Use `meta.quality_profile` or CLI `--quality`, then repair with label, route/channel/via/side, message-y, or placement controls. Do not silently add a profile to an existing v1 file.-- **Choose an engineering profile deliberately with the user**: `deployment-ownership` is Architecture-only, opt-in, and fail-closed for known deployment facts. It is not a visual preset, repository scanner, or claim about live infrastructure. Do not silently add it to an existing file or satisfy it with guessed owners, regions, security groups, or boundary-crossing labels.-- **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.--### Self-review checklist (run before delivering)--1. `grep -E 'fill="(#|rgb)|stroke="(#|rgb)' out.html` inside the SVG returns nothing except the template's own defs (Cardinal Rule).-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.-5. Legend y is below every boundary's y + height.-6. The `.toolbar`, `.diagram-nav`, `.overview-map`, `.semantic-lens`, `.route-probe`, `.intent-trace-status`, `<script>` blocks, and `:root` / `[data-theme]` CSS are untouched — they ARE the theme, Semantic Lens, Intent Trace, Route Probe, Node Finder, Semantic Radar, Presentation Stage, interaction, and export runtime.--### Perceptual delivery gate--Treat the first render as a candidate, not an automatic final result. After deterministic render, validate, and artifact checks pass, inspect the final browser artifact and a canonical raster export when an image reader is available. Check clipping, text fit, hierarchy, whitespace, misleading routes, label placement, and dark/light readability. Make a maximum of two focused correction rounds; change only the diagnosed coordinates, labels, routes, spacing, or viewBox, then rerun render, validate, and check after every round.--Use `deliver` for every final replacement, including after a visual correction. Its JSON receipt proves only deterministic renderer and artifact-check facts; never claim that the deterministic receipt includes visual review. `--open` is only a post-commit convenience and its status proves only whether the local opener invocation succeeded. Perceptual review remains the separate truthful receipt below.--Finish with a truthful receipt:--```text-validation: passed-visual_review: passed-correction_rounds: 0+node bin/archify.mjs doctor+node bin/archify.mjs demo <output-directory>```-When no browser or image reader is available, report `visual_review: skipped (image reader unavailable)` and still report the real correction count. Never report `visual_review: passed` without inspecting the final rendered pixels. Do not start an unbounded aesthetic loop, and do not use visual judgment to override a deterministic failure.+When shell access is unavailable, hand-place architecture SVG into `assets/template.html`, use CSS semantic classes rather than inline colors, and follow the visual review contract in `references/delivery-contract.md`.## Output-A single self-contained `.html`: embedded CSS (Google Fonts loads async and degrades to system monospace offline), one canonical inline SVG, and embedded JS for Intent Trace, Route Probe, Node Finder, Semantic Passport, runtime-built Semantic Radar, Presentation Stage, Story Trail playback, semantic focus, pan/zoom, theme, and export. It renders directly in any modern browser. Every semantic node has a deterministic DOM ID, accessible keyboard control, renderer-owned kind/responsibility/context attributes, and a compact native `<title>` tooltip; the SVG root includes its own `<title>` and `<desc>`. Explicit, successfully verified Architecture repository evidence may live in a separate HTML-only JSON payload for Passport/Node Finder use; it must never enter the SVG or visual exports. The viewer footer may link to Archify's bounded start page using only the diagram type; it must never serialize the title, semantic graph, repository path, or source JSON, must suppress the document referrer, and stays outside print and every canonical export. Raster exports render natively at up to 4× the viewBox (large diagrams step down to 3×/2× to stay under canvas limits); the SVG download is dual-theme self-contained and follows the host's `prefers-color-scheme` (manual override via `svg[data-theme="..."]`); trace-enabled diagrams can be recorded to WebM without external tooling.+Return the checked HTML path, diagram type, validation summary, specification/artifact receipt, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.diff --git a/archify/assets/template.html b/archify/assets/template.htmlindex 9358eed3..95393b1d 100644--- a/archify/assets/template.html+++ b/archify/assets/template.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><!-- ARCHIFY:SVG_SLOT_START --><svg viewBox="0 0 1000 680" role="img" aria-label="[PROJECT NAME] architecture diagram"><!-- Definitions -->@@ -10166,7 +10166,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex fb9f9b5f..4124af23 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -694,9 +694,11 @@ async function commandDeliver(args) {const renderer = rendererPath(type);const inputPath = path.resolve(input);+ let specification;let diagram;try {- diagram = JSON.parse(fs.readFileSync(inputPath, 'utf8'));+ specification = fs.readFileSync(inputPath);+ diagram = JSON.parse(specification.toString('utf8'));} catch (error) {const repair = inputDiagnostic(error, inputPath);reportDeliveryFailure({@@ -764,9 +766,32 @@ async function commandDeliver(args) {return;}const candidatePath = path.join(stagingDirectory, path.basename(outputPath));+ const specificationSnapshotPath = path.join(stagingDirectory, 'specification.snapshot.json');try {- const render = runNode([renderer, inputPath, candidatePath], {+ try {+ fs.writeFileSync(specificationSnapshotPath, specification, { flag: 'wx' });+ } catch (error) {+ const message = `Could not freeze the delivery specification: ${error.message}`;+ reportDeliveryFailure({+ json,+ stage: 'prepare',+ type,+ input: inputPath,+ output: outputPath,+ error: message,+ diagnostics: [diagnostic({+ code: 'delivery/freeze-specification',+ message,+ subject: { input: inputPath },+ evidence: { ...(error?.code ? { systemCode: error.code } : {}), reason: error.message },+ supportedFixes: ['choose a writable output directory on the target filesystem'],+ })],+ });+ return;+ }++ const render = runNode([renderer, specificationSnapshotPath, candidatePath], {stdio: 'pipe',env: rendererEnv(qualityArgs.quality, repoArgs.repoRoot, true),});@@ -882,6 +907,10 @@ async function commandDeliver(args) {type,input: inputPath,output: outputPath,+ specification: {+ sha256: createHash('sha256').update(specification).digest('hex'),+ bytes: specification.byteLength,+ },artifact: {sha256: createHash('sha256').update(artifact).digest('hex'),bytes: artifact.byteLength,@@ -1046,6 +1075,18 @@ async function commandDoctor() {missing: fs.existsSync(scenarioGuide) ? 0 : 1,});+ const authoringReferences = [+ path.join(skillRoot, 'references', 'authoring-contract.md'),+ path.join(skillRoot, 'references', 'viewer-runtime.md'),+ path.join(skillRoot, 'references', 'delivery-contract.md'),+ ];+ const authoringReferencesMissing = authoringReferences.filter((file) => !fs.existsSync(file)).length;+ checks.push({+ label: 'Progressive authoring references',+ ok: authoringReferencesMissing === 0,+ missing: authoringReferencesMissing,+ });+const compareRuntime = path.join(skillRoot, 'delta/architecture-delta.mjs');const compareFixtures = [path.join(skillRoot, 'examples/checkout-platform.base.architecture.json'),diff --git a/archify/examples/dataflow-product-analytics.html b/archify/examples/dataflow-product-analytics.htmlindex 07df163b..9daab182 100644--- a/archify/examples/dataflow-product-analytics.html+++ b/archify/examples/dataflow-product-analytics.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 760" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Product Analytics Data Flow</title><desc id="archify-diagram-description">Events, consent, PII isolation, warehouse sync, and downstream analytics</desc>@@ -10264,7 +10264,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/archify/examples/lifecycle-agent-run.html b/archify/examples/lifecycle-agent-run.htmlindex 0f617ed4..fc75e0b4 100644--- a/archify/examples/lifecycle-agent-run.html+++ b/archify/examples/lifecycle-agent-run.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 980 660" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Agent Run Lifecycle</title><desc id="archify-diagram-description">State machine for planning, tool execution, human approval, retries, and terminal outcomes</desc>@@ -10219,7 +10219,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/archify/examples/sequence-cache-miss-request.html b/archify/examples/sequence-cache-miss-request.htmlindex 9dbd25b8..7eb5ad37 100644--- a/archify/examples/sequence-cache-miss-request.html+++ b/archify/examples/sequence-cache-miss-request.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 820 760" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Cache Miss Request Sequence</title><desc id="archify-diagram-description">Frontend request path with auth, cache fallback, persistence, and async trace</desc>@@ -10279,7 +10279,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/archify/examples/web-app-rendered.html b/archify/examples/web-app-rendered.htmlindex 9d4d2c56..3aea3786 100644--- a/archify/examples/web-app-rendered.html+++ b/archify/examples/web-app-rendered.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 588" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Sample Web App</title><desc id="archify-diagram-description">Classic 3-tier SaaS on AWS — rendered by Archify</desc>@@ -10233,7 +10233,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/archify/examples/workflow-agent-tool-call-rendered.html b/archify/examples/workflow-agent-tool-call-rendered.htmlindex fd8b483d..f2be2f00 100644--- a/archify/examples/workflow-agent-tool-call-rendered.html+++ b/archify/examples/workflow-agent-tool-call-rendered.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 720 900" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">Agent Tool Call Workflow</title><desc id="archify-diagram-description">Renderer-driven workflow prototype with lanes, anchored nodes, and orthogonal edges</desc>@@ -10297,7 +10297,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.mdnew file mode 100644index 00000000..ccb53f19--- /dev/null+++ b/archify/references/authoring-contract.md@@ -0,0 +1,79 @@+# Authoring contract++Read this reference only after the Fast authoring path calls for more detail. The schemas and examples remain authoritative.++## Schema lookup++Read both the mode schema and `schemas/common.schema.json`. The mode schemas use `$ref`, so the common file is where shared enums live.++- `componentType`: `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`+- `variant`: `default`, `emphasis`, `security`, `dashed`+- Relationship IDs use the shared identifier pattern and must be unique in their collection.++Do not invent fields. Use the nearest matching example for structure, then author fresh IDs, wording, facts, and layout.++## Executable geometry rules++- Node anchors are side midpoints. `left`/`right` change the horizontal endpoint; `top`/`bottom` change the vertical endpoint.+- A side is a direction contract. The first and final route segment must be perpendicular and outward/inward in the named direction.+- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle diagrams. Shared automatic endpoints spread deterministically and symmetrically with a 16px corner gutter. It does not apply to sequence messages, single relationships, or explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes.+- Showcase route rhythm: every nonzero segment must be at least 8px; every interior segment must be at least 16px. When spread ports are nearly parallel, the router uses a 24px endpoint stub and a 16px outside bridge instead of manufacturing a tiny dogleg.+- Shared endpoint corridors are allowed only when they remain semantically unambiguous. Unrelated collinear overlap of 8px or more fails showcase.+- Container borders are intentional pass-through geometry, but a long edge running along a structural border is not.+- An edge crossing an unrelated opaque node is always a hard failure, independent of quality profile.++### Spacing and labels++Spacing recommendations mean clear gap between boxes, not center distance. A 200px center distance between 165px-wide nodes leaves only 35px of clear gap.++For a relationship label, require:++```text+clear gap > label mask width + 8px breathing room+label mask width ≈ 6.5px × ASCII units + 13px+CJK characters count as two units+```++If the gap is too small, prefer an unlabeled obvious edge. Otherwise increase the clear gap or apply a diagnosed `labelAt`, `labelDx`/`labelDy`, or `labelSegment`. Never guess several geometry controls at once.++### Repair order++1. Fix missing/invalid `meta.quality_profile` and schema errors.+2. Fix node overlap or out-of-range placement.+3. Fix edge-through-node and endpoint-direction errors.+4. Fix crossings, ambiguous corridors, border runs, and route rhythm.+5. Fix label-to-node, label-to-label, then label-to-route clearance.++Run `validate` after every edit. Consume `diagnostics[]` by stable `code`, exact `subject`, measured `evidence`, and `supportedFixes`. If the diagnostic gives `labelAt`, use that point instead of estimating another offset.++## Mode placement++### Architecture++Use one left-to-right spine with short vertical branches. Prefer 6–12 primary components and group only real ownership, trust, process, or deployment boundaries. Boundaries do not replace relationships.++Grid placement is preferred when the schema supports it. Free positions are appropriate for a bounded exception, not for prose-level coordinate planning. Keep external actors outside the system boundary when that is factually true.++### Workflow++Lanes express responsibility or phase. Columns express progression. Keep the happy path monotonic; route retries and exception returns outside the main lane corridor.++### Sequence++Participants are ordered by conversation role. Messages own their vertical order. Use return/async/security variants for meaning, not decoration; sequence does not use Automatic Port Spread.++### Dataflow++Stages express transformation or custody. Rows separate parallel streams. Label only data contracts, classifications, or cross-boundary movement that is not obvious.++### Lifecycle++Main phases use columns `0..4`; event and terminal bands use columns `0..2`. A recoverable failure needs a real transition back to an active state. A card or guided view saying “retry” is not topology.++## Repository evidence++When the diagram must reflect real code, inspect repository entrypoints, runtime boundaries, storage, transports, and deployment configuration before authoring. Record only evidence you actually verified. Use `--repo-root <path>` when the chosen renderer supports evidence receipts. Never infer runtime causality from file proximity or naming alone.++## Hand-placed fallback++Use only when no renderer can run. Start from `assets/template.html`, keep semantic CSS classes, preserve the inline SVG/accessibility structure, and run the delivery visual checklist. Never introduce inline literal colors that break dark/light parity.diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdnew file mode 100644index 00000000..6eb0c213--- /dev/null+++ b/archify/references/delivery-contract.md@@ -0,0 +1,59 @@+# Delivery contract++## Validate and deliver++Use `validate` after every candidate edit. Use final atomic delivery only after the candidate is frozen:++```bash+node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json+```++Deliver reads the specification once, writes those exact bytes to a private same-directory candidate snapshot, renders that snapshot, runs the complete artifact checker, and only replaces the target after all artifact checks pass. The JSON receipt includes SHA-256 and byte counts for both `specification` and `artifact`. Renderer, checker, receipt, or commit failure exits non-zero, removes private state, preserves the previous trusted artifact, and never invokes an opener.++The deterministic receipt proves byte identity and automated checks. Never claim that the deterministic receipt includes visual review.++## Optional opening++Add `--open` only when the user wants an immediate local preview. It runs after that atomic commit, uses one argument-array OS opener with a five-second bound, and records `open.status`. Keep it off for CI, unattended agents, and non-interactive environments. Failure or unsupported opening does not invalidate delivery; its status proves only whether the local opener invocation succeeded.++## Last-Good Live Preview++For an active desktop authoring loop only:++```bash+node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase+```++Preview watches one explicit input on loopback, binds each stable digest to a private snapshot, and advances only after the existing verified delivery pipeline passes. Invalid, half-written, deleted, or superseded input leaves the previous verified revision on screen and on disk. Identical bytes do not rebuild or reload.++Never start it by default. Do not use it for CI, unattended agents, remote sharing, or mobile use. `--no-open` is only for a user who will open the printed local URL or for loop testing. Stop it with Ctrl-C before handoff. Server state, port, source path, diagnostics, error text, and reload tokens must never enter the generated artifact or any export.++## Perceptual delivery gate++Automated validation cannot prove visual polish. After deterministic delivery, inspect the actual HTML in a capable browser or render a screenshot with an image reader. Check both themes when changed, the default READ view, line crossings/corridors, label masks, node/card fit, focus/search/passport closure, and export cleanliness.++Report exactly one truthful status:++- `visual_review: passed` — only after inspecting the rendered artifact.+- `visual_review: skipped (image reader unavailable)` — when no capable visual surface exists.+- `visual_review: failed` — with the concrete visible defect.++Use `correction_rounds: 0`, `correction_rounds: 1`, or `correction_rounds: 2`; never exceed a maximum of two focused correction rounds. Never report `visual_review: passed` without inspecting the artifact.++If visual review changes the candidate, validation and delivery must run again because the prior frozen specification receipt is no longer current.++## Handoff receipt++Return:++```text+diagram_type: architecture|workflow|sequence|dataflow|lifecycle+output: /absolute/path/to/file.html+specification_sha256: <receipt value>+artifact_sha256: <receipt value>+validation: 9/9 showcase, 0 errors, 0 warnings+visual_review: passed|skipped (image reader unavailable)|failed+correction_rounds: 0|1|2+```++Opening, preview status, Share Cards, and other viewer exports are not validation claims.diff --git a/archify/references/viewer-runtime.md b/archify/references/viewer-runtime.mdnew file mode 100644index 00000000..919b71bc--- /dev/null+++ b/archify/references/viewer-runtime.md@@ -0,0 +1,45 @@+# Viewer Runtime reference++Read this only when the user asks for a reader-facing capability. Ordinary generation does not require implementing or re-documenting these features; they are already in the generated HTML.++## Exploration++- Diagram Guide lists current actions and shortcuts.+- Reading Depth starts at READ at the default 100% scale, reveals FULL detail at 175%, and falls back to MAP only below 100%. Focus, story, route, and semantic interactions reveal their exact facts at any scale.+- Semantic Lens summarizes selected node/relationship kinds without changing authored geometry.+- Intent Trace previews a fine-pointer or keyboard target before committed focus.+- Node Finder searches labels and stable IDs.+- Semantic Passport opens on focus, shows authored upstream/downstream facts, supports a copyable deep link, has an explicit close action, closes on true outside activation and Escape, and never enters canonical export.+- Semantic Radar mirrors the visible viewport and authored graph without becoming a second source of truth.+- Direct Relationship Pin makes a unique compiled relationship operable while preserving the authored line and stable relationship identity. It must fail closed on conflicting source/target/label/ID metadata.+- Route Probe resolves exactly two endpoints over authored directed relationships. It never infers a route from geometry.++## Guided views and story++`meta.views` may define at most five curated chapters using stable node IDs. The Named Chapter Rail, Chapter Delta Preview, Story Beat Navigator, Story Follow Camera, Story Director Strip, Story Horizon, and Shareable Story Moment links all derive from that one authored array; none owns parallel topology or layout.++Story transitions classify only the exact relationship between adjacent authored stops: forward, reverse, multiple, or grouped/no direct link. Never infer a transitive edge, verb, causality, or runtime behavior from proximity, kinds, or story order. Playback is reader-started, bounded, stale-safe, and motion-governed.++## Motion and presentation++`meta.animation: "trace"` enables a finite reader-controlled Live/Still trace. Static is the default. Still, reduced motion, page hiding, print, and canonical export preserve complete static meaning. Presentation Stage changes viewer chrome and framing, never authored geometry. This is not a mobile product feature; narrow layouts get containment only.++## Canonical exports++The export menu can copy/download full-diagram PNG, download JPEG/WebP, download a dual-theme SVG, and record a trace-enabled WebM. Viewer state—Guide, Lens, finder, focus, route, story, camera, radar, presentation, motion ownership, and temporary overlays—must be removed from canonical export.++### Share Card++The optional 1200×630 Share Card PNG is for README, release, social, or launch previews. It uses the current theme and visual preset, contains the complete canonical diagram without cropping, and never claims validation. Copy Share Card reuses the same canonical PNG when clipboard image writes are supported.++### Route Share Card++After a real directed Route Probe resolves, the reader may use **Export → Route Share Card**. It reuses the exact ordered route snapshot and the shared Share Card seam: `format=share-card`, `variant=route`. The isolated clone may use only static `data-share-route-*` decoration. It is download-only, fails closed for stale/unreachable/conflicting routes, and never becomes the canonical artifact.++### Reach Share Card++After a non-empty authored reachability query, the reader may use **Export → Reach Share Card**. It consumes the already resolved upstream/downstream node and edge set without rerunning traversal: `format=share-card`, `variant=reach`. The isolated clone may use only static `data-share-reach-*` decoration. It is download-only. Call it authored reachability—not impact, blast radius, breakage, or runtime causality.++## Truth boundary++Viewer exports are communication assets. They do not replace the checked HTML, the deterministic delivery receipt, or a real visual review. Do not add a hosted service, storage surface, dependency, schema branch, or mobile product surface for these viewer-only capabilities.diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjsindex 43a1b98f..ba27666a 100644--- a/archify/renderers/architecture/render-architecture.mjs+++ b/archify/renderers/architecture/render-architecture.mjs@@ -10,6 +10,7 @@ import {isFinitePoint,rectsOverlap,segmentIntersectsRect,+ cleanEndpointSideProblems,cleanFlowProblems,cleanCrossingProblems,cleanAmbiguousCorridorProblems,@@ -20,9 +21,12 @@ import {suggestComponentSeparation,anchor,automaticPortSpread,+ automaticPortRhythmBridge,defaultFromSide,defaultToSide,chosenSide,+ routeHonorsEndpointSides,+ normalizeRoutePoints,polylinePath,routePointsValue,roundedPath,@@ -202,6 +206,16 @@ function validateArchitecture() {}}+ problems.push(...cleanEndpointSideProblems({+ relations: arch.connections,+ endpointIds: new Set(components.keys()),+ pathFor,+ diagramType: 'architecture',+ relationCollection: 'connections',+ fromSideFor: (conn) => inferredAutoSide(conn, 'source'),+ toSideFor: (conn) => inferredAutoSide(conn, 'target'),+ routeHint: 'keep automatic routing so the renderer can use a side-aware bridge, or set truthful fromSide/toSide with perpendicular via segments',+ }));problems.push(...cleanFlowProblems({relations: arch.connections,endpointIds: new Set(components.keys()),@@ -330,7 +344,89 @@ function routeClearsComponents(conn, points, clearance = 2) {return true;}-function routeVia(conn, from, to, start, end) {+function routeClearsEndpointComponents(points, from, to) {+ const lastSegment = points.length - 2;+ for (let index = 0; index <= lastSegment; index += 1) {+ const segment = { start: points[index], end: points[index + 1] };+ if (index > 0 && segmentIntersectsRect(segment, from)) return false;+ if (index < lastSegment && segmentIntersectsRect(segment, to)) return false;+ }+ return true;+}++const OUTWARD_SIDE_VECTOR = {+ left: [-1, 0],+ right: [1, 0],+ top: [0, -1],+ bottom: [0, 1],+};++function outwardStub(point, side, distance = 24) {+ const [dx, dy] = OUTWARD_SIDE_VECTOR[side] || [0, 0];+ return [point[0] + dx * distance, point[1] + dy * distance];+}++function collinearBacktrack(a, b, c) {+ const first = [b[0] - a[0], b[1] - a[1]];+ const second = [c[0] - b[0], c[1] - b[1]];+ const cross = first[0] * second[1] - first[1] * second[0];+ const dot = first[0] * second[0] + first[1] * second[1];+ return Math.abs(cross) <= 0.0001 && dot < -0.0001;+}++function sideAwareBridgeCandidates(start, end, fromSide, toSide) {+ const startStub = outwardStub(start, fromSide);+ const endStub = outwardStub(end, toSide);+ const rawCandidates = [];+ const minimumBridge = 16;+ const verticalSides = new Set(['top', 'bottom']);+ const horizontalSides = new Set(['left', 'right']);++ // Port spreading can leave parallel-side anchors only a few pixels apart.+ // Route through a bounded outside channel so we keep both endpoint normals+ // without introducing a tiny, noisy connector between the two stubs.+ if (verticalSides.has(fromSide) && verticalSides.has(toSide)+ && Math.abs(start[0] - end[0]) < minimumBridge) {+ for (const channelX of [+ Math.max(start[0], end[0]) + minimumBridge,+ Math.min(start[0], end[0]) - minimumBridge,+ ]) {+ rawCandidates.push([+ startStub,+ [channelX, startStub[1]],+ [channelX, endStub[1]],+ endStub,+ ]);+ }+ }+ if (horizontalSides.has(fromSide) && horizontalSides.has(toSide)+ && Math.abs(start[1] - end[1]) < minimumBridge) {+ for (const channelY of [+ Math.max(start[1], end[1]) + minimumBridge,+ Math.min(start[1], end[1]) - minimumBridge,+ ]) {+ rawCandidates.push([+ startStub,+ [startStub[0], channelY],+ [endStub[0], channelY],+ endStub,+ ]);+ }+ }++ rawCandidates.push(+ [startStub, [endStub[0], startStub[1]], endStub],+ [startStub, [startStub[0], endStub[1]], endStub],+ );+ return rawCandidates.map((candidate) => normalizeRoutePoints([start, ...candidate, end]))+ .filter((points) => points.length >= 2)+ .filter((points) => !collinearBacktrack(points[0], points[1], points[2] || points[1]))+ .filter((points) => !collinearBacktrack(points.at(-3) || points.at(-2), points.at(-2), points.at(-1)))+ .filter((points) => routeHonorsEndpointSides(points, fromSide, toSide))+ .map((points) => points.slice(1, -1));+}++function routeVia(conn, from, to, start, end, fromSide, toSide) {if (conn.via) return conn.via;switch (conn.route || 'auto') {case 'straight':@@ -348,7 +444,15 @@ function routeVia(conn, from, to, start, end) {// Direct line unless the anchors are clearly orthogonal-friendly.const deltaX = Math.abs(start[0] - end[0]);const deltaY = Math.abs(start[1] - end[1]);- if (deltaX < 4 || deltaY < 4) return [];+ if ((deltaX < 4 || deltaY < 4) && routeHonorsEndpointSides([start, end], fromSide, toSide)) return [];++ const rhythmBridge = automaticPortRhythmBridge(start, end, fromSide, toSide, {+ accept: (points) => (+ routeClearsEndpointComponents(points, from, to)+ && routeClearsComponents(conn, points)+ ),+ });+ if (rhythmBridge) return rhythmBridge.slice(1, -1);// Automatic port spreading can leave otherwise aligned endpoints only a// few pixels apart. A midpoint route would split that tiny difference@@ -364,7 +468,8 @@ function routeVia(conn, from, to, start, end) {];for (const channelX of outsideChannels) {const candidate = [[channelX, start[1]], [channelX, end[1]]];- if (routeClearsComponents(conn, [start, ...candidate, end])) return candidate;+ const points = [start, ...candidate, end];+ if (routeHonorsEndpointSides(points, fromSide, toSide) && routeClearsComponents(conn, points)) return candidate;}}@@ -377,36 +482,74 @@ function routeVia(conn, from, to, start, end) {];for (const channelY of outsideChannels) {const candidate = [[start[0], channelY], [end[0], channelY]];- if (routeClearsComponents(conn, [start, ...candidate, end])) return candidate;+ const points = [start, ...candidate, end];+ if (routeHonorsEndpointSides(points, fromSide, toSide) && routeClearsComponents(conn, points)) return candidate;}}const midX = (start[0] + end[0]) / 2;const horizontalFirst = [[midX, start[1]], [midX, end[1]]];- if (routeClearsComponents(conn, [start, ...horizontalFirst, end])) return horizontalFirst;-- // The only fallback is the complementary in-bounds dogleg. Both- // candidates stay between the authored anchors, preserve two bends, and- // remain deterministic. If neither is safe, keep the original route so- // the universal Clean Flow gate returns the actionable hard failure.const midY = (start[1] + end[1]) / 2;const verticalFirst = [[start[0], midY], [end[0], midY]];- if (routeClearsComponents(conn, [start, ...verticalFirst, end])) return verticalFirst;- return horizontalFirst;+ const candidates = [horizontalFirst, verticalFirst];+ const sideSafe = candidates.filter((candidate) => (+ routeHonorsEndpointSides([start, ...candidate, end], fromSide, toSide)+ ));+ const sideAware = sideAwareBridgeCandidates(start, end, fromSide, toSide);+ const nearParallelPorts = (+ ((fromSide === 'top' || fromSide === 'bottom')+ && (toSide === 'top' || toSide === 'bottom')+ && deltaX < minimumStub * 2)+ || ((fromSide === 'left' || fromSide === 'right')+ && (toSide === 'left' || toSide === 'right')+ && deltaY < minimumStub * 2)+ );+ const ordered = [+ ...(nearParallelPorts ? sideAware : sideSafe),+ ...(nearParallelPorts ? sideSafe : sideAware),+ ...candidates.filter((candidate) => !sideSafe.includes(candidate)),+ ];+ for (const candidate of ordered) {+ const points = [start, ...candidate, end];+ if (routeClearsEndpointComponents(points, from, to) && routeClearsComponents(conn, points)) return candidate;+ }++ // Both bounded doglegs are blocked. Keep the best endpoint-safe route+ // when one exists so the universal Clean Flow gate reports the actual+ // obstacle; otherwise preserve the historical deterministic fallback+ // and let the endpoint-direction gate explain the side mismatch.+ return sideSafe[0] || sideAware[0] || horizontalFirst;}}}const pathCache = new Map();const automaticPorts = automaticPortSpread(arch.connections, components);+function connectionSides(conn) {+ const from = components.get(conn.from);+ const to = components.get(conn.to);+ return {+ fromSide: chosenSide(conn.fromSide, defaultFromSide(from, to)),+ toSide: chosenSide(conn.toSide, defaultToSide(from, to)),+ };+}++function inferredAutoSide(conn, endpoint) {+ const field = endpoint === 'source' ? 'fromSide' : 'toSide';+ if (conn[field] && conn[field] !== 'auto') return conn[field];+ if (conn.via || (conn.route && conn.route !== 'auto')) return null;+ return connectionSides(conn)[field];+}+function pathFor(conn) {if (pathCache.has(conn)) return pathCache.get(conn);const from = components.get(conn.from);const to = components.get(conn.to);const ports = automaticPorts.get(conn);- const start = ports?.from || anchor(from, chosenSide(conn.fromSide, defaultFromSide(from, to)));- const end = ports?.to || anchor(to, chosenSide(conn.toSide, defaultToSide(from, to)));- const points = [start, ...routeVia(conn, from, to, start, end), end];+ const { fromSide, toSide } = connectionSides(conn);+ const start = ports?.from || anchor(from, fromSide);+ const end = ports?.to || anchor(to, toSide);+ const points = [start, ...routeVia(conn, from, to, start, end, fromSide, toSide), end];const routed = { d: roundedPath(points, 8), points };pathCache.set(conn, routed);return routed;diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjsindex ea2a2263..bcf5c866 100644--- a/archify/renderers/shared/geometry.mjs+++ b/archify/renderers/shared/geometry.mjs@@ -183,6 +183,132 @@ function relationshipSubject(diagramType, relationCollection, relationIndex, rel};}+const ENDPOINT_SIDE_RULES = {+ left: {+ axis: 'horizontal',+ sourceSign: -1,+ targetSign: 1,+ sourceDirection: 'leftward',+ targetDirection: 'rightward from the left',+ },+ right: {+ axis: 'horizontal',+ sourceSign: 1,+ targetSign: -1,+ sourceDirection: 'rightward',+ targetDirection: 'leftward from the right',+ },+ top: {+ axis: 'vertical',+ sourceSign: -1,+ targetSign: 1,+ sourceDirection: 'upward',+ targetDirection: 'downward from above',+ },+ bottom: {+ axis: 'vertical',+ sourceSign: 1,+ targetSign: -1,+ sourceDirection: 'downward',+ targetDirection: 'upward from below',+ },+};++function endpointSideIssue(points, endpoint, side) {+ const rule = ENDPOINT_SIDE_RULES[side];+ if (!rule) return null;+ const normalized = normalizeRoutePoints(points);+ if (normalized.length < 2) return null;+ const segmentIndex = endpoint === 'source' ? 0 : normalized.length - 2;+ const start = normalized[segmentIndex];+ const end = normalized[segmentIndex + 1];+ const dx = end[0] - start[0];+ const dy = end[1] - start[1];+ const along = rule.axis === 'horizontal' ? dx : dy;+ const across = rule.axis === 'horizontal' ? dy : dx;+ const expectedSign = endpoint === 'source' ? rule.sourceSign : rule.targetSign;+ if (Math.abs(across) <= 0.0001 && along * expectedSign > 0.0001) return null;+ return {+ endpoint,+ side,+ segmentIndex,+ start,+ end,+ expectedAxis: rule.axis,+ expectedDirection: endpoint === 'source' ? rule.sourceDirection : rule.targetDirection,+ };+}++// A side is a direction contract, not just a point on a box border. This pure+// predicate lets automatic routers prefer a dogleg whose first and final+// segments leave/enter the chosen sides perpendicularly.+export function routeHonorsEndpointSides(points, fromSide, toSide) {+ return !endpointSideIssue(points, 'source', fromSide)+ && !endpointSideIssue(points, 'target', toSide);+}++// Explicit fromSide/toSide are authored geometry, so a tangent or backwards+// endpoint segment changes their meaning. Fail this universally instead of+// leaving a malformed arrow for visual review to discover.+export function cleanEndpointSideProblems({+ relations,+ endpointIds,+ pathFor,+ diagramType,+ relationCollection,+ fromSideFor,+ toSideFor,+ routeHint = 'align the first/final via segment with fromSide/toSide, change the side, or remove explicit routing so auto can choose a perpendicular approach',+}) {+ const problems = [];+ for (const [relationIndex, relation] of asArray(relations).entries()) {+ if (!relation || !endpointIds?.has(relation.from) || !endpointIds?.has(relation.to)) continue;+ const points = pathFor(relation)?.points;+ if (!Array.isArray(points) || points.length < 2) continue;+ const authoredFromSide = relation.fromSide && relation.fromSide !== 'auto' ? relation.fromSide : null;+ const authoredToSide = relation.toSide && relation.toSide !== 'auto' ? relation.toSide : null;+ const fromSide = (typeof fromSideFor === 'function' ? fromSideFor(relation) : null) ?? authoredFromSide;+ const toSide = (typeof toSideFor === 'function' ? toSideFor(relation) : null) ?? authoredToSide;+ const checks = [+ fromSide+ ? { ...endpointSideIssue(points, 'source', fromSide), sideOrigin: authoredFromSide ? 'authored' : 'inferred' }+ : null,+ toSide+ ? { ...endpointSideIssue(points, 'target', toSide), sideOrigin: authoredToSide ? 'authored' : 'inferred' }+ : null,+ ].filter((issue) => issue?.endpoint);+ for (const issue of checks) {+ const relationId = relation.id ? ` id "${relation.id}"` : '';+ const authoredField = issue.endpoint === 'source' ? 'fromSide' : 'toSide';+ const sideField = issue.sideOrigin === 'inferred' ? `inferred ${authoredField}` : authoredField;+ const segmentRole = issue.endpoint === 'source' ? 'first' : 'final';+ const from = issue.start.map((value) => Math.round(value * 10) / 10).join(', ');+ const to = issue.end.map((value) => Math.round(value * 10) / 10).join(', ');+ const message = `[clean-flow/endpoint-side-direction] ${diagramType} ${relationCollection}[${relationIndex}]${relationId} "${relation.from}" -> "${relation.to}" ${segmentRole} segment ${issue.segmentIndex} [${from}] -> [${to}] does not honor ${sideField} "${issue.side}" — it must run ${issue.expectedAxis} ${issue.expectedDirection}; ${routeHint}.`;+ recordDiagnostic({+ code: 'clean-flow/endpoint-side-direction',+ severity: 'error',+ message,+ subject: relationshipSubject(diagramType, relationCollection, relationIndex, relation),+ evidence: {+ endpoint: issue.endpoint,+ authoredField,+ sideOrigin: issue.sideOrigin,+ side: issue.side,+ segmentIndex: issue.segmentIndex,+ from: issue.start,+ to: issue.end,+ expectedAxis: issue.expectedAxis,+ expectedDirection: issue.expectedDirection,+ },+ supportedFixes: [routeHint],+ });+ problems.push(message);+ }+ }+ return problems;+}+// One mechanical quality gate for every renderer-owned relationship path.// A renderer supplies its semantic obstacle set; source/target boxes are// always exempt because paths are expected to terminate on their boundaries.@@ -725,7 +851,7 @@ function segmentPosition(index, segmentCount) {return 'interior';}-function normalizeRoutePoints(points) {+export function normalizeRoutePoints(points) {const finite = asArray(points).filter((point) => Array.isArray(point) && point.length === 2 && isFinitePoint(...point));const deduped = [];for (const point of finite) {@@ -891,6 +1017,85 @@ export function anchor(rect, side) {}}+const PORT_OUTWARD_VECTOR = {+ left: [-1, 0],+ right: [1, 0],+ top: [0, -1],+ bottom: [0, 1],+};++// Automatic port spreading can put otherwise parallel anchors only a few+// pixels apart. A conventional midpoint dogleg then violates the renderer's+// own 8px/16px route-rhythm floors. Return a full outside-channel route when+// that happens, or null when the normal automatic route remains appropriate.+export function automaticPortRhythmBridge(+ start,+ end,+ fromSide,+ toSide,+ { endpointStubPx = 24, interiorSegmentPx = 16, accept } = {},+) {+ if (!Array.isArray(start) || !Array.isArray(end)+ || start.length !== 2 || end.length !== 2+ || !isFinitePoint(...start, ...end)) return null;+ const fromVector = PORT_OUTWARD_VECTOR[fromSide];+ const toVector = PORT_OUTWARD_VECTOR[toSide];+ if (!fromVector || !toVector) return null;++ const startStub = [+ start[0] + fromVector[0] * endpointStubPx,+ start[1] + fromVector[1] * endpointStubPx,+ ];+ const endStub = [+ end[0] + toVector[0] * endpointStubPx,+ end[1] + toVector[1] * endpointStubPx,+ ];+ const candidates = [];+ const verticalSides = new Set(['top', 'bottom']);+ const horizontalSides = new Set(['left', 'right']);++ if (verticalSides.has(fromSide) && verticalSides.has(toSide)+ && Math.abs(start[0] - end[0]) < interiorSegmentPx) {+ for (const channelX of [+ Math.max(start[0], end[0]) + interiorSegmentPx,+ Math.min(start[0], end[0]) - interiorSegmentPx,+ ]) {+ candidates.push([+ start,+ startStub,+ [channelX, startStub[1]],+ [channelX, endStub[1]],+ endStub,+ end,+ ]);+ }+ }+ if (horizontalSides.has(fromSide) && horizontalSides.has(toSide)+ && Math.abs(start[1] - end[1]) < interiorSegmentPx) {+ for (const channelY of [+ Math.max(start[1], end[1]) + interiorSegmentPx,+ Math.min(start[1], end[1]) - interiorSegmentPx,+ ]) {+ candidates.push([+ start,+ startStub,+ [startStub[0], channelY],+ [endStub[0], channelY],+ endStub,+ end,+ ]);+ }+ }++ return candidates+ .map((points) => normalizeRoutePoints(points))+ .find((points) => (+ routeHonorsEndpointSides(points, fromSide, toSide)+ && collectRouteRhythmIssues({ routedRelations: [{ points }], interiorSegmentPx }).length === 0+ && (typeof accept !== 'function' || accept(points))+ )) || null;+}+// Keep conservative auto-routed fan-out/fan-in relationships visually// distinct without changing authored route controls. The returned map only// contains endpoints that belong to a shared automatic midpoint anchor.diff --git a/archify/test/automatic-port-spread.test.mjs b/archify/test/automatic-port-spread.test.mjsindex 5895f54c..60d567da 100644--- a/archify/test/automatic-port-spread.test.mjs+++ b/archify/test/automatic-port-spread.test.mjs@@ -96,8 +96,10 @@ test('architecture: automatic port spread avoids micro-stubs when a target staysassert.deepEqual(connectionPoints(html, 'read'), [[742, 300],- [758, 300],- [758, 180],+ [742, 276],+ [758, 276],+ [758, 204],+ [735, 204],[735, 180],]);});diff --git a/archify/test/cli.test.mjs b/archify/test/cli.test.mjsindex c27f4150..04e464d3 100644--- a/archify/test/cli.test.mjs+++ b/archify/test/cli.test.mjs@@ -90,6 +90,7 @@ test('cli: doctor reports a complete installation is ready', () => {assert.match(result.stdout, /\[ok\] Example renderer/);assert.match(result.stdout, /\[ok\] Live preview runtime/);assert.match(result.stdout, /\[ok\] Scenario recipe guide/);+ assert.match(result.stdout, /\[ok\] Progressive authoring references/);assert.match(result.stdout, /\[ok\] Architecture compare runtime and proof fixtures/);assert.match(result.stdout, /\[ok\] Standalone schema validators/);assert.match(result.stdout, /\[ok\] architecture renderer, schema, and example/);@@ -244,6 +245,10 @@ test('cli: deliver atomically writes a checked artifact and structured receipt',assert.equal(receipt.type, 'workflow');assert.equal(receipt.input, input);assert.equal(receipt.output, out);+ assert.deepEqual(receipt.specification, {+ sha256: sha256(input),+ bytes: fs.statSync(input).size,+ });assert.match(receipt.artifact.sha256, /^[a-f0-9]{64}$/);assert.equal(receipt.artifact.sha256, sha256(out));assert.equal(receipt.artifact.bytes, fs.statSync(out).size);diff --git a/archify/test/delivery-contract.test.mjs b/archify/test/delivery-contract.test.mjsindex 9f3af744..f05a9daa 100644--- a/archify/test/delivery-contract.test.mjs+++ b/archify/test/delivery-contract.test.mjs@@ -6,26 +6,27 @@ import assert from 'node:assert/strict';const here = path.dirname(fileURLToPath(import.meta.url));const skill = readFileSync(path.join(here, '..', 'SKILL.md'), 'utf8');+const delivery = readFileSync(path.join(here, '..', 'references', 'delivery-contract.md'), 'utf8');test('skill requires a bounded and truthful perceptual delivery receipt', () => {- assert.match(skill, /visual_review: passed/);- assert.match(skill, /visual_review: skipped \(image reader unavailable\)/);- assert.match(skill, /correction_rounds: [0-2]/);- assert.match(skill, /maximum of two focused correction rounds/i);- assert.match(skill, /never report `visual_review: passed` without inspecting/i);+ assert.match(delivery, /visual_review: passed/);+ assert.match(delivery, /visual_review: skipped \(image reader unavailable\)/);+ assert.match(delivery, /correction_rounds: [0-2]/);+ assert.match(delivery, /maximum of two focused correction rounds/i);+ assert.match(delivery, /never report `visual_review: passed` without inspecting/i);});test('skill uses atomic verified delivery for the final artifact', () => {- assert.match(skill, /archify\.mjs deliver <type>/);- assert.match(skill, /same-directory candidate/i);- assert.match(skill, /only replaces the target after.*artifact checks pass/i);- assert.match(skill, /never claim that the deterministic receipt includes visual review/i);+ assert.match(delivery, /archify\.mjs deliver <type>/);+ assert.match(delivery, /same-directory candidate/i);+ assert.match(delivery, /only replaces the target after.*artifact checks pass/i);+ assert.match(delivery, /never claim that the deterministic receipt includes visual review/i);});test('skill keeps optional opening behind the verified commit and outside automation', () => {- assert.match(skill, /Add `--open` only when the user wants an immediate local preview/);- assert.match(skill, /runs after that atomic commit/);- assert.match(skill, /Keep it off for CI, unattended agents, and non-interactive environments/);- assert.match(skill, /never invokes an opener/);- assert.match(skill, /status proves only whether the local opener invocation succeeded/);+ assert.match(delivery, /Add `--open` only when the user wants an immediate local preview/);+ assert.match(delivery, /runs after that atomic commit/);+ assert.match(delivery, /Keep it off for CI, unattended agents, and non-interactive environments/);+ assert.match(delivery, /never invokes an opener/);+ assert.match(delivery, /status proves only whether the local opener invocation succeeded/);});diff --git a/archify/test/geometry.test.mjs b/archify/test/geometry.test.mjsindex 046561ed..d6d99e30 100644--- a/archify/test/geometry.test.mjs+++ b/archify/test/geometry.test.mjs@@ -13,6 +13,7 @@ import {segmentRectClearance,segmentRectIntersectionLength,collectLabelRouteClearance,+ cleanEndpointSideProblems,cleanFlowProblems,cleanCrossingProblems,collectAmbiguousCorridors,@@ -25,9 +26,11 @@ import {asArray,isFinitePoint,anchor,+ automaticPortRhythmBridge,defaultFromSide,defaultToSide,chosenSide,+ routeHonorsEndpointSides,polylinePath,roundedPath,labelPoint,@@ -38,6 +41,27 @@ import { textUnits, applyTemplate, renderSemanticSigil } from '../renderers/sharconst rect = (x, y, w, h) => ({ x, y, width: w, height: h, cx: x + w / 2, cy: y + h / 2 });+test('automaticPortRhythmBridge: near parallel ports use readable outside runs', () => {+ const points = automaticPortRhythmBridge(+ [742, 300],+ [735, 180],+ 'top',+ 'bottom',+ );++ assert.deepEqual(points, [+ [742, 300],+ [742, 276],+ [758, 276],+ [758, 204],+ [735, 204],+ [735, 180],+ ]);+ assert.deepEqual(collectRouteRhythmIssues({+ routedRelations: [{ relation: { id: 'read' }, points }],+ }), []);+});+test('rectsOverlap: separated rects do not overlap', () => {assert.equal(rectsOverlap(rect(0, 0, 10, 10), rect(20, 0, 10, 10)), false);});@@ -115,6 +139,42 @@ test('collectLabelRouteClearance exempts only the owning relationship at an exacassert.equal(hits[0].otherRelation, sharedSource);});+test('endpoint-side direction distinguishes perpendicular entry from a tangent border run', () => {+ const clean = [[350, 160], [350, 200], [150, 200], [150, 240]];+ const tangent = [[350, 160], [350, 200], [100, 200], [100, 240], [150, 240]];+ assert.equal(routeHonorsEndpointSides(clean, 'bottom', 'top'), true);+ assert.equal(routeHonorsEndpointSides(tangent, 'bottom', 'top'), false);++ const relation = { id: 'tasks-file', from: 'cli-agents', to: 'tasks-watch', fromSide: 'bottom', toSide: 'top' };+ const problems = cleanEndpointSideProblems({+ relations: [relation],+ endpointIds: new Set(['cli-agents', 'tasks-watch']),+ pathFor: () => ({ points: tangent }),+ diagramType: 'architecture',+ relationCollection: 'connections',+ });+ assert.equal(problems.length, 1);+ assert.match(problems[0], /\[clean-flow\/endpoint-side-direction\] architecture connections\[0\] id "tasks-file"/);+ assert.match(problems[0], /final segment 3 \[100, 240\] -> \[150, 240\]/);+ assert.match(problems[0], /toSide "top".*vertical downward from above/);+});++test('endpoint-side direction can fail closed on renderer-inferred automatic sides', () => {+ const relation = { id: 'terminal-return', from: 'stream-hub', to: 'workspace' };+ const problems = cleanEndpointSideProblems({+ relations: [relation],+ endpointIds: new Set(['stream-hub', 'workspace']),+ pathFor: () => ({ points: [[700, 130], [700, 230], [160, 230], [160, 330]] }),+ diagramType: 'architecture',+ relationCollection: 'connections',+ fromSideFor: () => 'left',+ toSideFor: () => 'right',+ });+ assert.equal(problems.length, 2);+ assert.match(problems[0], /inferred fromSide "left"/);+ assert.match(problems[1], /inferred toSide "right"/);+});+test('cleanFlowProblems reports collection index, ids, segment, clearance, and fix', () => {const relations = [{ id: 'checkout', from: 'client', to: 'database' }];const obstacles = [diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjsindex 04e59767..c1c5d815 100644--- a/archify/test/layout-rules.test.mjs+++ b/archify/test/layout-rules.test.mjs@@ -316,7 +316,76 @@ test('architecture: default auto route selects a safe orthogonal candidate arounconst { code, stderr, outPath } = render('architecture', d);assert.equal(code, 0, stderr);const html = fs.readFileSync(outPath, 'utf8');- assert.match(html, /data-composition-points="560,318;560,239;880,239;880,160"/);+ assert.match(html, /data-composition-points="560,318;856,318;856,160;880,160"/);+});++test('architecture: auto route enters explicit top and bottom ports perpendicularly', () => {+ const d = {+ schema_version: 1,+ diagram_type: 'architecture',+ meta: { title: 'Endpoint direction regression' },+ components: [+ { id: 'cli-agents', type: 'external', label: 'CLI Agents', pos: [300, 100], size: [100, 60] },+ { id: 'tasks-watch', type: 'backend', label: 'Tasks Watcher', pos: [100, 240], size: [100, 60] },+ ],+ connections: [+ { id: 'tasks-file', from: 'cli-agents', to: 'tasks-watch', variant: 'dashed', fromSide: 'bottom', toSide: 'top' },+ ],+ };+ const { code, stderr, outPath } = render('architecture', d);+ assert.equal(code, 0, stderr);+ const html = fs.readFileSync(outPath, 'utf8');+ assert.match(html, /data-composition-points="350,160;350,200;150,200;150,240"/);+});++test('architecture: auto route preserves inferred side normals when the primary dogleg is blocked', () => {+ const d = {+ schema_version: 1,+ diagram_type: 'architecture',+ meta: { title: 'Inferred endpoint direction regression' },+ components: [+ { id: 'workspace', type: 'frontend', label: 'Workspace UI', pos: [40, 300], size: [120, 60] },+ { id: 'runtime-server', type: 'backend', label: 'Runtime Server', pos: [220, 300], size: [120, 60] },+ { id: 'runtime-store', type: 'backend', label: 'Runtime Store', pos: [400, 300], size: [120, 60] },+ { id: 'stream-hub', type: 'messagebus', label: 'Terminal Stream Hub', pos: [700, 100], size: [120, 60] },+ ],+ connections: [+ { id: 'terminal-return', from: 'stream-hub', to: 'workspace' },+ ],+ };+ const { code, stderr, outPath } = render('architecture', d);+ assert.equal(code, 0, stderr);+ const html = fs.readFileSync(outPath, 'utf8');+ assert.match(html, /data-composition-points="700,130;184,130;184,330;160,330"/);+ assert.doesNotMatch(html, /data-composition-points="700,130;700,230;160,230;160,330"/);+});++test('architecture: explicit via cannot run tangentially into an authored top port', () => {+ const d = {+ schema_version: 1,+ diagram_type: 'architecture',+ meta: { title: 'Tangent endpoint regression' },+ components: [+ { id: 'cli-agents', type: 'external', label: 'CLI Agents', pos: [300, 100], size: [100, 60] },+ { id: 'tasks-watch', type: 'backend', label: 'Tasks Watcher', pos: [100, 240], size: [100, 60] },+ ],+ connections: [+ {+ id: 'tasks-file',+ from: 'cli-agents',+ to: 'tasks-watch',+ variant: 'dashed',+ fromSide: 'bottom',+ toSide: 'top',+ via: [[350, 200], [100, 200], [100, 240]],+ },+ ],+ };+ const { code, stderr } = render('architecture', d);+ assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);+ assert.match(stderr, /\[clean-flow\/endpoint-side-direction\] architecture connections\[0\] id "tasks-file"/);+ assert.match(stderr, /final segment 3 \[100, 240\] -> \[150, 240\]/);+ assert.match(stderr, /toSide "top".*vertical downward from above/);});test('architecture: explicit orthogonal route remains authoritative when it crosses a component', () => {@@ -331,9 +400,9 @@ test('architecture: explicit orthogonal route remains authoritative when it crosassert.match(stderr, /connections\[0\] "api" -> "queue" crosses component "cache"/);});-test('architecture: auto route still fails closed when both bounded doglegs are blocked', () => {+test('architecture: auto route still fails closed when doglegs and side-aware bridges are blocked', () => {const d = autoRoutePassThroughDocument({ from: 'api', to: 'queue', variant: 'dashed' });- d.components.push({ id: 'guard', type: 'security', label: 'Guard', pos: [790, 215], size: [60, 50] });+ d.components.push({ id: 'guard', type: 'security', label: 'Guard', pos: [825, 215], size: [70, 50] });const { code, stderr } = render('architecture', d);assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);assert.match(stderr, /connections\[0\] "api" -> "queue" crosses component "cache"/);diff --git a/archify/test/ordinary-model-floor.test.mjs b/archify/test/ordinary-model-floor.test.mjsindex 33e483d0..89b3e0d7 100644--- a/archify/test/ordinary-model-floor.test.mjs+++ b/archify/test/ordinary-model-floor.test.mjs@@ -834,13 +834,16 @@ test('benchmark documentation locks the fair-run and truthful-evidence contract'}});-test('packaged skill puts a bounded ordinary-model authoring path before the feature catalogue', () => {+test('packaged skill puts a bounded ordinary-model path before progressive feature references', () => {const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');+ const authoring = fs.readFileSync(path.join(skillRoot, 'references', 'authoring-contract.md'), 'utf8');+ const viewer = fs.readFileSync(path.join(skillRoot, 'references', 'viewer-runtime.md'), 'utf8');const fastPath = skill.indexOf('## Fast authoring path');- const featureCatalogue = skill.indexOf('Direct Relationship Pin');+ const progressiveReferences = skill.indexOf('references/authoring-contract.md');assert.ok(fastPath > 0, 'fast authoring path must exist');- assert.ok(fastPath < featureCatalogue, 'fast authoring path must precede the feature catalogue');+ assert.ok(fastPath < progressiveReferences, 'fast authoring path must precede progressive references');+ assert.ok(skill.trimEnd().split('\n').length <= 160, 'ordinary authors must not ingest the viewer catalogue');for (const required of ['one matching schema','one matching JSON example',@@ -866,8 +869,14 @@ test('packaged skill puts a bounded ordinary-model authoring path before the fea'validate <type>','supportedFixes',]) {- assert.match(skill.slice(fastPath, featureCatalogue), new RegExp(required.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));+ assert.match(+ skill.slice(fastPath, progressiveReferences),+ new RegExp(required.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'),+ );}+ assert.match(authoring, /componentType/);+ assert.match(authoring, /clear gap between boxes, not center distance/i);+ assert.match(viewer, /Direct Relationship Pin/);});test('dated three-model evidence retains every frozen attempt-1 candidate and truthful gate result', () => {diff --git a/archify/test/preview-contract.test.mjs b/archify/test/preview-contract.test.mjsindex f17fa290..32eaf1c1 100644--- a/archify/test/preview-contract.test.mjs+++ b/archify/test/preview-contract.test.mjs@@ -8,18 +8,19 @@ const here = path.dirname(fileURLToPath(import.meta.url));const skillRoot = path.resolve(here, '..');const repoRoot = path.resolve(skillRoot, '..');const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');+const delivery = fs.readFileSync(path.join(skillRoot, 'references', 'delivery-contract.md'), 'utf8');const readme = fs.readFileSync(path.join(repoRoot, 'README.md'), 'utf8');const english = fs.readFileSync(path.join(repoRoot, 'README_EN.md'), 'utf8');const chinese = fs.readFileSync(path.join(repoRoot, 'README_ZH.md'), 'utf8');const roadmap = fs.readFileSync(path.join(repoRoot, 'ROADMAP.md'), 'utf8');test('preview contract: the skill keeps live preview explicit, desktop-only, and last-good', () => {- assert.match(skill, /archify\.mjs preview <type> <input>\.json <output>\.html/);- assert.match(skill, /active desktop authoring loop/i);- assert.match(skill, /previous verified revision remains on screen and on disk/i);- assert.match(skill, /never start it by default/i);- assert.match(skill, /CI, unattended agents, remote sharing, or mobile use/i);- assert.match(skill, /must never enter the generated artifact or any export/i);+ assert.match(delivery, /archify\.mjs preview <type> <input>\.json <output>\.html/);+ assert.match(delivery, /active desktop authoring loop/i);+ assert.match(delivery, /previous verified revision on screen and on disk/i);+ assert.match(delivery, /never start it by default/i);+ assert.match(delivery, /CI, unattended agents, remote sharing, or mobile use/i);+ assert.match(delivery, /must never enter the generated artifact or any export/i);});test('preview contract: all README languages document the same optional command without changing the hero', () => {diff --git a/archify/test/reach-share-card.test.mjs b/archify/test/reach-share-card.test.mjsindex 99f2df51..822ab474 100644--- a/archify/test/reach-share-card.test.mjs+++ b/archify/test/reach-share-card.test.mjs@@ -120,12 +120,12 @@ test('Reach Share Card reuses the 1200x630 seam and publishes a truthful scoped});test('Skill, product docs, and READMEs keep the optional truthful boundary explicit', () => {- const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');- assert.match(skill, /Export → Reach Share Card/);- assert.match(skill, /variant=reach/);- assert.match(skill, /data-share-reach-\*/);- assert.match(skill, /authored reachability/i);- assert.match(skill, /download-only/i);+ const viewer = fs.readFileSync(path.join(skillRoot, 'references', 'viewer-runtime.md'), 'utf8');+ assert.match(viewer, /Export → Reach Share Card/);+ assert.match(viewer, /variant=reach/);+ assert.match(viewer, /data-share-reach-\*/);+ assert.match(viewer, /authored reachability/i);+ assert.match(viewer, /download-only/i);for (const readme of ['README.md', 'README_EN.md', 'README_ZH.md']) {const text = fs.readFileSync(path.join(repoRoot, readme), 'utf8');diff --git a/archify/test/route-share-card.test.mjs b/archify/test/route-share-card.test.mjsindex d2ffa6f9..e919db07 100644--- a/archify/test/route-share-card.test.mjs+++ b/archify/test/route-share-card.test.mjs@@ -138,12 +138,12 @@ test('Route Share Card reuses one 1200x630 variant seam and publishes a truthful});test('skill and READMEs describe the optional Export variant and show one real card without changing the hero', () => {- const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');- assert.match(skill, /Export → Route Share Card/);- assert.match(skill, /format=share-card/);- assert.match(skill, /variant=route/);- assert.match(skill, /data-share-route-\*/);- assert.match(skill, /download-only/i);+ const viewer = fs.readFileSync(path.join(skillRoot, 'references', 'viewer-runtime.md'), 'utf8');+ assert.match(viewer, /Export → Route Share Card/);+ assert.match(viewer, /format=share-card/);+ assert.match(viewer, /variant=route/);+ assert.match(viewer, /data-share-route-\*/);+ assert.match(viewer, /download-only/i);for (const readme of ['README.md', 'README_EN.md', 'README_ZH.md']) {const text = fs.readFileSync(path.join(repoRoot, readme), 'utf8');diff --git a/archify/test/semantic-zoom.test.mjs b/archify/test/semantic-zoom.test.mjsindex 3ff6dabf..29785119 100644--- a/archify/test/semantic-zoom.test.mjs+++ b/archify/test/semantic-zoom.test.mjs@@ -39,7 +39,7 @@ test('all typed renderers emit explicit context and fine reading-depth semanticsassert.match(html, /data-detail="fine"/, mode);assert.match(html, /data-detail-anchor/, mode);assert.doesNotMatch(html, /<text[^>]*data-detail="(?:context|fine)"[^>]*class="t-primary"/, mode);- assert.match(html, /class="diagram-container" data-detail-level="map"/, mode);+ assert.match(html, /class="diagram-container" data-detail-level="read"/, mode);}});@@ -48,7 +48,7 @@ test('semantic zoom exposes MAP, READ, and FULL at deterministic thresholds', ()assert.match(html, /function detailLevel\(\)/);assert.match(html, /if \(state\.mode === 'semantic'\) return 'full'/);assert.match(html, /if \(state\.scale >= 1\.75\) return 'full'/);- assert.match(html, /if \(state\.scale >= 1\.25\) return 'read'/);+ assert.match(html, /if \(state\.scale >= 1\) return 'read'/);assert.match(html, /return 'map'/);assert.match(html, /container\.setAttribute\('data-detail-level', detail\)/);assert.match(html, /detail === 'map' \? 'MAP ' : detail === 'read' \? 'READ ' : 'FULL '/);diff --git a/archify/test/share-card-export.test.mjs b/archify/test/share-card-export.test.mjsindex df3d00e1..f23024ac 100644--- a/archify/test/share-card-export.test.mjs+++ b/archify/test/share-card-export.test.mjs@@ -115,11 +115,11 @@ test('Share Card stays viewer-only and reuses export cleanup instead of source s});test('the skill and every README make the optional Share Card discoverable', () => {- const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');- assert.match(skill, /optional 1200(?:×|x)630 Share Card PNG/i);- assert.match(skill, /current theme and visual preset/i);- assert.match(skill, /never claim(?:s|ing)? validation/i);- assert.match(skill, /Copy Share Card/i);+ const viewer = fs.readFileSync(path.join(skillRoot, 'references', 'viewer-runtime.md'), 'utf8');+ assert.match(viewer, /optional 1200(?:×|x)630 Share Card PNG/i);+ assert.match(viewer, /current theme and visual preset/i);+ assert.match(viewer, /never claim(?:s|ing)? validation/i);+ assert.match(viewer, /Copy Share Card/i);for (const readme of ['README.md', 'README_EN.md', 'README_ZH.md']) {const text = fs.readFileSync(path.join(repoRoot, readme), 'utf8');diff --git a/archify/test/skill-metadata.test.mjs b/archify/test/skill-metadata.test.mjsindex 654387ac..553e7239 100644--- a/archify/test/skill-metadata.test.mjs+++ b/archify/test/skill-metadata.test.mjs@@ -24,7 +24,7 @@ test('skill description is portable across 1024-character runtimes and remains s});test('literal packaged-skill path references resolve inside the installed skill root', () => {- const references = [...skill.matchAll(/`((?:assets|bin|examples|recipes|renderers|schemas|scripts)\/[^`\s]+)`/g)]+ const references = [...skill.matchAll(/`((?:assets|bin|examples|recipes|references|renderers|schemas|scripts)\/[^`\s]+)`/g)].map((match) => match[1]).filter((reference) => !/[<>{}*\[\]]/.test(reference));@@ -33,3 +33,16 @@ test('literal packaged-skill path references resolve inside the installed skillassert.equal(existsSync(path.join(skillRoot, reference)), true, `SKILL.md references missing packaged path ${reference}`);}});++test('main skill stays a bounded authoring router with progressive references', () => {+ const lines = skill.trimEnd().split('\n');+ assert.ok(lines.length <= 160, `SKILL.md is ${lines.length} lines; keep the entrypoint at 160 or fewer`);+ for (const reference of [+ 'references/authoring-contract.md',+ 'references/viewer-runtime.md',+ 'references/delivery-contract.md',+ ]) {+ assert.match(skill, new RegExp(reference.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));+ assert.equal(existsSync(path.join(skillRoot, reference)), true, `${reference} must ship with the skill`);+ }+});diff --git a/docs/assets/archify-live-proof.gif b/docs/assets/archify-live-proof.gifindex b30b42ff..c5489121 100644Binary files a/docs/assets/archify-live-proof.gif and b/docs/assets/archify-live-proof.gif differdiff --git a/docs/assets/archify-live-proof.json b/docs/assets/archify-live-proof.jsonindex 8f471630..236798d5 100644--- a/docs/assets/archify-live-proof.json+++ b/docs/assets/archify-live-proof.json@@ -7,13 +7,13 @@"fps": 10,"frameCount": 54,"durationSeconds": 5.4,- "bytes": 1528284,- "sha256": "2724e367a0c1695a50964eaa8c704c97cc84dbe2452640803786d9fdf710dbe7",+ "bytes": 1532750,+ "sha256": "efd1ca676e5548e75781aec988afc6e2cbca54191bcb8bf44e3f1195a82c868a","scenes": [{"id": "signal-flow","artifact": "docs/gallery/artifacts/agent-tool-call.workflow.html",- "artifactSha256": "379d536b3a75589bed2a6b3a3c2f20947fffbef29376a7757f1aa45efc8197fc",+ "artifactSha256": "6e44131bafbfa576c1f471d41410b37b3c80b38160423d4de516771844a8e40a","view": "happy-path","eyebrow": "WORKFLOW · SIGNAL FLOW","title": "Agent Tool Call",@@ -22,7 +22,7 @@{"id": "blueprint","artifact": "docs/gallery/artifacts/production-deployment.architecture.html",- "artifactSha256": "e0ead588fb48511d5695fddbeb5871a76357d8c657644e163dfba454d082a1f5",+ "artifactSha256": "b0ec59f3ede5b08b2b90ab996410a6d16dde8d5874bd0d6295f83d57e38b5192","view": "request-boundary","eyebrow": "ARCHITECTURE · BLUEPRINT","title": "Production Deployment",@@ -31,7 +31,7 @@{"id": "classic","artifact": "docs/gallery/artifacts/cache-miss.sequence.html",- "artifactSha256": "1ca674c7ebd8df68f358adde54549cea4cb305f5c9c27ff090cff4715961b3c5",+ "artifactSha256": "3f461d05a742e6a2965942eb118686ddfad842c1c3f64bf1914db5838145dc40","view": "cache-fallback","eyebrow": "SEQUENCE · CLASSIC","title": "Cache Miss Request",diff --git a/docs/cases/mco-runtime.architecture.html b/docs/cases/mco-runtime.architecture.htmlindex ad4eef38..f60fbc3c 100644--- a/docs/cases/mco-runtime.architecture.html+++ b/docs/cases/mco-runtime.architecture.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1750 648" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">MCO Runtime Architecture</title><desc id="archify-diagram-description">mco-org/mco · explicit provider policy · parallel invocation · durable raw answers</desc>@@ -10285,7 +10285,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery.html b/docs/gallery.htmlindex eaf5f43e..4fd953d2 100644--- a/docs/gallery.html+++ b/docs/gallery.html@@ -339,7 +339,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">12N · 11E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="379d536b3a75589bed2a6b3a3c2f20947fffbef29376a7757f1aa45efc8197fc">379d536b3a75</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="6e44131bafbfa576c1f471d41410b37b3c80b38160423d4de516771844a8e40a">6e44131bafbf</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/agent-tool-call.workflow.html?present=1&play=1#view=happy-path" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -369,7 +369,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">12N · 12E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="e0ead588fb48511d5695fddbeb5871a76357d8c657644e163dfba454d082a1f5">e0ead588fb48</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="b0ec59f3ede5b08b2b90ab996410a6d16dde8d5874bd0d6295f83d57e38b5192">b0ec59f3ede5</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/production-deployment.architecture.html?present=1&play=1#view=request-boundary" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -398,7 +398,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">7N · 12E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="1ca674c7ebd8df68f358adde54549cea4cb305f5c9c27ff090cff4715961b3c5">1ca674c7ebd8</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="3f461d05a742e6a2965942eb118686ddfad842c1c3f64bf1914db5838145dc40">3f461d05a742</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/cache-miss.sequence.html?present=1&play=1#view=cache-fallback" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -427,7 +427,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">10N · 10E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="642e528f598b1ad8860a9c161fe9abde788232fe35fd58d5f81ac13388e8aad1">642e528f598b</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="ea9b02cac6bd1ec228f715291fdc3c5ab08266862120e6d660c9a1df6ed89514">ea9b02cac6bd</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/release-delivery.workflow.html?present=1&play=1#view=approval-to-production" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -456,7 +456,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">11N · 10E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="243b59fe0bb895fa0ce2a6200597c85435b5374a6acc52a9bc8201a2542ee60f">243b59fe0bb8</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="9d7b4ee88cc9c495f324dc28d29757b2c768637f313482cc0090b02a49e458ca">9d7b4ee88cc9</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/incident-response.workflow.html?present=1&play=1#view=mitigate-and-verify" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -485,7 +485,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">10N · 10E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="ced8f6d7dc818dd85510d9028b0ba91b524221648e6cdd1fc01084b8b1533ebf">ced8f6d7dc81</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="054ed6d3cdce7e0c05adc8537e60039c4c5254c54da054e6a1e996a7b59778d3">054ed6d3cdce</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/product-analytics.dataflow.html?present=1&play=1#view=consent-boundary" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -514,7 +514,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">7N · 14E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="de84aaab5faa9c7ebfd9131d954d082aec4f86339191b5e4c06b709ea434440f">de84aaab5faa</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="0739bdcdb5ad0295d2d4678cd35fd602f7dd6ec493f2cdbfa9b39e3daa5ba6ca">0739bdcdb5ad</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/async-job-roundtrip.sequence.html?present=1&play=1#view=work-and-retry" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -543,7 +543,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">12N · 12E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="e907d9738ed96b7916e9e11f4e586f743a97136a02ab9abcfe34654d36ebb6ca">e907d9738ed9</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="a2080899f33e2838dc2262631ffb0ccd5cc9fb733e0a70b3a10ea9db6a58f432">a2080899f33e</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/event-stream.dataflow.html?present=1&play=1#view=order-transit" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -572,7 +572,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">10N · 6E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="99f278926349209a9f1210c0474f955224a34954df9663729590aeae439342d2">99f278926349</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="d17afa5eb4d4dc46d3bdf36e933ae4e516c887436465aa3a38fb80e068eb4a4c">d17afa5eb4d4</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/agent-run.lifecycle.html?present=1&play=1#view=main-lifecycle" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -601,7 +601,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">11N · 6E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="4be5e1dd4dbf5cc4a282f3e1130a6396f2907c6f69de8e98b689d16d606bc050">4be5e1dd4dbf</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="07b7866bae2a55081b098e9ca138c78e21fbe7cd8a17019e6c3e4fa161dbd015">07b7866bae2a</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/deployment-release.lifecycle.html?present=1&play=1#view=rollback-outcomes" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -630,7 +630,7 @@<div class="receipt-cell"><span class="receipt-label">Artifact</span><span class="receipt-value ok">9/9 pass</span></div><div class="receipt-cell"><span class="receipt-label">Composition</span><span class="receipt-value ok" title="0 crossings · 0 border runs · 0 micro segments · 0 cramped turns">SHOWCASE · PASS</span></div><div class="receipt-cell"><span class="receipt-label">Graph</span><span class="receipt-value">10N · 9E</span></div>- <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="20b54eecdc52a5fe0de96e72aa60f55360745cc7bac9840ac13cdc451dffb27d">20b54eecdc52</span></div>+ <div class="receipt-cell"><span class="receipt-label">SHA-256</span><span class="receipt-value" title="81575f47e406dcd836af7a1f6b50d327ccfff6227773fca95b6681b8a8ae611c">81575f47e406</span></div></div><div class="card-actions"><a class="card-link primary" href="gallery/artifacts/web-app.architecture.html?present=1&play=1#view=request-path" target="_blank" rel="noopener" data-en="Play named chapter ↗" data-zh="播放命名章节 ↗">Play named chapter ↗</a>@@ -716,8 +716,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 12,"edgeCount": 11,- "artifactBytes": 619333,- "artifactSha256": "379d536b3a75589bed2a6b3a3c2f20947fffbef29376a7757f1aa45efc8197fc",+ "artifactBytes": 619331,+ "artifactSha256": "6e44131bafbfa576c1f471d41410b37b3c80b38160423d4de516771844a8e40a","sourceBytes": 6470,"sourceSha256": "a3afc6b30044eb256aa15c6195ddfbbcd1a14880d99967ed5605bc621ffb7e5f","checks": [@@ -814,8 +814,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": "deployment-ownership","nodeCount": 12,"edgeCount": 12,- "artifactBytes": 619649,- "artifactSha256": "e0ead588fb48511d5695fddbeb5871a76357d8c657644e163dfba454d082a1f5",+ "artifactBytes": 619647,+ "artifactSha256": "b0ec59f3ede5b08b2b90ab996410a6d16dde8d5874bd0d6295f83d57e38b5192","sourceBytes": 5546,"sourceSha256": "03e647d057eb20d99f7fb4ba4ddfdd5d58a7a813865338680e968038e6a90e0f","checks": [@@ -912,8 +912,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 7,"edgeCount": 12,- "artifactBytes": 613482,- "artifactSha256": "1ca674c7ebd8df68f358adde54549cea4cb305f5c9c27ff090cff4715961b3c5",+ "artifactBytes": 613480,+ "artifactSha256": "3f461d05a742e6a2965942eb118686ddfad842c1c3f64bf1914db5838145dc40","sourceBytes": 4442,"sourceSha256": "30098d81006a18813bab447da698edf74604a1463770f01dc056b0af8cb314ef","checks": [@@ -1010,8 +1010,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 10,"edgeCount": 10,- "artifactBytes": 615595,- "artifactSha256": "642e528f598b1ad8860a9c161fe9abde788232fe35fd58d5f81ac13388e8aad1",+ "artifactBytes": 615593,+ "artifactSha256": "ea9b02cac6bd1ec228f715291fdc3c5ab08266862120e6d660c9a1df6ed89514","sourceBytes": 5256,"sourceSha256": "44aa56ac6ca807937dfe84a6404e8b07d6394a38ae2ac53248a1985337dfd671","checks": [@@ -1108,8 +1108,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 11,"edgeCount": 10,- "artifactBytes": 615456,- "artifactSha256": "243b59fe0bb895fa0ce2a6200597c85435b5374a6acc52a9bc8201a2542ee60f",+ "artifactBytes": 615454,+ "artifactSha256": "9d7b4ee88cc9c495f324dc28d29757b2c768637f313482cc0090b02a49e458ca","sourceBytes": 5471,"sourceSha256": "9beb8698b275679a2fc92d4b51288cd5b5fc2115696d06b9168f3d7fef253a72","checks": [@@ -1206,8 +1206,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 10,"edgeCount": 10,- "artifactBytes": 616982,- "artifactSha256": "ced8f6d7dc818dd85510d9028b0ba91b524221648e6cdd1fc01084b8b1533ebf",+ "artifactBytes": 616980,+ "artifactSha256": "054ed6d3cdce7e0c05adc8537e60039c4c5254c54da054e6a1e996a7b59778d3","sourceBytes": 5719,"sourceSha256": "f71c89288f80255bdedcdc0057bcbc155d1d8b1b7476d024b35f4e27c730c974","checks": [@@ -1304,8 +1304,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 7,"edgeCount": 14,- "artifactBytes": 614279,- "artifactSha256": "de84aaab5faa9c7ebfd9131d954d082aec4f86339191b5e4c06b709ea434440f",+ "artifactBytes": 614277,+ "artifactSha256": "0739bdcdb5ad0295d2d4678cd35fd602f7dd6ec493f2cdbfa9b39e3daa5ba6ca","sourceBytes": 4483,"sourceSha256": "1b53d7c4ce7b2d8f6f40b8f33a394abe1d37fc991272b534c1ccd0255920ab52","checks": [@@ -1402,8 +1402,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 12,"edgeCount": 12,- "artifactBytes": 620937,- "artifactSha256": "e907d9738ed96b7916e9e11f4e586f743a97136a02ab9abcfe34654d36ebb6ca",+ "artifactBytes": 620935,+ "artifactSha256": "a2080899f33e2838dc2262631ffb0ccd5cc9fb733e0a70b3a10ea9db6a58f432","sourceBytes": 5543,"sourceSha256": "bbfedc2f1b73bf50932490f7f56d45d5f853e970d2fab26660a04947a783969c","checks": [@@ -1500,8 +1500,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 10,"edgeCount": 6,- "artifactBytes": 610314,- "artifactSha256": "99f278926349209a9f1210c0474f955224a34954df9663729590aeae439342d2",+ "artifactBytes": 610312,+ "artifactSha256": "d17afa5eb4d4dc46d3bdf36e933ae4e516c887436465aa3a38fb80e068eb4a4c","sourceBytes": 4527,"sourceSha256": "2e756b3d1ebc2f6c3f62f46c0fbb5584ed7bd6213627259ab43153b18c831cdf","checks": [@@ -1598,8 +1598,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 11,"edgeCount": 6,- "artifactBytes": 611304,- "artifactSha256": "4be5e1dd4dbf5cc4a282f3e1130a6396f2907c6f69de8e98b689d16d606bc050",+ "artifactBytes": 611302,+ "artifactSha256": "07b7866bae2a55081b098e9ca138c78e21fbe7cd8a17019e6c3e4fa161dbd015","sourceBytes": 4394,"sourceSha256": "aa614f0c9a82f210e301e382f362dfbd7f290bda4d5501de3c99a6cd81b4c0a4","checks": [@@ -1696,8 +1696,8 @@ receipt 99 checks / 11 artifacts / deterministic hashes</pre>"engineeringProfile": null,"nodeCount": 10,"edgeCount": 9,- "artifactBytes": 610936,- "artifactSha256": "20b54eecdc52a5fe0de96e72aa60f55360745cc7bac9840ac13cdc451dffb27d",+ "artifactBytes": 610934,+ "artifactSha256": "81575f47e406dcd836af7a1f6b50d327ccfff6227773fca95b6681b8a8ae611c","sourceBytes": 3863,"sourceSha256": "01567b5e49cad5139baa071533a028d22f0e80fedfb49095e0d9330aee7f87db","checks": [diff --git a/docs/gallery/artifacts/agent-run.lifecycle.html b/docs/gallery/artifacts/agent-run.lifecycle.htmlindex 0f617ed4..fc75e0b4 100644--- a/docs/gallery/artifacts/agent-run.lifecycle.html+++ b/docs/gallery/artifacts/agent-run.lifecycle.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 980 660" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Agent Run Lifecycle</title><desc id="archify-diagram-description">State machine for planning, tool execution, human approval, retries, and terminal outcomes</desc>@@ -10219,7 +10219,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/agent-tool-call.workflow.html b/docs/gallery/artifacts/agent-tool-call.workflow.htmlindex fd8b483d..f2be2f00 100644--- a/docs/gallery/artifacts/agent-tool-call.workflow.html+++ b/docs/gallery/artifacts/agent-tool-call.workflow.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 720 900" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">Agent Tool Call Workflow</title><desc id="archify-diagram-description">Renderer-driven workflow prototype with lanes, anchored nodes, and orthogonal edges</desc>@@ -10297,7 +10297,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/async-job-roundtrip.sequence.html b/docs/gallery/artifacts/async-job-roundtrip.sequence.htmlindex e7dd8029..34b01733 100644--- a/docs/gallery/artifacts/async-job-roundtrip.sequence.html+++ b/docs/gallery/artifacts/async-job-roundtrip.sequence.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 820 920" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">Async Job Roundtrip</title><desc id="archify-diagram-description">Acknowledgement, queueing, background work, retries, callback, polling, and final consistency</desc>@@ -10295,7 +10295,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/cache-miss.sequence.html b/docs/gallery/artifacts/cache-miss.sequence.htmlindex 9dbd25b8..7eb5ad37 100644--- a/docs/gallery/artifacts/cache-miss.sequence.html+++ b/docs/gallery/artifacts/cache-miss.sequence.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 820 760" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Cache Miss Request Sequence</title><desc id="archify-diagram-description">Frontend request path with auth, cache fallback, persistence, and async trace</desc>@@ -10279,7 +10279,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/deployment-release.lifecycle.html b/docs/gallery/artifacts/deployment-release.lifecycle.htmlindex 2a2ef555..a3b4bd43 100644--- a/docs/gallery/artifacts/deployment-release.lifecycle.html+++ b/docs/gallery/artifacts/deployment-release.lifecycle.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 980 680" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">Deployment Release Lifecycle</title><desc id="archify-diagram-description">Queued, building, verifying, approval, promotion, health regression, rollback, and terminal outcomes</desc>@@ -10231,7 +10231,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/event-stream.dataflow.html b/docs/gallery/artifacts/event-stream.dataflow.htmlindex fbf6ecf5..692fb6ec 100644--- a/docs/gallery/artifacts/event-stream.dataflow.html+++ b/docs/gallery/artifacts/event-stream.dataflow.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 780" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">Order Event-stream Topology</title><desc id="archify-diagram-description">Named events, ordered topics, processors, consumer groups, state, replay, and dead letters</desc>@@ -10303,7 +10303,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/incident-response.workflow.html b/docs/gallery/artifacts/incident-response.workflow.htmlindex f1867740..2d93e605 100644--- a/docs/gallery/artifacts/incident-response.workflow.html+++ b/docs/gallery/artifacts/incident-response.workflow.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 720 900" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">Incident Response Runbook</title><desc id="archify-diagram-description">Detection, triage, mitigation, communication, escalation, and recovery proof</desc>@@ -10266,7 +10266,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/product-analytics.dataflow.html b/docs/gallery/artifacts/product-analytics.dataflow.htmlindex 07df163b..9daab182 100644--- a/docs/gallery/artifacts/product-analytics.dataflow.html+++ b/docs/gallery/artifacts/product-analytics.dataflow.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 760" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Product Analytics Data Flow</title><desc id="archify-diagram-description">Events, consent, PII isolation, warehouse sync, and downstream analytics</desc>@@ -10264,7 +10264,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/production-deployment.architecture.html b/docs/gallery/artifacts/production-deployment.architecture.htmlindex b58191e5..ab1680fe 100644--- a/docs/gallery/artifacts/production-deployment.architecture.html+++ b/docs/gallery/artifacts/production-deployment.architecture.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1436 760" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="blueprint" data-engineering-profile="deployment-ownership" data-quality-profile="showcase"><title id="archify-diagram-title">Production Deployment Ownership</title><desc id="archify-diagram-description">Regions, network boundaries, workload owners, state, and named crossings</desc>@@ -10292,7 +10292,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/release-delivery.workflow.html b/docs/gallery/artifacts/release-delivery.workflow.htmlindex 199ee310..7d253d3e 100644--- a/docs/gallery/artifacts/release-delivery.workflow.html+++ b/docs/gallery/artifacts/release-delivery.workflow.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 720 900" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Release Delivery Workflow</title><desc id="archify-diagram-description">Commit, blocking checks, approval, production verification, and rollback</desc>@@ -10266,7 +10266,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/artifacts/web-app.architecture.html b/docs/gallery/artifacts/web-app.architecture.htmlindex 9d4d2c56..3aea3786 100644--- a/docs/gallery/artifacts/web-app.architecture.html+++ b/docs/gallery/artifacts/web-app.architecture.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 588" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Sample Web App</title><desc id="archify-diagram-description">Classic 3-tier SaaS on AWS — rendered by Archify</desc>@@ -10233,7 +10233,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/docs/gallery/manifest.json b/docs/gallery/manifest.jsonindex 7bbd06a0..36ea7fda 100644--- a/docs/gallery/manifest.json+++ b/docs/gallery/manifest.json@@ -27,8 +27,8 @@"engineeringProfile": null,"nodeCount": 12,"edgeCount": 11,- "artifactBytes": 619333,- "artifactSha256": "379d536b3a75589bed2a6b3a3c2f20947fffbef29376a7757f1aa45efc8197fc",+ "artifactBytes": 619331,+ "artifactSha256": "6e44131bafbfa576c1f471d41410b37b3c80b38160423d4de516771844a8e40a","sourceBytes": 6470,"sourceSha256": "a3afc6b30044eb256aa15c6195ddfbbcd1a14880d99967ed5605bc621ffb7e5f","checks": [@@ -125,8 +125,8 @@"engineeringProfile": "deployment-ownership","nodeCount": 12,"edgeCount": 12,- "artifactBytes": 619649,- "artifactSha256": "e0ead588fb48511d5695fddbeb5871a76357d8c657644e163dfba454d082a1f5",+ "artifactBytes": 619647,+ "artifactSha256": "b0ec59f3ede5b08b2b90ab996410a6d16dde8d5874bd0d6295f83d57e38b5192","sourceBytes": 5546,"sourceSha256": "03e647d057eb20d99f7fb4ba4ddfdd5d58a7a813865338680e968038e6a90e0f","checks": [@@ -223,8 +223,8 @@"engineeringProfile": null,"nodeCount": 7,"edgeCount": 12,- "artifactBytes": 613482,- "artifactSha256": "1ca674c7ebd8df68f358adde54549cea4cb305f5c9c27ff090cff4715961b3c5",+ "artifactBytes": 613480,+ "artifactSha256": "3f461d05a742e6a2965942eb118686ddfad842c1c3f64bf1914db5838145dc40","sourceBytes": 4442,"sourceSha256": "30098d81006a18813bab447da698edf74604a1463770f01dc056b0af8cb314ef","checks": [@@ -321,8 +321,8 @@"engineeringProfile": null,"nodeCount": 10,"edgeCount": 10,- "artifactBytes": 615595,- "artifactSha256": "642e528f598b1ad8860a9c161fe9abde788232fe35fd58d5f81ac13388e8aad1",+ "artifactBytes": 615593,+ "artifactSha256": "ea9b02cac6bd1ec228f715291fdc3c5ab08266862120e6d660c9a1df6ed89514","sourceBytes": 5256,"sourceSha256": "44aa56ac6ca807937dfe84a6404e8b07d6394a38ae2ac53248a1985337dfd671","checks": [@@ -419,8 +419,8 @@"engineeringProfile": null,"nodeCount": 11,"edgeCount": 10,- "artifactBytes": 615456,- "artifactSha256": "243b59fe0bb895fa0ce2a6200597c85435b5374a6acc52a9bc8201a2542ee60f",+ "artifactBytes": 615454,+ "artifactSha256": "9d7b4ee88cc9c495f324dc28d29757b2c768637f313482cc0090b02a49e458ca","sourceBytes": 5471,"sourceSha256": "9beb8698b275679a2fc92d4b51288cd5b5fc2115696d06b9168f3d7fef253a72","checks": [@@ -517,8 +517,8 @@"engineeringProfile": null,"nodeCount": 10,"edgeCount": 10,- "artifactBytes": 616982,- "artifactSha256": "ced8f6d7dc818dd85510d9028b0ba91b524221648e6cdd1fc01084b8b1533ebf",+ "artifactBytes": 616980,+ "artifactSha256": "054ed6d3cdce7e0c05adc8537e60039c4c5254c54da054e6a1e996a7b59778d3","sourceBytes": 5719,"sourceSha256": "f71c89288f80255bdedcdc0057bcbc155d1d8b1b7476d024b35f4e27c730c974","checks": [@@ -615,8 +615,8 @@"engineeringProfile": null,"nodeCount": 7,"edgeCount": 14,- "artifactBytes": 614279,- "artifactSha256": "de84aaab5faa9c7ebfd9131d954d082aec4f86339191b5e4c06b709ea434440f",+ "artifactBytes": 614277,+ "artifactSha256": "0739bdcdb5ad0295d2d4678cd35fd602f7dd6ec493f2cdbfa9b39e3daa5ba6ca","sourceBytes": 4483,"sourceSha256": "1b53d7c4ce7b2d8f6f40b8f33a394abe1d37fc991272b534c1ccd0255920ab52","checks": [@@ -713,8 +713,8 @@"engineeringProfile": null,"nodeCount": 12,"edgeCount": 12,- "artifactBytes": 620937,- "artifactSha256": "e907d9738ed96b7916e9e11f4e586f743a97136a02ab9abcfe34654d36ebb6ca",+ "artifactBytes": 620935,+ "artifactSha256": "a2080899f33e2838dc2262631ffb0ccd5cc9fb733e0a70b3a10ea9db6a58f432","sourceBytes": 5543,"sourceSha256": "bbfedc2f1b73bf50932490f7f56d45d5f853e970d2fab26660a04947a783969c","checks": [@@ -811,8 +811,8 @@"engineeringProfile": null,"nodeCount": 10,"edgeCount": 6,- "artifactBytes": 610314,- "artifactSha256": "99f278926349209a9f1210c0474f955224a34954df9663729590aeae439342d2",+ "artifactBytes": 610312,+ "artifactSha256": "d17afa5eb4d4dc46d3bdf36e933ae4e516c887436465aa3a38fb80e068eb4a4c","sourceBytes": 4527,"sourceSha256": "2e756b3d1ebc2f6c3f62f46c0fbb5584ed7bd6213627259ab43153b18c831cdf","checks": [@@ -909,8 +909,8 @@"engineeringProfile": null,"nodeCount": 11,"edgeCount": 6,- "artifactBytes": 611304,- "artifactSha256": "4be5e1dd4dbf5cc4a282f3e1130a6396f2907c6f69de8e98b689d16d606bc050",+ "artifactBytes": 611302,+ "artifactSha256": "07b7866bae2a55081b098e9ca138c78e21fbe7cd8a17019e6c3e4fa161dbd015","sourceBytes": 4394,"sourceSha256": "aa614f0c9a82f210e301e382f362dfbd7f290bda4d5501de3c99a6cd81b4c0a4","checks": [@@ -1007,8 +1007,8 @@"engineeringProfile": null,"nodeCount": 10,"edgeCount": 9,- "artifactBytes": 610936,- "artifactSha256": "20b54eecdc52a5fe0de96e72aa60f55360745cc7bac9840ac13cdc451dffb27d",+ "artifactBytes": 610934,+ "artifactSha256": "81575f47e406dcd836af7a1f6b50d327ccfff6227773fca95b6681b8a8ae611c","sourceBytes": 3863,"sourceSha256": "01567b5e49cad5139baa071533a028d22f0e80fedfb49095e0d9330aee7f87db","checks": [diff --git a/examples/dataflow-product-analytics.html b/examples/dataflow-product-analytics.htmlindex 07df163b..9daab182 100644--- a/examples/dataflow-product-analytics.html+++ b/examples/dataflow-product-analytics.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 760" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Product Analytics Data Flow</title><desc id="archify-diagram-description">Events, consent, PII isolation, warehouse sync, and downstream analytics</desc>@@ -10264,7 +10264,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/examples/lifecycle-agent-run.html b/examples/lifecycle-agent-run.htmlindex 0f617ed4..fc75e0b4 100644--- a/examples/lifecycle-agent-run.html+++ b/examples/lifecycle-agent-run.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 980 660" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Agent Run Lifecycle</title><desc id="archify-diagram-description">State machine for planning, tool execution, human approval, retries, and terminal outcomes</desc>@@ -10219,7 +10219,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/examples/sequence-cache-miss-request.html b/examples/sequence-cache-miss-request.htmlindex 9dbd25b8..7eb5ad37 100644--- a/examples/sequence-cache-miss-request.html+++ b/examples/sequence-cache-miss-request.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 820 760" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Cache Miss Request Sequence</title><desc id="archify-diagram-description">Frontend request path with auth, cache fallback, persistence, and async trace</desc>@@ -10279,7 +10279,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/examples/web-app-rendered.html b/examples/web-app-rendered.htmlindex 9d4d2c56..3aea3786 100644--- a/examples/web-app-rendered.html+++ b/examples/web-app-rendered.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 588" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Sample Web App</title><desc id="archify-diagram-description">Classic 3-tier SaaS on AWS — rendered by Archify</desc>@@ -10233,7 +10233,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/examples/web-app.html b/examples/web-app.htmlindex 02ad0191..3aea3786 100644--- a/examples/web-app.html+++ b/examples/web-app.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 1080 588" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-preset="classic" data-quality-profile="showcase"><title id="archify-diagram-title">Sample Web App</title><desc id="archify-diagram-description">Classic 3-tier SaaS on AWS — rendered by Archify</desc>@@ -4984,7 +4984,7 @@<!-- Footer --><p class="footer">- Architecture diagram • Built with Archify<span class="no-print"> • <a class="artifact-start-link" href="https://tt-a1i.github.io/archify/start.html?type=architecture" target="_blank" rel="noopener noreferrer">Create yours ↗</a> • Hover to trace • <kbd>R</kbd> route • Click to focus • <kbd>+</kbd>/<kbd>−</kbd> zoom • <kbd>M</kbd> radar • <kbd>[</kbd>/<kbd>]</kbd> views • <kbd>P</kbd> play story • <kbd>T</kbd> theme • <kbd>E</kbd> export</span>+ Architecture diagram • Built with Archify<span class="no-print"> • <a class="artifact-start-link" href="https://tt-a1i.github.io/archify/start.html?type=architecture&source=artifact" target="_blank" rel="noopener noreferrer">Create yours ↗</a> • Hover to trace • <kbd>R</kbd> route • Click to focus • <kbd>+</kbd>/<kbd>−</kbd> zoom • <kbd>M</kbd> radar • <kbd>[</kbd>/<kbd>]</kbd> views • <kbd>P</kbd> play story • <kbd>T</kbd> theme • <kbd>E</kbd> export</span></p></div>@@ -10233,7 +10233,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/examples/workflow-agent-tool-call-rendered.html b/examples/workflow-agent-tool-call-rendered.htmlindex fd8b483d..f2be2f00 100644--- a/examples/workflow-agent-tool-call-rendered.html+++ b/examples/workflow-agent-tool-call-rendered.html@@ -4543,7 +4543,7 @@</div><!-- Main Diagram -->- <div class="diagram-container" data-detail-level="map">+ <div class="diagram-container" data-detail-level="read"><svg viewBox="0 0 720 900" role="img" aria-labelledby="archify-diagram-title archify-diagram-description" data-animation="trace" data-preset="signal-flow" data-quality-profile="showcase"><title id="archify-diagram-title">Agent Tool Call Workflow</title><desc id="archify-diagram-description">Renderer-driven workflow prototype with lanes, anchored nodes, and orthogonal edges</desc>@@ -10297,7 +10297,7 @@function detailLevel() {if (state.mode === 'semantic') return 'full';if (state.scale >= 1.75) return 'full';- if (state.scale >= 1.25) return 'read';+ if (state.scale >= 1) return 'read';return 'map';}function renderControls() {diff --git a/scripts/package-smoke.mjs b/scripts/package-smoke.mjsindex 19a03f93..fd73fbb1 100644--- a/scripts/package-smoke.mjs+++ b/scripts/package-smoke.mjs@@ -60,7 +60,7 @@ try {const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');const skillReferences = [...skill.matchAll(- /`((?:assets|bin|examples|recipes|renderers|schemas|scripts)\/[^`\s]+)`/g,+ /`((?:assets|bin|examples|recipes|references|renderers|schemas|scripts)\/[^`\s]+)`/g,)].map((match) => match[1]).filter((reference) => !/[<>{}*\[\]]/.test(reference));@@ -116,7 +116,9 @@ try {'deliver', 'workflow', path.join(skillRoot, 'examples', fixtures[1][1]),path.join(scratch, 'workflow-delivered.html'), '--quality', 'showcase', '--json',]));- if (!delivered.ok || delivered.validation?.compositionStatus !== 'pass') {+ if (!delivered.ok || delivered.validation?.compositionStatus !== 'pass'+ || !/^[a-f0-9]{64}$/.test(delivered.specification?.sha256 || '')+ || !(delivered.specification?.bytes > 0)) {throw new Error('packaged workflow delivery did not return a passing receipt');}@@ -141,6 +143,55 @@ try {throw new Error('packaged skill did not return the expected unknown-field diagnostic');}+ const tangentEndpoint = {+ schema_version: 1,+ diagram_type: 'architecture',+ meta: { title: 'Endpoint direction smoke' },+ components: [+ { id: 'source', type: 'external', label: 'Source', pos: [300, 100], size: [100, 60] },+ { id: 'target', type: 'backend', label: 'Target', pos: [100, 240], size: [100, 60] },+ ],+ connections: [{+ id: 'tangent',+ from: 'source',+ to: 'target',+ fromSide: 'bottom',+ toSide: 'top',+ via: [[350, 200], [100, 200], [100, 240]],+ }],+ };+ const tangentPath = path.join(scratch, 'tangent-endpoint.architecture.json');+ fs.writeFileSync(tangentPath, JSON.stringify(tangentEndpoint));+ const tangentFailure = JSON.parse(runExpectFailure(['validate', 'architecture', tangentPath, '--json']));+ const tangentDiagnostic = tangentFailure.diagnostics?.find((diagnostic) => (+ diagnostic.code === 'clean-flow/endpoint-side-direction'+ ));+ if (tangentFailure.ok || tangentDiagnostic?.evidence?.authoredField !== 'toSide'+ || tangentDiagnostic?.evidence?.side !== 'top') {+ throw new Error('packaged skill did not reject a tangential target-port entry with structured repair evidence');+ }++ const inferredBridge = {+ schema_version: 1,+ diagram_type: 'architecture',+ meta: { title: 'Inferred endpoint bridge smoke' },+ components: [+ { id: 'workspace', type: 'frontend', label: 'Workspace UI', pos: [40, 300], size: [120, 60] },+ { id: 'runtime-server', type: 'backend', label: 'Runtime Server', pos: [220, 300], size: [120, 60] },+ { id: 'runtime-store', type: 'backend', label: 'Runtime Store', pos: [400, 300], size: [120, 60] },+ { id: 'stream-hub', type: 'messagebus', label: 'Terminal Stream Hub', pos: [700, 100], size: [120, 60] },+ ],+ connections: [{ id: 'terminal-return', from: 'stream-hub', to: 'workspace' }],+ };+ const inferredBridgePath = path.join(scratch, 'inferred-bridge.architecture.json');+ const inferredBridgeHtml = path.join(scratch, 'inferred-bridge.html');+ fs.writeFileSync(inferredBridgePath, JSON.stringify(inferredBridge));+ run(['render', 'architecture', inferredBridgePath, inferredBridgeHtml]);+ const inferredBridgeArtifact = fs.readFileSync(inferredBridgeHtml, 'utf8');+ if (!inferredBridgeArtifact.includes('data-composition-points="700,130;184,130;184,330;160,330"')) {+ throw new Error('packaged skill did not preserve inferred endpoint normals with a side-aware bridge');+ }+process.stdout.write(`package smoke passed on ${process.platform} (${skillRoot})\n`);} finally {fs.rmSync(scratch, { recursive: true, force: true });