docs/VAULTWARDEN-SETUP.md

@@ -6,10 +6,68 @@ Collection: `agent-secrets` (94ba61b8-633c-454e-b749-f115617eeac3).
 
 Agents use the `bw` CLI to retrieve secrets programmatically — no passwords in chat.
 
+> **Note:** `bw` CLI only accepts **personal** API keys (from Account Settings).  
+> Organization API keys are for the REST API, not the CLI. Do not use them here.
+
 ## Prerequisites
 
 - Node.js (for npm install) or a pre-built `bw` binary
-- Org API key from the operator (Samo or Hermes on debby)
+- A Vaultwarden user account — the operator (Samo) creates it and invites you to
+  the Clawdie org with access to the `agent-secrets` collection
+- Personal API key — you generate this from Account Settings → Security → Keys
+- Master password from the operator for vault unlock
+
+## Bootstrap Flow
+
+Vaultwarden has a circular bootstrap problem: an agent needs credentials to
+access Vaultwarden, but those credentials can't be stored in Vaultwarden itself
+as the only copy.
+
+**Operator's role:**
+1. Create a Vaultwarden user account for the agent.
+2. Invite the user to the Clawdie organization with access to `agent-secrets`.
+3. Share the master password via a secure channel (file drop, not chat).
+
+**Agent's role:**
+1. Generate personal API key: Account Settings → Security → Keys → View API Key.
+2. Write `BW_CLIENTID` (starts with `user.`), `BW_CLIENTSECRET`, and
+   `BW_PASSWORD` to a 0600 bootstrap file: `~/.config/vault-bootstrap.env`.
+3. Follow the Setup steps below to install `bw`, login, and unlock.
+4. Run the verification test before claiming Vaultwarden access works.
+5. Keep or remove the bootstrap file according to operator policy. If kept, it
+   must stay mode 0600 and must never be committed, pasted, or logged.
+6. Use `--passwordenv BW_PASSWORD` and `BW_SESSION` for all future access.
+
+**Why not self-serve:** a brand-new agent cannot pull credentials from Vaultwarden
+because it needs a personal API key + master password to unlock Vaultwarden. The
+operator must create the user account and deliver the master password out-of-band.
+
+## Verification Test
+
+After onboarding, verify with this smoke test — run from the agent host:
+
+```sh
+# 1. Load bootstrap env without echoing secrets.
+set -a
+. ~/.config/vault-bootstrap.env
+set +a
+
+# 2. Configure, login, unlock, and capture a raw session token.
+bw config server https://vault.smilepowered.org
+bw login --apikey
+BW_SESSION="$(bw unlock --raw --passwordenv BW_PASSWORD)"
+export BW_SESSION
+
+# 3. List items in agent-secrets collection.
+bw list items --session "$BW_SESSION" --collectionid 94ba61b8-633c-454e-b749-f115617eeac3 >/dev/null
+
+# 4. Retrieve the hermes-debby Forgejo username.
+bw list items --session "$BW_SESSION" --search "hermes-debby" | jq -r '.[0].login.username'
+
+# Expected output: hermes-debby
+```
+
+If the username resolves: Vaultwarden onboarding complete. Lock the vault (`bw lock`).
 
 ## Setup
 
@@ -26,15 +84,14 @@ npm install -g @bitwarden/cli
 bw config server https://vault.smilepowered.org
 ```
 
-### 3. Get API key from operator
+### 3. Get API key
 
-Ask Samo or Hermes to generate an org API key scoped to the `agent-secrets` collection.
+Generate your personal API key: Account Settings → Security → Keys → View API Key.
 You'll receive:
-- `BW_CLIENTID` (starts with `organization.`)
+- `BW_CLIENTID` (starts with `user.`)
 - `BW_CLIENTSECRET`
 
-The operator also provides the master password for unlocking. This is shared
-across the org — handle it like any other secret.
+The operator provides the master password (`BW_PASSWORD`).
 
 ### 4. Login and unlock
 
@@ -45,7 +102,7 @@ bw login --apikey
 
 # Every session: unlock
 bw unlock --passwordenv BW_PASSWORD
-# → copy the BW_SESSION value from output
+# → capture BW_SESSION from output
 
 export BW_SESSION="..."
 ```
@@ -53,7 +110,7 @@ export BW_SESSION="..."
 Alternative for scripting (no prompts):
 
 ```sh
-export BW_CLIENTID="organization...."
+export BW_CLIENTID="user...."
 export BW_CLIENTSECRET="..."
 
 bw login --apikey          # uses env vars if set
@@ -84,6 +141,7 @@ bw lock
 ## Rules
 
 - Never store `BW_CLIENTSECRET` or `BW_PASSWORD` in git, chat logs, or AGENTS.md.
-- Use `--passwordenv BW_PASSWORD` — the env var is safer than passing on command line.
+- If a client secret is exposed, rotate your personal API key immediately.
+- Use `--passwordenv BW_PASSWORD` — the env var is safer than on the command line.
 - Lock the vault (`bw lock`) after each session. Sessions auto-expire.
 - If you need a new secret stored, ask the operator to add it via `bw create item`.