docs: production architecture (mermaid), KNELBMS integration, README

Component + sequence + rotation-flow diagrams; consumer pattern; KNELBMS
secrets-flow table + provisioning sequence; README to prod standard.
Ticket: https://projects.knownelement.com/issues/832

README.md

@@ -1,5 +1,43 @@
-# KNELSecretsManager (ARCHIVED — moved to KNEL/secrets)
+# KNELSecretsManager
 
-This body of work moved to **[KNEL/secrets](https://git.knownelement.com/KNEL/secrets)** per the 2026-09-03 repo split ([#769](https://projects.knownelement.com/issues/769)); content was ported as `legacy-knelsecretsmanager/` (secret-scanned clean — placeholders only).
+Fleet secrets management: a **pure-Go Bitwarden/Vaultwarden CLI** (`smcli`)
+in a house container, backed by the self-hosted TSGCOO vault. No upstream
+Rust `bw` binary, no Node runtime, no `.creds` text files — those patterns
+are retired (ADR-003; founder rulings #829/#832).
 
-This repo is historical. New secrets-management work happens in KNEL/secrets (#770).
+- Docs: [docs/architecture.md](docs/architecture.md) (diagrams, crypto, rotation program)
+- KNELBMS integration: [docs/integration-knelbms.md](docs/integration-knelbms.md)
+- Redmine: https://projects.knownelement.com/issues/832 (build) / #829 (migration+rotation)
+
+## Quick start (lane)
+
+```bash
+# TSGCOO account (COO-area chats; docker group, no sudo)
+/data2/TSGCOO/.local/bin/sm status
+
+# reachableceo crossover
+~/projects/KNEL/OAM/.tools/sm env creds/cloudron   # export URI/USERNAME/PASSWORD + keys
+~/projects/KNEL/OAM/.tools/sm get creds/librenms --field password
+~/projects/KNEL/OAM/.tools/sm setfield creds/<item> <KEY> <newvalue>   # rotation updates
+```
+
+## Layout
+
+| Path | What |
+|---|---|
+| `cli/cmd/smcli/` | the Go CLI (crypto, API, commands) |
+| `docker/Dockerfile.cli` | golang build → alpine runtime (CA certs, non-root) |
+| `docker/compose.yaml` | always-hot service `ukrrs-secretsmgr-cli` (digest-pinned) |
+| `archive/rust-bw-era/` | retired upstream-binary wrapper scripts |
+| `docs/ADR-003-GoCLI.md` | decision record |
+
+## Rules (binding)
+
+- Secrets live ONLY in the TSGCOO Bitwarden vault, accessed ONLY via this
+  CLI (container `ukrrs-secretsmgr-cli`, shims above). No textfile creds,
+  no upstream bw CLI — anywhere.
+- All work product is authored by Cloudron account identities
+  (ic-builder / ic-reviewer / manager-tsg / vptechops); the founder
+  account (ReachableCEO) reviews and approves.
+- Production-affecting rotations follow the CR gating + cross-linking
+  house rules (GLPI CR deep link in the PR/ticket; evidence on solve).

docs/architecture.md

@@ -0,0 +1,99 @@
+# KNELSecretsManager — Architecture
+
+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
+    S1 --> C
+    S2 --> C
+    W1 --> C
+    W2 --> C
+    W3 --> C
+    C -->|HTTPS: prelogin/login(TOTP)/sync/CRUD| V
+    C -.->|reads after rotation| B
+    C -.-> K
+    C -.-> R
+```
+
+## Auth + unlock sequence
+
+```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)
+```
+
+Item payloads are type-2 encStrings (AES-256-CBC + HMAC-SHA256, 32B enc +
+32B mac keys) encrypted/decrypted locally; the vault never sees plaintext.
+
+## Consumer pattern
+
+```bash
+# env-style consumers (export lines; URI/USERNAME/PASSWORD + original keys)
+eval "$(docker exec -i ukrrs-secretsmgr-cli smcli env creds/<name>)"
+# surgical single-field rotation update
+docker exec -i ukrrs-secretsmgr-cli smcli setfield creds/<name> <KEY> <newvalue>
+```
+
+Items are LOGIN type: username + password/API-key as first-class fields,
+service URLs as URIs, remaining keys as named custom fields (hidden where
+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
+from a failed rotation):
+
+1. Tooling tokens (librenms*, wazuh ✓, 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)
+4. Deep-wired (flux PAT + gitea runner + HA on-box secrets.yaml + k8s
+   secrets + PVE upsagent tokens)
+
+\* item-specific notes: librenms — token-mint API route absent on this
+install (UI/DB path); grafana — SSO-managed, local admin parked (instance
+password policy blocks CLI reset).
+
+## KNELBMS integration
+
+See [integration-knelbms.md](integration-knelbms.md). Short form: the BMS
+deploy pipeline (KNELBMS repo, packages/deploy_pipeline.yaml) consumes
+`gitea_auth_header` + `kuma_push_url` + `pve_*_api_token` from on-box
+`/config/secrets.yaml`; the vault is the source of record and rotations
+push to the box through the CR-gated provisioning path.

docs/integration-knelbms.md

@@ -0,0 +1,50 @@
+# 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).
+
+## 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 |
+| `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 |
+| `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 |
+
+## Provisioning + rotation flow
+
+```mermaid
+sequenceDiagram
+    participant R as Rotation run (#829 wave)
+    participant V as TSGCOO vault
+    participant B as pfv-bms on-box 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
+```
+
+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).
+- 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).
+- The dead-man heartbeat (`pfv-bms-ha-heartbeat-2026-09`, Kuma id 291)
+  is the canary for provisioning mistakes: if the on-box secret and the
+  vault disagree, the push fails and the monitor pages.
+
+## Current integration state (2026-09-06)
+
+- On-box `secrets.yaml` provisioned manually under CR 21 (PVE tokens +
+  rotated Kuma push URL); git-side KNELBMS matches for the `!secret`
+  keys it owns (PR #6 on dev, awaiting founder release merge).
+- Automated push-from-vault (rotation waves writing the box directly via
+  the AWX ssh path) is **planned, not built** — wave 4. Until then the
+  table above is the manual runbook, executed under CR.