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
docs(skill): answer what fresh generations kept asking
tt-a1i3c4007b38456
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.mdindex 3af34129..49dcc1ff 100644--- a/archify/references/authoring-contract.md+++ b/archify/references/authoring-contract.md@@ -276,7 +276,7 @@ Compare diagnostics by code, subject, and stage instead of total count alone.5. Fix label-to-node, label-to-label, then label-to-route clearance.6. Fix labels that leave the canvas: move the label with `labelAt`/`labelDx`/`labelDy`/`labelSegment`, or widen `meta.viewBox`. Suggested `labelDx`/`labelDy` values replace the authored field; they are not added to it.-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.+After every edit, rerun the complete `finalize` as the delivery contract requires; use `validate` only for focused diagnosis between finalize runs. 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 placementdiff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.mdindex 68ca7838..fcf577ff 100644--- a/archify/references/authoring-defaults.md+++ b/archify/references/authoring-defaults.md@@ -28,7 +28,7 @@ Start with automatic routes and endpoint sides. Pin a side only for a necessaryFor a real repository, follow [Repository authoring](repository-authoring.md) while inspecting source. Freeze its credential-free origin and 40-character commit in `meta.repository`, attach inspected repository-relative `sources` to each key semantic node, and pass `--repo-root` to the first `finalize`. Each reference proves only the fact visible at that location. Follow material relationships and conditions to their actual source; do not reuse a startup citation as protocol or persistence evidence.-Examples show field shape, not legal values or source facts. Read the mode schema and shared definition before adding a field, enum, or constrained text. In particular, inspect Architecture boundary kinds. Keep longer evidence in a card while retaining the fact. See [Schema lookup](authoring-contract.md#schema-lookup) for details.+Examples show field shape, not legal values or source facts. They are finished showcases, so their optional presentation fields (`meta.subtitle`, `meta.viewBox`, `meta.column_fit`, `meta.animation`, `via`, `labelAt`) are not defaults; these defaults win. Read the mode schema and shared definition before adding a field, enum, or constrained text. In particular, inspect Architecture boundary kinds. Keep longer evidence in a card while retaining the fact. See [Schema lookup](authoring-contract.md#schema-lookup) for details.## Presentation and modes@@ -36,6 +36,6 @@ Use one primary authored language from the user's choice or the request/conversaOmit `meta.visual_preset` for classic, `meta.subtitle` for a title-only header, `meta.legend` for truthful auto, and `meta.engineering_profile` for an ordinary system overview. Explicit styles and a subtitle require a user request. Use legend or deployment ownership under the [legend](authoring-contract.md#legend-contract) or [engineering profile](authoring-contract.md#engineering-profile-default) contracts. Branding is optional and explicit when a node names a real product; [Brand marks](brand-marks.md) gives lookup and capture rules for that branch. Never let a badge replace semantic type, label, or relationship facts. Set required `meta.output` to a portable POSIX-relative `.html` path within the working directory; see [Output path contracts](delivery-contract.md#output-path-contracts) for native path exceptions.-For a fresh Workflow use schema v2 and omit `meta.viewBox` so the compiler measures the real footprint; do not add empty canvas just to satisfy a viewport ratio. Preserve supplied fixed geometry and v1 sources. Use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail. For Sequence omit `meta.column_fit` for spread columns on both automatic and authored canvases; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. Describe a participant's internal action in a note on its surrounding real cross-participant message, preserving its meaning and order; Sequence self-message loops are not supported. For a fresh Dataflow start with the stage/row grid and follow the canonical [Dataflow canvas and showcase defaults](authoring-contract.md#dataflow); add dimensions or route controls for supplied geometry or a measured constraint. For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Give an exit shared by several consecutive phases the same label so it draws once, and keep transition labels short; a recoverable failure needs a real transition back. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail.+For a fresh Workflow use schema v2 and omit `meta.viewBox` so the compiler measures the real footprint; do not add empty canvas just to satisfy a viewport ratio. Preserve supplied fixed geometry and v1 sources. Use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail. For a fresh Sequence omit `meta.viewBox` and `meta.column_fit`: the canvas widens for participant labels up to its readable width; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. Describe a participant's internal action in a note on its surrounding real cross-participant message, preserving its meaning and order; Sequence self-message loops are not supported. For a fresh Dataflow start with the stage/row grid and follow the canonical [Dataflow canvas and showcase defaults](authoring-contract.md#dataflow); add dimensions or route controls for supplied geometry or a measured constraint. For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Give an exit shared by several consecutive phases the same label so it draws once, and keep transition labels short; a recoverable failure needs a real transition back. For Class omit `meta.viewBox` and keep the grid to at most four columns of default-width types, or three when members are long: every extra column widens the canvas and shrinks all text toward the readability floor, so add rows instead. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail.`finalize` performs the browser gate. Keep the complete drawing comfortably readable on desktop, with zero horizontal overflow. Use meaningful vertical rows and intrinsic-height page scroll when necessary. The 6px projected-text check is a failure floor; at 1440px, aim for ordinary context text around 7.5px or larger. See [Automated browser evidence](delivery-contract.md#automated-browser-evidence) when viewport evidence fails.diff --git a/archify/references/repository-authoring.md b/archify/references/repository-authoring.mdindex bf3e2162..8ba33f4b 100644--- a/archify/references/repository-authoring.md+++ b/archify/references/repository-authoring.md@@ -1,6 +1,6 @@-# Repository-backed architecture authoring+# Repository-backed authoring-Use this reference when a diagram must explain a real repository. The source is+Use this reference when a diagram of any type must explain a real repository. The source isthe authority for responsibilities, calls, boundaries, and persistence. Thediagram is complete when the requested meaning is covered and every assertedfact has supporting source evidence.@@ -70,6 +70,20 @@ an unresolved question that can change the diagram. Reuse concise facts andtheir source ranges already verified in this task; across revisions, recheckthe affected entry points, configuration, dependencies, and evidence.+## Evidence by diagram type++Only the primary elements carry `sources`, at most three ranges each:+Architecture components, Workflow, Dataflow and Tree nodes, Sequence+participants, Lifecycle states, ERD entities, Class types, Timeline events and+Waterfall spans. Relationships, messages, flows and transitions have none: cite+the call, write or transition site on the element that owns it (the caller, the+writer, the state being left) and keep further evidence in a note or card. A+folder node cites its own README or entry file. A Timeline event cites a file at+the pinned revision that records it, such as a changelog entry; a tag or commit+outside that history is not citable, so say so in a card. A Waterfall without a+recorded trace uses `meta.evidence: "illustrative"` and keeps its durations+labelled as such; do not run the project only to time it.+## Choose an example by structureSelect the main example in the [Type router](../SKILL.md#type-router) before