|
|
|
|
@@ -0,0 +1,102 @@
|
|
|
|
|
---
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## 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.
|
