iTool

Design

Archify

By tt-a1i43,291 stars

Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export.

agent-skillsarchitecture-as-codearchitecture-diagramclaude-skillcode-visualizationcodex
Install Command
npx skills add tt-a1i/archify
Open on GitHub
Supported Clients
Claude CodeCursorVS Code CopilotWindsurf

Skill Details

<p align="center"> <strong>English</strong> · <a href="./README_ZH.md">简体中文</a> </p> <p align="center"> <a href="https://trendshift.io/repositories/31352?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-31352" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/31352" alt="Archify on Trendshift" width="250" height="55"/></a> </p>

Archify product preview

Archify

Turn a codebase or system description into a polished, interactive system map — directly in chat.

Archify is a Node.js rendering and validation system for Cursor, Claude Code, Codex CLI, and OpenCode. Agents produce typed JSON IR; Archify deterministically compiles it into HTML/SVG.

  • Open it and present — five diagram types, four presets, dark/light themes, built-in brand marks, and finite motion
  • Review architecture changes before merge — compare two validated snapshots as Before / Delta / After, with exact added, removed, changed, moved, and rerouted facts
  • Every interaction stays grounded — search nodes, optionally open revision-verified source, trace upstream/downstream authored reach and exact routes, compare roles, and play guided stories without inventing topology
  • One file, ready to trust and share — typed JSON IR and deterministic checks produce self-contained HTML plus PNG, SVG, WebM, and 1200×630 share cards

License Agent Skill Development Version

Current development version: v2.17.0-dev.1. See Changelog.

Project page · Scenario guide · Proof Lab

npx skills add tt-a1i/archify -g

Using Cursor? Open the agent-aware quick start for exact global and project commands.

No repository is required: describe the system in any agent chat.

❤️ Sponsors

<table> <tr><td align="center" width="240"><a href="https://apinebula.ai/ref/wywnaATT"><img src="docs/assets/sponsors/apinebula-archify.jpg" alt="APINEBULA" width="200" /></a><br/><strong><a href="https://apinebula.ai/ref/wywnaATT">APINEBULA</a></strong></td><td>APINEBULA sponsors Archify with one API for Claude, GPT, Gemini, and more. <a href="https://apinebula.ai/ref/wywnaATT">Register through Archify</a> and use <strong><code>Archify</code></strong> for <strong>10% off</strong>.</td></tr> <tr><td align="center" width="240"><a href="https://github.com/EverMind-AI/Raven"><img src="docs/assets/sponsors/evermind-archify-raven.png" alt="Archify × Raven" width="200" /></a><br/><strong><a href="https://github.com/EverMind-AI">EverMind</a> · <a href="https://github.com/EverMind-AI/Raven">Raven</a></strong></td><td>EverMind sponsors Archify and builds memory infrastructure for agents. Its <a href="https://github.com/EverMind-AI/Raven"><strong>Raven</strong></a> harness supports Archify as a Skill for verified, interactive system maps.</td></tr> </table>

Want to sponsor Archify? Contact us by email.

See Archify in action

These are generated Archify artifacts, not product mockups. Click a frame to open its live, shareable state.

<p align="center"> <a href="https://tt-a1i.github.io/archify/gallery.html"><img src="docs/assets/archify-live-proof.gif" alt="Three verified Archify artifacts moving through Signal Flow, Blueprint, and Classic presets" width="960"/></a> <br/> <sub><strong>Three real generated artifacts.</strong> Signal Flow · Blueprint · Classic · <a href="https://tt-a1i.github.io/archify/gallery.html">open the interactive Proof Lab ↗</a></sub> </p>
Guided storyRoute probeSemantic lens
Agent workflow playing one authored chapterCache-miss sequence showing the Web App to Postgres routeProduction architecture comparing backend and database roles
Play one finite named chapter.Inspect the shortest authored directed path.Compare real traffic between semantic roles.

The Proof Lab contains all 11 checked-in scenarios, their JSON sources, named views, and validation receipts.

A real repository, mapped from source

MCO runtime architecture generated from the public mco-org/mco repository

Archify traced mco-org/mco at 9f1a1cf and produced this checked map. Open it ↗ · trace reach ↗ · typed source

Preview

Same diagram, two themes, one click to switch:

DarkLight
Dark themeLight theme

The Export menu copies PNG to the clipboard and downloads static or motion formats:

Export menu

Use Copy Share Card when you want a canonical 1200×630 image for a README, release, or social post.

After tracing a route, Export → Route Share Card downloads that authored path as a 1200×630 PNG with the full diagram retained for context.

Route Share Card showing the exact Users to API Server path with the full architecture retained as context

After tracing authored Upstream or Downstream reach, Export → Reach Share Card captures that exact reading without claiming runtime impact.

MCO downstream Reach Share Card showing authored relationships from Command Router

Open examples/web-app.html locally to try the complete viewer.

Quick start

1. Install

npx skills add tt-a1i/archify -g

For an explicit, non-interactive Cursor install:

npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

To try without installing:

npx skills use tt-a1i/archify@archify --agent codex

DSH community opt-in: dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0

The agent switcher covers cursor, codex, claude-code, and opencode. For Raven's manual ZIP install, extract archify.zip into ~/.raven/workspace/skills; it yields ~/.raven/workspace/skills/archify. Raven is not a switcher target.

Archify may GET the fixed stable manifest solely to show an optional reminder; it never downloads or installs updates. Successful checks wait about 72 hours (±20%); active use retries failures after 6, then 24 hours. The server sees normal HTTP metadata (IP and time), but receives no version, Agent, project data, prompts, account/device ID, or ETag. You decide whether and when to update. Set ARCHIFY_UPDATE_CHECK_DISABLED=1 to disable networking and reminder-state writes.

2. Start from a description — no repository required

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

For source evidence, open a repository and ask:

Analyze this repository, then use archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

3. Refine in chat

Continue with focused requests such as add Redis, move auth to the left, or highlight the rollback path. Archify keeps the typed source available for targeted iteration.

Choose the right diagram

TypeBest forInclude in your prompt
ArchitectureComponents, services, storage, boundariesScope, core components, primary path
WorkflowCI/CD, approvals, tool calls, runbooksParticipants, order, branches, exceptions
SequenceAPI calls, cache fallback, auth, async tracesCallers, callees, returns, timing
Data FlowPipelines, lineage, PII, consumersSources, transforms, stores, boundaries
LifecycleStates, retries, waits, terminal outcomesStates, events, retry and cancellation paths

Architecture's optional deployment-ownership profile fails closed when authored owners, region placement, private database scope, or named crossings are missing; it is never implicit and does not inspect live infrastructure. See the checked deployment proof.

For design or PR review, Architecture Delta compares validated Before / Delta / After snapshots with a machine receipt. Select an authored change or play one finite, viewer-only Review; it infers no impact, risk, or merge safety.

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

Architecture Delta showing added, removed, changed, and moved authored facts

Not sure which one fits? Use the interactive scenario guide, or ask the zero-dependency CLI:

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

Workflow keeps the happy path clear across lanes:

Workflow example

Sequence explains one interaction over time:

Sequence example

Data Flow makes movement and sensitivity boundaries explicit:

Data Flow example

Lifecycle separates progress, waits, retries, and terminal outcomes:

Lifecycle example

Architecture examples: web-app · Archify pipeline · grid placement · desktop agent

Why Archify

  • Layout judgment over generic auto-layout — the agent chooses hierarchy, spacing, routes, and emphasis; shared automatic endpoints spread deterministically instead of piling arrows on one midpoint.
  • Typed JSON IR — every renderer-backed mode has a schema and reproducible source.
  • Atomic validation before delivery — schema, layout, HTML/SVG, route, and label-to-route clearance checks must all pass before a showcase artifact replaces the last known good output.
  • Failures come with a repair receipt — validate --json and deliver --json return stable rule codes, the exact subject, measured evidence, and only supported repair controls instead of a Node stack or an unstructured retry guess.
  • Last-good live preview — an optional desktop loop watches one JSON file, refreshes only after the latest candidate passes every gate, and keeps the previous verified diagram visible when a save is incomplete or invalid.
  • Truthful interaction — focus, upstream/downstream reach, exact routes, role comparison, and stories reuse authored nodes and relationships instead of inventing topology or claiming runtime impact.
  • Source evidence, only when requested — Evidence-backed Architecture nodes mark themselves SRC n and open Git-verified files and line ranges pinned to one public commit; ordinary artifacts stay source-free.
  • Portable by default — the result is one HTML file; exports remain full-diagram and free of temporary viewer state.

Archify is not a general-purpose drawing editor or a Mermaid theme. It turns technical intent into a communication artifact.

How it works

StepWhat happens
GenerateThe agent creates typed JSON IR from your description.
ValidateBundled validators and layout rules check the source; failures identify the exact local repair in machine-readable JSON.
Preview (optional)A loopback-only desktop session watches one source and reloads only verified revisions; failures keep the last-good artifact.
DeliverA same-directory candidate is rendered and checked; only a passing artifact atomically replaces the target, then optional --open launches that exact file.
IterateThe agent updates the source while unrelated structure stays stable.

Useful repository commands:

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs preview workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

preview is an explicit loopback-only desktop mode: it watches one JSON file on a random 127.0.0.1 port, keeps the last verified output through failures, stops with Ctrl-C, and adds no generated-HTML runtime. Use --no-open for tests or manual URL opening.

deliver --open is an opt-in one-shot handoff after commit. Opener failure preserves success; JSON remains on stdout and the absolute fallback path goes to stderr.

On failure, validate --json and deliver --json emit one JSON object. Apply only each diagnostics[] subject's supportedFixes, within the Skill's two correction rounds; visual review remains separate.

Settings:

{
  "meta": {
    "locale": "en",
    "animation": "trace",
    "visual_preset": "signal-flow"
  }
}

meta.locale=en|zh-CN localizes page title, Legend, states/errors, a11y, HTML/SVG lang—never authored content. Otherwise omit; preserve requested-language copy; disclose English fallback. Static omits animation; classic defaults.

Explore and share the output

ActionControl
Open the factual Diagram Guide<kbd>?</kbd>
Find and focus a semantic node<kbd>/</kbd>
Trace upstream/downstream authored reachFocus a node → Upstream / Downstream
Probe a directed route and inspect its journey<kbd>R</kbd> or PATH
Compare one or two semantic roles<kbd>L</kbd> or LENS
Open the live overview radar<kbd>M</kbd> or MAP
Play a guided story / change chapter<kbd>P</kbd> / <kbd>[</kbd> <kbd>]</kbd>
Enter Presentation Stage<kbd>F</kbd>
Choose visual style (S cycles) / toggle theme / open Export<kbd>S</kbd> / <kbd>T</kbd> / <kbd>E</kbd>
Zoom or reset<kbd>+</kbd> / <kbd>-</kbd> / <kbd>0</kbd>

Stable links can restore #focus=<id>, #focus=<id>&reach=upstream|downstream, #relation=<id>, #route=<source>~<target>, #lens=<kind>~<kind>, and #view=<view-id>. Reader-driven motion is finite, respects prefers-reduced-motion, and never enters canonical exports.

The complete generation and viewer contract lives in archify/SKILL.md.

Installation options

SurfaceInstall location or methodCapability
RavenManual ZIP into ~/.raven/workspace/skills → ~/.raven/workspace/skills/archifyFull renderer + validation workflow
Claude Code~/.claude/skills/ or .claude/skills/Full renderer + validation workflow
Codex CLI~/.agents/skills/ or .agents/skills/Full renderer + validation workflow
opencode~/.config/opencode/skills/, .opencode/skills/, or .agents/skills/Full renderer + validation workflow
Claude.aiUpload archify.zip under Settings → Capabilities → SkillsDepends on Node.js access in the sandbox
Project KnowledgeUpload archify.zip to the projectPrompt-driven architecture fallback
DeepSeek HarnessOpt-in: dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0. Invoke: Use the archify skill to map this repository's runtime architecture. Remove: dsh plugin --profile web remove @tt-a1i/archify-dsh.Community integration for developer-preview @deepseek-ai/dsh@0.1.0-rc.6; Node ^22.19.0 || >=24.0.0; not an official DeepSeek product. No telemetry. Shell files need exact workspace paths, not Web Produced Files. Details.

Reference and scope

Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope.

License

MIT — free to use, modify, and distribute.

Contributing

Issues, pull requests, and real-world diagrams are welcome. Start with the contribution guide, use the reproducible bug form for failures, or submit a validated diagram through the community showcase form. · LINUX DO

Star History

<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tt-a1i/archify/star-history/assets/star-history-dark.svg" /><img alt="Star History" src="https://raw.githubusercontent.com/tt-a1i/archify/star-history/assets/star-history-light.svg" /></picture></p>

archify

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, 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: MIT metadata: version: "2.17" author: tt-a1i based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)

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.

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

TypeUse for
architectureComponents, services, cloud/security boundaries, infrastructure
workflowProcesses, approval gates, tool calls, runbooks, CI/CD
sequenceAPI call chains, request lifecycles, async traces, returns
dataflowPipelines, ETL/ELT, lineage, governance, consumers
lifecycleState/status transitions, retries, waiting and terminal states

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

  • One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
  • Omit meta.visual_preset by default so every diagram opens in classic, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set signal-flow, blueprint, or editorial only when the user explicitly requests that visual style.
  • Omit meta.subtitle by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
  • Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit meta.viewBox. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require document.documentElement.scrollWidth <= window.innerWidth and scrollHeight <= window.innerHeight at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with overflow: hidden, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
  • Omit meta.legend for the truthful auto default. When needed, use only mode: auto|all|hidden and renderer-supported entries.<kind>.label|visible; labels never change semantics.
  • Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. meta.locale controls only renderer-owned Viewer UI: use "en" or "zh-CN" for the corresponding supported primary language. For every other language, omit meta.locale and explicitly disclose that the fixed Viewer UI and <html lang> fall back to English. The renderer never translates authored content. See references/authoring-contract.md for details.
  • Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
  • Brand identity is optional and explicit. Put a canonical built-in ID in brand when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run node bin/archify.mjs brands capture "<url>" --json, then author the returned digest-pinned brand object. Render and validate never perform an unpinned capture. Otherwise omit brand. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic type, label, or relationship facts.
  • For sequence diagrams, omit meta.column_fit for the stable fixed layout. Set it to "spread" when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying spread.
  • Component types are frontend, backend, database, cloud, security, messagebus, and external; variants are default, emphasis, security, and dashed.
  • Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
  • Omit meta.engineering_profile by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable deployment-ownership only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
  • Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
  • 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. Architecture separately keeps unobstructed facing automatic ports (left/right or top/bottom) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
  • Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.

Read references/authoring-contract.md only when you need field enums, spacing math, geometry repair rules, repository evidence, or 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.

Related Skills