ArcKit: Interactive Diagram Rendering
You render ArcKit's governed artefacts as interactive, self-contained HTML — a single file with inline SVG, dark/light themes, pan/zoom and dependency tracing, that opens offline with no external requests.
Two engines sit behind this one command:
| Requested type | Engine | Availability |
|---|---|---|
architecture, workflow, sequence, dataflow, lifecycle |
Archify (third party, MIT) | Only when the user has installed it |
wardley |
ArcKit's own renderer (scripts/owm-to-html.mjs) |
Always — ships with the plugin |
ArcKit does not bundle Archify. It is an independently maintained skill (https://github.com/tt-a1i/archify, MIT, by tt-a1i). This command detects it, uses it when present, and degrades honestly when it is not. Never claim a diagram was rendered by Archify unless its CLI actually exited zero.
User Input
$ARGUMENTS
Step 1: Route on the requested type
Parse $ARGUMENTS for a diagram type and a subject.
- If the type is
wardley(or the subject names a WARD artefact / Wardley Map), go to Step 5. Archify is not involved and not required. - Otherwise continue to Step 2.
- If no type is given, infer one from the subject and say what you inferred. Default to
architecture.
Step 2: Detect Archify
Run the bundled detector:
node .arckit/scripts/archify-detect.mjs --json
It searches $ARCKIT_ARCHIFY_HOME, then project-local skill directories, then
each runtime's global skill directory. Exit code 0 means found, 1 means absent.
If found is false, stop and tell the user plainly:
Archify is not installed, so I can't render an interactive {type} diagram.
Install it (one-off, ~7.5MB, MIT licensed, third party):
npx skills add tt-a1i/archify -g
Or point ArcKit at an existing checkout:
export ARCKIT_ARCHIFY_HOME=/path/to/archify
In the meantime I can run /skill:arckit-diagram to produce the Mermaid or
PlantUML C4 version of the same diagram, which needs no extra install.
Then offer to run /skill:arckit-diagram instead. Do not attempt to install
Archify yourself, and do not fabricate an interactive artefact by hand — a
hand-written HTML file is not an Archify render and must never be presented as
one.
If found is true, note root, version and cli from the JSON and
continue. Confirm the requested type appears in the reported types array.
Step 3: Gather the governed source material
Note: The ArcKit Project Context hook has already detected projects, artefacts, external documents and global policies. Use that context — do not scan directories manually.
Read what the requested type needs, and use the artefacts as the facts of record. The diagram must depict what ArcKit's artefacts actually say, not a plausible generic architecture.
| Type | Read | Extract |
|---|---|---|
architecture |
Vendor HLD, DIAG, REQ, PRIN | Containers, technology choices, boundaries, external systems |
workflow |
SOW, PLAN, PROC, delivery artefacts | Stages, approval gates, decision points, owners |
sequence |
Vendor DLD, INT requirements, API contracts | Participants, ordered messages, returns, async hops |
dataflow |
DFD, DATA (data model), DPIA | Sources, transformations, stores, consumers, PII flows |
lifecycle |
REQ (status fields), DATA, ADRs | States, transitions, retries, terminal and failure states |
Also read any external documents in external/ and enterprise standards in
projects/000-global/external/. When a diagram element comes from an external
source, follow .arckit/references/citation-instructions.md and
record the citation in the governed artefact you write in Step 7 — the HTML
itself carries no citation markers.
If there is nothing to depict, say so and stop. Do not invent an architecture.
Step 4: Author, validate and deliver through Archify
Follow Archify's own authoring contract; it is the authority on its schema, not
this command. Read <root>/schemas/<type>.schema.json, <root>/schemas/common.schema.json
and one matching example under <root>/examples/ before writing anything.
Write the candidate first. Save the IR to
projects/{project-dir}/diagrams/.archify/ARC-{PROJECT_ID}-DIAG-{NUM}.{type}.json. Use the Write tool. Start with one clear main path, at most 12 primary nodes, automatic routes, andmeta.quality_profile: "showcase".Validate:
node <cli> validate <type> <candidate.json> --quality showcase --jsonA showcase pass reports 9 artefact checks, 0 errors, 0 warnings. A receipt showing only 4 checks is basic validation, not showcase acceptance.
Repair from the diagnostics, not by guessing. Each diagnostic names a
subject,evidenceand often a literal suggested fix (labelAt [615, 322]). Apply the diagnosed change only. Continue while the error count reaches a new minimum; if two consecutive rounds do not improve it, stop and report the remaining diagnostics truthfully rather than deleting semantic labels to force a pass.Deliver once, as final acceptance:
node <cli> deliver <type> <candidate.json> projects/{project-dir}/diagrams/ARC-{PROJECT_ID}-DIAG-{NUM}.html --quality showcase --jsonA non-zero exit is never success. Record the returned
artifact.sha256andvalidation.checksPassed— they go in the governed artefact.
Then go to Step 6.
Step 5: Render a Wardley Map (no Archify required)
ArcKit renders Wardley Maps itself, because Archify has no Wardley diagram type and a Wardley Map's continuous evolution/value-chain plane does not fit its node-graph IR.
Locate the source. Prefer an existing WARD artefact in
projects/{project-dir}/wardley-maps/. Extract the OnlineWardleyMaps code block (the```wardleyfence) into a temp file:cat > /tmp/arckit-wardley-render.owm <<'OWM' {the OWM block, verbatim} OWMIf no WARD artefact exists, stop and offer
/skill:arckit-wardleyto create one. Do not invent a map.Render:
node .arckit/scripts/owm-to-html.mjs /tmp/arckit-wardley-render.owm \ projects/{project-dir}/wardley-maps/ARC-{PROJECT_ID}-WARD-{NUM}-v{VERSION}.html \ --title "{Map Title}" --jsonThe JSON receipt reports
components,links,annotationsand anywarnings. Warnings matter: a warning naming an unknown component means the OWM source has a typo — a dependency pointing at a component that was never declared. Fix the WARD artefact's OWM block, do not silence it.The output is self-contained: no network requests, safe for OFFICIAL-SENSITIVE work and air-gapped review, and it embeds the OWM source so the map round-trips. It does not replace the OWM code block in the WARD artefact — that block stays canonical.
Then continue to Step 6.
Step 6: Verify the artefact opens
Confirm the delivered file exists and is non-empty:
ls -l <output.html> && head -c 120 <output.html>
If Archify was used and the user wants browser evidence, node <cli> visual-check <output.html> --json
collects it from the exact delivered file. Report its measurements as browser
evidence only — it does not establish perceptual quality, and neither does an
unaided glance at the markup. Keep those claims separate and do not overstate
either.
Step 7: Write the governed artefact
The HTML is a rendering; the governed record is a markdown artefact.
Use .arckit/scripts/generate-document-id.mjs --next-num for the
sequence number, and write to
projects/{project-dir}/diagrams/ARC-{PROJECT_ID}-DIAG-{NUM}-v1.0.md
(Wardley renders live alongside their existing WARD artefact instead — update
that artefact's Document Control Last Modified and note the render, rather
than creating a DIAG).
Read the template first — check .arckit/templates-custom/ for an override,
then fall back to the shipped default:
cat .arckit/templates/architecture-diagram-template.md
Populate its Document Control block in full (Document ID, Classification, Status, Owner, Review Cycle, Next Review Date), then add a Rendering section recording:
- Engine and version (
Archify 2.17.0/ArcKit owm-to-html) - Source IR or OWM path
- Delivered HTML path
artifact.sha256and checks passed, when Archify delivered it- Source artefacts the diagram depicts, with citation markers for external ones
Step 8: Summarise
✅ Interactive Diagram Delivered: {type} — {subject}
📁 HTML: {output.html}
📁 Source: {candidate.json or .owm}
📁 Governed: projects/{project}/diagrams/ARC-{PROJECT_ID}-DIAG-{NUM}-v1.0.md
🔧 Engine: {Archify {version} | ArcKit owm-to-html}
✅ Validation: {9/9 checks, 0 errors, 0 warnings | N components, N dependencies}
🔐 SHA-256: {artifact.sha256, when Archify delivered}
🖥️ Open it: open the HTML file directly — it needs no server and makes no
external requests.
⚠️ {Any unresolved diagnostics or parser warnings, stated plainly}
🎯 Next Steps:
- /skill:arckit-pages — publish the render into the documentation site
- /skill:arckit-diagram — Mermaid/PlantUML companion for the same subject
Remember: Archify is third-party software the user installed, not part of ArcKit. Attribute it, never vendor it, and never claim its validation passed when it did not.
Suggested Next Steps
After completing this command, consider running:
/skill:arckit-diagram-- Produce the Mermaid/PlantUML companion for the same subject/skill:arckit-pages-- Publish the delivered HTML into the documentation site/skill:arckit-hld-review-- Review the High Level Design the diagram depicts/skill:arckit-wardley-- Create or update the Wardley Map this command renders (when Wardley render requested but no WARD artefact exists)