docs(npu): update service maps and runbooks

2026-06-04 13:08:18 -07:00
parent 703c1df860
commit 420df812c0
7 changed files with 1151 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Diagram maintenance
+
+Keep infrastructure diagrams current as first-class documentation, not as one-off screenshots.
+
+## Current diagrams
+
+- [`swarm-infrastructure.html`](./swarm-infrastructure.html) — full Atlas/Hermes + n8n + agentmon + local AI/search/voice topology.
+
+## When to update an existing diagram
+
+Update the relevant diagram in the same change set when you change any of these:
+
+- service topology, ports, or container names
+- monitoring or alerting paths
+- n8n workflow architecture
+- Hermes/Atlas routing or gateway responsibilities
+- local AI/search/voice endpoints
+- OpenVINO NPU live/prototype status, ports, or safety gates (`:18810`, `:18816`, `:18817`, `:18818`, `:18819`, `:18820`, optional `:18829`)
+- Obsidian/RAG data flow
+- OpenClaw/VM operational mode
+- ownership/source-of-truth paths for a component
+
+## When to create a new diagram
+
+Create a new focused diagram when the existing overview would become too dense. Good candidates:
+
+- n8n workflow family or alerting-only diagram
+- agentmon internals: collectors → NATS → processor → Postgres → query/UI
+- Obsidian/RAG automation pipeline
+- local AI routing: Hermes/LiteLLM/llama.cpp/Ollama/provider boundaries
+- OpenVINO NPU assistant sidecars, with live baseline and approved/not-live prototype lanes separated
+- messaging/channel routing: Telegram/Discord/email → Hermes/n8n/alerts
+- disaster recovery / backup topology
+
+## Style rules
+
+- Prefer standalone `.html` files with inline SVG so they render offline in any browser.
+- Keep the source file committed alongside the docs; do not rely on generated screenshots as the only artifact.
+- Link diagrams from the nearest README or operational doc.
+- Keep labels operational: service name, port, responsibility, and data direction.
+- Avoid secrets, credential names that imply secret values, private tokens, raw webhook URLs, or sensitive sample payloads.
+- Do not imply live Atlas/Hermes/RAG routing to an OpenVINO NPU prototype unless a reviewed implementation actually enabled it; label approved prototypes as `not live` or `approval required`.
+- If a raw export or live config was used to build the diagram, commit only the sanitized diagram/docs, not the raw sensitive source.
+
+## Verification before committing
+
+```bash
+# Check the files are valid text and do not contain obvious secret markers
+python - <<'PY'
+from pathlib import Path
+for p in Path('docs').glob('*.html'):
+    text = p.read_text()
+    hits = [s for s in ['api_key', 'token', 'password', 'Authorization', 'Bearer ', 'secret'] if s.lower() in text.lower()]
+    print(p, hits)
+PY
+
+# Inspect targeted diff only
+git diff --stat -- docs README.md
+```
+
+After editing diagrams, commit with a docs-focused message, for example:
+
+```bash
+git add docs/*.md docs/*.html README.md
+git commit -m "docs: update swarm infrastructure diagrams"
+```