axstack 0.23.0 → 0.24.1

package/README.md

@@ -29,6 +29,9 @@ coordination. You can start at the phase you need.
 | Operate | [axstack-relay](skills/axstack-relay/SKILL.md) | Send an explicit message or authorized notification. |
 | Understand | [axstack-research](skills/axstack-research/SKILL.md) | Answer one bounded question with sources. |
 | Understand | [axstack-explain](skills/axstack-explain/SKILL.md) | Explain a system and separate known behavior from gaps. |
+| Understand | [axstack-diagram](skills/axstack-diagram/SKILL.md) | Draw Mermaid diagrams or verified interactive archify viewers. |
+
+Interactive viewers use [archify](https://github.com/tt-a1i/archify) (MIT).
 
 Small, bounded changes can begin with your request or an existing issue;
 substantial work needs an approved spec and matching tickets before

package/bin/axstack.js

@@ -13,7 +13,7 @@ import {
   uninstallBundle,
   validateBundle,
 } from '../src/installer.js';
-import { BUN_FLOOR, checkCapabilities, meetsFloor, runRealCheck } from '../src/capabilities.js';
+import { BUN_FLOOR, checkArchify, checkCapabilities, meetsFloor, runRealCheck } from '../src/capabilities.js';
 import { findLegacyRoutingLines } from '../src/instructions.js';
 import { harnessLocations } from '../src/locations.js';
 
@@ -43,7 +43,7 @@ function packageVersion() {
 const HELP = `axstack — Axstack setup CLI (installation bookkeeping only)
 
 Usage:
-  axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
+  axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--tools-dir <dir>] [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
   axstack check [--bundle <dir>] [--instructions <file>] [--skills-dir <dir>|--harness <name>]
   axstack uninstall --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
   axstack --help | --version
@@ -62,6 +62,8 @@ Flags:
                       Aliases: codex = codex-only; claude = claude-only.
   --skills-dir <dir>  Explicit install target. Overrides harness skill defaults
                       and automatic legacy Codex skill retirement.
+  --tools-dir <dir>   Pinned archify copies. Defaults to ~/.axstack/tools.
+                      Must be outside skills roots and contain no symlink path.
   --instructions <file>
                       Instruction file to receive the owned routing block.
                       Harness defaults: ~/.claude/CLAUDE.md for Claude,
@@ -105,7 +107,7 @@ function parseArgs(argv) {
   }
   out.command = rest.shift();
   const wantsValue = new Set([
-    '--bundle', '--skills-dir', '--instructions', '--harness', '--preset', '--claude-settings',
+    '--bundle', '--skills-dir', '--tools-dir', '--instructions', '--harness', '--preset', '--claude-settings',
   ]);
   while (rest.length > 0) {
     const tok = rest.shift();
@@ -300,6 +302,7 @@ async function main() {
         bundleDir: flags.bundle ? resolve(flags.bundle) : PACKAGE_ROOT,
         skillsDir,
         preset: flags.preset,
+        toolsDir: flags['tools-dir'] ? expandHome(flags['tools-dir']) : undefined,
         instructionsPath,
         inheritedInstructions: legacyCodexManifest?.instructions,
         force: !!flags.force,
@@ -399,6 +402,18 @@ async function main() {
     }
     if (command === 'check') {
       const report = await checkCapabilities(runRealCheck);
+      const toolSkillsDir = flags['skills-dir'] ? expandHome(flags['skills-dir']) :
+        flags.harness ? resolveHarnessTarget(flags.harness) : null;
+      if (toolSkillsDir) {
+        const tool = await checkArchify(toolSkillsDir);
+        console.log(`archify record: ${tool.recordFile}`);
+        if (tool.record) console.log(`archify copy: ${tool.record.path}; recorded SHA: ${tool.record.sha}; checked-out SHA: ${tool.actual ?? 'unavailable'}`);
+        if (tool.reason) {
+          console.log(`archify: ${tool.reason}`);
+          report.gaps.push(`archify: ${tool.reason}`);
+        }
+        console.log(tool.chrome ? `Chrome: ${tool.chrome}` : 'WARN Chrome: unavailable (viewer verification needs Chrome)');
+      }
       if (flags.bundle) {
         const bundle = await validateBundle(resolve(flags.bundle));
         const presetNames = Object.keys(bundle.presets);

package/docs/installation.md

@@ -8,8 +8,10 @@ workflow database.
 Requirements: Bun >=1.3.14, Git, `gh`, the `gh stack` extension, and a running
 T3 Code `0.0.46-nightly.20261003.2610` or newer. The driver is a T3 thread
 with the `t3-code` MCP. See the [T3 runtime boundary](../skills/axstack/references/t3-runtime.md).
-There are no runtime dependencies. Filesystem access uses Bun-backed `node:fs`
-and `node:fs/promises`; no other Node runtime contract is introduced.
+Axstack has no runtime package dependencies. Filesystem access uses Bun-backed
+`node:fs` and `node:fs/promises`. The pinned archify tool is the sole external-tool
+exception: installation uses Git and the network, and Bun runs its Node-oriented
+code. This exception introduces no Node.js runtime requirement.
 
 ## T3 setup
 
@@ -45,7 +47,7 @@ and its configured home channel under recorded notification authority.
 ### Install
 
 ```text
-axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
+axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-dir <dir> [--tools-dir <dir>] [--instructions <file>] [--claude-settings <file>|--no-claude-settings] [--harness <name>] [--force] [--yes]
 ```
 
 - `--preset` is required. `codex` and `claude` are aliases for the canonical
@@ -56,6 +58,9 @@ axstack install --preset <mixed|codex-only|claude-only> --bundle <dir> --skills-
 - `--skills-dir` is required unless a verified harness default resolves it.
   Codex defaults to the shared `~/.agents/skills` root; an explicit override
   remains authoritative and disables automatic legacy Codex-root retirement.
+- `--tools-dir` defaults to `~/.axstack/tools`. It must not overlap a skills
+  root or pass through a symlink. Home writes require `--yes`, including the
+  default tools directory.
 - `--instructions` selects the instruction file that receives Axstack's owned
   marker block. `--harness claude` defaults to `~/.claude/CLAUDE.md`;
   `--harness codex` defaults to `$CODEX_HOME/AGENTS.md` or `~/.codex/AGENTS.md`;
@@ -90,6 +95,16 @@ the settings sidecar preserves the value while any other install still owns it.
 - `--yes` confirms writes under the user's home directory. Tests use temporary
   homes and fixtures only.
 
+Installation sparse-clones archify at the reviewed full SHA in `src/archify-pin.js`
+into `<tools-dir>/archify-<sha>`. It verifies HEAD before use and keeps the
+payload's licence and third-party notices. The manifest owns
+`<skills-dir>/axstack-diagram/archify.json`, which records `{path, sha}`.
+The adjacent `<tools-dir>/archify-<sha>.owners.json` lists its skills-root owners.
+Multiple roots share one copy. Repeat installs leave unchanged files untouched.
+An offline, Git-less, or failed clone still installs the skills, reports
+`archify: unavailable (<reason>)`, and exits 0. An existing SHA mismatch fails.
+Tests use a local repository through `AXSTACK_ARCHIFY_REPO` and never use the network.
+
 ## Role presets
 
 The selected bundle input is one of:
@@ -121,6 +136,13 @@ owned, missing, unowned, edited, or bound to a different path. Hand-written
 legacy routing outside the owned block is reported for manual migration and
 preserved byte for byte.
 
+With `--skills-dir` or `--harness`, check reports the archify record path, copy
+path, recorded SHA, and checked-out SHA. A missing record, missing copy, or SHA
+mismatch fails the check. Chrome absence prints a warning and does not fail it.
+`ARCHIFY_CHROME` selects the Chrome executable. Without it, check looks for
+common Chrome and Chromium executables on PATH. A check without a skills target
+probes host capabilities only.
+
 A successful check is not provider/model availability, effective permission,
 skill reload, task execution, mobile delivery, or end-to-end compatibility
 proof. Those require their own runtime receipts.
@@ -135,6 +157,15 @@ Uninstall removes only unchanged Axstack-owned files whose current bytes match
 the manifest. Edited, custom, unknown, and unrelated files survive. Directories
 are pruned only when empty, and the target root is never removed.
 
+Uninstall drops that skills root from archify's owners file. It removes the copy
+only when no owners remain, HEAD matches the recorded SHA, and
+`git status --porcelain --ignored` is empty. Otherwise it keeps the copy and
+reports why, even with `--force`. A pin bump or a changed `--tools-dir` releases
+the old copy through the same guard. Installation clones into a temporary sibling
+and renames it into place. A later owner or manifest write failure restores
+ownership and removes only a copy created by that installation. Older manifests
+without an archify record still load.
+
 ## Owned instruction block
 
 The deterministic `<!-- axstack:begin v1 -->` / `<!-- axstack:end -->` block
@@ -323,8 +354,8 @@ need separate authority and verified backups.
 ## Examples
 
 ```sh
-axstack install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
-axstack install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
+axstack install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --tools-dir /tmp/ax-tools --instructions /tmp/AGENTS.md
+axstack install --preset mixed --bundle ./bundle --skills-dir /tmp/ax-skills --tools-dir /tmp/ax-tools --instructions /tmp/AGENTS.md
 axstack check --bundle ./bundle --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
 axstack uninstall --skills-dir /tmp/ax-skills --instructions /tmp/AGENTS.md
 ```

package/docs/workflows.md

@@ -22,6 +22,11 @@ Direct routes need no spec ceremony:
   Only the user invokes it.
 - `axstack-explain` separates implemented, intended, tested, live, and unknown
   behavior; complex visuals receive exact-artifact QA where applicable.
+- [axstack-diagram](../skills/axstack-diagram/SKILL.md) selects Mermaid for chat,
+  GitHub, and docs, or an interactive viewer for required complex visuals.
+  Explain loads it for every diagram. Viewers use
+  [archify](https://github.com/tt-a1i/archify) (MIT) with a pinned tool,
+  a passing finalize receipt, rendered QA, and node-and-edge source review.
 - `axstack-improve` returns a small ranked set of evidenced improvement
   candidates without editing code. Its test-audit lens marks every declaration
   in one owner boundary R/F/C/D, reports reviewed and eligible counts, and routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks T3 Code capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/references/automations.md

@@ -34,7 +34,7 @@ T3 sessions are exempt from Claude trust preflight.
 
 ## Session admission
 
-Perform guarded predecessor retirement in [Finite-session teardown](#finite-session-teardown).
+The owner-of-record performs guarded retirement in [Finite-session teardown](#finite-session-teardown).
 Lane identity requires exact thread/run identity, never a title or directory-name
 guess; never infer lane ownership from an empty local workspace.
 Reconcile saved state, current GitHub state, and native T3 threads, runs,
@@ -54,8 +54,36 @@ events and the unserved count. If a duplicate finds a stalled owner idle at its
 prompt with a final turn lacking a completion receipt for more than five
 minutes (nudged or not), record it in that private note and send one deduplicated
 notification under the recorded `Notification policy`.
-Unknown liveness blocks admission and shared-record writes; it does not
-permit takeover or cleanup. Preserve user-taken-over threads.
+A **wedged lane pass**, whether owner, successor or duplicate, has a non-terminal
+run with more than 60 minutes of verified inactivity across its thread, all its
+runs, delegated tasks and descendant threads, and is free of `user_takeover`.
+A user-taken-over descendant holds recovery and excludes its pass from the
+wedged category, and is never interrupted.
+A live pass has a non-terminal run and is not wedged.
+Exactly one successor recovers a wedged owner or resumes an interrupted takeover:
+the earliest-started live pass, selected by native run start
+ordering; missing or tied ordering evidence holds admission and recovery.
+The successor interrupts the owner and its descendant threads with
+`t3_thread_interrupt`, naming each exact `runId` and a stable `clientRequestId`
+per run, and reads back terminal state for the whole tree
+before recording the takeover in continuity and becoming owner.
+If a successor wedges between interrupt and takeover, the next elected live pass
+interrupts the wedged successor and its tree with `t3_thread_interrupt` at each
+exact `runId` using the same per-run procedure, and reads back terminal state for
+that whole tree before recording any takeover, then resumes recovery from terminal readback
+of the interrupted owner, which is
+excluded from the potentially-live-owner hold.
+The owner-of-record, including a successor immediately after takeover, interrupts
+wedged non-owner passes (duplicates or failed successors) using the same exact-run
+procedure and terminal readback, then retires them under Finite-session teardown.
+Before any admission, the successor reconciles the previous owner's in-flight
+jobs from GitHub and evidence. Only a verdict already published and read back
+counts as served. Otherwise the event is unserved/`INCOMPLETE` and re-eligible.
+A failed interrupt or unverified terminal state keeps the existing hold plus
+one deduplicated notification under the recorded `Notification policy`.
+Outside the wedged-pass recovery above, unknown liveness blocks admission,
+shared-record writes, takeover and cleanup, including when activity is recent.
+Preserve user-taken-over threads.
 This is prompt policy, not an atomic lock: the overlap canary must demonstrate
 one admission owner before activation. Count all unsettled PR jobs and descendants.
 
@@ -132,7 +160,9 @@ under [T3 runtime](t3-runtime.md). For a worker's own brief question, confirm th
 brief once.
 A second brief ask follows the five-minute stop rule, never an open-ended hold.
 An idle final turn without a valid completion
-receipt is incomplete, not successful. A started coordinator waiting on its
+receipt is incomplete, not successful. A wait with more than 60 minutes of
+verified inactivity across its whole tree is a wedge, not a running wait.
+A started coordinator waiting on its
 reviewers (a live reviewer task or running wait) is not idle and is never
 stopped for waiting. Reconcile terminal failure and all descendants before
 recording an event unserved and re-admissible.
@@ -260,16 +290,21 @@ or separate model gate.
 
 ## Finite-session teardown
 
-Each pass retires settled predecessor passes and reports the retained worktree
-count. Retirement requires terminal run evidence and settled descendants,
+Only the owner-of-record pass retires settled predecessor passes and qualifying
+terminal duplicates, including duplicates newer than the owner and immediately
+after successor takeover.
+Qualifying duplicates have a terminal run, no descendants and only their own pass note.
+Each pass reports the retained worktree count.
+Retirement requires terminal run evidence and settled descendants,
 durable continuity, evidence read-back and verified salvage where needed;
 follow [Workspace hygiene](workspace-hygiene.md) and [T3 runtime](t3-runtime.md).
 Then run the driver-start orphan sweep under Workspace hygiene; the sweep is
 silent when nothing was removed. Record sweep results and holds in continuity's
 Open holds table.
 The orphan sweep covers the run record's repositories plus registered repositories on this host.
-`t3_thread_organize` settle/archive changes metadata only; exact guarded Git
-worktree removal remains separate. Unknown, active or user-taken-over threads,
+Retirement settles duplicate threads with `t3_thread_organize` (settle/archive
+changes metadata only) before separate guarded Git worktree removal.
+Unknown, active or user-taken-over threads,
 ambiguous publication and failed salvage stay preserved.
 
 A review-manager pass may retire a predecessor pass's local `t3code/*` branch
@@ -295,7 +330,8 @@ removal, not settled execution capacity. The next pass retires this settled pass
 
 The canary runs two overlapping `run_scheduled_task_now` passes and proves one
 admission owner per PR. The canary reviews or correctly no-ops one real PR event.
-The canary reconciles a killed predecessor.
+The canary reconciles a killed predecessor and demonstrates wedged-pass recovery:
+exactly one successor interrupts and retires a wedged predecessor.
 With a temporary limit equal to the current count, the canary disables the
 schedule and verifies that the following interval creates zero new pass worktrees.
 The previous review-manager automation is disabled, never deleted, only after all four T3 canary checks pass.

package/skills/axstack/references/ui-verification.md

@@ -5,6 +5,12 @@ browser" step, goes through async `delegate_task` to `axstack-ui-verifier` from
 run's role snapshot. Give it the exact build, URL, or artifact and the private
 dispatch's evidence folder. The verifier is read-only: it never edits source.
 The PR writer remains the sole writer.
+
+The sole author browser exception is archify `finalize` as a headless build gate.
+Keep finalize outputs only in the private evidence folder.
+Never replace the verifier's rendered pass with finalize.
+All other browser checks remain delegated to `axstack-ui-verifier`.
+
 Read the [T3 runtime boundary](t3-runtime.md) before dispatch and use its
 driver-made disposable detached checkout at the pinned candidate SHA.
 The verifier uses T3 `preview_*` tools for rendered checks.

package/skills/axstack-diagram/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: axstack-diagram
+description: When an explanation needs a diagram, use axstack-diagram to choose Mermaid or a pinned archify viewer with source fidelity and rendered QA.
+---
+
+# Diagram
+
+Usage: `/axstack-diagram <question + destination>` or load this skill from explain.
+Load [Standing contracts](../axstack/references/contracts.md) before acting.
+Follow [Fidelity](references/fidelity.md) for every format.
+
+Use archify HTML for an explicit viewer request or explain's complex-visual path.
+For the viewer, follow [Archify](references/archify.md).
+Otherwise use Mermaid for chat, GitHub, or docs.
+Include `accTitle` and `accDescr` in each Mermaid view.
+Never use theme init in Mermaid.
+Split large Mermaid diagrams into views.
+T3 chat renders the Mermaid fence once the reply settles.
+
+Explain owns evidence, claim labels, the word cap, dispatch, and delivery.
+Diagram owns format and visual rules.
+Never call explain.
+For direct use, keep fidelity and rendered QA.
+
+Ideas: [archify](https://github.com/tt-a1i/archify), [diagram-design](https://github.com/cathrynlavery/diagram-design), [visual-explainer](https://github.com/nicobailon/visual-explainer), [Matt Pocock](https://github.com/mattpocock/skills), and [poteto](https://github.com/poteto/how); guidance uses Axstack's own words.

package/skills/axstack-diagram/references/archify.md

@@ -0,0 +1,76 @@
+# Archify
+
+Archify turns a typed JSON intermediate representation (IR) into an HTML viewer.
+Follow [Fidelity](fidelity.md) before authoring.
+
+## Bind the tool
+
+Read `archify.json` beside the skill entrypoint for its `{path, sha}` record.
+Verify that `git -C <path> rev-parse HEAD` equals the recorded SHA.
+If the record or copy is missing, HEAD mismatches the recorded SHA, or Chrome is missing, hold and ask the user.
+Honor `ARCHIFY_CHROME` when set.
+Otherwise find Chrome or Chromium on `PATH`.
+Set `ARCHIFY_UPDATE_CHECK_DISABLED=1` on every archify call.
+Never substitute Mermaid or unverified HTML when the viewer is required.
+
+## Author the IR
+
+If the pinned archify procedure conflicts with this file, this file takes precedence.
+Read `<path>/archify/SKILL.md` and follow its named references for IR authoring and repair.
+Run the referenced archify commands with Bun.
+
+Set `meta.title` and a portable relative HTML filename in `meta.output`.
+Use `meta.quality_profile: "showcase"`.
+Set `meta.animation: "none"`.
+Keep trace motion, exports, share cards, and brand marks off unless the user asks.
+Deliver the viewer with `?theme=dark` unless the user names a theme.
+Theme is viewer state rather than an IR field; without the query, localStorage and `prefers-color-scheme` determine it.
+Preserve explain's claim labels in `meta.subtitle` or the companion explanation.
+Set `meta.repository` to the inspected repository URL and full `revision`.
+Keep per-node source pins in each node's `sources` entries for inspected paths and line ranges.
+Keep the private source map for relationships that have no source field.
+Keep proposed sources distinct from factual pins.
+Use [Fidelity](fidelity.md) for visible planned and unknown markers.
+For a separate check, run `bun <path>/archify/bin/archify.mjs validate <type> <ir.json> --json --repo-root <repo>`.
+When sources are declared, require `--repo-root <repo>` on both `validate` and `finalize`.
+For sequence and dataflow, a schema-valid legend cue is `meta.legend.entries.dashed: {"label":"Planned or unknown"}`.
+
+Use one top-level `cards[]` entry with `{dot, title, items[]}` per key node as its node detail card.
+Each node detail card has at most 40 words and cites its source.
+Count the title plus all items toward each card's 40-word cap.
+Cite each card's source inline as `file:lines` in its `items[]`.
+Node detail cards are exempt from explain's 700-word cap.
+Count node labels, headings, captions, and all non-card text.
+
+## Build and hold
+
+Write the IR, HTML, and receipt only inside the private evidence folder.
+For direct invocation, create a private run evidence folder first.
+Override archify's default `.archify/` folder with an evidence output path and `--out-dir <evidence dir>`.
+Run `bun <path>/archify/bin/archify.mjs finalize <type> <ir.json> <out.html> --quality showcase --json --out-dir <evidence dir> --repo-root <repo>`.
+This is the author's headless build gate.
+Read the saved receipt named by the JSON result's `evidence.receipt`.
+Accept only receipt `status: "pass"` as success.
+Never trust exit codes as proof of a pass.
+When a receipt is missing or remains non-pass after two repair rounds, hold delivery and ask the user.
+If Chrome is missing, report "viewer not verified: Chrome missing".
+Chrome absence yields `status: "skipped"` and exit 2.
+Follow archify's receipt fixes and references for layout and composition repairs.
+After every repair edit, rerun the complete `finalize` command.
+Count one repair round as one complete `finalize` rerun after an edit.
+Validate runs never count as repair rounds.
+Do not require validate before finalize.
+Run at most two repair rounds, then hold with remaining defects for the user's decision.
+Never use archify's extra evidence-based retry.
+
+## Rendered and source checks
+
+Follow [UI verification](../../axstack/references/ui-verification.md) for dispatch.
+Keep `finalize` as the only author browser check.
+Delegate `visual-check`, browser opening, preview, and first-screen inspection to `axstack-ui-verifier`.
+Require `axstack-ui-verifier` checks of the receipt's `artifact.sha256` bytes on desktop, 390px mobile, keyboard, reduced motion, and the text alternative.
+Include theme, search or focus, and directional reach interactions.
+Require `axstack-ui-verifier` checks with the theme set explicitly.
+Require `explainer-review` of every node and edge against source for archify output.
+Every byte change requires fresh checks.
+Keep these independent verdicts with the build receipt before delivery.

package/skills/axstack-diagram/references/fidelity.md

@@ -0,0 +1,25 @@
+# Fidelity
+
+Map factual nodes and edges to an inspected source path at a recorded full revision.
+Drop unsupported factual elements.
+For uncommitted sources, use the content hash and mark their pins unknown.
+Keep the source map outside the reader view.
+Display the short SHA.
+
+Give planned and unknown nodes a visible marker in the node label and their card, if any.
+Use the literal marker `planned` or `unknown` for all five types.
+Give planned and unknown edges a visible `planned` or `unknown` marker in the edge label.
+For dashed styling, use only properties the pinned schema accepts and verify with `validate`.
+This is an extra cue, such as a dashed relationship where supported.
+The pinned node collections reject `variant`.
+Add a planned or unknown legend entry only for sequence and dataflow.
+Architecture, workflow, and lifecycle reject a `dashed` legend entry.
+In Mermaid, use the same visible markers and a dashed cue where its syntax permits.
+
+Treat about 9 core nodes as a signal to split.
+This is a design signal rather than a hard gate.
+Use 1–2 accent nodes.
+Keep labels short and name each relationship's direction and meaning.
+Provide a text alternative that describes nodes and edges.
+Never load network assets in the HTML.
+Write diagrams into repo docs only when the user asks.

package/skills/axstack-explain/SKILL.md

@@ -51,6 +51,10 @@ immediately before an actual profile dispatch.
 
 ## 2. Choose proportional output
 
+Load [Diagram](../axstack-diagram/SKILL.md) for every diagram.
+Explain owns evidence gathering, claim labels, the 700-word cap, dispatch, and delivery.
+Diagram never calls explain.
+
 1. Keep the primary reader-facing explanation to a maximum of 700 words in
    chat, HTML, and every other requested format. Preserve in that primary view
    the answer or purpose, key rationale, meaningful alternatives, main data or
@@ -63,11 +67,17 @@ immediately before an actual profile dispatch.
    maximum. If the draft is longer, compress repetition first and move only
    supporting detail to a separate linked ticket or appendix. Essential answers
    must not be hidden behind links, and evidence must not be silently discarded.
+   Only archify node detail cards are exempt from the 700-word cap.
+   Each card has at most 40 words and cites its source, as defined in
+   [Archify](../axstack-diagram/references/archify.md).
+   Count node labels, headings, captions, and all non-card text.
 2. For a simple request, answer concisely in the current chat. Use a compact
    diagram when useful. This needs no mandatory agent or intermediate artifact.
+   For simple chat answers, never dispatch an agent when applying its Mermaid rules inline.
 3. For a complex visual, use the configured `axstack-explainer` role to create
-   self-contained HTML, or use the requested artifact format. An explicit user
-   theme wins; otherwise use the dark default.
+   self-contained HTML through the archify path by default.
+   For a complex visual, honor an explicitly requested artifact format.
+   An explicit user theme wins; otherwise use the dark default.
 4. Profile IDs are presets, not availability proof. Before dispatch, follow the
    launch sequence and preserve the configured model, mode, and effort. Report
    an unavailable route; never substitute a model.
@@ -77,8 +87,9 @@ immediately before an actual profile dispatch.
 1. Any HTML explanation requires the full [visual QA
    checklist](references/visual-qa.md): actual desktop and mobile rendering,
    interaction, accessibility, and reduced-motion checks where relevant.
-2. Use the configured independent `axstack-explainer-review` role when
-   warranted, bound to the exact artifact identity. Any byte change invalidates
+2. For archify output, require the configured independent `axstack-explainer-review`;
+   for other artifacts, use it when warranted. Bind it to the exact artifact identity.
+   Any byte change invalidates
    that review and requires a fresh check. In `claude-only`, separate Sonnet
    author xhigh and reviewer high sessions are allowed for explanations as
    session independence only. This exception never permits same-model code

package/skills/axstack-explain/references/visual-qa.md

@@ -7,6 +7,8 @@ Browser and visual checks must run in the delegated `axstack-ui-verifier` in its
 
 1. Identify the final artifact bytes and theme. The explicit user theme wins;
    otherwise use the dark default.
+   For archify output, bind the `axstack-ui-verifier` pass to the finalize receipt's `artifact.sha256`.
+   For archify output, bind `axstack-explainer-review` to the same finalize receipt's `artifact.sha256`.
 2. Delegate the rendered pass through [UI verification](../../axstack/references/ui-verification.md).
    Record actual desktop and mobile observations, or name the missing layout
    check.
@@ -16,5 +18,6 @@ Browser and visual checks must run in the delegated `axstack-ui-verifier` in its
 4. The explainer reviewer checks text and source fidelity. Keep source
    correctness, tests, rendered behavior, independent review, and publication
    evidence separate.
+   For archify output, require `axstack-explainer-review` of every node and edge against source.
 5. Bind review to the exact artifact identity. Any byte change invalidates the
    affected approval and requires fresh QA and review.

package/src/archify-pin.js

@@ -0,0 +1,5 @@
+// Pin changes require a reviewed chore PR and an upstream smoke run.
+export const ARCHIFY_PIN = Object.freeze({
+  repo: 'https://github.com/tt-a1i/archify',
+  sha: '594f6087358610bd16e64e5602976020871b6bff',
+});

package/src/archify.js

@@ -0,0 +1,149 @@
+import { lstat, mkdir, mkdtemp, readFile, rename, rm } from 'node:fs/promises';
+import { join } from './posixpath.js';
+import { ARCHIFY_PIN } from './archify-pin.js';
+
+export const ARCHIFY_RECORD = 'axstack-diagram/archify.json';
+
+export function archifyGit(path, ...args) {
+  try {
+    const result = Bun.spawnSync(['git', ...(path ? ['-C', path] : []), ...args], {
+      stdout: 'pipe', stderr: 'pipe', timeout: 60000,
+      env: { ...Bun.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    if (result.exitCode !== 0) throw new Error(result.stderr.toString().trim() || `git exit ${result.exitCode}`);
+    return result.stdout.toString().trim();
+  } catch (err) {
+    throw new Error(`git: ${err.message}`);
+  }
+}
+
+function verifySha(record, actual) {
+  if (actual === record.sha) return;
+  const error = new Error(`archify SHA mismatch: expected ${record.sha}, got ${actual}`);
+  error.code = 'ARCHIFY_SHA_MISMATCH';
+  throw error;
+}
+
+async function ownersSnapshot(path) {
+  const st = await lstat(path).catch((err) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (st && (!st.isFile() || st.isSymbolicLink())) throw new Error(`unsafe archify owners file: ${path}`);
+  const bytes = st ? await readFile(path) : null;
+  const owners = bytes ? JSON.parse(bytes) : [];
+  if (!Array.isArray(owners) || owners.some((owner) => typeof owner !== 'string' || !owner.startsWith('/'))) {
+    throw new Error(`invalid archify owners file: ${path}`);
+  }
+  return { bytes, owners, mode: st ? st.mode & 0o777 : null };
+}
+
+// Drop ownership transactionally; defer destructive cleanup until the skills
+// manifest commits. A failed manifest write can then restore the owner list.
+export async function planArchifyRelease({ record, skillsRoot, writeAtomic, log }) {
+  const ownersFile = `${record.path}.owners.json`;
+  const before = await ownersSnapshot(ownersFile);
+  const remaining = before.owners.filter((owner) => owner !== skillsRoot);
+  if (!before.owners.includes(skillsRoot)) {
+    return { rollback: async () => {}, finish: async () => log(`archify: kept ${record.path} (owner is absent)`) };
+  }
+  try {
+    await writeAtomic(ownersFile, JSON.stringify(remaining) + '\n', { mode: 0o600 });
+  } catch (err) {
+    const current = await readFile(ownersFile);
+    if (!current.equals(before.bytes)) {
+      try { await writeAtomic(ownersFile, before.bytes, { mode: before.mode }); }
+      catch (restoreErr) { err.message += ` (archify owner restore failed: ${restoreErr.message})`; }
+    }
+    throw err;
+  }
+  return {
+    rollback: () => writeAtomic(ownersFile, before.bytes, { mode: before.mode }),
+    finish: async () => {
+      try {
+        if (remaining.length) throw new Error('other skills roots still own this copy');
+        const st = await lstat(record.path);
+        if (!st.isDirectory() || st.isSymbolicLink()) throw new Error('copy is not a real directory');
+        if (archifyGit(record.path, 'rev-parse', 'HEAD') !== record.sha) throw new Error('HEAD differs from the recorded SHA');
+        if (archifyGit(record.path, 'status', '--porcelain', '--ignored')) throw new Error('copy has tracked, untracked, or ignored changes');
+        await rm(record.path, { recursive: true });
+        await rm(ownersFile);
+        log(`archify: removed ${record.path}`);
+      } catch (err) {
+        log(`archify: kept ${record.path} (${err.message})`);
+      }
+    },
+  };
+}
+
+// The caller includes this transaction in the skills/manifest rollback.
+export async function provisionArchify({ toolsRoot, skillsRoot, writeAtomic, log }) {
+  if (!Bun.which('git')) {
+    log('archify: unavailable (git is not on PATH)');
+    return { record: null, rollback: async () => {} };
+  }
+  const record = { path: join(toolsRoot, `archify-${ARCHIFY_PIN.sha}`), sha: ARCHIFY_PIN.sha };
+  const ownersFile = `${record.path}.owners.json`;
+  const before = await ownersSnapshot(ownersFile);
+  let created = false;
+  let ownersWritten = false;
+  const rollback = async () => {
+    const errors = [];
+    if (ownersWritten) {
+      try {
+        if (before.bytes === null) await rm(ownersFile);
+        else await writeAtomic(ownersFile, before.bytes, { mode: before.mode });
+      } catch (err) { errors.push(`${ownersFile}: ${err.message}`); }
+    }
+    if (created) {
+      try { await rm(record.path, { recursive: true }); }
+      catch (err) { errors.push(`${record.path}: ${err.message}`); }
+    }
+    if (errors.length) throw new Error(`incomplete archify rollback: ${errors.join('; ')}`);
+  };
+  const existing = await lstat(record.path).catch((err) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (existing && (!existing.isDirectory() || existing.isSymbolicLink())) {
+    throw new Error(`unsafe archify copy: ${record.path}`);
+  }
+  if (existing) {
+    const actual = archifyGit(record.path, 'rev-parse', 'HEAD');
+    verifySha(record, actual);
+  } else {
+    let temp = null;
+    try {
+      await mkdir(toolsRoot, { recursive: true });
+      temp = await mkdtemp(join(toolsRoot, '.archify-'));
+      archifyGit(null, 'clone', '--filter=blob:none', '--no-checkout', '--', Bun.env.AXSTACK_ARCHIFY_REPO || ARCHIFY_PIN.repo, temp);
+      archifyGit(temp, 'sparse-checkout', 'set', '--no-cone', '/archify/');
+      archifyGit(temp, 'checkout', '--detach', record.sha);
+      const actual = archifyGit(temp, 'rev-parse', 'HEAD');
+      verifySha(record, actual);
+      await rename(temp, record.path);
+      temp = null;
+      created = true;
+    } catch (err) {
+      if (err.code === 'ARCHIFY_SHA_MISMATCH') throw err;
+      log(`archify: unavailable (${err.message.replace(/\s+/g, ' ').slice(0, 180)})`);
+      return { record: null, rollback: async () => {} };
+    } finally {
+      if (temp) await rm(temp, { recursive: true });
+    }
+  }
+  try {
+    if (!before.owners.includes(skillsRoot)) {
+      ownersWritten = true;
+      await writeAtomic(ownersFile, JSON.stringify([...before.owners, skillsRoot].sort()) + '\n', { mode: 0o600 });
+    }
+  } catch (err) {
+    const current = await readFile(ownersFile).catch(() => null);
+    ownersWritten = before.bytes === null ? current !== null : current?.equals(before.bytes) !== true;
+    try { await rollback(); }
+    catch (restoreErr) { err.message += ` (${restoreErr.message})`; }
+    throw err;
+  }
+  log(`archify: ${record.path} (${record.sha})`);
+  return { record, rollback };
+}

package/src/capabilities.js

@@ -1,4 +1,8 @@
 // Host capability checks. Injected execution keeps tests off live runtimes.
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from './posixpath.js';
+import { ARCHIFY_RECORD, archifyGit } from './archify.js';
+import { ARCHIFY_PIN } from './archify-pin.js';
 export const BUN_FLOOR = '1.3.14';
 export const T3_FLOOR = '0.0.46-nightly.20261003.2610';
 
@@ -106,3 +110,29 @@ export async function checkCapabilities(exec) {
   const gaps = checks.filter((c) => !c.ok).map((c) => `missing ${c.label}`);
   return { checks, gaps, limitations: [...PROBE_LIMITATIONS] };
 }
+
+export async function checkArchify(skillsDir) {
+  const recordFile = join(skillsDir, ARCHIFY_RECORD);
+  const override = Bun.env.ARCHIFY_CHROME;
+  const chrome = override ? Bun.which(override) :
+    ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'chrome']
+      .map((name) => Bun.which(name)).find(Boolean);
+  let record = null;
+  let actual = null;
+  let reason = null;
+  try {
+    if ((await lstat(recordFile)).isSymbolicLink()) throw new Error('record is a symlink');
+    record = JSON.parse(await readFile(recordFile, 'utf8'));
+    if (!record || typeof record.path !== 'string' || !record.path.startsWith('/') ||
+        !/^[a-f0-9]{40}$/.test(record.sha)) throw new Error('invalid record');
+    const copy = await lstat(record.path);
+    if (!copy.isDirectory() || copy.isSymbolicLink()) throw new Error('copy is not a real directory');
+    actual = archifyGit(record.path, 'rev-parse', 'HEAD');
+    if (actual !== record.sha || record.sha !== ARCHIFY_PIN.sha) {
+      throw new Error(`SHA mismatch: recorded ${record.sha}, checked-out ${actual}, expected ${ARCHIFY_PIN.sha}`);
+    }
+  } catch (err) {
+    reason = err.code === 'ENOENT' ? 'missing record or copy' : err.message;
+  }
+  return { recordFile, record, actual, chrome: chrome ?? null, reason };
+}

package/src/installer.js

@@ -38,6 +38,7 @@ import {
   writeManifest,
 } from './manifest.js';
 import { planInstallClaudeSettings, planUninstallClaudeSettings } from './claude-settings.js';
+import { ARCHIFY_RECORD, planArchifyRelease, provisionArchify } from './archify.js';
 import {
   applyInstructionPlan,
   findLegacyRoutingLines,
@@ -205,6 +206,15 @@ export function assertOutsideHome(target, { yes = false, kind = 'target' } = {})
   }
 }
 
+async function guardArchifyRecord(record, skillsRoot, yes) {
+  if (!record) return;
+  await assertNoSymlinksBelow('/', record.path);
+  if (withinRoot(record.path, skillsRoot) || withinRoot(skillsRoot, dirname(record.path))) {
+    throw new Error('recorded archify tools directory overlaps the skills root; refusing');
+  }
+  assertOutsideHome(record.path, { yes, kind: 'archify copy' });
+}
+
 // Validate the bundle directory and return its payload. Throws before any
 // target mutation on any problem.
 export async function validateBundle(bundleDir, selectedPreset = null) {
@@ -461,6 +471,7 @@ export async function installBundle({
   bundleDir,
   skillsDir,
   preset,
+  toolsDir = null,
   instructionsPath = null,
   inheritedInstructions = null,
   force = false,
@@ -479,6 +490,14 @@ export async function installBundle({
     ? await canonicalInstructionFile(instructionsPath)
     : null;
   assertOutsideHome(skillsRoot, { yes, kind: 'skills directory' });
+  const toolsPath = toolsDir ?? (homeDir() ? join(homeDir(), '.axstack', 'tools') : null);
+  if (!toolsPath) throw new Error('HOME is unavailable; pass --tools-dir explicitly');
+  await assertNoSymlinksBelow('/', resolve(toolsPath));
+  const toolsRoot = await canonicalTargetDir(toolsPath);
+  if (withinRoot(toolsRoot, skillsRoot) || withinRoot(skillsRoot, toolsRoot)) {
+    throw new Error('tools directory overlaps the skills root; refusing');
+  }
+  assertOutsideHome(toolsRoot, { yes, kind: 'tools directory' });
   if (instructionsFile) assertOutsideHome(instructionsFile, { yes, kind: 'instruction file' });
   const claudePlan = await planInstallClaudeSettings({ claude, skillsRoot });
   if (claudePlan.report.path) {
@@ -503,6 +522,7 @@ export async function installBundle({
     );
   }
   const ownedFiles = prevManifest.files ?? {};
+  await guardArchifyRecord(prevManifest.archify, skillsRoot, yes);
   const legacyProfiles = prevManifest.profiles;
   const legacyProfileNote = Object.keys(legacyProfiles?.entries ?? {}).length > 0
     ? 'legacy Paseo profile provenance retained inert; see legacy cleanup guidance in docs/installation.md'
@@ -545,6 +565,11 @@ export async function installBundle({
   // manifest entry resolves its destination, current bytes, and pristine
   // flag through the same guard before Phase 2 mutates anything.
   const desired = [];
+  const archifyTarget = await readOwnedTarget(skillsRoot, ARCHIFY_RECORD);
+  if (archifyTarget.current !== null &&
+      hashContent(archifyTarget.current) !== ownedFiles[ARCHIFY_RECORD]) {
+    throw new Error('archify record is edited or unowned; refusing to replace it');
+  }
   for (const { rel, abs, content: inlineContent } of bundle.files) {
     const { dest, current, mode } = await readOwnedTarget(skillsRoot, rel);
     const content = inlineContent ?? await readFile(abs);
@@ -562,6 +587,7 @@ export async function installBundle({
   }
 
   const bundleRels = new Set(bundle.files.map((file) => file.rel));
+  bundleRels.add(ARCHIFY_RECORD);
   const stalePlan = [];
   for (const rel of Object.keys(ownedFiles)) {
     if (bundleRels.has(rel)) continue;
@@ -591,8 +617,23 @@ export async function installBundle({
   const installedHashes = {};
   const claudeWritten = [];
   let instructionWritten = false;
+  let archify = null;
+  let archifyRelease = null;
+  const manifestFile = join(skillsRoot, '.axstack-manifest.json');
+  const manifestBefore = await readFile(manifestFile).catch((err) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  const manifestMode = manifestBefore === null ? null : (await stat(manifestFile)).mode & 0o777;
+  let manifestAttempted = false;
   log('plan complete');
   try {
+    archify = await provisionArchify({ toolsRoot, skillsRoot, writeAtomic, log });
+    const archifyRecord = archify.record ?? prevManifest.archify ?? null;
+    if (archifyRecord) {
+      desired.push({ rel: ARCHIFY_RECORD, ...archifyTarget,
+        content: Buffer.from(JSON.stringify(archifyRecord, null, 2) + '\n') });
+    }
     if (instructionsFile) {
       await assertFileSnapshot(instructionsFile, existingInstructionsRaw);
     }
@@ -709,6 +750,12 @@ export async function installBundle({
       )
       : null;
 
+    if (prevManifest.archify && archifyRecord?.path !== prevManifest.archify.path) {
+      archifyRelease = await planArchifyRelease({
+        record: prevManifest.archify, skillsRoot, writeAtomic, log,
+      });
+    }
+    manifestAttempted = true;
     await writeManifest(skillsRoot, {
       version: MANIFEST_VERSION,
       files: installedHashes,
@@ -717,7 +764,9 @@ export async function installBundle({
         path: claudePlan.settingsPath ?? boundClaudeSettingsPath,
       },
       instructions: nextInstructions,
+      archify: archifyRecord,
     });
+    if (archifyRelease) await archifyRelease.finish();
     if (legacyProfileNote || legacyInstructionNote) {
       summary.notes = [
         ...(summary.notes ?? []),
@@ -751,6 +800,26 @@ export async function installBundle({
     // Restore failures are collected and reported: a swallowed restore would
     // leave ownership claims describing bytes that are not on disk.
     const rollbackErrors = [];
+    if (manifestAttempted) {
+      try {
+        const current = await readFile(manifestFile).catch((readErr) => {
+          if (readErr.code === 'ENOENT') return null;
+          throw readErr;
+        });
+        if (manifestBefore === null && current !== null) await rm(manifestFile);
+        else if (manifestBefore !== null && current?.equals(manifestBefore) !== true) {
+          await writeAtomic(manifestFile, manifestBefore, { mode: manifestMode });
+        }
+      } catch (restoreErr) { rollbackErrors.push(`manifest: ${restoreErr.message}`); }
+    }
+    if (archifyRelease) {
+      try { await archifyRelease.rollback(); }
+      catch (restoreErr) { rollbackErrors.push(`old archify owner: ${restoreErr.message}`); }
+    }
+    if (archify) {
+      try { await archify.rollback(); }
+      catch (restoreErr) { rollbackErrors.push(`archify: ${restoreErr.message}`); }
+    }
     for (const write of claudeWritten.reverse()) {
       try {
         if (write.before === null) await rm(write.path);
@@ -812,6 +881,7 @@ export async function uninstallBundle({
     instructions: { path: null, hash: null },
   };
   const boundClaudeSettingsPath = manifest.claudeSettings?.path ?? null;
+  await guardArchifyRecord(manifest.archify, skillsRoot, yes);
   const claudePlan = await planUninstallClaudeSettings({
     claude,
     skillsRoot,
@@ -920,6 +990,7 @@ export async function uninstallBundle({
   const deletedFiles = [];
   const claudeWritten = [];
   let instructionWritten = false;
+  let archifyRelease = null;
   try {
     for (const rel of uninstallPlan) {
       const { dest, current, mode } = await readOwnedTarget(skillsRoot, rel);
@@ -958,6 +1029,11 @@ export async function uninstallBundle({
     }
     summary.claudeSettings = claudePlan.report;
 
+    const remainingArchify = ARCHIFY_RECORD in remainingFiles ? manifest.archify : null;
+    if (manifest.archify && !remainingArchify) {
+      archifyRelease = await planArchifyRelease({ record: manifest.archify, skillsRoot, writeAtomic, log });
+    }
+
     if (
       Object.keys(remainingFiles).length === 0 &&
       !hasLegacyProfiles &&
@@ -975,11 +1051,17 @@ export async function uninstallBundle({
         profiles: legacyProfiles,
         claudeSettings: { path: remainingClaudeSettingsPath },
         instructions: remainingInstructions,
+        archify: remainingArchify,
       });
     }
+    if (archifyRelease) await archifyRelease.finish();
     return summary;
   } catch (err) {
     const rollbackErrors = [];
+    if (archifyRelease) {
+      try { await archifyRelease.rollback(); }
+      catch (restoreErr) { rollbackErrors.push(`archify owner: ${restoreErr.message}`); }
+    }
     for (const write of claudeWritten.reverse()) {
       try {
         if (write.before === null) await rm(write.path);

package/src/manifest.js

@@ -80,6 +80,13 @@ function normalizeManifest(parsed) {
     throw new Error('invalid ownership manifest: files must be an object of path hashes');
   }
   const rawClaudeSettings = parsed.claudeSettings ?? { path: null };
+  const archify = parsed.archify ?? null;
+  if (archify !== null && (typeof archify !== 'object' ||
+      typeof archify.path !== 'string' || !isAbsolute(archify.path) ||
+      !/^[a-f0-9]{40}$/.test(archify.sha) ||
+      !archify.path.endsWith(`/archify-${archify.sha}`))) {
+    throw new Error('invalid ownership manifest: archify must bind an absolute pinned copy');
+  }
   if (
     typeof rawClaudeSettings !== 'object' || rawClaudeSettings === null ||
     Array.isArray(rawClaudeSettings) ||
@@ -118,6 +125,7 @@ function normalizeManifest(parsed) {
       profiles: { path: null, preset: null, entries: { ...rawProfiles } },
       claudeSettings: { path: rawClaudeSettings.path },
       instructions,
+      ...(archify ? { archify } : {}),
     };
   }
   if (
@@ -137,6 +145,7 @@ function normalizeManifest(parsed) {
       },
       claudeSettings: { path: rawClaudeSettings.path },
       instructions,
+      ...(archify ? { archify } : {}),
     };
   }
   throw new Error('invalid ownership manifest: profiles must bind a config path to id hashes');