pi-config/skills/project-diagramming-archify/SKILL.md

---
name: project-diagramming-archify
description: Create or update an interactive Archify architecture map for a project. Accept plain-language requirements or pasted Mermaid (flowchart/sequence/stateDiagram) and compile typed JSON IR into a self-contained interactive HTML diagram (architecture, workflow, sequence, dataflow, lifecycle) under the project's docs/ directory. Use when the user asks for architecture/flow/data visualization, or the diagrams were just created/updated with project-diagramming-mermaid. Per-project only — never global.
version: 1.1.0
---

# project-diagramming-archify

Create polished, validated, interactive architecture diagrams as standalone HTML (with inline SVG, dark/light themes, pan/zoom, search, route tracing, PNG/SVG/WebM export) from typed JSON IR, using the bundled `archify.mjs` renderer. Everything lands under the project's `docs/` directory.

## When to use

- User asks for a client-facing / interactive architecture or flow visualization.
- The mermaid flow just completed (project-diagramming-mermaid) and the user said yes to the follow-up prompt.
- User asks to update an existing Archify map.

## The skill asset

The renderer/vendor skill lives at `~/.agents/skills/archify/` (Archify v2.14, MIT, from tt-a1i/archify). It is self-contained: pure Node ≥18, zero npm deps. Key entry point:

```bash
node ~/.agents/skills/archify/bin/archify.mjs <command> ...
```

Commands (from the vendored skill's fast authoring path):
- `guide "<scenario>" --json` — when unsure which diagram type fits the ask.
- `validate <type> <candidate.json> --quality showcase --json` — iterate during authoring; **showcase pass = 9 artifact checks, 0 composition errors, 0 warnings**.
- `validate <type> <candidate.json> --quality standard --json` — **dense-map tier**: 4 artifact checks, far fewer composition constraints. Use for rich/large topologies (see "Dense maps" below). Pass the same `--quality` to `deliver`.
- `deliver <type> <candidate.json> <output.html> --quality showcase --json` — final acceptance (freezes spec bytes, atomically commits HTML, reports SHA-256 + byte counts).
- `visual-check <output.html> --json` — best-effort screenshot/containment evidence; needs Chrome/Chromium, exit 2 = skipped gracefully (e.g. .13 has no chrome). Never claim visual inspection you did not perform.

## Canonical workflow (per project)

1. **Scope + type** — map the ask to a type: architecture (components/services/boundaries), workflow (processes/gates), sequence (API/request chains), dataflow (pipelines/ETL/lineage), lifecycle (state transitions). If ambiguous: `node ~/.agents/skills/archify/bin/archify.mjs guide "<scenario>" --json`.
2. **Author JSON IR** — read one matching schema (`schemas/<type>.schema.json` + `schemas/common.schema.json`) and one matching example (`examples/<type>.*.json`) from the vendored skill. Author **fresh** JSON: new stable IDs, domain wording, layout. ≤ 12 primary nodes; one obvious main path; sparse labels. Set `meta.quality_profile` to `"showcase"` unless the user explicitly asks for a dense `standard` map.
3. **Accept Mermaid input** (common path — after project-diagramming-mermaid): read the Mermaid for topology & meaning, then author fresh Archify JSON (do not mechanically copy styling):
   - `flowchart` / `graph` → `workflow`, or `architecture` for a component map.
   - `sequenceDiagram` → `sequence` (participants → semantic participants, arrows → messages).
   - `stateDiagram` → `lifecycle` (states & transitions keep meaning).
4. **Validate-iterate**: `validate` after every candidate edit and immediately before handoff. Fix only diagnosed issues; if ~2–3 consecutive rounds don't improve the error count, stop iterating and use the **dense-map escape** below (standard profile / bigger viewBox / split) instead of forcing a simplified node set.
5. **Deliver**: `deliver <type> <candidate.json> <output.html> --quality showcase --json`. Non-zero exit is never success.

## Dense maps — the sanctioned escape hatches (read before simplifying)

Archify is a **curation** tool, not an everything-map. Two hard gates can make a rich topology fight you:

- **showcase composition** — 9 checks: ≥8px segments, no edge-through-node, no ambiguous corridors, no label collisions.
- **visual-check viewport fit** — the whole map must fit **1440×900 without scrolling** (`scrollWidth ≤ innerWidth && scrollHeight ≤ innerHeight` at every checked size). A 4-lane, 6-column flow physically cannot fit 900px tall → vertical overflow is expected for such maps.

When ~2–3 rounds don't improve, do **NOT** silently simplify to fewer nodes. Work through these in order, and tell the user what you did:

1. **Drop to `standard` quality** (recommended for dense maps) — pass `--quality standard` to BOTH `validate` and `deliver` (4 artifact checks instead of 9; the §composition constraints that blocked you are mostly gone). A user who asks for a rich/dense map IS asking for standard — the skill's default is showcase *unless the user explicitly requests a dense standard map*.
2. **Enlarge `meta.viewBox`** — schema min is 320×240, **no max** (examples ship up to 1080×780). More Y room fixes squeezed lanes. Caveat: to still *pass* visual-check, keep total height ≤ ~900px; anything taller may overflow (report it truthfully — never fake a pass with `overflow: hidden`).
3. **Split into multiple maps** — main flow in one map; detail (rejected paths, secondary stores) in a second map or as `cards` / Obsidian / Outline content. One obvious main path is the design philosophy; low-value edges belong in cards, not the canvas.
4. **Only then** simplify the node set — and say so explicitly ("kept the N-node validated map; detail lives in X").

> Design envelope: shipped examples run **10–12 primary components**, viewBox 720×900 → 1080×780. Above ~12 primary nodes → split-map territory, not an everything-map.

## Output locations (per-project, always under the project's docs/)

- **JSON IR source (single source of truth):** `<project>/docs/archify/<topic>.<type>.json`
- **Interactive HTML map:** `<project>/docs/<topic>-map.html`
- Schemas/examples to consult: `~/.agents/skills/archify/schemas/`, `~/.agents/skills/archify/examples/`.

Create `<project>/docs/` (+ `docs/archify/`) if missing. Never write artifacts outside the project directory.

## Publish to the central maps site (optional but recommended)

After a successful `deliver`, offer to **publish** the project's `docs/` to the LAN maps site:

```bash
~/.agents/skills/project-diagramming-archify/publish-maps.sh [<project-dir>]
```

- Uploads `docs/` to Caddy on `.35` → **`https://maps.lab.audasmedia.com.au/<project>/docs/`** (site index at `https://maps.lab.audasmedia.com.au/` — Caddy `file_server browse`, no auth, read-only static hosting).
- **Incremental + atomic** (rsync -az): only changed blocks transfer; no half-written files on failure.
- Excludes `*.visual-check.*` sidecars automatically (keeps the browse index clean).
- Works from any machine with ssh key access to `.35` (all three pi machines have it).
- `publish-maps.sh --list` shows what's already published.
- Wait for `visual-check` to pass first; `publish-maps.sh` does NOT re-run it.

## Authoring rules (subset of the vendored skill — read SKILL.md for full invariants)

- Omit `meta.visual_preset`, `meta.subtitle`, `meta.legend`, `meta.engineering_profile` by default.
- Omit `meta.viewBox` by default (schema min 320×240, no max); **enlarge it for dense maps** so lanes/labels fit cleanly without shrinking nodes.
- Match authored strings to the user's language; preserve exact product names / commands / API paths / env names.
- Automatic routes own their endpoint sides; never accept an edge crossing an unrelated opaque node.
- Sequence: omit `meta.column_fit` (fixed); use `"spread"` when participants don't fit.
- Component types: `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`. Variants: `default`, `emphasis`, `security`, `dashed`.

## Per-project activation

Activated **per project** with `/config-add skill project-diagramming-archify` (and the vendor skill `archify` is the renderer asset). If not available in the current project, that's expected — assets activate per project to keep context lean.

## Related

- `project-diagramming-mermaid` — Mermaid flow that feeds into this skill (and the user-facing prompt to come here).
- `pi-mermaid` extension — ASCII preview of Mermaid in-chat.
- `nixos-workflow` skill — asset management (Gitea pi-config).
- `system-architect` skill — infra reference.

## Obsidian documentation

Tools documented at `300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md` (+ the network & container docs link it). Do not recreate diagram versions of those docs.