From bdde39f77328e9207265c6e2436fcb89f586318d Mon Sep 17 00:00:00 2001 From: Sam Rolfe Date: Sun, 6 Sep 2026 10:54:08 +1000 Subject: [PATCH] sam-4screen-desktop 2026-9-6:10:54:8 --- .obsidian/workspace.json | 4 +- .../350 AI/Pi Agent Extensions & Skills.md | 3 + ...g — Mermaid, Archify, Vikunja & Outline.md | 102 ++++++++++++++++++ .../Docker Containers.md | 2 + .../Home Network Map Overview.md | 6 ++ 5 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md diff --git a/.obsidian/workspace.json b/.obsidian/workspace.json index e9984b4..d1fc56d 100644 --- a/.obsidian/workspace.json +++ b/.obsidian/workspace.json @@ -209,8 +209,9 @@ "templater-obsidian:Templater": false } }, - "active": "b0724d9a8e78110f", + "active": "8018aa52f0591df9", "lastOpenFiles": [ + "300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md", "300 areas/360 Dev-Ops Network Computers/Docker Containers.md", "300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md", "300 areas/360 Dev-Ops Network Computers/Home Voice Assistant System.md", @@ -236,7 +237,6 @@ "300 areas/360 Dev-Ops Network Computers/FAMILY CONSOLE.md", "000 daily/FAMILY S3 Storage Integration & Blueprint.md", "000 daily/FAMILY DeepSeek Harness (dsh) Home Lab Setup.md", - "000 daily/FAMILY Enterprise Homelab AI Multimedia Suite. Systems Architecture & Blueprint.md", "000 daily/ThinkPad Recommendations", "500 archive/510 Daily", "300 areas/305 Ideas Businesses", diff --git a/300 areas/350 AI/Pi Agent Extensions & Skills.md b/300 areas/350 AI/Pi Agent Extensions & Skills.md index 18430fb..6d56a39 100644 --- a/300 areas/350 AI/Pi Agent Extensions & Skills.md +++ b/300 areas/350 AI/Pi Agent Extensions & Skills.md @@ -111,6 +111,7 @@ pi is **Nix-managed on all three** — the nixpkgs **`pi-coding-agent`** package | **@tintinweb/pi-tasks** | npm (global) | Task management with dependency tracking, auto-cascade, background process tracking, TaskExecute spawns subagents via RPC | | **gentle-engram** | `~/.agents` | Memory service connecting to engram via ENGRAM_URL. Replaces memory-vault. Session capture, compaction recovery | | **headroom-bridge** | `~/.agents` | `compress_for_agent` tool — compresses >20K chars via Headroom Docker on .13:8787. 60-95% token reduction | +| **pi-mermaid** | `~/.agents` (vendored from npm 0.3.0, commit `8e68df0`) | Renders ` ```mermaid ` blocks as ASCII in the TUI (beautiful-mermaid) + Mermaid parser syntax warnings/errors. `/pi-mermaid` re-renders last assistant message. Per project: `/config-add ext pi-mermaid` | | **pi-langfuse** | `~/.agents` (vendored from npm 1.5.8, commit `bc91a15`) | Langfuse LLM observability for pi — one trace per conversation, grouped by pi session, with tokens + cost. Activate per project via `/config-add ext pi-langfuse`. See [[#pi-langfuse — LLM Observability for Pi]] | | **pi-tool-display** | `~/.agents` (vendored npm 0.5.0, commit `41cc33d`) | OpenCode-style compact tool rendering, adaptive edit/write diffs, pending-edit previews, thinking labels. **Global** — 0 tools / 0 token cost (added via home.nix settings). `/tool-display` presets: opencode / balanced / verbose | | **pi-lsp-extension** | `~/.agents` (vendored npm 1.3.0, commit `41cc33d`) | LSP diagnostics, hover, definition, references, symbols, rename, completions, code_actions + tree-sitter `code_overview`/`ast_search`/`code_rewrite`. **Per-project** via `/config-add ext pi-lsp-extension` (10 tools — token-lean). Commands: `/lsp`, `/lsp-config`, `/lsp-restart`, `/lsp-lombok` | @@ -166,6 +167,8 @@ v0.7.0, installed globally. 7 task tools: `TaskCreate`, `TaskList`, `TaskGet`, ` | **openspec-explore** | Explore ideas and clarify requirements | | **npm-security** | Scan packages with SafeDep Vet, check typosquatting with npq, wrap installs with Socket Firewall | | **ste-writing** | Rewrite prose (docs, READMEs, PRs, errors) into ASD-STE100 Simplified Technical English. Removes AI slop. Two modes: strict (procedures) and STE-flavored (general prose). Includes heuristic anti-slop linter (ste-lint.py). | +| **project-diagramming-mermaid** | Outline codebase/project as Mermaid → `/docs/.mmd` + render to `/docs/diagrams/` via mmdc (nixpkgs mermaid-cli) → prompt for Archify follow-up. Per project: `/config-add skill project-diagramming-mermaid`. See [[Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline]] | +| **project-diagramming-archify** | Mermaid or plain language → Archify JSON IR → validate (showcase) → deliver interactive HTML to `/docs/-map.html`. Vendor renderer: `~/.agents/skills/archify` (v2.14). Per project: `/config-add skill project-diagramming-archify`. See [[Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline]] | | **design-build** | Generate production-ready HTML/Tailwind code from design specifications and DESIGN.md design tokens. | | **design-explore** | Generate UI design mockups as images for exploration and ideation. Supports DESIGN.md for design-token-accurate mockups. | | **markitdown** | Convert files (PDF, Word, Excel, PowerPoint, images, HTML, CSV, JSON, XML, ZIP, EPubs, YouTube) to Markdown for LLM consumption. Image analysis via Qwen 2.5 VL 72B on OpenRouter. | diff --git a/300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md b/300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md new file mode 100644 index 0000000..5a95c26 --- /dev/null +++ b/300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md @@ -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 `/docs/.mmd`; images `/docs/diagrams/.png|svg`. +- Render: `mmdc -i /docs/.mmd -o /docs/diagrams/.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 --quality showcase --json` → `archify.mjs deliver --quality showcase --json`. +- **Project artifacts**: spec `/docs/archify/..json`; map `/docs/-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 `/docs/.mmd` → render to `/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 `/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 **`/docs/`**: + ``` + /docs/.mmd # Mermaid source (single source of truth) + /docs/diagrams/.png # rendered Mermaid image(s) + /docs/archify/..json # Archify JSON IR source + /docs/-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. \ No newline at end of file diff --git a/300 areas/360 Dev-Ops Network Computers/Docker Containers.md b/300 areas/360 Dev-Ops Network Computers/Docker Containers.md index 72bc275..3f4132a 100644 --- a/300 areas/360 Dev-Ops Network Computers/Docker Containers.md +++ b/300 areas/360 Dev-Ops Network Computers/Docker Containers.md @@ -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/` diff --git a/300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md b/300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md index 3cff588..eea8b41 100644 --- a/300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md +++ b/300 areas/360 Dev-Ops Network Computers/Home Network Map Overview.md @@ -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)