docs: upgrade README to the docs standard

Purpose kept; adds dated status line, scope/non-goals (no admin UI,
memory-only), today-vs-planned table (KNELSecretsManager interim), and
links to the porting-notes study plus its open questions for Charles.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2

README.md

@@ -4,16 +4,50 @@ A 100% Go CLI for Bitwarden / Bitwarden Secrets Manager, replacing the Node
 `bw` CLI in supply-chain-sensitive (CMMC L3/TS posture) environments. One
 static binary, one auditable vendored module tree, no Node runtime.
 
+Status: 2026-08-28 — spec seed; reference study complete, open questions
+pending Charles, no code yet.
+
+## Scope
+
 - Talks to the Bitwarden Secrets Manager REST API directly with stdlib —
   NO official SDK (its source-available license is AGPL-incompatible).
 - Machine-account auth (access-token flow) for headless/agent use; human
   auth flows where needed.
 - Porcelain/plumbing model: `bwg get|set|list|sync ...` with JSON out for
   scripting, plain text for humans.
-- Pairs with ukrrs/mopac-keyproxy (placeholder keys to consumers; this CLI
+- Memory-only secrets handling: session token held in memory for the
-  is how material gets INTO the vault) but fully standalone.
+  process lifetime and zeroed on exit; values never written to logs, disk
-- AGPLv3. Part of the MOPAC family; composable by anyone, no org-specific
+  cache, REPORT files, or crash dumps; refs logged only in redacted form.
-  assumptions in code.
+- Pairs with [ukrrs/mopac-keyproxy](https://git.knownelement.com/ukrrs/mopac-keyproxy)
+  (placeholder keys to consumers; this CLI is how material gets INTO the
+  vault) but fully standalone.
 
-Status: specification phase. Building 2026-08-28 onward; reference study
+## Non-goals
-of KNEL/KNELSecretsManager in flight tonight.
+
+- No admin UI; a CLI and nothing else.
+- Not a vault server — Vaultwarden/Bitwarden stays the store of record.
+- No disk cache of secret values; no long-lived persisted sessions by
+  default (open question 4 below may change that, founder's call).
+- Not org-specific: hosts/credentials come from config and environment,
+  never baked in.
+
+## Today vs planned
+
+| | State |
+|---|---|
+| Today | Spec only (this README + LICENSE). Interim in production: the KNELSecretsManager containerized `bw` wrapper (ADR-002) — plain `bw` behind docker, plaintext env on disk, full login/unlock/sync per call. |
+| Planned | Go CLI per the reference study: `bw:` key-ref resolution for the MOPAC harness, lookup by item name (password field), per-process unlock, never `bw logout`, typed not-found/unlock errors, fake-bw test stub. |
+
+## Design references
+
+- [KNELSecretsManager study — current surface, replacement design sketch, open questions](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/docs/PORTING-NOTES-secrets.md)
+  (section 3 lists seven open questions for Charles: substrate, machine
+  account, ref syntax, session lifetime, secret names, scope, subprocess
+  injection)
+- [MOPAC harness DESIGN.md — Toolchain policy, 100% Go HARD RULE](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/DESIGN.md#user-content-toolchain-policy-charles-2026-08-28-evening--hard-rule)
+- [MOPAC harness DESIGN.md — Key proxy](https://git.knownelement.com/ukrrs/MOPAC/src/branch/main/DESIGN.md#user-content-key-proxy-placeholders-only-material-never-leaves-the-vault-charles-2026-08-28-evening)
+- Parent: [ukrrs/MOPAC](https://git.knownelement.com/ukrrs/MOPAC) — the harness whose `bw:` key refs this unblocks
+
+## License
+
+AGPLv3 — see [LICENSE](LICENSE).