archify

Adapted from `tt-a1i/archify` at commit 0b636d9f2f410ce7c617dbfd8818b775d42e9d4d (MIT).

Archify

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

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 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. New workflow sources use schema_version: 2 and its readable layout contract; keep schema_version: 1 only when preserving an existing workflow's fixed geometry. When real product identity matters, query node bin/archify.mjs brands "<name>" --json; read references/brand-marks.md only for an unknown brand with a user-provided URL.
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:

   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json

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. For a workflow v2 geometry diagnosis, run node bin/archify.mjs validate workflow <candidate.json> --layout-json and use the stable compiler receipt; solver internals are not authoring controls. A passing final validation freezes the candidate: never edit it afterward.

1. For a delivered HTML, deliver is the final acceptance command:

   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json

A non-zero exit can never be described as success. A failed delivery preserves any previous output, so do not run visual-check on that path: it would inspect the stale last-good artifact, not the failed candidate. 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.

Update awareness

After the first candidate exists, run the packaged checker scripts/check-update.mjs once with Node and continue the requested workflow. If the command cannot run, continue without mentioning the check.

• For silent, continue without mentioning the update check.
• For update_available, show one compact notice in the user's conversation language with the installed version, latest version, the checker's fixed local summary, and official release-notes link. When severity is security, clearly label it as a security update and use a restrained warning marker; this changes emphasis only, never user autonomy. Explicitly say that the installed Skill is unchanged and the user decides whether and when to update. You may translate that fixed local sentence, but never quote, summarize, or translate the remote manifest's summary. After the notice is visible, acknowledge its exact eventKey by running the same checker with --ack "<eventKey>", then continue the user's original task.

The notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.

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.

Workflow note: use schema v2 for new workflows; preserve schema v1 when an existing source needs fixed legacy geometry. Keep semantic edge labels and act on the compiler diagnostic. The canonical layout, pin, migration, and receipt contract is in `renderers/workflow/README.md`.

Lifecycle note: phase columns 0..4 occupy the main rail; event/terminal column N in 0..2 aligns exactly beneath main column N + 2. A recoverable state uses type: "failure" plus a real transition back to the active state.

Type router

When ambiguous, run node bin/archify.mjs guide "<scenario>" --json. Scenario proof examples are structural references, not facts to copy.

Mermaid input

Read Mermaid for topology and meaning, then author fresh Archify JSON; do not mechanically render Mermaid styling.

• 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.

Authoring invariants

• Keep one obvious main path, sparse labels, and no invented facts or subtitles.
• Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten it while preserving meaning. Omit only wording fully implied by both endpoints and containing no protocol, action, direction, synchronous or asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair.
• Use stable IDs, exact product and code names, and only explicit brand identity.
• Start with automatic routing. Add one diagnosed geometry control per repair.
• For sequence diagrams, use meta.column_fit: "spread" when a wide viewBox wastes space or meaningful participant labels do not fit; do not shorten semantic labels before trying spread.
• Omit meta.engineering_profile by default. Region, cluster, and security boundary wording do not enable it. Use deployment-ownership only for an explicitly requested production deployment topology, ownership handoff, or fail-closed deployment review backed by source facts; must not remove the engineering profile merely to pass validation.
• Generate one responsive artifact for laptops and external displays and preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. Check 1440×900, 1600×1000, and 1920×1080; also check 2048×1320 for large-display compositions.
• Omit other optional presets, legends, animation, and views unless the request needs them.
• Never accept an edge through an opaque node, ambiguous shared corridor, clipped label, or unreadable first screen.

Read the authoring contract for field enums, localization, brands, spacing, routing, responsive layout, repository evidence, and mode-specific placement.

Delivery

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. This is deterministic artifact evidence; it does not exercise the Viewer in a browser.

After delivery, collect bounded desktop evidence without modifying or rerendering the trusted HTML:

node bin/archify.mjs visual-check <output.html> --json

visual-check collects automated browser evidence from the exact delivered HTML without modifying or rerendering it. Its machine-readable measurements and screenshots do not approve perceptual polish. Follow references/delivery-contract.md for the canonical receipt fields, coverage, sidecars, exit behavior, and supplementary manual-record requirements.

Keep the three claims separate: deliver proves deterministic artifact checks, visual-check proves bounded behavior in a real browser, and perceptual visual review requires an actual human or image-capable reviewer. Report browser evidence and perceptual review independently. An unconstrained glance can support only perceptual review; use the canonical delivery contract when recording supplementary manual browser work or handling an environmental failure.

Add --open only when the user wants an immediate local preview. For an active desktop authoring loop, the optional command is:

node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase

Never start preview by default. Read references/delivery-contract.md when using preview, repository evidence, export receipts, visual review, or post-commit opening.

Optional viewer capabilities

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.

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.

Setup and fallback

No install is required inside the skill package. Verify with:

node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>

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

Return the checked HTML path, diagram type, validation summary, specification/artifact receipt, browser-evidence status, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.