Archify

Create an interactive HTML diagram from typed JSON. Static output is the default; enable motion only when requested.

Run commands from your working directory. Unless the user names another location, give each new diagram request its own folder .archify/<type>-<slug>-<YYYYMMDD-HHMMSS>/ there (local time, chosen once when the request starts): keep candidate.json and <slug>.html in it, set meta.output to that relative HTML path, and reuse the folder for every repair rerun. A later request gets a new folder, so earlier versions stay intact. Replace bin/archify.mjs in the commands below with the installed package's absolute path, or its path relative to your working directory; input and output paths resolve from that working directory.

For a real codebase, read Repository authoring while tracing the requested behavior. A system description uses the steps below; an existing JSON uses the handoff path.

Local adaptation notes

This section is not upstream; see PROVENANCE.md. Apply it before the first command.

• Host conventions win. If the repository requires editable diagrams (for example draw.io) or a specific output folder, follow that rule; Archify HTML supplements it and never replaces a required editable source or image.
• Node on Windows. Run this probe once per machine: node -e "const f=require('fs'),o=require('os'),p=require('path');const d=f.mkdtempSync(p.join(o.tmpdir(),'archify-probe-'));try{const x=p.join(d,'f');f.writeFileSync(x,'');const h=f.openSync(x,'r');console.log(f.lstatSync(x).dev===f.fstatSync(h).dev);f.closeSync(h)}finally{f.rmSync(d,{recursive:true})}". If it prints false, or finalize fails before any gate with finalize-receipt-changed-during-inspection, that Node build reports a path dev of 0, which Archify's file-identity checks reject. Observed on Node 22.14.0 and 22.15.0; Node 20.19.6 passed all four gates. Run the same commands with a Node 18–20 executable by absolute path instead of switching the global Node version.
• Browser. browser-check finds Chrome or Chromium only. When neither is installed, set ARCHIFY_CHROME to a Chromium-based browser executable; Microsoft Edge through this variable is untested.
• Network. finalize and deliver fetch the upstream update manifest. Set ARCHIFY_UPDATE_CHECK_DISABLED=1 when the task must stay offline. Never update this copy in place; re-import it as described in PROVENANCE.md.
• Evidence hygiene. JSON sidecars (*.finalize.json, *.finalize-summary.json, *.delivery.json, *.delivery-pending.json, *.browser-check.json, *.visual-check.json, *.receipt.json, and any custom --receipt <name>.json path plus its derived <name>-summary.json) and captured command output contain absolute local paths and the OS user name. Put custom receipts inside the .archify/ folder, add that folder and these sidecar patterns to the host repository's ignore file, keep all of them out of commits and shared material, and report the gate summary instead.

Existing candidate handoff