docs QA: diagrams must parse in a real mermaid renderer

The first architecture set did not render (backslash-n escapes,
semicolons in sequence messages, braces in text). All diagrams
rewritten to conservative syntax and QA-verified with mermaid-cli
(3/3 PARSE-OK). qa-diagrams.sh added; CI enforces it on docs changes.

Ticket: https://projects.knownelement.com/issues/832

docs/architecture.md

@@ -1,35 +1,29 @@
 # KNELSecretsManager — Architecture
 
-Status: production. Ruling chain: ADR-002 (containerized CLI) → ADR-003
+Status: production. Ruling chain: ADR-002 (containerized CLI) -> ADR-003
 (pure-Go `smcli`, Rust `bw` retired). Founder directives: #829/#832.
 
 ## Components
 
 ```mermaid
 flowchart LR
-    subgraph vault["TSGCOO Bitwarden vault (self-hosted)"]
-        V["pwvault.turnsys.com\n(Vaultwarden API)"]
-    end
-    subgraph workstation["Workstation (dev-only host)"]
-        C["ukrrs-secretsmgr-cli\n(compose, always-hot)\npure-Go smcli v9+"]
-        S1["/data2/TSGCOO/.local/bin/sm\n(TSGCOO account entry)"]
-        S2[".tools/sm\n(reachableceo crossover)"]
-        W1["mred-vp → Redmine identity"]
-        W2["ci-green.sh → Gitea admin"]
-        W3["redmine-sweep.sh"]
-    end
-    subgraph fleet["Fleet consumers (rotation waves)"]
-        B["KNELBMS: on-box secrets.yaml\n(deploy webhook, gitea_auth_header,\nkuma_push_url, pve_*_api_token)"]
-        K["pfv-k8s secrets\n(glpi-creds for kuma-glpi-bridge,\nflux PAT — wave 4)"]
-        R["Nightly timers\n(pve-config-backup, glpi-reconcile)"]
-    end
+    V["Vaultwarden vault - pwvault.turnsys.com"]
+    C["smcli container - ukrrs-secretsmgr-cli"]
+    S1["TSGCOO entry - data2 TSGCOO bin sm"]
+    S2["lane crossover - tools sm"]
+    W1["mred-vp - Redmine identity"]
+    W2["ci-green.sh - Gitea admin"]
+    W3["redmine-sweep.sh"]
+    B["KNELBMS on-box secrets.yaml"]
+    K["pfv-k8s secrets - glpi-creds, flux PAT"]
+    R["nightly timers - pve backup, glpi reconcile"]
     S1 --> C
     S2 --> C
     W1 --> C
     W2 --> C
     W3 --> C
-    C -->|HTTPS: prelogin/login(TOTP)/sync/CRUD| V
-    C -.->|reads after rotation| B
+    C -->|HTTPS login sync CRUD| V
+    C -.-> B
     C -.-> K
     C -.-> R
 ```
@@ -38,22 +32,22 @@ flowchart LR
 
 ```mermaid
 sequenceDiagram
-    participant U as Operator/Consumer
-    participant S as smcli (container)
-    participant V as pwvault.turnsys.com
-    U->>S: smcli login (SM_EMAIL, SM_PASSWORD, SM_TOTP_SECRET)
-    S->>V: POST /api/accounts/prelogin {email}
-    V-->>S: kdf type + iterations (PBKDF2 600k / Argon2id)
-    S->>S: masterKey = KDF(password, email); authHash = PBKDF2(masterKey, password, 1)
-    S->>V: POST /identity/connect/token (password grant, device fields)
-    V-->>S: 400 Two factor required (provider 0)
-    S->>S: TOTP code from SM_TOTP_SECRET (RFC 6238)
-    S->>V: token request + twoFactorToken
-    V-->>S: access_token (+Key, PrivateKey)
-    S->>V: GET /api/sync
-    V-->>S: profile.key (enc, type 2)
-    S->>S: stretchedKey = HKDF(masterKey,"enc"/"mac"); userSymKey = decrypt(profile.key)
-    S->>S: state.json 0600 (master/stretched/user keys + token)
+    participant U as Consumer
+    participant S as smcli
+    participant V as Vault
+    U->>S: login with email password TOTP seed
+    S->>V: POST prelogin - get KDF params
+    V-->>S: PBKDF2 iterations or Argon2id
+    S->>S: derive master key and auth hash
+    S->>V: POST identity connect token
+    V-->>S: 400 - two factor required
+    S->>S: compute TOTP code - RFC 6238
+    S->>V: token request plus twoFactorToken
+    V-->>S: access token and encrypted keys
+    S->>V: GET sync
+    V-->>S: profile key - encrypted
+    S->>S: stretch master key - decrypt user key
+    S->>S: write state file 0600
 ```
 
 Item payloads are type-2 encStrings (AES-256-CBC + HMAC-SHA256, 32B enc +
@@ -75,11 +69,11 @@ secret). Original env key names are preserved as the custom-field names.
 ## Rotation program (#829)
 
 All pre-migration material is presumed BURNED (plaintext on disk + LLM
-exposure). Waves, each item = rotate at source → `setfield` in vault →
-rewire consumers to `sm env` → validate (guard rule: never write the vault
+exposure). Waves, each item = rotate at source -> `setfield` in vault ->
+rewire consumers to `sm env` -> validate (guard rule: never write the vault
 from a failed rotation):
 
-1. Tooling tokens (librenms*, wazuh ✓, grafana*, gvm, technitium, phpipam,
+1. Tooling tokens (librenms*, wazuh DONE, grafana*, gvm, technitium, phpipam,
    rancher-sectest, beszel, pihole, PMG pair, PBS tokens)
 2. Agent identities (gitea agent-stack, vptechops gitea/redmine)
 3. Platform (cloudron API token, kuma, discourse)

docs/integration-knelbms.md

@@ -1,15 +1,15 @@
 # KNELBMS integration — secrets flow
 
 Repo: https://git.knownelement.com/KNEL/KNELBMS (PhysicalPlant lane;
-Home Assistant BMS on VM 100 @ pfv-tsys1, dev→release deploy by git).
+Home Assistant BMS on VM 100 @ pfv-tsys1, dev -> release deploy by git).
 
 ## What the BMS consumes
 
 | On-box secret (HA `secrets.yaml`) | Vault item + field | Provenance |
 |---|---|---|
-| `gitea_auth_header` | `creds/pfv-bms-deploy` → GITEA_DEPLOY_WATCH_TOKEN | release-branch sha-watch REST sensor |
+| `gitea_auth_header` | `creds/pfv-bms-deploy` -> GITEA_DEPLOY_WATCH_TOKEN | release-branch sha-watch REST sensor |
 | `deploy_webhook_id` / `pfv_relay_webhook_id` | `creds/pfv-bms-deploy` | fast-path deploy webhook |
-| `kuma_push_url` | `creds/pfv-bms-beta` sibling — dead-man monitor `pfv-bms-ha-heartbeat-2026-09` (push token) | rotated 2026-09-06 under CR 21 |
+| `kuma_push_url` | dead-man monitor `pfv-bms-ha-heartbeat-2026-09` push token | rotated 2026-09-06 under CR 21 |
 | `pve_tsys{1,3,4,5,6,7}_api_token` | `creds/pve-upsagent` (per-node fields) | `upsagent@pam!ups`, PVEAdmin-on-/vms, privsep=0 |
 | `doorman_*`, `pfvbms_smb_*`, beta HA creds | respective `creds/*` items | as rotated |
 
@@ -17,22 +17,22 @@ Home Assistant BMS on VM 100 @ pfv-tsys1, dev→release deploy by git).
 
 ```mermaid
 sequenceDiagram
-    participant R as Rotation run (#829 wave)
-    participant V as TSGCOO vault
-    participant B as pfv-bms on-box secrets.yaml
+    participant R as Rotation run - 829 wave
+    participant V as Vault
+    participant B as pfv-bms secrets.yaml
     participant H as Home Assistant
-    R->>V: new value (sm setfield creds/<item> <KEY>)
-    R->>B: CR-gated provisioning (ssh -p 22222, CR + ha core check)
-    R->>H: ha core restart (Kuma window; dead-man covers the gap)
-    H-->>R: post-deploy validation (entity/heartbeat checks)
-    R->>V: rotation evidence on #829
+    R->>V: setfield new value
+    R->>B: CR-gated provisioning - ssh port 22222
+    R->>H: ha core restart - Kuma window
+    H-->>R: post-deploy validation
+    R->>V: rotation evidence on ticket 829
 ```
 
 Rules that bind this flow (house rules + #811):
 
 - pfv-bms prod changes need a GLPI CR **and** a Kuma maintenance window
   when a restart is involved; the deploy path itself stays
-  dev → CI → release PR (founder merges).
+  dev -> CI -> release PR (founder merges).
 - HA runtime template contexts cannot read secrets — the on-box
   `shell_command` entries reference `!secret` names only (see KNELBMS
   PR #6 / CR 21 for the dead-man fix that taught us this).