docs: add diagram maintenance conventions

README.md

@@ -36,6 +36,7 @@ For the current host-side AI/search/voice automation stack, n8n watchdogs, and a
 
 - [`docs/swarm-infrastructure.md`](docs/swarm-infrastructure.md) — operational overview and quick checks
 - [`docs/swarm-infrastructure.html`](docs/swarm-infrastructure.html) — dark SVG architecture diagram
+- [`docs/diagram-maintenance.md`](docs/diagram-maintenance.md) — diagram upkeep conventions
 
 ## VM: zap
 

docs/diagram-maintenance.md

@@ -0,0 +1,63 @@
+# 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
+- 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
+- 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.
+- 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"
+```

docs/swarm-infrastructure.md

@@ -37,7 +37,10 @@ local AI/search/voice services
         +--> Whisper :18811
 ```
 
-See also: [`swarm-infrastructure.html`](./swarm-infrastructure.html) for a visual architecture diagram.
+See also:
+
+- [`swarm-infrastructure.html`](./swarm-infrastructure.html) — visual architecture diagram
+- [`diagram-maintenance.md`](./diagram-maintenance.md) — how to keep diagrams updated and when to create new ones
 
 ## Runtime layers