Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline

The home-lab's dev-ops toolbelt for pi-agent: Mermaid + Archify for diagrams, Vikunja for tasks, Outline for docs. See Home Network Map Overview and Docker Containers for the machines/containers themselves — this note documents the tools.

The four tools at a glance

Tool	What it does	For whom	Model
Mermaid	Text diagrams in Markdown (```mermaid), rendered to SVG/PNG	Humans (visual)	Declarative diagram-as-code
Archify	Compiles JSON IR → interactive self-contained HTML architecture maps	Humans (client-facing) + machines (validation)	AI-agent skill (JSON IR → renderer)
Vikunja	Projects, tasks, kanban stages, percent-done progress	Humans AND machines (REST API)	Web app + API
Outline	Project documentation store	Machines (AI agents resume work) + humans	Web app + API

Mermaid

What: mermaid-js diagram syntax inside standard Markdown fenced blocks.
Rendering engines available:
- mmdc (mermaid-cli, v11.16.0) — renders .mmd source → PNG/SVG/PDF. Installed via nixpkgs pkgs.mermaid-cli in home.packages on .27, .13, .51 (bundles its own Chromium from the Nix store — deterministic, offline, private). Check: which mmdc.
- Obsidian renders ```mermaid blocks natively (viewing in vault = zero tooling).
- pi-mermaid extension (v0.3.0) — renders Mermaid blocks as ASCII in the pi TUI for in-chat preview + parser warnings/errors. Activated per project (/config-add ext pi-mermaid).
Project artifacts (per-project convention, see below): source <project>/docs/<topic>.mmd; images <project>/docs/diagrams/<topic>.png|svg.
Render: mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --scale 2.
Focus: high-level dependencies and data flows; avoid complex layout overlaps. Split busy topics into multiple diagrams.

Archify

What: tt-a1i/archify (MIT, v2.14) — an AI-agent skill that turns a small typed JSON IR spec into a self-contained interactive HTML diagram (inline SVG, dark/light themes, pan/zoom, search, route tracing, PNG/SVG/WebM export).
Vendored location: ~/.agents/skills/archify/ (pure Node ≥18, zero npm deps). Pushed via Gitea pi-config.
Five diagram types: architecture (components/services/boundaries), workflow (processes/gates), sequence (API/request chains), dataflow (pipelines/ETL/lineage), lifecycle (state transitions).
Accepts Mermaid input directly: flowchart→workflow/architecture, sequenceDiagram→sequence, stateDiagram→lifecycle.
Authoring flow (see ~/.agents/skills/archify/SKILL.md): read schema + example → author fresh JSON (≤12 primary nodes, one main path) → archify.mjs validate <type> <candidate.json> --quality showcase --json → archify.mjs deliver <type> <candidate.json> <out.html> --quality showcase --json.
Project artifacts: spec <project>/docs/archify/<topic>.<type>.json; map <project>/docs/<topic>-map.html.
visual-check (screenshot/containment evidence) needs Chrome/Chromium — present on .27/.51, not on .13 (skips gracefully, exit 2).

Vikunja — tasks & stages (for humans and machines)

Base API: https://vikunja.lab.audasmedia.com.au/api/v1 (bearer token VIKUNJA_TOKEN, in ~/.config/environment.d/10-secrets.conf).
Projects → tasks → kanban buckets (stages) → percent_done / done.
Transient 401 flake: retry once with the same token before assuming it's wrong.
Machines use the API to open/update tasks and move them between stages; humans use the web UI.
Full API notes + code: ~/.agents/skills/project-ops/SKILL.md (section 2).

Outline — documentation (for AI agents)

Base API: https://outline.lab.audasmedia.com.au/api (key OL_API_KEY; endpoints are POST).
Known flakiness: public (Caddy) endpoint intermittently 502s on writes/reads — retry once; for reliable create/update go direct to the container from .13: POST http://127.0.0.1:3000/api/....
Intended use: per-project documentation + configs with comprehensive overviews so AI agents can resume work after a break.
Full API notes + code: ~/.agents/skills/project-ops/SKILL.md (section 3).

pi-agent skills (the orchestration layer)

Skill	Purpose
project-diagramming-mermaid	Outline a codebase/project as Mermaid → save `<project>/docs/<topic>.mmd` → render to `<project>/docs/diagrams/` via mmdc → prompt user to create/update the Archify doc.
project-diagramming-archify	From Mermaid or plain language → author JSON IR → `validate` (showcase) → `deliver` interactive HTML under `<project>/docs/`.

Workflow (from pi-agent): 1) call Mermaid to create/update the project's Mermaid doc; 2) pi prompts to update/create the Archify doc after Mermaid; 3) Archify doc can be created on demand any time.

PER-PROJECT CONVENTION (important)

Everything is per-project. No global output, no global skills config.

Artifacts always land under <project>/docs/:

<project>/docs/<topic>.mmd            # Mermaid source (single source of truth)
<project>/docs/diagrams/<topic>.png   # rendered Mermaid image(s)
<project>/docs/archify/<topic>.<type>.json  # Archify JSON IR source
<project>/docs/<topic>-map.html       # Archify interactive map

Activation is per project via /config-add (pi-config extension) — never global — to keep LLM context lean. Currently active in: sys_config, sys_config/ai_setup, archify_mermaid_install.
```
/config-add ext pi-mermaid
/config-add skill project-diagramming-mermaid
/config-add skill project-diagramming-archify
```
Asset repo: ~/.agents (Gitea pi-config, per-machine clones — see Pi Agent Extensions & Skills and the nixos-workflow skill).

Machines

Machine	mmdc (mermaid-cli)	Chrome (for archify visual-check)
`.27` sam-4screen-desktop	✅ nixpkgs	✅ google-chrome
`.13` nixos-desktop	✅ nixpkgs	❌ (visual-check skipped)
`.51` sam-thinkpad	✅ nixpkgs	✅ google-chrome

Chrome note: visual-check exits 2 (skipped) where Chrome is unavailable — that is expected, not a failure.

6.5 KiB Raw Blame History