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: streamline README with interactive demos (#27)
tt-a1i6d5204d23dfa
diff --git a/README.md b/README.mdindex 2d9b2b43..c97cd5a5 100644--- a/README.md+++ b/README.md@@ -6,60 +6,28 @@<a href="https://trendshift.io/repositories/31352?utm_source=repository-badge&utm_medium=badge&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>-<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>+# Archify-**Generate beautiful architecture, technical workflow, sequence, data-flow, and lifecycle diagrams in chat. Switch dark / light. Add motion. Export crisp PNG / JPEG / WebP / SVG / WebM.**--Archify is an agent skill for Claude, Codex CLI, and opencode. It turns a plain-English description of your system or process into a polished, self-contained technical diagram — a single HTML file you can open, toggle themes on, copy to the clipboard, and export at maximum resolution.--- **No design skills needed** — describe your architecture in English, get a diagram-- **Workflow, sequence, data-flow, and lifecycle diagrams too** — technical flows, approvals, tool calls, CI/CD, runbooks, request call chains, data pipelines, PII boundaries, and state machines can be drawn-- **Built-in theme toggle** — one click between dark and light, persists across sessions-- **Three contract-backed visual presets** — keep the stable `classic` default, choose luminous `signal-flow` for demos, or use precise `blueprint` for deployment and design reviews-- **Semantic Sigils at a glance** — every renderer gives each frontend, backend, database, cloud, security, stream, external, and lifecycle node a small theme-aware inline SVG role stamp; no vendor logo pack, network request, or new schema field is required-- **Semantic Flow Tokens on real paths** — exact-edge previews carry a compact call, data, event, security, or lifecycle-state cue along the authored source-to-target geometry; the finite desktop reading aid respects Still/reduced motion and stays out of canonical exports-- **Semantic Story Carrier** — guided Story Beats reuse those same cues on the one exact authored relationship, so the camera move also communicates what is moving; labeled edges are deduplicated by stable identity, and passive embeds/Still/exports stay static-- **Control motion without losing meaning** — trace-enabled artifacts spend one finite ambient pass, settle back to their authored solid/security/async line styles, and expose one 44px `Live` / `Still` switch; Story, Route, Lens, and previews retain deliberate one-shot motion while `Still` pauses playback at a complete static reading-- **Read the right amount at every zoom** — `MAP` keeps the whole system quiet, `READ` reveals responsibilities and relationship labels, and `FULL` adds tags, notes, steps, and classifications; semantic focus reveals the exact detail it needs automatically-- **Discover the artifact without reading docs first** — press <kbd>?</kbd> for Diagram Guide: exact node, relationship, and story counts plus working actions for Find, Route, Radar, Lens, Story, and Presentation-- **Preview intent before committing** — hover or keyboard-focus any node to animate only its direct incoming and outgoing paths; click or press Enter to lock the same one-hop context into Semantic Passport-- **Inspect and play any real route** — press <kbd>R</kbd> or use `PATH`, search valid starts and reachable destinations, then inspect any stop or play one finite Route Journey over the exact shortest authored directed path before copying its endpoint-only `#route=` link-- **Trace and share named relationships directly** — hover or keyboard-focus any authored line to preview its real source, path, and target; click, tap, Enter, or Space pins that exact Lens row, and an optional authored relationship `id` makes it a durable `#relation=` link-- **Understand and share the focused node** — Semantic Passport shows its renderer-owned kind, responsibility, structural scope, authored tag, and stable ID; copy the existing `#focus=<id>` link in one click-- **Find any node fast** — press <kbd>/</kbd> to search labels, responsibilities, scopes, tags, kinds, or stable IDs; selecting a result resets the viewport, reveals it in a contained wide canvas, and opens the same shareable semantic focus-- **Choose, inspect, anticipate, play, and share a path-aware guided story** — a compact Story Shelf keeps Play and every named chapter visible while giving the cold overview back to the diagram, then expands the complete Director after deliberate entry; every Story Trail stop is a native beat control, and Story Horizon distinguishes the one exact next stop from farther future state-- **Follow the story without losing local context** — reader-started playback frames the previous, current, and next authored stops, settles before advancing, and yields immediately to pause, manual navigation, `Still`, or reduced motion-- **Let meaning drive the camera** — node neighborhoods, relationship jumps, Finder results, and guided-story steps smoothly frame themselves with safe padding; manual zoom or pan instantly takes control and pauses playback-- **Keep your bearings on large diagrams** — press <kbd>M</kbd> for Semantic Radar: a live, type-colored overview that shows the current viewport, focuses nodes by stable ID, and supports click, drag, and arrow-key desktop navigation-- **Compare system roles without losing the map** — press <kbd>L</kbd> for a counted Semantic Lens: select one kind to reveal its real traffic or two kinds to count only their direct authored relationships; a restrained direction signal travels only on those exact matched edges, and the stable `#lens=` view is ready to copy-- **Read exact legends as live maps** — architecture, workflow, and lifecycle type rows show compiled node counts; hover or keyboard-focus for a quiet topology preview, then click, tap, Enter, or Space to pin that kind in Semantic Lens; ambiguous edge and mixed-semantics legends stay honestly static-- **Share a chapter that explains itself once** — add `?play=1#view=...` to show its title, exact Story Trail route, live state, and progress on a readable per-beat cadence, then leave it still and readable; reduced-motion readers get the same chapter labeled `Still`-- **Enter Presentation Stage** — press <kbd>F</kbd> to give the live diagram the viewport, keep the story controls, and share the exact stage with `?present=1&play=1#view=...`; Escape unwinds the current view/focus before leaving the stage-- **Dependency-free pan and zoom** — inspect dense diagrams with the built-in view controls while exports remain clean, canonical full-diagram artifacts-- **Copy PNG to clipboard** — one click, paste straight into Slack / Notion / GitHub-- **Ultra-crisp image export** — PNG / JPEG / WebP rendered natively at up to 4× source resolution (no upsampling blur), or SVG for true vector-- **Shareable motion export** — trace-enabled diagrams record a six-second WebM directly in the browser, with no Puppeteer or ffmpeg dependency-- **SVG follows system dark/light** — exported SVGs ship with both variable sets + `@media (prefers-color-scheme)`, so dropping one into a GitHub README makes it follow the reader's color preference (no more two PNGs wrapped in `<picture>`)-- **Validation loop built in** — renderer-backed diagrams go through JSON schema validation and established layout checks; explicitly selecting `standard` or `showcase` also enables Clean Flow and structural border-run gates, while profile-less v1 files remain backward-compatible. `showcase` additionally rejects sub-8px route hooks, sub-16px interior turns, and unrelated X crossings without misclassifying ordinary endpoint stubs-- **Semantic tech labels** — describe components as `aws.lambda`, `postgres`, `redis`, `github-actions`, `openai`, etc.; Archify maps them to the right visual category without needing a full icon library-- **Self-contained HTML** — the generated file has zero dependencies, share by sending it-- **Iterate by chat** — "add Redis", "move auth to the left", "use emerald for the API"+**Turn plain-English system descriptions into polished architecture, workflow, sequence, data-flow, and lifecycle diagrams — directly in chat.**++Archify is an agent skill for Claude, Codex CLI, and opencode. It produces a self-contained HTML diagram that opens in any modern browser, switches between dark and light themes, supports focused exploration, and exports clean static or motion assets.++- **Five diagram types** — architecture, workflow, sequence, data flow, and lifecycle+- **Three visual presets** — stable `classic`, luminous `signal-flow`, and precise `blueprint`+- **Explore real topology** — find nodes, inspect relationships, trace routes, compare roles, and play guided stories+- **Motion is optional** — output stays static unless `meta.animation: "trace"` is explicitly enabled+- **Portable exports** — copy PNG or download PNG, JPEG, WebP, dual-theme SVG, and trace-enabled WebM+- **Typed and checked** — JSON IR, bundled schema validation, layout checks, and opt-in quality profiles+- **Self-contained output** — one shareable HTML file with no viewer runtime dependency+- **Built for agent workflows** — install once, then create and refine diagrams through conversation-**Project page:** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/) · **Scenario guide:** [tt-a1i.github.io/archify/guide.html](https://tt-a1i.github.io/archify/guide.html) · **Generated proof gallery:** [gallery.html](https://tt-a1i.github.io/archify/gallery.html)--The project page puts real generated diagram canvas in the first viewport: one bounded, interactive proof rather than a mockup or rotating carousel.--**Start in 60 seconds:**+**[Project page](https://tt-a1i.github.io/archify/)** · **[Scenario guide](https://tt-a1i.github.io/archify/guide.html)** · **[Proof Lab](https://tt-a1i.github.io/archify/gallery.html)**```bashnpx skills add tt-a1i/archify -g@@ -67,6 +35,23 @@ npx skills add tt-a1i/archify -gThen ask your agent: `Use archify to map this repository's runtime architecture.`+## Interactive demos in 2.11++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 story | Route probe | Semantic lens |+|---|---|---|+| [](https://tt-a1i.github.io/archify/gallery/artifacts/agent-tool-call.workflow.html?theme=dark&present=1&play=1#view=happy-path) | [](https://tt-a1i.github.io/archify/gallery/artifacts/cache-miss.sequence.html?theme=dark&present=1#route=web~db) | [](https://tt-a1i.github.io/archify/gallery/artifacts/production-deployment.architecture.html?theme=dark&present=1#lens=backend~database) |+| Play one finite named chapter. | Inspect the shortest authored directed path. | Compare real traffic between semantic roles. |++The [Proof Lab](https://tt-a1i.github.io/archify/gallery.html) contains all 11 checked-in scenarios, their JSON sources, named views, and validation receipts.+## PreviewSame diagram, two themes, one click to switch:@@ -75,11 +60,11 @@ Same diagram, two themes, one click to switch:|---|---||  |  |-The Export menu — Copy PNG to clipboard plus static and motion downloads (all raster exports at up to 4× source resolution):+The Export menu copies PNG to the clipboard and downloads static or motion formats:-Example file: [`examples/web-app.html`](examples/web-app.html). Download or clone the repository, open the file locally, then press <kbd>?</kbd> for Diagram Guide, <kbd>R</kbd> to probe a route, <kbd>/</kbd> to find a node, <kbd>M</kbd> for Semantic Radar, <kbd>L</kbd> for Semantic Lens, <kbd>F</kbd> for Presentation Stage, <kbd>T</kbd> to toggle themes, or <kbd>E</kbd> to open Export.+Open [`examples/web-app.html`](examples/web-app.html) locally to try the complete viewer.## Quick start@@ -89,23 +74,19 @@ Example file: [`examples/web-app.html`](examples/web-app.html). Download or clonnpx skills add tt-a1i/archify -g```-This installs Archify for supported agents through the open-source [`skills` CLI](https://github.com/vercel-labs/skills).-To try it without a permanent install:```bashnpx skills use tt-a1i/archify@archify --agent codex```-Replace `codex` with `claude-code` or `opencode` when needed.+Replace `codex` with `claude-code` or `opencode` when needed. The packaged [`archify.zip`](archify.zip) also works without `npm install`.-### 2. Ask for one clear view--Start with an overview instead of asking one diagram to explain the entire repository:+### 2. Ask for one bounded view```textAnalyze this repository, then use archify to create a high-level runtime architecture diagram.-Show 8–12 core components, one primary request or data path, external dependencies, and trust boundaries.+Show 8–12 core components, one primary path, external dependencies, and trust boundaries.Put supporting detail in cards instead of adding more edges.```@@ -113,100 +94,69 @@ For a focused flow:```textUse archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->-Redis session lookup -> PostgreSQL fallback. Make the cache-miss path secondary.+Redis session lookup -> PostgreSQL fallback. Keep the cache-miss path secondary.```### 3. Refine in chat-Ask for focused changes such as `add Redis`, `move auth to the left`, or `highlight the rollback path` while the source JSON remains available in the session.--Archify returns a self-contained HTML file that opens in any modern browser and exports to PNG, JPEG, WebP, SVG, or WebM when trace motion is enabled.+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.-## Diagram types--Choose the view that matches the question you need to answer:--Not sure which view fits? Use the [interactive scenario guide](https://tt-a1i.github.io/archify/guide.html), or ask the zero-dependency CLI. It recommends one of 11 bounded recipes and returns the required evidence, usage boundary, presentation settings, and a copy-ready prompt:--```bash-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-```+## Choose the right diagram| Type | Best for | Include in your prompt ||---|---|---|| **Architecture** | Components, services, storage, boundaries | Scope, core components, primary path || **Workflow** | CI/CD, approvals, tool calls, runbooks | Participants, order, branches, exceptions || **Sequence** | API calls, cache fallback, auth, async traces | Callers, callees, returns, timing |-| **Data Flow** | Pipelines, lineage, PII, downstream consumers | Sources, transforms, stores, boundaries |-| **Lifecycle** | State machines, retries, waits, terminal states | States, events, retry and cancellation paths |+| **Data Flow** | Pipelines, lineage, PII, consumers | Sources, transforms, stores, boundaries |+| **Lifecycle** | States, retries, waits, terminal outcomes | States, events, retry and cancellation paths |-Architecture examples:+Not sure which one fits? Use the [interactive scenario guide](https://tt-a1i.github.io/archify/guide.html), or ask the zero-dependency CLI:-- [`examples/web-app.html`](examples/web-app.html) — compact SaaS architecture-- [`examples/archify-repo.html`](examples/archify-repo.html) — Archify's skill → JSON IR → renderer pipeline-- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — explicit `row` / `col` grid placement-- [`examples/maka-architecture.html`](examples/maka-architecture.html) — a third-party desktop agent workbench+```bash+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 uses swimlanes, a clear happy path, and restrained secondary branches.+Workflow keeps the happy path clear across lanes:-Sequence focuses on one interaction over time.+Sequence explains one interaction over time:-Data Flow makes movement, transformation, and sensitivity boundaries explicit.+Data Flow makes movement and sensitivity boundaries explicit:-Lifecycle separates normal progress, wait states, retries, and terminal outcomes.+Lifecycle separates progress, waits, retries, and terminal outcomes:-## Why Archify--- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story being told.-- **Typed JSON IR** — architecture, workflow, sequence, data-flow, and lifecycle diagrams use renderer-backed schemas.-- **Validation before delivery** — schema, layout, HTML, and SVG checks catch malformed or unreadable output early; after an explicit quality profile is selected, Clean Flow names exact node pass-through geometry and the composition receipt rejects structural border-riding, classifies final visible relationship crossings, separates endpoint stubs from cramped turns, and keeps bend/stretch evidence neutral until it is role-aware.-- **Portable output** — one HTML file, no server or framework required, with local font fallbacks when external fonts are unavailable.-- **Semantic technology labels** — names such as `postgres`, `redis`, `aws.lambda`, and `github-actions` guide visual categorization without a heavyweight icon runtime.--Archify is not a general-purpose drawing editor or a Mermaid theme. Its job is to turn technical intent into a polished communication artifact.--## Installation options--The primary installation command is:+Architecture examples: [`web-app`](examples/web-app.html) · [`Archify pipeline`](examples/archify-repo.html) · [`grid placement`](examples/archify-repo-grid.html) · [`desktop agent`](examples/maka-architecture.html)-```bash-npx skills add tt-a1i/archify -g-```--The same [`archify.zip`](archify.zip) can also be installed manually:+## Why Archify-| Surface | Install location or method | Capability |-|---|---|---|-| **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.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |-| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture mode only |+- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story.+- **Typed JSON IR** — every renderer-backed mode has a schema and reproducible source.+- **Validation before delivery** — schema, layout, HTML/SVG, route, and optional showcase checks catch broken output.+- **Truthful interaction** — focus, routes, role comparison, and stories reuse authored nodes and relationships instead of inventing topology.+- **Portable by default** — the result is one HTML file; exports remain full-diagram and free of temporary viewer state.-Manual installation means unzipping the archive into the matching directory. No `npm install` is required for the packaged skill.+Archify is not a general-purpose drawing editor or a Mermaid theme. It turns technical intent into a communication artifact.## How it works-Renderer-backed diagrams follow a small, inspectable loop:-| Step | What happens ||---|---|-| **Generate JSON IR** | The agent creates a typed description instead of hand-editing final SVG markup. |-| **Validate** | Bundled standalone validators check the schema without installing runtime dependencies. |-| **Render** | The selected renderer produces the HTML/SVG artifact. |-| **Check** | Layout and artifact checks catch invalid coordinates, malformed SVG, and unsafe routes. |-| **Iterate** | Targeted changes are applied to the JSON IR while unrelated structure stays stable. |+| **Generate** | The agent creates typed JSON IR from your description. |+| **Validate** | Bundled validators and layout rules check the source. |+| **Render** | The selected renderer produces standalone HTML and SVG. |+| **Check** | Artifact checks reject malformed geometry and unsafe routes. |+| **Iterate** | The agent updates the source while unrelated structure stays stable. |-The packaged CLI exposes the same workflow. From a repository checkout:+Useful repository commands:```bashcd archify@@ -214,129 +164,67 @@ node bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demonode bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.html-node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --jsonnode bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --jsonnode bin/archify.mjs check /tmp/workflow.html-node bin/archify.mjs examples```-Optional trace animation can be enabled for demos:+Optional motion and presentation styling are explicit:```json{"meta": {- "title": "Release Flow","animation": "trace","visual_preset": "signal-flow"}}```-`visual_preset` is optional: `classic` remains the stable default, `signal-flow` adds a luminous layered canvas and tighter motion styling, and `blueprint` adds a high-contrast drafting grid, squared review materials, and precise boundary treatment without changing geometry. Trace-enabled artifacts expose one `Live` / `Still` Motion Governor: ambient motion runs once, settles back to authored relationship styles, and yields to stronger semantic actions; `Still` pauses active Story playback without auto-restarting it, and the reader choice is remembered when browser storage is available. Dynamic `prefers-reduced-motion` and hidden-page changes use the same safe stop path; omit `animation` for a truly static diagram with no motion control.--Optional `meta.views` turns one stable overview into a short guided reading sequence. Each view contains a unique ID, label, an ordered list of existing semantic node IDs, and an optional note; it cannot move or restyle the underlying diagram. On the untouched overview, Story Shelf keeps the compact guided-view identity, Play, and every authored chapter visible while hiding director-only controls that cannot yet act; selecting a chapter, starting playback, or restoring a valid deep link expands the complete Director, while Show all or Escape returns to the shelf. A Named Chapter Rail exposes every authored label and two-digit position. Before selection, candidates truthfully read `=0 +N −0` from the overview; once a chapter is current, it keeps its stop count while every other candidate shows the exact `=stay +enter −leave` focus delta. Fine-pointer hover or keyboard focus applies that same static Chapter Delta Preview without changing the current chapter, camera, Story Trail, or URL; Escape dismisses it in place, while touch still activates on the first tap. Selecting a chapter delegates to the same guided-view state as previous/next and `#view=` links. When two chapters share a real stable-ID node, Shared Anchor Handoff holds that node in place, names the continuity, then settles one interruptible camera move; when none exists, Archify uses an explicit `no-anchor` retarget instead of inventing continuity. Story Beat Navigator renders every resolved ordered stop as a native control and classifies only the exact authored edge(s) between consecutive stops as forward, reverse, grouped, or multiple. Story Follow Camera frames the current authored window, while Story Director Strip names its exact route, edge label, responsibility, and context without inventing a relationship. Desktop Presentation playback keeps Previous, Next, and Pause but temporarily removes secondary story chrome, then restores it on pause. Direct activation pins that beat without changing the chapter, focus set, camera, scroll, or URL; one unambiguous edge may run one finite signal, and Play resumes the same beat's remaining dwell. **Copy moment** freezes playback if necessary and creates a stable `#view=<view-id>&beat=<node-id>` link; opening it restores that exact authored node without motion, while invalid beat IDs fail closed to the chapter. JSON, authored edge styling, SVG geometry, and canonical exports stay unchanged.--Story Horizon completes that reader-controlled sequence with a static `past → active → next → pending` hierarchy. It previews exactly one immediate next node and only the authored connector set already resolved for that step: grouped transitions add no edge, multiple transitions keep every real edge, and the final beat has no horizon. It does not pre-move the camera, add autoplay, or enter canonical export.--## Using the output--Open the generated HTML in a modern browser. The controls in the top-right provide:--- **Theme** — switch between dark and light. Shortcut: <kbd>T</kbd>.-- **Present** — enter a viewport-filling live stage without changing the diagram or export. Shortcut: <kbd>F</kbd>.-- **Export** — copy PNG or download PNG, JPEG, WebP, SVG, or a six-second WebM for trace-enabled diagrams. Shortcut: <kbd>E</kbd>.+Omit `animation` for a truly static diagram. `classic` remains the default visual preset.-Reading Depth starts at `MAP 100%` with primary labels and topology, moves to `READ 125%` for responsibilities and relationship labels, and reaches `FULL 175%` for tags, notes, steps, and classifications. Focus, Semantic Lens, Intent Trace, Route Probe, Story Trail, Direct Relationship Pin, and Relationship Preview reveal the exact local detail they need at any scale; print and export always retain the complete diagram.+## Explore and share the output-Every authored relationship is also a direct entrance. Its invisible 24px non-scaling rail follows the exact visible geometry without widening the artwork. Fine-pointer hover or roving keyboard focus previews the real source, path, and target; click, tap, Enter, or Space opens the source Passport and pins the exact existing Relationship Lens row. Give important `connections`, `edges`, `messages`, `flows`, or `transitions` an optional author-controlled `id`: the pin then writes and copies `#relation=<id>`, restores the same authored relationship after array reordering, and keeps that identity in canonical SVG. Legacy ID-less relationships still pin locally and fall back to copying the source node—numeric runtime keys never enter a public URL. Duplicate authored relationship IDs fail validation. Stronger Focus, Story, Route, Lens, and Chapter states take priority, and runtime-only rails never enter embed, print, or canonical export.--The diagram itself is explorable. Before committing, hover a node—or reach it with keyboard focus—to start Intent Trace: unrelated elements recede while a short direction-aware signal previews only that node's incoming, outgoing, and self-loop paths. Touch readers skip hover and go straight to focus; reduced-motion readers receive the same static one-hop contrast. Press <kbd>R</kbd> or use `PATH` to start Route Probe: choose a source, then one of the highlighted reachable destinations, and Archify traces the deterministic fewest-hop directed route, frames it, names every stop in a compact receipt, and offers a copyable `#route=<source>~<target>` link. It never invents an undirected fallback, and reduced-motion readers receive the same static result. Click a node, or press <kbd>Enter</kbd> / <kbd>Space</kbd>, to lock its immediate neighbors and relationships in place. Semantic Camera frames that one-hop neighborhood without covering Relationship Lens. Semantic Passport immediately names the node's renderer-owned kind, responsibility, structural scope, authored tag, and stable ID; its Copy link action writes the current `#focus=<id>` deep link. The Lens names every incoming, outgoing, and self-loop relationship. On phones, its list stays behind an explicit relationship count so the compact Passport does not cover the selected node. Enter a row with a fine pointer—or reach it with Arrow keys, Home, and End—to dim the other connections and send one short source-to-target pulse over that exact authored path; incoming rows retain their real authored direction, the static edge and endpoints remain emphasized after the pulse ends, and reduced-motion readers receive that same static meaning immediately. Touch stays direct: one tap follows the relationship without a fake hover step. Activate the row to move the camera to the neighboring node. Press <kbd>M</kbd> to open Semantic Radar, a simplified type-colored overview with a live viewport rectangle; click a radar node to focus it, drag the surface or use Arrow keys to recenter, and press Escape to close it. The radar docks only while the diagram is visible, avoids the focused node and Passport when space allows, reports visible width on contained mobile diagrams, and remains outside embed, print, and canonical SVG output. Press <kbd>/</kbd> to open Node Finder and search the same labels, responsibilities, scopes, tags, kinds, or stable IDs; each result reports its context and relationship count, then resets and frames the selected node. Diagrams with guided views also expose Play/Pause, previous, next, and Show all controls. Their Named Chapter Rail reveals every authored label and exact chapter-focus delta up front; Left/Right/Home/End move focus and statically preview `stay / enter / leave` membership without changing the current diagram, activation delegates to the same `activeIndex` and `#view=` contract, and entering the rail pauses playback so the reader owns the next move. Escape removes only that preview and keeps focus in place. Story Beat Navigator turns every resolved Story Trail stop into a native control: click, tap, Enter, or Space pauses and pins the exact beat while the chapter, selected focus, camera, contained scroll, and `#view=` URL stay fixed. The receipt distinguishes a real forward edge, a reverse-authored edge, a grouped transition with no direct relationship, and multiple authored edges; only one unambiguous exact edge may run one finite signal. Keyboard focus alone pauses at the current playhead, and Play continues the remaining dwell from that beat instead of restarting the chapter. During playback, earlier beats settle, the current node and exact adjacent relationship stay strongest, future beats remain visible, and the next chapter waits for Shared Anchor Handoff to finish. Press <kbd>P</kbd> to play the full story or <kbd>[</kbd> / <kbd>]</kbd> to change chapters manually. A share link with `?play=1#view=<view-id>` instead plays only that named chapter once for 3.2 seconds, never auto-advances, and remains static for `prefers-reduced-motion`. In embed mode, a Share Chapter Cue names the view, prints its exact authored route, reports the current `Step NN / NN` plus Playing/Settled/Paused/Still state, and follows the same one-shot progress without entering the SVG or exports. Each chapter fits its authored nodes with bounded zoom and padding; manual zoom, pan, or mobile swiping pauses playback and takes control. Presentation Stage hides supporting cards and fills the viewport while preserving those live controls. Playback also pauses when the page is hidden or the reader starts exploring. <kbd>Escape</kbd> closes the radar or Route Probe first, then removes Chapter Delta Preview, unwinds the active guided view/focus, and finally exits the stage. Use <kbd>+</kbd>, <kbd>-</kbd>, and <kbd>0</kbd> to zoom or reset; drag the canvas while zoomed. Node focus is stored in `#focus=<node-id>`, authored relationship pins in `#relation=<relationship-id>`, probed routes in `#route=<source>~<target>`, and guided stories in `#view=<view-id>`. Export always uses the complete untransformed diagram.--A completed Route Probe also exposes Route Journey. Its native path chips, Previous, Next, Journey/Pause/Replay, and Overview controls preserve the whole shortest route while strengthening one ordered position and its exact incoming relationship. Playback starts only after deliberate activation, runs once, resumes the remaining dwell after pause, and yields to path focus, manual pan/zoom, Guide, page hiding, Motion Still, and reduced motion. Manual position inspection remains available without animation. Escape pauses first, returns to Overview next, and clears the route last. The shared `#route=<source>~<target>` remains endpoint-only and always restores to a still Overview rather than autoplaying.--While Route Probe is choosing an endpoint, <kbd>/</kbd>, the normal Finder control, or `Find start` / `Find target` turns Node Finder into a contextual endpoint picker. Source search omits dead ends; destination search contains only nodes reachable in authored direction and previews the shortest hop count. Escape closes Finder without discarding the in-progress route. Outside Route Probe, Finder keeps its normal semantic-focus behavior.--Press <kbd>?</kbd> or use the question-mark control to open Diagram Guide. It reads the compiled artifact and reports exact semantic node, relationship, and guided-view counts, then runs the existing Finder, Route Probe, Semantic Radar, Semantic Lens, Story Trail, and Presentation interactions from outcome-oriented task rows. Arrow keys, Home, End, direct shortcuts, and Escape all work inside the guide; opening it pauses playback and closes overlapping panels without clearing focus or an in-progress route.--Press <kbd>L</kbd> or use `LENS` to compare compiled semantic kinds without losing the map. Exact node-kind rows in architecture, workflow, and lifecycle legends also show their compiled counts inline: fine-pointer hover or keyboard focus gives a quiet preview of matching nodes, touching authored relationships, and connected peers; click, tap, Enter, or Space pins the kind and opens the same Lens. Sequence and data-flow legends remain static because their rows describe edge variants or mixed node/edge meaning rather than one exact kind. Every Lens kind shows its exact node count. One selection keeps its nodes, touching relationships, and connected peers readable; a second isolates and counts only direct authored relationships between the two roles. Only those exact authored paths receive a short, selection-triggered direction pulse: outgoing/forward, incoming/reverse, and within-kind traffic stay visually distinct without moving nodes or rerouting edges. The one-shot signal inherits the active visual preset, becomes static for reduced-motion readers, stays quiet above 24 matched edges, and is omitted in embed, print, and canonical export. Unrelated topology remains softly visible, closing the panel preserves the selection, and `#lens=<kind>~<kind>` restores it. Escape closes the panel before clearing its active selection.--| Format | Use it for |+| Action | Control ||---|---|-| **Copy PNG** | Slack, Notion, GitHub comments, and quick reviews |-| **PNG / JPEG / WebP** | Slides, documents, websites, and print |-| **SVG** | READMEs, blogs, Figma, Illustrator, and lossless scaling |-| **WebM** | Product demos, release notes, social posts, and animated documentation |--Raster exports are rendered natively at the highest safe resolution, up to 4×. Oversized diagrams step down automatically to stay within browser canvas limits.--Exported SVGs include dark and light variables plus `prefers-color-scheme`, so one SVG can follow the reader's system theme.--Useful URL parameters:--- `?theme=light` or `?theme=dark` — force the starting theme.-- `?present=1` — open directly in Presentation Stage; combine with `?play=1#view=<view-id>` for a shareable live slide.-- `?play=1` — play the current named view once for 3.2 seconds, with a title/route/state/progress cue in embed mode, then stop; with no `#view`, play the first authored view. Never advances to another view and respects reduced motion.-- `?openExport=1` — open the Export menu on load.-- `#focus=<node-id>` — open with a semantic node and its one-hop neighborhood focused.-- `#relation=<relationship-id>` — reopen one exact authored relationship with a stable ID.-- `#route=<source-id>~<target-id>` — restore the shortest authored directed route between two semantic nodes.-- `#view=<view-id>` — open a named guided reading path defined by `meta.views`.-- `#view=<view-id>&beat=<node-id>` — open one exact, static Story Moment; add `?play=1` only when the remaining chapter should play once.--WebP, WebM, and clipboard support depend on browser capabilities. WebM is available only when the diagram uses `animation: "trace"`. The HTML uses local font fallbacks when an external font cannot be loaded.+| Open the factual Diagram Guide | <kbd>?</kbd> |+| Find and focus a semantic node | <kbd>/</kbd> |+| 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> |+| Toggle theme / open Export | <kbd>T</kbd> / <kbd>E</kbd> |+| Zoom or reset | <kbd>+</kbd> / <kbd>-</kbd> / <kbd>0</kbd> |-## Prompt patterns+Stable links can restore `#focus=<id>`, `#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.-**Repository overview**+The complete generation and viewer contract lives in [`archify/SKILL.md`](archify/SKILL.md).-```text-Map this repository's runtime architecture with no more than 12 core components.-Show the main request path, external systems, and trust boundaries. Move implementation detail into cards.-```--**CI/CD workflow**--```text-Draw a CI/CD workflow: pull request -> tests -> approval -> build image -> staging ->-smoke test -> production. Show rollback as a secondary failure path.-```--**Data lineage**--```text-Draw a data-flow diagram from Web and Mobile events through Consent Gate, Kafka,-Warehouse, and Feature Store to Dashboards and ML consumers. Mark the PII boundary.-```--## Reference--Semantic labels guide color and grouping:--| Examples | Category |-|---|---|-| `react`, `nextjs`, `ios`, `browser` | Frontend |-| `node`, `go-service`, `python-worker`, `api-gateway` | Backend |-| `postgres`, `redis`, `s3`, `bigquery`, `snowflake` | Data and storage |-| `aws.lambda`, `gcp.pubsub`, `azure.functions`, `kubernetes` | Cloud and infrastructure |-| `auth0`, `oauth`, `vault`, `security-group` | Security |-| `kafka`, `rabbitmq`, `sqs`, `nats` | Messaging |-| `stripe`, `github-actions`, `openai`, `slack` | External systems |+## Installation options-See the [schema reference](archify/schemas/README.md) for renderer inputs and [CHANGELOG.md](CHANGELOG.md) for release history.+| Surface | Install location or method | Capability |+|---|---|---|+| **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.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |+| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture fallback |-## Current status and roadmap+## Reference and scope-The current viewer includes progressive `MAP` / `READ` / `FULL` Reading Depth across all five renderer-backed modes.+- [Schema reference](archify/schemas/README.md)+- [Skill and renderer contract](archify/SKILL.md)+- [Examples](archify/examples/)+- [Changelog](CHANGELOG.md)+- [Roadmap](ROADMAP.md)+- [Generated Proof Lab](https://tt-a1i.github.io/archify/gallery.html)-Archify 2.11 uses typed JSON IR across all five renderer-backed modes and adds stable semantic hooks, shareable authored relationship IDs, pre-click Intent Trace previews, two-endpoint Route Probe analysis with a finite inspectable Route Journey, Semantic Camera framing, a live Semantic Radar overview, a Named Chapter Rail with Chapter Delta Preview, Shared Anchor Handoff, directly inspectable Story Beat Navigator controls, and Shareable Story Moment links, plus a reader-controlled Live/Still Motion Governor, Semantic Passport context with copyable focus links, a named incoming/outgoing Relationship Lens with exact path preview, searchable Node Finder navigation, one-hop focus, a shareable Presentation Stage, pan/zoom, Signal Flow motion, and browser-native WebM export. The project page now leads with three real, moving, clickable proof artifacts across Signal Flow, Blueprint, and Classic rather than a static product mockup. The [proof gallery](https://tt-a1i.github.io/archify/gallery.html) is regenerated from 11 checked-in scenario examples. Every recipe publishes a matching interactive artifact with three named reader views, its exact JSON source, seven validation checks, and a source digest instead of relying on hand-authored capability claims.+Archify 2.11 includes typed IR across all five modes, three visual presets, optional finite motion, guided views, semantic exploration, shareable deep links, browser-native WebM recording, and explicit `standard` / `showcase` quality profiles.-See [ROADMAP.md](ROADMAP.md) for planned work and design boundaries. Automatic Mermaid parsing, generic auto-layout, a hosted sharing service, and a WYSIWYG editor are not current goals.+Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope.## Attribution-Archify is a fork and rewrite of [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 by Cocoon AI.--The original visual language remains credited to that project. Archify 2.x adds themes, export tooling, typed renderers, validation, accessibility, and the unified CLI. Both projects use the MIT license.+Archify is a fork and rewrite of [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0. The original visual language remains credited to Cocoon AI; Archify 2.x adds themes, exports, typed renderers, validation, accessibility, interaction, and a unified CLI. Both projects use the MIT License.## License@@ -344,4 +232,4 @@ The original visual language remains credited to that project. Archify 2.x adds## Contributing-Issues, pull requests, and shared diagrams are welcome. When reporting generated-output problems, include the prompt, diagram type, and Archify version when possible. Run `node scripts/build-gallery.mjs` after changing bundled examples or the standalone viewer so the generated showcase stays current.+Issues, pull requests, and shared diagrams are welcome. For generated-output problems, include the prompt, diagram type, and Archify version. Run `node scripts/build-gallery.mjs` after changing bundled examples or the standalone viewer.diff --git a/README_EN.md b/README_EN.mdindex 2d9b2b43..c97cd5a5 100644--- a/README_EN.md+++ b/README_EN.md@@ -6,60 +6,28 @@<a href="https://trendshift.io/repositories/31352?utm_source=repository-badge&utm_medium=badge&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>-<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>+# Archify-**Generate beautiful architecture, technical workflow, sequence, data-flow, and lifecycle diagrams in chat. Switch dark / light. Add motion. Export crisp PNG / JPEG / WebP / SVG / WebM.**--Archify is an agent skill for Claude, Codex CLI, and opencode. It turns a plain-English description of your system or process into a polished, self-contained technical diagram — a single HTML file you can open, toggle themes on, copy to the clipboard, and export at maximum resolution.--- **No design skills needed** — describe your architecture in English, get a diagram-- **Workflow, sequence, data-flow, and lifecycle diagrams too** — technical flows, approvals, tool calls, CI/CD, runbooks, request call chains, data pipelines, PII boundaries, and state machines can be drawn-- **Built-in theme toggle** — one click between dark and light, persists across sessions-- **Three contract-backed visual presets** — keep the stable `classic` default, choose luminous `signal-flow` for demos, or use precise `blueprint` for deployment and design reviews-- **Semantic Sigils at a glance** — every renderer gives each frontend, backend, database, cloud, security, stream, external, and lifecycle node a small theme-aware inline SVG role stamp; no vendor logo pack, network request, or new schema field is required-- **Semantic Flow Tokens on real paths** — exact-edge previews carry a compact call, data, event, security, or lifecycle-state cue along the authored source-to-target geometry; the finite desktop reading aid respects Still/reduced motion and stays out of canonical exports-- **Semantic Story Carrier** — guided Story Beats reuse those same cues on the one exact authored relationship, so the camera move also communicates what is moving; labeled edges are deduplicated by stable identity, and passive embeds/Still/exports stay static-- **Control motion without losing meaning** — trace-enabled artifacts spend one finite ambient pass, settle back to their authored solid/security/async line styles, and expose one 44px `Live` / `Still` switch; Story, Route, Lens, and previews retain deliberate one-shot motion while `Still` pauses playback at a complete static reading-- **Read the right amount at every zoom** — `MAP` keeps the whole system quiet, `READ` reveals responsibilities and relationship labels, and `FULL` adds tags, notes, steps, and classifications; semantic focus reveals the exact detail it needs automatically-- **Discover the artifact without reading docs first** — press <kbd>?</kbd> for Diagram Guide: exact node, relationship, and story counts plus working actions for Find, Route, Radar, Lens, Story, and Presentation-- **Preview intent before committing** — hover or keyboard-focus any node to animate only its direct incoming and outgoing paths; click or press Enter to lock the same one-hop context into Semantic Passport-- **Inspect and play any real route** — press <kbd>R</kbd> or use `PATH`, search valid starts and reachable destinations, then inspect any stop or play one finite Route Journey over the exact shortest authored directed path before copying its endpoint-only `#route=` link-- **Trace and share named relationships directly** — hover or keyboard-focus any authored line to preview its real source, path, and target; click, tap, Enter, or Space pins that exact Lens row, and an optional authored relationship `id` makes it a durable `#relation=` link-- **Understand and share the focused node** — Semantic Passport shows its renderer-owned kind, responsibility, structural scope, authored tag, and stable ID; copy the existing `#focus=<id>` link in one click-- **Find any node fast** — press <kbd>/</kbd> to search labels, responsibilities, scopes, tags, kinds, or stable IDs; selecting a result resets the viewport, reveals it in a contained wide canvas, and opens the same shareable semantic focus-- **Choose, inspect, anticipate, play, and share a path-aware guided story** — a compact Story Shelf keeps Play and every named chapter visible while giving the cold overview back to the diagram, then expands the complete Director after deliberate entry; every Story Trail stop is a native beat control, and Story Horizon distinguishes the one exact next stop from farther future state-- **Follow the story without losing local context** — reader-started playback frames the previous, current, and next authored stops, settles before advancing, and yields immediately to pause, manual navigation, `Still`, or reduced motion-- **Let meaning drive the camera** — node neighborhoods, relationship jumps, Finder results, and guided-story steps smoothly frame themselves with safe padding; manual zoom or pan instantly takes control and pauses playback-- **Keep your bearings on large diagrams** — press <kbd>M</kbd> for Semantic Radar: a live, type-colored overview that shows the current viewport, focuses nodes by stable ID, and supports click, drag, and arrow-key desktop navigation-- **Compare system roles without losing the map** — press <kbd>L</kbd> for a counted Semantic Lens: select one kind to reveal its real traffic or two kinds to count only their direct authored relationships; a restrained direction signal travels only on those exact matched edges, and the stable `#lens=` view is ready to copy-- **Read exact legends as live maps** — architecture, workflow, and lifecycle type rows show compiled node counts; hover or keyboard-focus for a quiet topology preview, then click, tap, Enter, or Space to pin that kind in Semantic Lens; ambiguous edge and mixed-semantics legends stay honestly static-- **Share a chapter that explains itself once** — add `?play=1#view=...` to show its title, exact Story Trail route, live state, and progress on a readable per-beat cadence, then leave it still and readable; reduced-motion readers get the same chapter labeled `Still`-- **Enter Presentation Stage** — press <kbd>F</kbd> to give the live diagram the viewport, keep the story controls, and share the exact stage with `?present=1&play=1#view=...`; Escape unwinds the current view/focus before leaving the stage-- **Dependency-free pan and zoom** — inspect dense diagrams with the built-in view controls while exports remain clean, canonical full-diagram artifacts-- **Copy PNG to clipboard** — one click, paste straight into Slack / Notion / GitHub-- **Ultra-crisp image export** — PNG / JPEG / WebP rendered natively at up to 4× source resolution (no upsampling blur), or SVG for true vector-- **Shareable motion export** — trace-enabled diagrams record a six-second WebM directly in the browser, with no Puppeteer or ffmpeg dependency-- **SVG follows system dark/light** — exported SVGs ship with both variable sets + `@media (prefers-color-scheme)`, so dropping one into a GitHub README makes it follow the reader's color preference (no more two PNGs wrapped in `<picture>`)-- **Validation loop built in** — renderer-backed diagrams go through JSON schema validation and established layout checks; explicitly selecting `standard` or `showcase` also enables Clean Flow and structural border-run gates, while profile-less v1 files remain backward-compatible. `showcase` additionally rejects sub-8px route hooks, sub-16px interior turns, and unrelated X crossings without misclassifying ordinary endpoint stubs-- **Semantic tech labels** — describe components as `aws.lambda`, `postgres`, `redis`, `github-actions`, `openai`, etc.; Archify maps them to the right visual category without needing a full icon library-- **Self-contained HTML** — the generated file has zero dependencies, share by sending it-- **Iterate by chat** — "add Redis", "move auth to the left", "use emerald for the API"+**Turn plain-English system descriptions into polished architecture, workflow, sequence, data-flow, and lifecycle diagrams — directly in chat.**++Archify is an agent skill for Claude, Codex CLI, and opencode. It produces a self-contained HTML diagram that opens in any modern browser, switches between dark and light themes, supports focused exploration, and exports clean static or motion assets.++- **Five diagram types** — architecture, workflow, sequence, data flow, and lifecycle+- **Three visual presets** — stable `classic`, luminous `signal-flow`, and precise `blueprint`+- **Explore real topology** — find nodes, inspect relationships, trace routes, compare roles, and play guided stories+- **Motion is optional** — output stays static unless `meta.animation: "trace"` is explicitly enabled+- **Portable exports** — copy PNG or download PNG, JPEG, WebP, dual-theme SVG, and trace-enabled WebM+- **Typed and checked** — JSON IR, bundled schema validation, layout checks, and opt-in quality profiles+- **Self-contained output** — one shareable HTML file with no viewer runtime dependency+- **Built for agent workflows** — install once, then create and refine diagrams through conversation-**Project page:** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/) · **Scenario guide:** [tt-a1i.github.io/archify/guide.html](https://tt-a1i.github.io/archify/guide.html) · **Generated proof gallery:** [gallery.html](https://tt-a1i.github.io/archify/gallery.html)--The project page puts real generated diagram canvas in the first viewport: one bounded, interactive proof rather than a mockup or rotating carousel.--**Start in 60 seconds:**+**[Project page](https://tt-a1i.github.io/archify/)** · **[Scenario guide](https://tt-a1i.github.io/archify/guide.html)** · **[Proof Lab](https://tt-a1i.github.io/archify/gallery.html)**```bashnpx skills add tt-a1i/archify -g@@ -67,6 +35,23 @@ npx skills add tt-a1i/archify -gThen ask your agent: `Use archify to map this repository's runtime architecture.`+## Interactive demos in 2.11++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 story | Route probe | Semantic lens |+|---|---|---|+| [](https://tt-a1i.github.io/archify/gallery/artifacts/agent-tool-call.workflow.html?theme=dark&present=1&play=1#view=happy-path) | [](https://tt-a1i.github.io/archify/gallery/artifacts/cache-miss.sequence.html?theme=dark&present=1#route=web~db) | [](https://tt-a1i.github.io/archify/gallery/artifacts/production-deployment.architecture.html?theme=dark&present=1#lens=backend~database) |+| Play one finite named chapter. | Inspect the shortest authored directed path. | Compare real traffic between semantic roles. |++The [Proof Lab](https://tt-a1i.github.io/archify/gallery.html) contains all 11 checked-in scenarios, their JSON sources, named views, and validation receipts.+## PreviewSame diagram, two themes, one click to switch:@@ -75,11 +60,11 @@ Same diagram, two themes, one click to switch:|---|---||  |  |-The Export menu — Copy PNG to clipboard plus static and motion downloads (all raster exports at up to 4× source resolution):+The Export menu copies PNG to the clipboard and downloads static or motion formats:-Example file: [`examples/web-app.html`](examples/web-app.html). Download or clone the repository, open the file locally, then press <kbd>?</kbd> for Diagram Guide, <kbd>R</kbd> to probe a route, <kbd>/</kbd> to find a node, <kbd>M</kbd> for Semantic Radar, <kbd>L</kbd> for Semantic Lens, <kbd>F</kbd> for Presentation Stage, <kbd>T</kbd> to toggle themes, or <kbd>E</kbd> to open Export.+Open [`examples/web-app.html`](examples/web-app.html) locally to try the complete viewer.## Quick start@@ -89,23 +74,19 @@ Example file: [`examples/web-app.html`](examples/web-app.html). Download or clonnpx skills add tt-a1i/archify -g```-This installs Archify for supported agents through the open-source [`skills` CLI](https://github.com/vercel-labs/skills).-To try it without a permanent install:```bashnpx skills use tt-a1i/archify@archify --agent codex```-Replace `codex` with `claude-code` or `opencode` when needed.+Replace `codex` with `claude-code` or `opencode` when needed. The packaged [`archify.zip`](archify.zip) also works without `npm install`.-### 2. Ask for one clear view--Start with an overview instead of asking one diagram to explain the entire repository:+### 2. Ask for one bounded view```textAnalyze this repository, then use archify to create a high-level runtime architecture diagram.-Show 8–12 core components, one primary request or data path, external dependencies, and trust boundaries.+Show 8–12 core components, one primary path, external dependencies, and trust boundaries.Put supporting detail in cards instead of adding more edges.```@@ -113,100 +94,69 @@ For a focused flow:```textUse archify to draw this login flow: Browser -> Web App -> API -> JWT validation ->-Redis session lookup -> PostgreSQL fallback. Make the cache-miss path secondary.+Redis session lookup -> PostgreSQL fallback. Keep the cache-miss path secondary.```### 3. Refine in chat-Ask for focused changes such as `add Redis`, `move auth to the left`, or `highlight the rollback path` while the source JSON remains available in the session.--Archify returns a self-contained HTML file that opens in any modern browser and exports to PNG, JPEG, WebP, SVG, or WebM when trace motion is enabled.+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.-## Diagram types--Choose the view that matches the question you need to answer:--Not sure which view fits? Use the [interactive scenario guide](https://tt-a1i.github.io/archify/guide.html), or ask the zero-dependency CLI. It recommends one of 11 bounded recipes and returns the required evidence, usage boundary, presentation settings, and a copy-ready prompt:--```bash-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-```+## Choose the right diagram| Type | Best for | Include in your prompt ||---|---|---|| **Architecture** | Components, services, storage, boundaries | Scope, core components, primary path || **Workflow** | CI/CD, approvals, tool calls, runbooks | Participants, order, branches, exceptions || **Sequence** | API calls, cache fallback, auth, async traces | Callers, callees, returns, timing |-| **Data Flow** | Pipelines, lineage, PII, downstream consumers | Sources, transforms, stores, boundaries |-| **Lifecycle** | State machines, retries, waits, terminal states | States, events, retry and cancellation paths |+| **Data Flow** | Pipelines, lineage, PII, consumers | Sources, transforms, stores, boundaries |+| **Lifecycle** | States, retries, waits, terminal outcomes | States, events, retry and cancellation paths |-Architecture examples:+Not sure which one fits? Use the [interactive scenario guide](https://tt-a1i.github.io/archify/guide.html), or ask the zero-dependency CLI:-- [`examples/web-app.html`](examples/web-app.html) — compact SaaS architecture-- [`examples/archify-repo.html`](examples/archify-repo.html) — Archify's skill → JSON IR → renderer pipeline-- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — explicit `row` / `col` grid placement-- [`examples/maka-architecture.html`](examples/maka-architecture.html) — a third-party desktop agent workbench+```bash+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 uses swimlanes, a clear happy path, and restrained secondary branches.+Workflow keeps the happy path clear across lanes:-Sequence focuses on one interaction over time.+Sequence explains one interaction over time:-Data Flow makes movement, transformation, and sensitivity boundaries explicit.+Data Flow makes movement and sensitivity boundaries explicit:-Lifecycle separates normal progress, wait states, retries, and terminal outcomes.+Lifecycle separates progress, waits, retries, and terminal outcomes:-## Why Archify--- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story being told.-- **Typed JSON IR** — architecture, workflow, sequence, data-flow, and lifecycle diagrams use renderer-backed schemas.-- **Validation before delivery** — schema, layout, HTML, and SVG checks catch malformed or unreadable output early; after an explicit quality profile is selected, Clean Flow names exact node pass-through geometry and the composition receipt rejects structural border-riding, classifies final visible relationship crossings, separates endpoint stubs from cramped turns, and keeps bend/stretch evidence neutral until it is role-aware.-- **Portable output** — one HTML file, no server or framework required, with local font fallbacks when external fonts are unavailable.-- **Semantic technology labels** — names such as `postgres`, `redis`, `aws.lambda`, and `github-actions` guide visual categorization without a heavyweight icon runtime.--Archify is not a general-purpose drawing editor or a Mermaid theme. Its job is to turn technical intent into a polished communication artifact.--## Installation options--The primary installation command is:+Architecture examples: [`web-app`](examples/web-app.html) · [`Archify pipeline`](examples/archify-repo.html) · [`grid placement`](examples/archify-repo-grid.html) · [`desktop agent`](examples/maka-architecture.html)-```bash-npx skills add tt-a1i/archify -g-```--The same [`archify.zip`](archify.zip) can also be installed manually:+## Why Archify-| Surface | Install location or method | Capability |-|---|---|---|-| **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.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |-| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture mode only |+- **Layout judgment over generic auto-layout** — the agent chooses hierarchy, spacing, routes, and emphasis for the story.+- **Typed JSON IR** — every renderer-backed mode has a schema and reproducible source.+- **Validation before delivery** — schema, layout, HTML/SVG, route, and optional showcase checks catch broken output.+- **Truthful interaction** — focus, routes, role comparison, and stories reuse authored nodes and relationships instead of inventing topology.+- **Portable by default** — the result is one HTML file; exports remain full-diagram and free of temporary viewer state.-Manual installation means unzipping the archive into the matching directory. No `npm install` is required for the packaged skill.+Archify is not a general-purpose drawing editor or a Mermaid theme. It turns technical intent into a communication artifact.## How it works-Renderer-backed diagrams follow a small, inspectable loop:-| Step | What happens ||---|---|-| **Generate JSON IR** | The agent creates a typed description instead of hand-editing final SVG markup. |-| **Validate** | Bundled standalone validators check the schema without installing runtime dependencies. |-| **Render** | The selected renderer produces the HTML/SVG artifact. |-| **Check** | Layout and artifact checks catch invalid coordinates, malformed SVG, and unsafe routes. |-| **Iterate** | Targeted changes are applied to the JSON IR while unrelated structure stays stable. |+| **Generate** | The agent creates typed JSON IR from your description. |+| **Validate** | Bundled validators and layout rules check the source. |+| **Render** | The selected renderer produces standalone HTML and SVG. |+| **Check** | Artifact checks reject malformed geometry and unsafe routes. |+| **Iterate** | The agent updates the source while unrelated structure stays stable. |-The packaged CLI exposes the same workflow. From a repository checkout:+Useful repository commands:```bashcd archify@@ -214,129 +164,67 @@ node bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demonode bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.html-node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --jsonnode bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --jsonnode bin/archify.mjs check /tmp/workflow.html-node bin/archify.mjs examples```-Optional trace animation can be enabled for demos:+Optional motion and presentation styling are explicit:```json{"meta": {- "title": "Release Flow","animation": "trace","visual_preset": "signal-flow"}}```-`visual_preset` is optional: `classic` remains the stable default, `signal-flow` adds a luminous layered canvas and tighter motion styling, and `blueprint` adds a high-contrast drafting grid, squared review materials, and precise boundary treatment without changing geometry. Trace-enabled artifacts expose one `Live` / `Still` Motion Governor: ambient motion runs once, settles back to authored relationship styles, and yields to stronger semantic actions; `Still` pauses active Story playback without auto-restarting it, and the reader choice is remembered when browser storage is available. Dynamic `prefers-reduced-motion` and hidden-page changes use the same safe stop path; omit `animation` for a truly static diagram with no motion control.--Optional `meta.views` turns one stable overview into a short guided reading sequence. Each view contains a unique ID, label, an ordered list of existing semantic node IDs, and an optional note; it cannot move or restyle the underlying diagram. On the untouched overview, Story Shelf keeps the compact guided-view identity, Play, and every authored chapter visible while hiding director-only controls that cannot yet act; selecting a chapter, starting playback, or restoring a valid deep link expands the complete Director, while Show all or Escape returns to the shelf. A Named Chapter Rail exposes every authored label and two-digit position. Before selection, candidates truthfully read `=0 +N −0` from the overview; once a chapter is current, it keeps its stop count while every other candidate shows the exact `=stay +enter −leave` focus delta. Fine-pointer hover or keyboard focus applies that same static Chapter Delta Preview without changing the current chapter, camera, Story Trail, or URL; Escape dismisses it in place, while touch still activates on the first tap. Selecting a chapter delegates to the same guided-view state as previous/next and `#view=` links. When two chapters share a real stable-ID node, Shared Anchor Handoff holds that node in place, names the continuity, then settles one interruptible camera move; when none exists, Archify uses an explicit `no-anchor` retarget instead of inventing continuity. Story Beat Navigator renders every resolved ordered stop as a native control and classifies only the exact authored edge(s) between consecutive stops as forward, reverse, grouped, or multiple. Story Follow Camera frames the current authored window, while Story Director Strip names its exact route, edge label, responsibility, and context without inventing a relationship. Desktop Presentation playback keeps Previous, Next, and Pause but temporarily removes secondary story chrome, then restores it on pause. Direct activation pins that beat without changing the chapter, focus set, camera, scroll, or URL; one unambiguous edge may run one finite signal, and Play resumes the same beat's remaining dwell. **Copy moment** freezes playback if necessary and creates a stable `#view=<view-id>&beat=<node-id>` link; opening it restores that exact authored node without motion, while invalid beat IDs fail closed to the chapter. JSON, authored edge styling, SVG geometry, and canonical exports stay unchanged.--Story Horizon completes that reader-controlled sequence with a static `past → active → next → pending` hierarchy. It previews exactly one immediate next node and only the authored connector set already resolved for that step: grouped transitions add no edge, multiple transitions keep every real edge, and the final beat has no horizon. It does not pre-move the camera, add autoplay, or enter canonical export.--## Using the output--Open the generated HTML in a modern browser. The controls in the top-right provide:--- **Theme** — switch between dark and light. Shortcut: <kbd>T</kbd>.-- **Present** — enter a viewport-filling live stage without changing the diagram or export. Shortcut: <kbd>F</kbd>.-- **Export** — copy PNG or download PNG, JPEG, WebP, SVG, or a six-second WebM for trace-enabled diagrams. Shortcut: <kbd>E</kbd>.+Omit `animation` for a truly static diagram. `classic` remains the default visual preset.-Reading Depth starts at `MAP 100%` with primary labels and topology, moves to `READ 125%` for responsibilities and relationship labels, and reaches `FULL 175%` for tags, notes, steps, and classifications. Focus, Semantic Lens, Intent Trace, Route Probe, Story Trail, Direct Relationship Pin, and Relationship Preview reveal the exact local detail they need at any scale; print and export always retain the complete diagram.+## Explore and share the output-Every authored relationship is also a direct entrance. Its invisible 24px non-scaling rail follows the exact visible geometry without widening the artwork. Fine-pointer hover or roving keyboard focus previews the real source, path, and target; click, tap, Enter, or Space opens the source Passport and pins the exact existing Relationship Lens row. Give important `connections`, `edges`, `messages`, `flows`, or `transitions` an optional author-controlled `id`: the pin then writes and copies `#relation=<id>`, restores the same authored relationship after array reordering, and keeps that identity in canonical SVG. Legacy ID-less relationships still pin locally and fall back to copying the source node—numeric runtime keys never enter a public URL. Duplicate authored relationship IDs fail validation. Stronger Focus, Story, Route, Lens, and Chapter states take priority, and runtime-only rails never enter embed, print, or canonical export.--The diagram itself is explorable. Before committing, hover a node—or reach it with keyboard focus—to start Intent Trace: unrelated elements recede while a short direction-aware signal previews only that node's incoming, outgoing, and self-loop paths. Touch readers skip hover and go straight to focus; reduced-motion readers receive the same static one-hop contrast. Press <kbd>R</kbd> or use `PATH` to start Route Probe: choose a source, then one of the highlighted reachable destinations, and Archify traces the deterministic fewest-hop directed route, frames it, names every stop in a compact receipt, and offers a copyable `#route=<source>~<target>` link. It never invents an undirected fallback, and reduced-motion readers receive the same static result. Click a node, or press <kbd>Enter</kbd> / <kbd>Space</kbd>, to lock its immediate neighbors and relationships in place. Semantic Camera frames that one-hop neighborhood without covering Relationship Lens. Semantic Passport immediately names the node's renderer-owned kind, responsibility, structural scope, authored tag, and stable ID; its Copy link action writes the current `#focus=<id>` deep link. The Lens names every incoming, outgoing, and self-loop relationship. On phones, its list stays behind an explicit relationship count so the compact Passport does not cover the selected node. Enter a row with a fine pointer—or reach it with Arrow keys, Home, and End—to dim the other connections and send one short source-to-target pulse over that exact authored path; incoming rows retain their real authored direction, the static edge and endpoints remain emphasized after the pulse ends, and reduced-motion readers receive that same static meaning immediately. Touch stays direct: one tap follows the relationship without a fake hover step. Activate the row to move the camera to the neighboring node. Press <kbd>M</kbd> to open Semantic Radar, a simplified type-colored overview with a live viewport rectangle; click a radar node to focus it, drag the surface or use Arrow keys to recenter, and press Escape to close it. The radar docks only while the diagram is visible, avoids the focused node and Passport when space allows, reports visible width on contained mobile diagrams, and remains outside embed, print, and canonical SVG output. Press <kbd>/</kbd> to open Node Finder and search the same labels, responsibilities, scopes, tags, kinds, or stable IDs; each result reports its context and relationship count, then resets and frames the selected node. Diagrams with guided views also expose Play/Pause, previous, next, and Show all controls. Their Named Chapter Rail reveals every authored label and exact chapter-focus delta up front; Left/Right/Home/End move focus and statically preview `stay / enter / leave` membership without changing the current diagram, activation delegates to the same `activeIndex` and `#view=` contract, and entering the rail pauses playback so the reader owns the next move. Escape removes only that preview and keeps focus in place. Story Beat Navigator turns every resolved Story Trail stop into a native control: click, tap, Enter, or Space pauses and pins the exact beat while the chapter, selected focus, camera, contained scroll, and `#view=` URL stay fixed. The receipt distinguishes a real forward edge, a reverse-authored edge, a grouped transition with no direct relationship, and multiple authored edges; only one unambiguous exact edge may run one finite signal. Keyboard focus alone pauses at the current playhead, and Play continues the remaining dwell from that beat instead of restarting the chapter. During playback, earlier beats settle, the current node and exact adjacent relationship stay strongest, future beats remain visible, and the next chapter waits for Shared Anchor Handoff to finish. Press <kbd>P</kbd> to play the full story or <kbd>[</kbd> / <kbd>]</kbd> to change chapters manually. A share link with `?play=1#view=<view-id>` instead plays only that named chapter once for 3.2 seconds, never auto-advances, and remains static for `prefers-reduced-motion`. In embed mode, a Share Chapter Cue names the view, prints its exact authored route, reports the current `Step NN / NN` plus Playing/Settled/Paused/Still state, and follows the same one-shot progress without entering the SVG or exports. Each chapter fits its authored nodes with bounded zoom and padding; manual zoom, pan, or mobile swiping pauses playback and takes control. Presentation Stage hides supporting cards and fills the viewport while preserving those live controls. Playback also pauses when the page is hidden or the reader starts exploring. <kbd>Escape</kbd> closes the radar or Route Probe first, then removes Chapter Delta Preview, unwinds the active guided view/focus, and finally exits the stage. Use <kbd>+</kbd>, <kbd>-</kbd>, and <kbd>0</kbd> to zoom or reset; drag the canvas while zoomed. Node focus is stored in `#focus=<node-id>`, authored relationship pins in `#relation=<relationship-id>`, probed routes in `#route=<source>~<target>`, and guided stories in `#view=<view-id>`. Export always uses the complete untransformed diagram.--A completed Route Probe also exposes Route Journey. Its native path chips, Previous, Next, Journey/Pause/Replay, and Overview controls preserve the whole shortest route while strengthening one ordered position and its exact incoming relationship. Playback starts only after deliberate activation, runs once, resumes the remaining dwell after pause, and yields to path focus, manual pan/zoom, Guide, page hiding, Motion Still, and reduced motion. Manual position inspection remains available without animation. Escape pauses first, returns to Overview next, and clears the route last. The shared `#route=<source>~<target>` remains endpoint-only and always restores to a still Overview rather than autoplaying.--While Route Probe is choosing an endpoint, <kbd>/</kbd>, the normal Finder control, or `Find start` / `Find target` turns Node Finder into a contextual endpoint picker. Source search omits dead ends; destination search contains only nodes reachable in authored direction and previews the shortest hop count. Escape closes Finder without discarding the in-progress route. Outside Route Probe, Finder keeps its normal semantic-focus behavior.--Press <kbd>?</kbd> or use the question-mark control to open Diagram Guide. It reads the compiled artifact and reports exact semantic node, relationship, and guided-view counts, then runs the existing Finder, Route Probe, Semantic Radar, Semantic Lens, Story Trail, and Presentation interactions from outcome-oriented task rows. Arrow keys, Home, End, direct shortcuts, and Escape all work inside the guide; opening it pauses playback and closes overlapping panels without clearing focus or an in-progress route.--Press <kbd>L</kbd> or use `LENS` to compare compiled semantic kinds without losing the map. Exact node-kind rows in architecture, workflow, and lifecycle legends also show their compiled counts inline: fine-pointer hover or keyboard focus gives a quiet preview of matching nodes, touching authored relationships, and connected peers; click, tap, Enter, or Space pins the kind and opens the same Lens. Sequence and data-flow legends remain static because their rows describe edge variants or mixed node/edge meaning rather than one exact kind. Every Lens kind shows its exact node count. One selection keeps its nodes, touching relationships, and connected peers readable; a second isolates and counts only direct authored relationships between the two roles. Only those exact authored paths receive a short, selection-triggered direction pulse: outgoing/forward, incoming/reverse, and within-kind traffic stay visually distinct without moving nodes or rerouting edges. The one-shot signal inherits the active visual preset, becomes static for reduced-motion readers, stays quiet above 24 matched edges, and is omitted in embed, print, and canonical export. Unrelated topology remains softly visible, closing the panel preserves the selection, and `#lens=<kind>~<kind>` restores it. Escape closes the panel before clearing its active selection.--| Format | Use it for |+| Action | Control ||---|---|-| **Copy PNG** | Slack, Notion, GitHub comments, and quick reviews |-| **PNG / JPEG / WebP** | Slides, documents, websites, and print |-| **SVG** | READMEs, blogs, Figma, Illustrator, and lossless scaling |-| **WebM** | Product demos, release notes, social posts, and animated documentation |--Raster exports are rendered natively at the highest safe resolution, up to 4×. Oversized diagrams step down automatically to stay within browser canvas limits.--Exported SVGs include dark and light variables plus `prefers-color-scheme`, so one SVG can follow the reader's system theme.--Useful URL parameters:--- `?theme=light` or `?theme=dark` — force the starting theme.-- `?present=1` — open directly in Presentation Stage; combine with `?play=1#view=<view-id>` for a shareable live slide.-- `?play=1` — play the current named view once for 3.2 seconds, with a title/route/state/progress cue in embed mode, then stop; with no `#view`, play the first authored view. Never advances to another view and respects reduced motion.-- `?openExport=1` — open the Export menu on load.-- `#focus=<node-id>` — open with a semantic node and its one-hop neighborhood focused.-- `#relation=<relationship-id>` — reopen one exact authored relationship with a stable ID.-- `#route=<source-id>~<target-id>` — restore the shortest authored directed route between two semantic nodes.-- `#view=<view-id>` — open a named guided reading path defined by `meta.views`.-- `#view=<view-id>&beat=<node-id>` — open one exact, static Story Moment; add `?play=1` only when the remaining chapter should play once.--WebP, WebM, and clipboard support depend on browser capabilities. WebM is available only when the diagram uses `animation: "trace"`. The HTML uses local font fallbacks when an external font cannot be loaded.+| Open the factual Diagram Guide | <kbd>?</kbd> |+| Find and focus a semantic node | <kbd>/</kbd> |+| 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> |+| Toggle theme / open Export | <kbd>T</kbd> / <kbd>E</kbd> |+| Zoom or reset | <kbd>+</kbd> / <kbd>-</kbd> / <kbd>0</kbd> |-## Prompt patterns+Stable links can restore `#focus=<id>`, `#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.-**Repository overview**+The complete generation and viewer contract lives in [`archify/SKILL.md`](archify/SKILL.md).-```text-Map this repository's runtime architecture with no more than 12 core components.-Show the main request path, external systems, and trust boundaries. Move implementation detail into cards.-```--**CI/CD workflow**--```text-Draw a CI/CD workflow: pull request -> tests -> approval -> build image -> staging ->-smoke test -> production. Show rollback as a secondary failure path.-```--**Data lineage**--```text-Draw a data-flow diagram from Web and Mobile events through Consent Gate, Kafka,-Warehouse, and Feature Store to Dashboards and ML consumers. Mark the PII boundary.-```--## Reference--Semantic labels guide color and grouping:--| Examples | Category |-|---|---|-| `react`, `nextjs`, `ios`, `browser` | Frontend |-| `node`, `go-service`, `python-worker`, `api-gateway` | Backend |-| `postgres`, `redis`, `s3`, `bigquery`, `snowflake` | Data and storage |-| `aws.lambda`, `gcp.pubsub`, `azure.functions`, `kubernetes` | Cloud and infrastructure |-| `auth0`, `oauth`, `vault`, `security-group` | Security |-| `kafka`, `rabbitmq`, `sqs`, `nats` | Messaging |-| `stripe`, `github-actions`, `openai`, `slack` | External systems |+## Installation options-See the [schema reference](archify/schemas/README.md) for renderer inputs and [CHANGELOG.md](CHANGELOG.md) for release history.+| Surface | Install location or method | Capability |+|---|---|---|+| **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.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox |+| **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture fallback |-## Current status and roadmap+## Reference and scope-The current viewer includes progressive `MAP` / `READ` / `FULL` Reading Depth across all five renderer-backed modes.+- [Schema reference](archify/schemas/README.md)+- [Skill and renderer contract](archify/SKILL.md)+- [Examples](archify/examples/)+- [Changelog](CHANGELOG.md)+- [Roadmap](ROADMAP.md)+- [Generated Proof Lab](https://tt-a1i.github.io/archify/gallery.html)-Archify 2.11 uses typed JSON IR across all five renderer-backed modes and adds stable semantic hooks, shareable authored relationship IDs, pre-click Intent Trace previews, two-endpoint Route Probe analysis with a finite inspectable Route Journey, Semantic Camera framing, a live Semantic Radar overview, a Named Chapter Rail with Chapter Delta Preview, Shared Anchor Handoff, directly inspectable Story Beat Navigator controls, and Shareable Story Moment links, plus a reader-controlled Live/Still Motion Governor, Semantic Passport context with copyable focus links, a named incoming/outgoing Relationship Lens with exact path preview, searchable Node Finder navigation, one-hop focus, a shareable Presentation Stage, pan/zoom, Signal Flow motion, and browser-native WebM export. The project page now leads with three real, moving, clickable proof artifacts across Signal Flow, Blueprint, and Classic rather than a static product mockup. The [proof gallery](https://tt-a1i.github.io/archify/gallery.html) is regenerated from 11 checked-in scenario examples. Every recipe publishes a matching interactive artifact with three named reader views, its exact JSON source, seven validation checks, and a source digest instead of relying on hand-authored capability claims.+Archify 2.11 includes typed IR across all five modes, three visual presets, optional finite motion, guided views, semantic exploration, shareable deep links, browser-native WebM recording, and explicit `standard` / `showcase` quality profiles.-See [ROADMAP.md](ROADMAP.md) for planned work and design boundaries. Automatic Mermaid parsing, generic auto-layout, a hosted sharing service, and a WYSIWYG editor are not current goals.+Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope.## Attribution-Archify is a fork and rewrite of [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 by Cocoon AI.--The original visual language remains credited to that project. Archify 2.x adds themes, export tooling, typed renderers, validation, accessibility, and the unified CLI. Both projects use the MIT license.+Archify is a fork and rewrite of [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0. The original visual language remains credited to Cocoon AI; Archify 2.x adds themes, exports, typed renderers, validation, accessibility, interaction, and a unified CLI. Both projects use the MIT License.## License@@ -344,4 +232,4 @@ The original visual language remains credited to that project. Archify 2.x adds## Contributing-Issues, pull requests, and shared diagrams are welcome. When reporting generated-output problems, include the prompt, diagram type, and Archify version when possible. Run `node scripts/build-gallery.mjs` after changing bundled examples or the standalone viewer so the generated showcase stays current.+Issues, pull requests, and shared diagrams are welcome. For generated-output problems, include the prompt, diagram type, and Archify version. Run `node scripts/build-gallery.mjs` after changing bundled examples or the standalone viewer.diff --git a/README_ZH.md b/README_ZH.mdindex 55f08d62..b68da424 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -2,66 +2,51 @@<a href="./README.md">English</a> · <strong>简体中文</strong></p>-<p align="center">- <a href="https://tt-a1i.github.io/archify/gallery.html"><img src="docs/assets/archify-live-proof.gif" alt="三个经过验证的 Archify 成品依次展示 Signal Flow、Blueprint 和 Classic 预设" width="960"/></a>- <br/>- <sub><strong>三个真实生成、校验通过的成品。</strong> Signal Flow · Blueprint · Classic · <a href="https://tt-a1i.github.io/archify/gallery.html">打开可交互验证作品集 ↗</a></sub>-</p>+# Archify-**聊两句就画出好看的架构图、技术流程图、调用时序图、数据流图和生命周期图。深色 / 浅色一键切,还能动起来。导出清晰 PNG / JPEG / WebP / SVG / WebM。**--Archify 是一个可用于 Claude、Codex CLI 和 opencode 的 agent skill:你用大白话描述自己的系统或流程,它就把你的描述变成一张做工精细的技术图 —— 一个单文件 HTML,在浏览器里打开就能切主题、复制到剪贴板、导出成各种图片格式。--- **不需要会画图** —— 把组件和连接关系说给 Claude 就行-- **支持 workflow / sequence / data flow / lifecycle** —— 技术流程、审批链、工具调用、CI/CD、请求调用链、数据管线、PII 边界、状态机都可以画-- **内置主题切换** —— 深色 / 浅色一键切,浏览器记住偏好-- **三套有契约的视觉预设** —— `classic` 保持稳定默认,`signal-flow` 适合有光感的演示,`blueprint` 适合部署与设计评审-- **一眼识别 Semantic Sigils** —— 五种 renderer 会给前端、后端、数据库、云、安全、消息流、外部系统与生命周期状态加上小型主题自适应 SVG 语义印记,不需要品牌图标包、网络请求或新 schema 字段-- **沿真实路径移动的 Semantic Flow Tokens** —— 精确关系预览会沿作者定义的起点→终点几何携带调用、数据、事件、安全或生命周期状态标记;这一有限动效服务桌面读图,遵守 Still/减少动态且不进入标准导出-- **Semantic Story Carrier** —— 引导故事会在唯一真实关系上复用同一套语义标记,让镜头移动时也能看懂正在传递什么;带标签的边按稳定身份去重,普通嵌入、Still 与导出保持静态-- **让动态可控,但不丢语义** —— 开启 Trace 的成品只运行一次有限环境动效,随后稳定回到作者定义的实线、安全虚线和异步虚线,并显示一个 44px 的 `Live` / `Still` 开关;Story、Route、Lens 与预览仍保留有意触发的一次性动态,`Still` 会停在完整静态读法上-- **每个缩放层级只读刚好的信息** —— `MAP` 保持全局安静,`READ` 显示职责与关系标签,`FULL` 再展开标签、备注、步骤和分类;语义聚焦会自动显示当前问题需要的精确细节-- **不用先读文档也能探索成品** —— 按 <kbd>?</kbd> 打开 Diagram Guide:查看精确节点、关系和故事数量,并直接执行查找、路径、雷达、语义透镜、故事和演示动作-- **先预览意图,再决定是否聚焦** —— 悬停或用键盘聚焦任意节点,只让它直接相关的入向与出向路径流动;点击或按 Enter 后,再把同一跳上下文锁定到 Semantic Passport-- **检查并播放任意真实链路** —— 按 <kbd>R</kbd> 或点击 `PATH`,搜索有效起点和可达终点后,可逐站检查或沿精确最短作者有向路径播放一次有限 Route Journey,再复制只包含端点问题的 `#route=` 链接-- **直接追踪并分享命名关系** —— 悬停或用键盘到达任意作者关系线,即可预览真实起点、路径和终点;点击、触摸、Enter 或 Space 会钉住精确关系行,可选作者关系 `id` 还能生成持久的 `#relation=` 链接-- **读懂并分享当前节点** —— Semantic Passport 会显示 renderer 给出的类型、职责、结构范围、作者标签和稳定 ID,并可一键复制现有的 `#focus=<id>` 链接-- **快速找到任意节点** —— 按 <kbd>/</kbd> 搜索标题、职责、结构范围、标签、类型或稳定 ID;选择结果后自动复位视口,在受限宽画布中定位节点,并进入同一个可分享的语义聚焦-- **选择、检查、预判、播放并分享能看懂路径的引导故事** —— 紧凑的 Story Shelf 会保留 Play 与每个命名章节,把冷启动总览的空间还给图;读者进入后再展开完整 Director,Story Trail 的每一站仍是原生 beat 控件,Story Horizon 继续区分唯一下一站与更远未来-- **跟着故事走,也不丢局部上下文** —— 由读者启动的播放会同时框住上一站、当前站和下一站,镜头稳定后才继续,并会立即让位给暂停、手动导航、`Still` 或“减少动态效果”-- **让语义控制镜头** —— 节点邻域、关系跳转、Finder 结果和故事步骤会带安全留白自动入镜;用户手动缩放、拖拽或滑动时立即接管,并暂停自动播放-- **在大图里始终知道自己在哪** —— 按 <kbd>M</kbd> 打开 Semantic Radar:它用类型色显示全图和当前视窗,可按稳定 ID 点击节点,也支持拖动和方向键桌面导航-- **对比系统角色但不丢掉全局方位** —— 按 <kbd>L</kbd> 打开带精确计数的 Semantic Lens:选择一种类型查看真实流量,再选择一种类型,只统计两类之间的直接作者关系;克制的方向信号只沿这些真实命中边流动,并可复制稳定的 `#lens=` 视图-- **把精确图例当作实时地图** —— 架构、工作流和生命周期图里的类型行会显示编译后节点数量;悬停或键盘聚焦时安静预览对应拓扑,点击、轻触、Enter 或 Space 后把该类型固定到 Semantic Lens;边样式或节点/边混合语义的图例会诚实地保持静态-- **分享一个会自我解释的章节** —— 使用 `?play=1#view=...` 展示标题、精确 Story Trail 路径、实时状态和进度,以可读的逐站节奏播放后停住供阅读;开启“减少动态效果”的读者会看到同一章节并标记为 `Still`-- **进入演示舞台** —— 按 <kbd>F</kbd> 让动态图占满浏览器视口,同时保留故事控制;`?present=1&play=1#view=...` 可直接分享当前演示页,Escape 会先退出视图/聚焦,再离开舞台-- **零依赖平移缩放** —— 用内置视图控件检查复杂图,导出仍然保持完整、无临时变换的标准结果-- **一键复制到剪贴板** —— 直接贴到 Slack、飞书、微信、Notion、GitHub issue-- **导出图片超清晰** —— PNG / JPEG / WebP 全部由浏览器在最高 4× 源分辨率下**原生光栅化**(不是位图放大,没有糊),或导出 SVG 做真矢量-- **动态结果可分享** —— 开启 Trace 的图可直接在浏览器录制 6 秒 WebM,不依赖 Puppeteer 或 ffmpeg-- **SVG 自动跟系统深浅色** —— 导出的 SVG 内嵌两套变量 + `@media (prefers-color-scheme)`,贴到 GitHub README 里,读者切深浅色图跟着切(不用两张 PNG + `<picture>` 包起来)-- **内置质量闭环** —— renderer 驱动的图会经过 JSON schema 与既有布局检查;显式选择 `standard` 或 `showcase` 后,还会启用节点穿线 Clean Flow 和结构容器贴边走线门禁,而未设置 profile 的旧 v1 文件继续保持向后兼容。`showcase` 还会拒绝小于 8px 的线路小钩、小于 16px 的内部转折和无关关系 X 交叉,同时不会误杀普通端点短桩-- **语义技术标签** —— 可以把组件写成 `aws.lambda`、`postgres`、`redis`、`github-actions`、`openai` 等;Archify 会把它们映射到合适的视觉类别,不需要完整图标库-- **单文件 HTML** —— 生成的 HTML 零运行时依赖,发一个文件就能分享-- **聊天迭代** —— "把 Redis 挪到左边"、"鉴权服务换成玫红"、"加个 Kafka"+**在对话里,把自然语言描述变成漂亮、可靠的架构图、工作流图、时序图、数据流图和生命周期图。**++Archify 是一个可用于 Claude、Codex CLI 和 opencode 的 Agent Skill。它生成单文件 HTML 技术图:浏览器直接打开,可切换深浅主题、聚焦探索真实拓扑,并导出清晰的静态或动态结果。++- **五种图表类型** —— Architecture、Workflow、Sequence、Data Flow、Lifecycle+- **三套视觉预设** —— 稳定的 `classic`、有光感的 `signal-flow`、精确的 `blueprint`+- **探索真实拓扑** —— 查找节点、检查关系、探查路径、对比角色、播放引导故事+- **动态默认关闭** —— 只有显式设置 `meta.animation: "trace"` 才启用动态+- **便携导出** —— 复制 PNG,下载 PNG / JPEG / WebP / 双主题 SVG / WebM+- **Typed + Checked** —— Typed JSON IR、内置 Schema 校验、布局检查和可选质量门禁+- **结果完全独立** —— 一个 HTML 文件即可查看和分享,不依赖 Viewer 服务+- **适合 Agent 工作流** —— 安装一次,通过对话持续生成和细调-**[在线落地页 → tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)** · **[场景选图指南 → guide.html](https://tt-a1i.github.io/archify/guide.html)** · **[自动生成验证作品集 → gallery.html](https://tt-a1i.github.io/archify/gallery.html)**--在线落地页会在首屏直接露出真实生成的图面:只有一个有限、可交互的成品证明,不用假图,也不做自动轮播。--**60 秒开始:**+**[在线项目页](https://tt-a1i.github.io/archify/)** · **[场景选图指南](https://tt-a1i.github.io/archify/guide.html)** · **[Proof Lab](https://tt-a1i.github.io/archify/gallery.html)**```bashnpx skills add tt-a1i/archify -g```-然后告诉你的 agent:`使用 archify 梳理这个仓库的运行时架构。`+然后告诉 Agent:`使用 archify 梳理这个仓库的运行时架构。`++## 2.11 交互演示++下面都是真实生成的 Archify 成品,不是产品效果图。点击画面即可打开对应的可分享交互状态。++<p align="center">+ <a href="https://tt-a1i.github.io/archify/gallery.html"><img src="docs/assets/archify-live-proof.gif" alt="三个经过验证的 Archify 成品依次展示 Signal Flow、Blueprint 和 Classic 预设" width="960"/></a>+ <br/>+ <sub><strong>三个真实生成、校验通过的成品。</strong> Signal Flow · Blueprint · Classic · <a href="https://tt-a1i.github.io/archify/gallery.html">打开可交互验证作品集 ↗</a></sub>+</p>++| 引导故事 | 路径探查 | 语义角色对比 |+|---|---|---|+| [](https://tt-a1i.github.io/archify/gallery/artifacts/agent-tool-call.workflow.html?theme=dark&present=1&play=1#view=happy-path) | [](https://tt-a1i.github.io/archify/gallery/artifacts/cache-miss.sequence.html?theme=dark&present=1#route=web~db) | [](https://tt-a1i.github.io/archify/gallery/artifacts/production-deployment.architecture.html?theme=dark&present=1#lens=backend~database) |+| 播放一次有限的命名章节。 | 检查最短的作者有向路径。 | 对比语义角色之间的真实流量。 |++[Proof Lab](https://tt-a1i.github.io/archify/gallery.html) 收录全部 11 个仓库内场景、JSON 源、命名视图和校验回执。## 预览@@ -71,11 +56,11 @@ npx skills add tt-a1i/archify -g|---|---||  |  |-Export 菜单 —— 复制到剪贴板 + 静态和动态格式下载:+Export 菜单支持复制 PNG,并下载静态或动态格式:-想亲自体验:下载或克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html)。按 <kbd>?</kbd> 打开 Diagram Guide,按 <kbd>R</kbd> 探查路径,按 <kbd>/</kbd> 查找节点,按 <kbd>M</kbd> 打开 Semantic Radar,按 <kbd>L</kbd> 打开 Semantic Lens,按 <kbd>F</kbd> 进入演示舞台,按 <kbd>T</kbd> 切换主题,按 <kbd>E</kbd> 打开导出菜单。+在本地打开 [`examples/web-app.html`](examples/web-app.html),即可体验完整 Viewer。## 快速开始@@ -85,23 +70,19 @@ Export 菜单 —— 复制到剪贴板 + 静态和动态格式下载:npx skills add tt-a1i/archify -g```-这条命令通过开源的 [`skills` CLI](https://github.com/vercel-labs/skills) 为支持的 Agent 安装 Archify。--如果只想临时体验,不做永久安装:+如果只想临时体验:```bashnpx skills use tt-a1i/archify@archify --agent codex```-需要时可以把 `codex` 换成 `claude-code` 或 `opencode`。+需要时可以把 `codex` 换成 `claude-code` 或 `opencode`。仓库内的 [`archify.zip`](archify.zip) 也不需要执行 `npm install`。### 2. 先画一个边界清楚的视图-不要一开始就要求一张图解释整个仓库。先从 Overview 开始:-```text分析这个仓库,然后使用 archify 生成一张高层运行时架构图。-只保留 8–12 个核心组件,突出一条主要请求或数据路径,并标出外部依赖与信任边界。+只保留 8–12 个核心组件,突出一条主要路径,并标出外部依赖与信任边界。辅助信息放进说明卡片,不要继续增加连线。```@@ -114,231 +95,136 @@ Redis Session 查询 -> PostgreSQL 回源。把缓存未命中作为次要路径### 3. 在对话中细调-只要当前会话里仍保留源 JSON,就可以继续说:`增加 Redis`、`把鉴权移到左侧`、`突出回滚路径`。--最终得到的是一个可直接在现代浏览器中打开的 HTML 文件,并可导出 PNG、JPEG、WebP、SVG;开启 Trace 后还可导出 WebM。+继续说:`增加 Redis`、`把鉴权移到左侧`、`突出回滚路径`。Archify 会保留 Typed Source,只修改相关部分。-## 图表类型+## 选择合适的图表-先确定你想回答的问题,再选择对应视图:+| 类型 | 最适合 | Prompt 中应包含 |+|---|---|---|+| **Architecture** | 组件、服务、存储和系统边界 | 范围、核心组件、主要路径 |+| **Workflow** | CI/CD、审批、工具调用、Runbook | 参与者、顺序、分支、异常 |+| **Sequence** | API 调用、缓存回源、鉴权、异步链路 | 调用方、被调用方、返回、时序 |+| **Data Flow** | 数据管线、血缘、PII、下游消费者 | 来源、转换、存储、边界 |+| **Lifecycle** | 状态、重试、等待、终态 | 状态、事件、重试与取消路径 |-不知道该用哪一种图?可以打开[交互式场景指南](https://tt-a1i.github.io/archify/guide.html),也可以直接询问零依赖 CLI。它会从 11 个小而专的配方中给出推荐,同时返回证据清单、使用边界、表现建议和可复制提示词:+不知道选哪一种?打开[交互式场景指南](https://tt-a1i.github.io/archify/guide.html),或直接询问零依赖 CLI:```bashnode archify/bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求"node archify/bin/archify.mjs guide "梳理 Kafka Topic、消费者组、重放和死信队列" --json```-| 类型 | 最适合 | Prompt 中应包含 |-|---|---|---|-| **Architecture** | 组件、服务、存储和系统边界 | 范围、核心组件、主要路径 |-| **Workflow** | CI/CD、审批、工具调用、runbook | 参与者、顺序、分支、异常 |-| **Sequence** | API 调用、缓存回源、鉴权和异步链路 | 调用方、被调用方、返回和时序 |-| **Data Flow** | 数据管线、血缘、PII 和下游消费 | 来源、转换、存储、敏感边界 |-| **Lifecycle** | 状态机、等待、重试和终态 | 状态、事件、重试与取消路径 |--Architecture 示例:--- [`examples/web-app.html`](examples/web-app.html) — 精简 SaaS 架构-- [`examples/archify-repo.html`](examples/archify-repo.html) — Archify 的 Skill → JSON IR → Renderer 流水线-- [`examples/archify-repo-grid.html`](examples/archify-repo-grid.html) — 显式 `row` / `col` 网格布局-- [`examples/maka-architecture.html`](examples/maka-architecture.html) — 第三方桌面 Agent 工作台--Workflow 使用泳道、清晰主路径和克制的次要分支。+Workflow 用泳道保持主路径清晰:-Sequence 聚焦一段随时间展开的交互。+Sequence 解释一次交互随时间如何推进:-Data Flow 明确表现数据移动、转换以及敏感边界。+Data Flow 突出数据移动和敏感边界:-Lifecycle 区分正常进展、等待态、重试路径和终态。+Lifecycle 区分正常进展、等待、重试和终态:-## 为什么用 Archify--- **用布局判断代替通用自动布局** —— Agent 根据要讲的故事决定层级、间距、线路和视觉重点。-- **Typed JSON IR** —— 五种图都由对应 Schema 和 Renderer 驱动。-- **交付前验证** —— Schema、布局、HTML 和 SVG 检查会尽早发现结构错误和明显的可读性问题;显式选择质量 profile 后,Clean Flow 会精确指出节点穿线几何,构图收据会拒绝关系线贴着结构容器边框行走、分类最终可见的 X 交叉、区分端点短桩与拥挤转折,并在路由角色尚未校准前继续把 bend / stretch 保留为中性证据。-- **便于分享** —— 一个 HTML 文件即可打开,无需服务器或前端框架;外部字体不可用时会使用本地字体。-- **语义技术标签** —— `postgres`、`redis`、`aws.lambda`、`github-actions` 等名称会参与视觉分类,不需要沉重的图标运行时。--Archify 不是通用绘图编辑器,也不是 Mermaid 换肤工具。它的目标是把技术意图编译成适合沟通的成品图。+Architecture 示例:[`Web App`](examples/web-app.html) · [`Archify Pipeline`](examples/archify-repo.html) · [`Grid 布局`](examples/archify-repo-grid.html) · [`桌面 Agent`](examples/maka-architecture.html)-## 安装方式--推荐直接使用:--```bash-npx skills add tt-a1i/archify -g-```--同一个 [`archify.zip`](archify.zip) 也可以手动安装:--| 使用方式 | 安装位置或方法 | 能力 |-|---|---|---|-| **Claude Code** | `~/.claude/skills/` 或 `.claude/skills/` | 完整 Renderer + 校验流程 |-| **Codex CLI** | `~/.agents/skills/` 或 `.agents/skills/` | 完整 Renderer + 校验流程 |-| **opencode** | `~/.config/opencode/skills/`、`.opencode/skills/` 或 `.agents/skills/` | 完整 Renderer + 校验流程 |-| **Claude.ai** | 在 Settings → Capabilities → Skills 上传 `archify.zip` | 取决于沙箱是否允许执行 Node.js |-| **Project Knowledge** | 把 `archify.zip` 上传到项目知识库 | 仅 Prompt 驱动的 Architecture 模式 |--Claude.ai 的 Skills 上传入口:+## 为什么用 Archify-+- **用布局判断代替通用自动布局** —— Agent 根据故事选择层级、留白、线路和强调关系。+- **Typed JSON IR** —— 每种 Renderer 模式都有 Schema 和可复现的源文件。+- **交付前校验** —— Schema、布局、HTML/SVG、线路和可选 Showcase 检查会拦截坏结果。+- **交互不编造拓扑** —— 聚焦、路径、角色对比和故事都复用作者定义的节点与关系。+- **结果默认便携** —— 一个 HTML 文件即可分享;导出永远是完整原图,不携带临时 Viewer 状态。-手动安装就是把压缩包解压到对应目录。分发包已包含独立校验器,不需要执行 `npm install`。+Archify 不是通用绘图编辑器,也不是 Mermaid 主题;它负责把技术意图变成可交流的成品。## 工作原理-Renderer 驱动的图会经过一条简短、可检查的流水线:-| 步骤 | 发生什么 ||---|---|-| **生成 JSON IR** | Agent 先生成类型化描述,而不是直接修改最终 SVG。 |-| **校验** | 内置独立校验器检查 Schema,无需安装运行时依赖。 |-| **渲染** | 对应 Renderer 生成 HTML/SVG。 |-| **检查** | 布局和 Artifact 检查发现无效坐标、损坏 SVG 和不安全线路。 |-| **迭代** | 修改集中在 JSON IR,尽量保持无关结构稳定。 |+| **生成** | Agent 根据描述创建 Typed JSON IR。 |+| **校验** | 内置 Validator 和布局规则检查源文件。 |+| **渲染** | 对应 Renderer 生成独立 HTML 和 SVG。 |+| **检查** | Artifact 门禁拒绝错误几何和不安全线路。 |+| **迭代** | Agent 修改源文件,不干扰无关结构。 |-从仓库源码运行 CLI:+仓库常用命令:```bashcd archifynode bin/archify.mjs doctornode bin/archify.mjs demo /tmp/archify-demo-node bin/archify.mjs guide "展示 CI/CD 检查、审批、发布和回滚"+node bin/archify.mjs guide "展示 CI/CD 检查、审批、部署和回滚"node bin/archify.mjs render workflow examples/agent-tool-call.workflow.json /tmp/workflow.html-node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --jsonnode bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --jsonnode bin/archify.mjs check /tmp/workflow.html-node bin/archify.mjs examples```-演示场景可以选择开启轻量 Trace 动画:+动态和演示样式需要显式选择:```json{"meta": {- "title": "Release Flow","animation": "trace","visual_preset": "signal-flow"}}```-`visual_preset` 是可选项:`classic` 保持稳定默认,`signal-flow` 提供有光感的分层画布和更紧凑的动态节奏,`blueprint` 则提供高对比工程网格、方正评审材质和更精确的边界表达,同时不改变图形几何。开启 Trace 的成品会提供统一的 `Live` / `Still` Motion Governor:环境动效只播放一次,随后恢复作者定义的关系线型,并让位给更强的语义动作;`Still` 会暂停正在播放的 Story 且切回 `Live` 后不会擅自续播,浏览器存储可用时也会记住读者选择。动态 `prefers-reduced-motion` 与页面隐藏会走同一条安全停止路径;不设置 `animation` 时则保持真正静态,也不显示动态控制。--可选的 `meta.views` 可以把一张稳定总览变成简短的引导阅读序列。每个视图只包含唯一 ID、标题、有序的既有语义节点 ID 和可选说明,不能移动或重绘底层图。尚未进入章节时,Story Shelf 只保留紧凑的引导视图身份、Play 和所有作者章节,把暂时无效的导演控件收起;选择章节、开始播放或恢复有效深链后,完整 Director 会立即展开,Show all 或 Escape 则回到 Shelf。Named Chapter Rail 会列出每个作者标题和两位序号;尚未选中章节时,候选项会诚实显示从总览出发的 `=0 +N −0`,选中后当前章节保留停靠点数,其余候选则显示精确的 `=保留 +进入 −离开` 聚焦差异。精细指针悬停或键盘聚焦会在不改变当前章节、镜头、Story Trail 与 URL 的前提下显示同一份静态 Chapter Delta Preview;Escape 只撤销预览并保留焦点,触屏仍然首次轻触直接激活。选择章节继续委托给上一步/下一步与 `#view=` 共用的引导视图状态。当相邻章节拥有真实的稳定 ID 共同节点时,Shared Anchor Handoff 会先把该节点保持在原位并说明连续关系,再完成一次可打断的相机移动;没有共同节点时则明确使用 `no-anchor` 重定向,不编造连续性。Story Beat Navigator 会把每个解析后的有序停靠点做成原生控件,并且只把相邻节点之间精确 authored edge 分类为正向、反向、grouped 或 multiple;直接激活会钉住 beat,不改变章节、焦点集、镜头、滚动或 URL,唯一无歧义的边最多运行一次有限信号,Play 则从同一 beat 剩余 dwell 继续。**Copy moment** 会在必要时冻结播放,并生成稳定的 `#view=<view-id>&beat=<node-id>` 链接;打开后无动画恢复这个作者节点,无效 beat 则安全退回有效章节。JSON、原始边样式、SVG 几何和标准导出都保持不变。--Story Follow Camera 会框住当前 authored 窗口,Story Director Strip 则用真实路径、边标签、职责与上下文解释当前镜头,不编造关系。Story Horizon 以静态的 `past → active → next → pending` 层级预告唯一的下一节点,并且只复用该下一步已经解析出的真实边;grouped 不造边,multiple 保留全部作者关系,最终 beat 不残留预告,也不会提前移动镜头。桌面 Presentation 播放时保留上一步、下一步与暂停,只暂时收起次要故事控件,暂停后完整恢复。--## 使用生成结果+不设置 `animation` 时结果完全静态;`classic` 始终是默认视觉预设。-在现代浏览器中打开 HTML,右上角提供三个入口:+## 探索与分享-- **Theme** —— 切换深色和浅色,快捷键 <kbd>T</kbd>。-- **Present** —— 让实时图占满浏览器视口,不改变图形或导出结果,快捷键 <kbd>F</kbd>。-- **Export** —— 复制 PNG,或下载 PNG、JPEG、WebP、SVG;开启 Trace 时还能导出 6 秒 WebM,快捷键 <kbd>E</kbd>。--Reading Depth 从只保留主标签与拓扑的 `MAP 100%` 开始,到 `READ 125%` 显示职责与关系标签,再到 `FULL 175%` 展开标签、备注、步骤和分类。聚焦、Semantic Lens、Intent Trace、Route Probe、Story Trail、Direct Relationship Pin 与关系预览会在任意缩放下自动显示当前问题需要的局部细节;打印和导出始终保留完整图。--每条作者关系现在也都是直接入口。不可见的 24px 非缩放命中轨道会精确贴合原有几何,但不会把画面里的线变粗。精细指针悬停或键盘漫游会预览真实起点、路径与终点;点击、触摸、Enter 或 Space 会打开起点 Passport,并钉住现有 Relationship Lens 的精确关系行。五种关系数组都可以提供可选作者 `id`;命名关系会写入并复制 `#relation=<relationship-id>`,即使关系数组重新排序,也能恢复同一条作者关系。标准 SVG 保留 `data-edge-id` 作为语义身份,运行时命中轨道与信号副本则会移除它。旧的无 ID 文档仍然有效,其关系钉住状态只留在本页,Copy 会安全回退到起点节点;私有数字 key 永远不会进入分享 URL,重复作者关系 ID 会在输出前失败。Focus、Story、Route、Lens 与 Chapter 等更强状态仍然优先,普通嵌入、打印和标准导出保持干净。--图本身也可以探索。在正式聚焦前,悬停节点或用键盘到达它,就会启动 Intent Trace:无关元素轻轻退后,只有该节点直接相关的入向、出向和自环路径显示带方向的短促流动信号。触屏用户不模拟悬停,仍然一次点击直达聚焦;减少动态偏好的用户会看到同样的一跳静态对比。按 <kbd>R</kbd> 或使用 `PATH` 可启动 Route Probe:先选起点,再从高亮的可达节点中选择终点,Archify 会用确定性的最少跳数有向路径框选并追踪整条链路,在紧凑回执中列出每一站,并提供 `#route=<source>~<target>` 复制链接;它不会用无向路径制造看似方便但语义错误的回退,减少动态模式则显示同样的静态结果。点击节点,或按 <kbd>Enter</kbd> / <kbd>Space</kbd>,即可把该节点、直接邻居和关联路径锁定;Semantic Camera 会在不遮挡 Relationship Lens 的前提下框选这一跳邻域。Semantic Passport 会立即说明该节点由 renderer 给出的类型、职责、结构范围、作者标签和稳定 ID;Copy link 会写入当前 `#focus=<id>` 深链。Lens 会给每条入向、出向和自环关系命名;在手机上,完整列表默认收在明确的关系数量按钮后面,让紧凑 Passport 不会盖住选中节点。悬停某一行,或用方向键、Home、End 到达它时,其余关系会暂时变暗,画布会精确指出这条关系的起点、路径和终点;激活该行即可沿边跳转,并把镜头交给相邻节点。按 <kbd>M</kbd> 打开 Semantic Radar:它用类型色显示简化全图和实时视窗框;点击雷达节点即可聚焦,拖动表面或使用方向键可重新居中,Escape 关闭。雷达只在图表可见时停靠,会尽量避开焦点节点和 Passport;手机受限横向图会报告实际可见宽度,并且雷达始终不进入嵌入、打印或标准 SVG 导出。按 <kbd>/</kbd> 打开 Node Finder,可搜索同一组标题、职责、结构范围、标签、类型或稳定 ID;每条结果会显示上下文和关系数量,选择后自动复位并框选该节点。带引导视图的图还会提供播放/暂停、上一步、下一步和显示全图控件。Named Chapter Rail 会预先显示所有作者章节和精确章节聚焦差异;Left/Right/Home/End 只移动焦点,并静态预览 `保留 / 进入 / 离开` 成员,不会切换当前图。激活仍委托给同一个 `activeIndex` 与 `#view=` 状态,焦点进入轨道时会暂停播放,把下一步交还读者;Escape 只撤掉差异预览并把焦点留在原处。Story Beat Navigator 把 Story Trail 的每个已解析停靠点变成原生控件:点击、触摸、Enter 或 Space 会暂停并钉住精确 beat,同时保持章节、选中焦点、镜头、受限滚动和 `#view=` URL 不变。回执会区分真实正向边、反向 authored edge、没有直接关系的 grouped transition,以及多条 authored edge;只有唯一且无歧义的精确边可以播放一次有限信号。键盘焦点本身只会在当前 playhead 暂停,Play 会从这个 beat 尚未完成的 dwell 继续,而不是重启章节。播放时,较早 beat 会沉降,当前节点及精确相邻关系保持最高权重,未来 beat 仍然可见,下一章则会等 Shared Anchor Handoff 完成后才开始。按 <kbd>P</kbd> 播放完整故事,或用 <kbd>[</kbd> / <kbd>]</kbd> 手动换章。分享链接 `?play=1#view=<view-id>` 则只让该命名章节播放一次 3.2 秒,不会自动跳到下一章,并会遵守 `prefers-reduced-motion`。嵌入模式的 Share Chapter Cue 会显示章节名、精确作者路径、当前 `Step NN / NN`、Playing/Settled/Paused/Still 状态和同一个一次性进度,并始终留在 SVG 与导出之外。每个章节都会用受限缩放和留白框选作者指定的节点;用户手动缩放、拖拽或在手机上滑动时,会接管镜头并暂停播放。演示舞台会隐藏支持性卡片并让图占满视口,但保留这些实时控制。页面隐藏或读者开始自由探索时也会自动暂停;按 <kbd>Escape</kbd> 会先关闭雷达或 Route Probe,再撤销 Chapter Delta Preview、退出当前引导视图/聚焦,最后离开舞台。使用 <kbd>+</kbd>、<kbd>-</kbd>、<kbd>0</kbd> 缩放或复位,放大后可以拖动画布。节点聚焦记录在 `#focus=<node-id>`,作者关系钉住记录在 `#relation=<relationship-id>`,路径探查记录在 `#route=<source>~<target>`,引导故事记录在 `#view=<view-id>`;导出始终使用完整、未变换的原图。--Relationship Lens 的关系预览是一次性方向提示,不是环境动画。用精细指针进入某一行,或用方向键、Home、End 把焦点移到该行时,Archify 只在对应稳定边键的真实几何上播放一次约 1.2 秒的起点→终点脉冲;移动标记会根据编译后的渲染器证据区分调用、数据、事件、安全边界与生命周期状态变化,入向关系仍按作者定义的真实方向移动。脉冲结束后,精确边与两端节点保持静态强调。窄屏复用同一套基础容错,不作为独立产品面;减少动态偏好直接显示同样的静态含义。该临时信号不会进入嵌入、打印、SVG 或栅格导出。--Route Probe 完成后还会显示 Route Journey。原生路径节点、Previous、Next、Journey/Pause/Replay 与 Overview 控件会保留整条最短路径作为上下文,同时强化一个有序位置及其精确入向关系。只有读者主动按下播放才会启动一次有限旅程;暂停后从剩余停留时间继续,路径焦点、手动平移缩放、Guide、页面隐藏、Motion Still 和减少动态都会立即接管。静态模式仍可逐站手动检查。Escape 依次执行暂停、回到 Overview、清除路径;分享的 `#route=<source>~<target>` 始终只记录端点,并静态恢复到 Overview,绝不自动播放。--Route Probe 正在选择端点时,按 <kbd>/</kbd>、使用常规 Finder 控件,或点击 `Find start` / `Find target`,都会把 Node Finder 切换成上下文端点选择器。起点搜索会略过无出向关系的死路;终点搜索只保留按作者方向真实可达的节点,并提前显示最短跳数。Escape 只关闭 Finder,不会丢掉正在进行的路径问题;离开 Route Probe 后,Finder 仍保持原来的语义聚焦行为。--按 <kbd>?</kbd> 或点击问号控件可打开 Diagram Guide。它会读取编译后的真实成品,报告精确语义节点、关系和引导视图数量,再通过面向结果的任务行直接运行现有 Finder、Route Probe、Semantic Radar、Semantic Lens、Story Trail 与 Presentation 交互。面板内支持方向键、Home、End、直接快捷键和 Escape;打开时会暂停播放并关闭互相遮挡的面板,但不会清除当前聚焦或正在进行的路径问题。--按 <kbd>L</kbd> 或点击 `LENS` 可以在不丢失全局方位的前提下比较编译后的语义类型。架构、工作流和生命周期图中与节点类型精确对应的图例行也会直接显示编译计数:精细指针悬停或键盘聚焦时,会安静预览对应节点、相连作者关系和对端节点;点击、轻触、Enter 或 Space 后,把该类型固定并打开同一个 Lens。Sequence 与 Data Flow 图例仍保持静态,因为其行表达的是边变体或节点/边混合含义,而不是一种精确类型。每种 Lens 类型都会显示精确节点数;单选时保留该类节点、所有相接关系和对端节点,双选时只突出并统计两类之间的直接作者关系。只有这些精确的作者路径会出现由选择触发的一次短方向脉冲:出向/正向、入向/反向和同类流量视觉上各自明确,但节点不会移动,连线也不会重排。一次性信号会继承当前视觉预设,在减少动态模式下变为静态,命中超过 24 条边时自动静默,并且不进入嵌入、打印与标准导出。无关拓扑只是柔和退后,不会消失;关闭面板会保留当前选择,`#lens=<kind>~<kind>` 可恢复同一视图,Escape 会先关闭面板、再清除选择。--| 格式 | 适合 |+| 操作 | 控制方式 ||---|---|-| **复制 PNG** | 飞书、Slack、Notion、GitHub 评论和快速评审 |-| **PNG / JPEG / WebP** | 演示文稿、文档、网站和印刷 |-| **SVG** | README、博客、Figma、Illustrator 和无损缩放 |-| **WebM** | 产品演示、版本说明、社交媒体和动态文档 |--位图会以浏览器允许的最高安全分辨率原生渲染,最高 4×。图太大时会自动降到 3× 或 2×,避免超过 Canvas 限制。+| 打开事实型 Diagram Guide | <kbd>?</kbd> |+| 查找并聚焦语义节点 | <kbd>/</kbd> |+| 探查有向路径并逐站检查 | <kbd>R</kbd> 或 `PATH` |+| 对比一种或两种语义角色 | <kbd>L</kbd> 或 `LENS` |+| 打开实时全局雷达 | <kbd>M</kbd> 或 `MAP` |+| 播放故事 / 切换章节 | <kbd>P</kbd> / <kbd>[</kbd> <kbd>]</kbd> |+| 进入 Presentation Stage | <kbd>F</kbd> |+| 切换主题 / 打开 Export | <kbd>T</kbd> / <kbd>E</kbd> |+| 缩放或复位 | <kbd>+</kbd> / <kbd>-</kbd> / <kbd>0</kbd> |-导出的 SVG 同时包含深色、浅色变量和 `prefers-color-scheme`,因此同一个文件可以跟随读者的系统主题。+稳定链接可以恢复 `#focus=<id>`、`#relation=<id>`、`#route=<source>~<target>`、`#lens=<kind>~<kind>` 和 `#view=<view-id>`。读者触发的动态有限运行、遵守 `prefers-reduced-motion`,并且不会进入标准导出。-常用 URL 参数:+完整生成与 Viewer 契约请查看 [`archify/SKILL.md`](archify/SKILL.md)。-- `?theme=light` 或 `?theme=dark` —— 固定初始主题。-- `?present=1` —— 直接进入演示舞台;可与 `?play=1#view=<view-id>` 组合成可分享的实时演示页。-- `?play=1` —— 当前命名视图只播放一次 3.2 秒,嵌入模式同时显示标题、路径、状态和进度提示,然后停住;不带 `#view` 时播放第一个作者视图。不会自动换章,并遵守减少动态效果设置。-- `?openExport=1` —— 加载后自动打开导出菜单。-- `#focus=<node-id>` —— 打开时聚焦指定语义节点及其一跳邻域。-- `#relation=<relationship-id>` —— 打开时恢复一条带作者稳定 ID 的精确关系。-- `#route=<source-id>~<target-id>` —— 恢复两个语义节点之间作者关系上的最短有向路径。-- `#view=<view-id>` —— 打开 `meta.views` 定义的命名阅读路径。-- `#view=<view-id>&beat=<node-id>` —— 打开一个精确、静态的 Story Moment;只有需要从该处播放剩余章节时才添加 `?play=1`。--WebP、WebM 和剪贴板能力取决于浏览器;WebM 只在使用 `animation: "trace"` 时开放。外部字体不可用时,HTML 会使用本地字体 fallback。--## Prompt 模板--**仓库概览**--```text-梳理这个仓库的运行时架构,最多保留 12 个核心组件。-展示主要请求路径、外部系统和信任边界,把实现细节放进说明卡片。-```--**CI/CD Workflow**--```text-画一张 CI/CD workflow:pull request -> tests -> approval -> build image ->-staging -> smoke test -> production。把 rollback 画成次要失败路径。-```--**数据血缘**--```text-画一张从 Web、Mobile 事件经过 Consent Gate、Kafka、Warehouse、Feature Store,-最终到 Dashboard 和 ML 消费方的数据流图,并明确标出 PII 边界。-```--## 参考+## 安装方式-语义标签会参与颜色和分组:+| 使用位置 | 安装位置或方法 | 能力 |+|---|---|---|+| **Claude Code** | `~/.claude/skills/` 或 `.claude/skills/` | 完整 Renderer + Validation 工作流 |+| **Codex CLI** | `~/.agents/skills/` 或 `.agents/skills/` | 完整 Renderer + Validation 工作流 |+| **opencode** | `~/.config/opencode/skills/`、`.opencode/skills/` 或 `.agents/skills/` | 完整 Renderer + Validation 工作流 |+| **Claude.ai** | Settings → Capabilities → Skills 中上传 `archify.zip` | 取决于沙箱是否提供 Node.js |+| **Project Knowledge** | 把 `archify.zip` 上传到项目 | Prompt 驱动的 Architecture Fallback |-| 示例 | 类别 |-|---|---|-| `react`、`nextjs`、`ios`、`browser` | 前端 |-| `node`、`go-service`、`python-worker`、`api-gateway` | 后端 |-| `postgres`、`redis`、`s3`、`bigquery`、`snowflake` | 数据和存储 |-| `aws.lambda`、`gcp.pubsub`、`azure.functions`、`kubernetes` | 云与基础设施 |-| `auth0`、`oauth`、`vault`、`security-group` | 安全 |-| `kafka`、`rabbitmq`、`sqs`、`nats` | 消息系统 |-| `stripe`、`github-actions`、`openai`、`slack` | 外部系统 |+Claude.ai 中的上传入口:-Renderer 输入请查看 [Schema 说明](archify/schemas/README.md),版本历史请查看 [CHANGELOG.md](CHANGELOG.md)。+-## 当前状态与路线图+## 参考与边界-当前 Viewer 已在五种 Renderer 模式中提供渐进式 `MAP` / `READ` / `FULL` Reading Depth。+- [Schema 说明](archify/schemas/README.md)+- [Skill 与 Renderer 契约](archify/SKILL.md)+- [示例](archify/examples/)+- [版本历史](CHANGELOG.md)+- [路线图](ROADMAP.md)+- [自动生成的 Proof Lab](https://tt-a1i.github.io/archify/gallery.html)-Archify 2.11 的五种 Renderer 模式都已经使用 Typed JSON IR,并支持可分享的作者关系 ID、聚焦前 Intent Trace 路径预览、带有限可检查 Route Journey 的双端点 Route Probe 分析、稳定语义标记、Semantic Camera、实时 Semantic Radar 全局导航、带 Chapter Delta Preview、Shared Anchor Handoff、可直接检查 Story Beat Navigator 与 Shareable Story Moment 的命名章节轨、读者可控的 Live/Still Motion Governor、带可复制焦点链接的 Semantic Passport、具名入向/出向 Relationship Lens、Node Finder 搜索导航、一跳聚焦、可分享的演示舞台、平移缩放、Signal Flow 动态效果和浏览器原生 WebM 导出。项目页现在不再用静态效果图充当首要证据,而是直接展示 Signal Flow、Blueprint 和 Classic 三个真实、会动、可点击的成品。[验证作品集](https://tt-a1i.github.io/archify/gallery.html) 会从仓库内 11 个场景示例自动重建;每个配方都发布对应交互成品、三个命名阅读视图、精确 JSON 源、七项校验和源摘要,不依赖手写且可能过期的能力声明。+Archify 2.11 已覆盖五种 Typed IR、三套视觉预设、可选有限动态、引导视图、语义探索、可分享深链、浏览器原生 WebM,以及显式 `standard` / `showcase` 质量档位。-规划和产品边界请查看 [ROADMAP.md](ROADMAP.md)。自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不是目标。+自动 Mermaid Parser、通用自动布局、托管分享服务和 WYSIWYG 编辑器目前都不在产品范围内。## 致谢-Archify 基于 Cocoon AI 的 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 进行 Fork 和重写。--原项目的视觉语言仍归功于 Cocoon AI。Archify 2.x 在其基础上增加了主题、导出、Typed Renderer、校验、无障碍支持和统一 CLI。两个项目都采用 MIT License。+Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 Fork 和重写。原始视觉语言仍归功于 Cocoon AI;Archify 2.x 在此基础上增加主题、导出、Typed Renderer、校验、无障碍、交互和统一 CLI。两个项目都采用 MIT License。## License@@ -346,4 +232,4 @@ Archify 基于 Cocoon AI 的 [Cocoon-AI/architecture-diagram-generator](https://## 参与贡献-欢迎提交 Issue、Pull Request 和分享生成的图。报告产物问题时,请尽量附上 Prompt、图表类型和 Archify 版本。修改内置示例或独立 Viewer 后,请运行 `node scripts/build-gallery.mjs` 同步自动生成的作品集。+欢迎提交 Issue、Pull Request 和分享生成的图。报告产物问题时,请附上 Prompt、图表类型和 Archify 版本。修改内置示例或独立 Viewer 后,请运行 `node scripts/build-gallery.mjs` 同步自动生成作品集。diff --git a/archify/test/readme-showcase.test.mjs b/archify/test/readme-showcase.test.mjsindex cf9c5c97..ce2d56f1 100644--- a/archify/test/readme-showcase.test.mjs+++ b/archify/test/readme-showcase.test.mjs@@ -103,12 +103,17 @@ test('README motion proof is compact, looping, and backed by current gallery art}});-test('all README languages lead with the verified animated proof', () => {+test('all README languages keep the product hero and retain the verified animated proof', () => {for (const filename of ['README.md', 'README_EN.md', 'README_ZH.md']) {const readme = fs.readFileSync(path.join(repoRoot, filename), 'utf8');+ const heroIndex = readme.indexOf('docs/assets/archify-readme-hero.png');+ const titleIndex = readme.indexOf('# Archify');+ const proofIndex = readme.indexOf('docs/assets/archify-live-proof.gif');+ const demosIndex = Math.max(readme.indexOf('## Interactive demos in 2.11'), readme.indexOf('## 2.11 交互演示'));+ assert.ok(heroIndex >= 0 && heroIndex < titleIndex, `${filename}: product hero is not above the title`);+ assert.ok(proofIndex > demosIndex, `${filename}: animated proof must live in the demo section`);assert.match(readme, /docs\/assets\/archify-live-proof\.gif/);assert.match(readme, /https:\/\/tt-a1i\.github\.io\/archify\/gallery\.html/);- assert.doesNotMatch(readme, /docs\/assets\/archify-readme-hero\.png/);}assert.equal(fs.readFileSync(path.join(repoRoot, 'README.md'), 'utf8'),@@ -116,3 +121,79 @@ test('all README languages lead with the verified animated proof', () => {'README.md and README_EN.md must stay synchronized',);});++test('README 2.11 demos use checked-in captures and live deep links below the existing hero', () => {+ const demos = [+ {+ asset: 'archify-demo-story.png',+ link: 'agent-tool-call.workflow.html?theme=dark&present=1&play=1#view=happy-path',+ },+ {+ asset: 'archify-demo-route.png',+ link: 'cache-miss.sequence.html?theme=dark&present=1#route=web~db',+ },+ {+ asset: 'archify-demo-lens.png',+ link: 'production-deployment.architecture.html?theme=dark&present=1#lens=backend~database',+ },+ ];++ for (const demo of demos) {+ const buffer = fs.readFileSync(path.join(repoRoot, 'docs', 'assets', demo.asset));+ assert.equal(buffer.subarray(1, 4).toString('ascii'), 'PNG', `${demo.asset}: invalid PNG signature`);+ assert.equal(buffer.readUInt32BE(16), 1280, `${demo.asset}: unexpected width`);+ assert.equal(buffer.readUInt32BE(20), 720, `${demo.asset}: unexpected height`);+ assert.ok(buffer.byteLength < 400 * 1024, `${demo.asset}: capture is too large`);+ }++ for (const filename of ['README.md', 'README_EN.md', 'README_ZH.md']) {+ const readme = fs.readFileSync(path.join(repoRoot, filename), 'utf8');+ const heroIndex = readme.indexOf('docs/assets/archify-readme-hero.png');+ const proofIndex = readme.indexOf('docs/assets/archify-live-proof.gif');+ const previewIndex = Math.max(readme.indexOf('## Preview'), readme.indexOf('## 预览'));+ const demosIndex = Math.max(readme.indexOf('## Interactive demos in 2.11'), readme.indexOf('## 2.11 交互演示'));+ const quickStartIndex = Math.max(readme.indexOf('## Quick start'), readme.indexOf('## 快速开始'));+ assert.ok(heroIndex >= 0 && heroIndex < demosIndex, `${filename}: existing hero proof moved`);+ assert.ok(demosIndex < previewIndex && previewIndex < quickStartIndex, `${filename}: demo section is misplaced`);+ assert.ok(demosIndex < proofIndex && proofIndex < previewIndex, `${filename}: animated proof is outside the demo section`);+ for (const demo of demos) {+ assert.match(readme, new RegExp(`docs/assets/${demo.asset.replaceAll('.', '\\.')}`));+ assert.ok(readme.includes(demo.link), `${filename}: missing ${demo.link}`);+ }+ }+});++test('README stays scannable without deleting the visual proof set', () => {+ const commonAssets = [+ 'archify-readme-hero.png',+ 'archify-live-proof.gif',+ 'archify-demo-story.png',+ 'archify-demo-route.png',+ 'archify-demo-lens.png',+ 'archify-dark.png',+ 'archify-light.png',+ 'archify-menu.png',+ 'archify-workflow.png',+ 'archify-sequence.png',+ 'archify-dataflow.png',+ 'archify-lifecycle.png',+ ];++ for (const filename of ['README.md', 'README_EN.md', 'README_ZH.md']) {+ const readme = fs.readFileSync(path.join(repoRoot, filename), 'utf8');+ assert.ok(readme.split('\n').length <= 280, `${filename}: README grew beyond the scannable line budget`);+ for (const asset of commonAssets) {+ assert.ok(readme.includes(`docs/assets/${asset}`), `${filename}: visual proof ${asset} was removed`);+ }+ }++ const english = fs.readFileSync(path.join(repoRoot, 'README.md'), 'utf8');+ const wordCount = english.trim().split(/\s+/).length;+ const intro = english.slice(0, english.indexOf('![License]'));+ const introBullets = intro.match(/^- \*\*/gm) || [];+ assert.ok(wordCount <= 2000, `README.md is too verbose again (${wordCount} words)`);+ assert.ok(introBullets.length <= 8, `README.md has too many top-level capability bullets (${introBullets.length})`);++ const chinese = fs.readFileSync(path.join(repoRoot, 'README_ZH.md'), 'utf8');+ assert.ok(chinese.includes('docs/assets/claude-skills-settings.png'), 'README_ZH.md lost the Claude Skills setup image');+});diff --git a/docs/assets/archify-demo-lens.png b/docs/assets/archify-demo-lens.pngnew file mode 100644index 00000000..e69bfbe3Binary files /dev/null and b/docs/assets/archify-demo-lens.png differdiff --git a/docs/assets/archify-demo-route.png b/docs/assets/archify-demo-route.pngnew file mode 100644index 00000000..412bd28fBinary files /dev/null and b/docs/assets/archify-demo-route.png differdiff --git a/docs/assets/archify-demo-story.png b/docs/assets/archify-demo-story.pngnew file mode 100644index 00000000..96cf9f40Binary files /dev/null and b/docs/assets/archify-demo-story.png differ