sam/obsidian-vault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sam-4screen-desktop 2026-9-6:10:54:8

Browse Source
This commit is contained in:
Sam Rolfe
2026-09-06 10:54:08 +10:00
parent 99d0c93982
commit bdde39f773
5 changed files with 115 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md Normal file
View File

@@ -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.

2
300 areas/360 Dev-Ops Network Computers/Docker Containers.md
View File

@@ -20,6 +20,8 @@ id: 1778553013-ARYX
- MeTube https://github.com/alexta69/metube
# Docker Containers
> Dev-Ops tooling (Mermaid, Archify, Vikunja, Outline) is documented in **[[Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline]]**.
## .13 Machine NixOS Desktop (192.168.20.13)
### `/home/sam/voice_bridge/`

6
300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md
View File

@@ -20,6 +20,12 @@ aliases: []
---
## Dev-Ops Tooling
Mermaid + Archify (diagrams), Vikunja (tasks) and Outline (docs) are documented as tools in **[[Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline]]** — including the per-project `/docs/` artifact convention and pi-agent skills (`project-diagramming-mermaid`, `project-diagramming-archify`).
---
## Machines
### .27 — sam-4screen-desktop (Main Desktop)