---
created: 2026-09-06
modified: 2026-09-06
type: note
tags:
  - dev-ops
  - diagramming
  - mermaid
  - archify
  - vikunja
  - outline
  - pi-agent
aliases:
  - Dev-Ops Tooling
  - Mermaid Archify Vikunja Outline
---

# 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](https://mermaid.js.org/) 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](https://github.com/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.

## Viewing maps — maps.lab.audasmedia.com.au

Archify maps (and Mermaid `docs/`) publish to **`https://maps.lab.audasmedia.com.au/<project>/docs/`** (site index: `https://maps.lab.audasmedia.com.au/`) — Caddy `file_server browse` on `.35`, no auth, read-only. Each project appears as a folder; click through to open the interactive map.

**Hosted entirely on `.35` (Caddy) — independent of `.13`**: the maps site stays up even when nixos-desktop (.13) is down/offline (it was offline during setup). Publish requires only ssh reachability to `.35` from the current machine.

Publish after `deliver`: `~/.agents/skills/project-diagramming-archify/publish-maps.sh [<project-dir>]` (incremental rsync; `--list` shows published projects).

---

## 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`.
  ```text
  /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.