docs: add architecture diagrams (Mermaid + Archify map) for pi-dashboard

- docs/pi-dashboard.mmd — Mermaid source of truth
- docs/diagrams/pi-dashboard.png|svg — rendered via mmdc (mermaid-cli 11.16.0)
- docs/archify/pi-dashboard.architecture.json — Archify JSON IR
- docs/pi-dashboard-map.html — interactive map (9/9 showcase checks)
- docs/README.md — embedded mermaid + artifact index + regenerate commands
- visual-check screenshots/evidence at 1440x900 + 2048x1320 (light/dark)

Generated by project-diagramming-mermaid + project-diagramming-archify skills.

docs/README.md

@@ -0,0 +1,44 @@
+# Pi Dashboard — Diagrams
+
+Architecture artifacts for pi-dashboard, generated by the `project-diagramming-mermaid` + `project-diagramming-archify` skills (per-project `docs/` convention).
+
+## Overview
+
+- **Source of truth**: [`pi-dashboard.mmd`](./pi-dashboard.mmd)
+- **Rendered** (via `mmdc`, mermaid-cli 11.16.0):
+  - [`diagrams/pi-dashboard.png`](./diagrams/pi-dashboard.png) (@2x, white bg)
+  - [`diagrams/pi-dashboard.svg`](./diagrams/pi-dashboard.svg) (vector)
+- **Interactive map** (Archify, 9/9 showcase checks): [`pi-dashboard-map.html`](./pi-dashboard-map.html) — open in a browser for pan/zoom, search, theme toggle, route tracing
+- **Archify spec** (JSON IR): [`archify/pi-dashboard.architecture.json`](./archify/pi-dashboard.architecture.json)
+
+## Diagram (Mermaid)
+
+Renders natively in Obsidian; shows as ASCII in pi via the `pi-mermaid` extension.
+
+```mermaid
+flowchart LR
+  EXT["dashboard.ts pi extension"] -->|"writes JSON"| SF[("state files ~/.pi/agent/dashboard")]
+  REM["remote machines .13 .51"] -->|"ssh cat *.json, 5s timeout + cooldown"| ST["state.go"]
+  SF -->|"readLocalStates"| ST
+  ST -->|"AgentState"| MAIN["main.go bubbletea TUI"]
+  CFG["pi-dashboard.yaml"] -->|"loadConfig"| MAIN
+  MAIN -->|"2s poll tick"| ST
+  MAIN -->|"table + detail"| UI["Table + Detail panes"]
+  UI -->|"Enter"| AT["tmux / zellij attach"]
+  UI -->|"d"| HK["hunk diff"]
+  UI -->|"Tab"| TX["tuxedo todo.txt"]
+  UI -->|"Del"| SF
+```
+
+## Regenerate
+
+```bash
+# update the source
+vim pi-dashboard.mmd
+# re-render images
+mmdc -i pi-dashboard.mmd -o diagrams/pi-dashboard.png --scale 2 -b white
+mmdc -i pi-dashboard.mmd -o diagrams/pi-dashboard.svg
+# update the Archify map (JSON IR in archify/, then):
+node ~/.agents/skills/archify/bin/archify.mjs validate architecture archify/pi-dashboard.architecture.json --quality showcase --json
+node ~/.agents/skills/archify/bin/archify.mjs deliver architecture archify/pi-dashboard.architecture.json pi-dashboard-map.html --quality showcase --json
+```

docs/archify/pi-dashboard.architecture.json

@@ -0,0 +1,236 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Pi Dashboard",
+    "quality_profile": "showcase"
+  },
+  "components": [
+    {
+      "id": "ext",
+      "type": "backend",
+      "label": "dashboard.ts",
+      "sublabel": "pi extension",
+      "pos": [
+        40,
+        140
+      ]
+    },
+    {
+      "id": "sf",
+      "type": "database",
+      "label": "state files",
+      "sublabel": "~/.pi/agent/dashboard",
+      "pos": [
+        260,
+        140
+      ]
+    },
+    {
+      "id": "st",
+      "type": "backend",
+      "label": "state.go",
+      "sublabel": "read + liveness",
+      "pos": [
+        480,
+        140
+      ]
+    },
+    {
+      "id": "main",
+      "type": "backend",
+      "label": "main.go",
+      "sublabel": "bubbletea TUI",
+      "pos": [
+        700,
+        140
+      ]
+    },
+    {
+      "id": "ui",
+      "type": "frontend",
+      "label": "Table + Detail",
+      "sublabel": "views",
+      "pos": [
+        920,
+        140
+      ]
+    },
+    {
+      "id": "cfg",
+      "type": "backend",
+      "label": "pi-dashboard.yaml",
+      "sublabel": "config",
+      "pos": [
+        700,
+        40
+      ]
+    },
+    {
+      "id": "rem",
+      "type": "external",
+      "label": "remotes .13 .51",
+      "sublabel": "ssh cat *.json",
+      "pos": [
+        40,
+        340
+      ]
+    },
+    {
+      "id": "at",
+      "type": "external",
+      "label": "tmux / zellij",
+      "sublabel": "attach",
+      "pos": [
+        1180,
+        540
+      ]
+    },
+    {
+      "id": "hk",
+      "type": "external",
+      "label": "hunk",
+      "sublabel": "diff review",
+      "pos": [
+        1180,
+        390
+      ]
+    },
+    {
+      "id": "tx",
+      "type": "external",
+      "label": "tuxedo",
+      "sublabel": "todo.txt",
+      "pos": [
+        1180,
+        240
+      ]
+    }
+  ],
+  "boundaries": [
+    {
+      "kind": "region",
+      "label": "pi-dashboard (Go)",
+      "wraps": [
+        "st",
+        "main",
+        "ui",
+        "cfg"
+      ]
+    },
+    {
+      "kind": "region",
+      "label": "data sources",
+      "wraps": [
+        "ext",
+        "sf",
+        "rem"
+      ]
+    }
+  ],
+  "connections": [
+    {
+      "id": "ext-to-sf",
+      "from": "ext",
+      "to": "sf",
+      "label": "writes JSON"
+    },
+    {
+      "id": "rem-to-st",
+      "from": "rem",
+      "to": "st",
+      "label": "ssh"
+    },
+    {
+      "id": "sf-to-st",
+      "from": "sf",
+      "to": "st",
+      "label": "readLocalStates"
+    },
+    {
+      "id": "st-to-main",
+      "from": "st",
+      "to": "main",
+      "label": "AgentState",
+      "labelAt": [
+        620,
+        215
+      ]
+    },
+    {
+      "id": "cfg-to-main",
+      "from": "cfg",
+      "to": "main",
+      "label": "loadConfig",
+      "labelAt": [
+        760,
+        114
+      ]
+    },
+    {
+      "id": "main-to-st",
+      "from": "main",
+      "to": "st",
+      "label": "2s poll tick",
+      "fromSide": "bottom",
+      "toSide": "bottom"
+    },
+    {
+      "id": "main-to-ui",
+      "from": "main",
+      "to": "ui",
+      "label": "model"
+    },
+    {
+      "id": "ui-to-at",
+      "from": "ui",
+      "to": "at",
+      "label": "Enter",
+      "labelAt": [
+        1060,
+        480
+      ]
+    },
+    {
+      "id": "ui-to-hk",
+      "from": "ui",
+      "to": "hk",
+      "label": "d",
+      "labelAt": [
+        1060,
+        360
+      ]
+    },
+    {
+      "id": "ui-to-tx",
+      "from": "ui",
+      "to": "tx",
+      "label": "Tab",
+      "labelAt": [
+        1060,
+        240
+      ]
+    }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Source of truth",
+      "items": [
+        "dashboard.ts extension writes session JSON per machine",
+        "state.go: heartbeat/staleness (45s window, legacy 30m)",
+        "remote reads: ssh cat *.json, 5s hard timeout + cooldown"
+      ]
+    },
+    {
+      "dot": "emerald",
+      "title": "UI actions",
+      "items": [
+        "Enter: tmux / zellij attach (local or ssh -t)",
+        "d: hunk diff in the agent's folder",
+        "Tab: tuxedo task board (<cwd>/todo.txt)",
+        "Del: remove closed/lost state file (local or ssh)"
+      ]
+    }
+  ]
+}

docs/pi-dashboard-map.visual-check.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Archify visual-check · pi-dashboard-map.html</title>
+<style>
+*{box-sizing:border-box}body{margin:0;padding:24px;background:#e9eef5;color:#172033;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}header{max-width:1500px;margin:0 auto 18px}h1{margin:0 0 6px;font-size:20px}p{margin:0;color:#526176}.grid{max-width:1500px;margin:auto;display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:18px}figure{margin:0;padding:10px;background:white;border:1px solid #c9d4e3;border-radius:12px;box-shadow:0 10px 30px rgba(15,23,42,.08)}img{display:block;width:100%;height:auto;border:1px solid #e2e8f0}figcaption{padding:9px 4px 2px;color:#526176}@media(max-width:900px){.grid{grid-template-columns:1fr}}
+</style>
+</head>
+<body>
+<header><h1>Archify visual-check</h1><p>pi-dashboard-map.html · automated containment pass · visual review pending</p></header>
+<main class="grid">
+      <figure>
+        <img src="pi-dashboard-map.visual-check.1440x900.light.png" alt="light 1440 by 900">
+        <figcaption><strong>LIGHT</strong> · 1440×900 · containment pass</figcaption>
+      </figure>
+      <figure>
+        <img src="pi-dashboard-map.visual-check.1440x900.dark.png" alt="dark 1440 by 900">
+        <figcaption><strong>DARK</strong> · 1440×900 · containment pass</figcaption>
+      </figure>
+      <figure>
+        <img src="pi-dashboard-map.visual-check.2048x1320.light.png" alt="light 2048 by 1320">
+        <figcaption><strong>LIGHT</strong> · 2048×1320 · containment pass</figcaption>
+      </figure>
+      <figure>
+        <img src="pi-dashboard-map.visual-check.2048x1320.dark.png" alt="dark 2048 by 1320">
+        <figcaption><strong>DARK</strong> · 2048×1320 · containment pass</figcaption>
+      </figure>
+</main>
+</body>
+</html>

docs/pi-dashboard-map.visual-check.json

@@ -0,0 +1,143 @@
+{
+  "schemaVersion": 1,
+  "ok": true,
+  "command": "visual-check",
+  "status": "pass",
+  "visualReview": "pending",
+  "artifact": {
+    "path": "/home/sam/src/pi-dashboard/docs/pi-dashboard-map.html",
+    "sha256": "e36d87bd9e1567751a9d5837584aa7122a2a64c566263b8321fd69235d6977f2",
+    "bytes": 637800
+  },
+  "state": {
+    "detail": "read",
+    "motion": "still"
+  },
+  "chrome": {
+    "status": "available",
+    "executable": "/run/current-system/sw/bin/google-chrome"
+  },
+  "containment": {
+    "status": "pass",
+    "viewports": [
+      {
+        "width": 1440,
+        "height": 900,
+        "theme": "light",
+        "innerWidth": 1440,
+        "innerHeight": 900,
+        "scrollWidth": 1440,
+        "scrollHeight": 900,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      },
+      {
+        "width": 1600,
+        "height": 1000,
+        "theme": "light",
+        "innerWidth": 1600,
+        "innerHeight": 1000,
+        "scrollWidth": 1600,
+        "scrollHeight": 1000,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      },
+      {
+        "width": 1920,
+        "height": 1080,
+        "theme": "light",
+        "innerWidth": 1920,
+        "innerHeight": 1080,
+        "scrollWidth": 1920,
+        "scrollHeight": 1080,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      },
+      {
+        "width": 2048,
+        "height": 1320,
+        "theme": "light",
+        "innerWidth": 2048,
+        "innerHeight": 1320,
+        "scrollWidth": 2048,
+        "scrollHeight": 1320,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light"
+      }
+    ]
+  },
+  "captures": {
+    "status": "pass",
+    "screenshots": [
+      {
+        "width": 1440,
+        "height": 900,
+        "theme": "light",
+        "innerWidth": 1440,
+        "innerHeight": 900,
+        "scrollWidth": 1440,
+        "scrollHeight": 900,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light",
+        "file": "pi-dashboard-map.visual-check.1440x900.light.png"
+      },
+      {
+        "width": 1440,
+        "height": 900,
+        "theme": "dark",
+        "innerWidth": 1440,
+        "innerHeight": 900,
+        "scrollWidth": 1440,
+        "scrollHeight": 900,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "dark",
+        "file": "pi-dashboard-map.visual-check.1440x900.dark.png"
+      },
+      {
+        "width": 2048,
+        "height": 1320,
+        "theme": "light",
+        "innerWidth": 2048,
+        "innerHeight": 1320,
+        "scrollWidth": 2048,
+        "scrollHeight": 1320,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "light",
+        "file": "pi-dashboard-map.visual-check.2048x1320.light.png"
+      },
+      {
+        "width": 2048,
+        "height": 1320,
+        "theme": "dark",
+        "innerWidth": 2048,
+        "innerHeight": 1320,
+        "scrollWidth": 2048,
+        "scrollHeight": 1320,
+        "overflowX": false,
+        "overflowY": false,
+        "ok": true,
+        "resolvedTheme": "dark",
+        "file": "pi-dashboard-map.visual-check.2048x1320.dark.png"
+      }
+    ],
+    "contactSheet": "pi-dashboard-map.visual-check.html"
+  },
+  "sidecars": {
+    "receipt": "pi-dashboard-map.visual-check.json",
+    "contactSheet": "pi-dashboard-map.visual-check.html"
+  }
+}

docs/pi-dashboard.mmd

@@ -0,0 +1,12 @@
+flowchart LR
+  EXT[dashboard.ts pi extension] -->|writes JSON| SF[(state files<br/>~/.pi/agent/dashboard)]
+  REM[remote machines .13 .51] -->|ssh cat *.json<br/>5s timeout + cooldown| ST[state.go]
+  SF -->|readLocalStates| ST
+  ST -->|AgentState| MAIN[main.go bubbletea TUI]
+  CFG[pi-dashboard.yaml] -->|loadConfig| MAIN
+  MAIN -->|2s poll tick| ST
+  MAIN -->|table + detail| UI[Table + Detail panes]
+  UI -->|Enter| AT[tmux / zellij attach]
+  UI -->|d| HK[hunk diff]
+  UI -->|Tab| TX[tuxedo todo.txt]
+  UI -->|Del| SF