Merge pull request 'Document the Vaultwarden fetch contract' (#12) from secrets-out-of-the-box into main

Reviewed-on: #12

docs/VAULTWARDEN-DOMEDOG-FINDINGS-2026-06-19.md

@@ -0,0 +1,81 @@
+# Vaultwarden Connectivity — domedog Findings (2026-06-19, updated)
+
+**Host:** domedog (`domedog.pro`, Linux)
+**Agent:** Claude
+**PRs under evaluation:** clawdie-iso #65 (merged as #67) + clawdie-ai #14 (doc contract)
+
+## Test results — end-to-end PASS ✅
+
+Full chain proven: bootstrap creds → `bw` login → unlock → fetch → `.env` → re-lock.
+
+| Step             | Command                                                   | Result                                              |
+| ---------------- | --------------------------------------------------------- | --------------------------------------------------- |
+| Server reachable | `curl -sI https://vault.smilepowered.org/`                | ✅ HTTP 200 (Rocket/Vaultwarden)                    |
+| bw CLI installed | `bw --version`                                            | ✅ 2026.5.0                                         |
+| API key login    | `bw login --apikey` (via `BW_CLIENTID`/`BW_CLIENTSECRET`) | ✅ Logged in as `samo.blatnik@gmail.com`            |
+| Vault unlock     | `bw unlock --passwordenv BW_PASSWORD`                     | ✅ Unlock succeeds — master password is correct     |
+| Fetch item       | `clawdie-vault-fetch --keys DEEPSEEK_API_KEY`             | ✅ Resolved 1 of 1 key                              |
+| Write to `.env`  | `--write-env /tmp/smoke.env`                              | ✅ Written 0600, value correct (35 chars, `sk-...`) |
+| Re-lock on exit  | trap cleanup                                              | ✅ Vault re-locked automatically                    |
+
+## The test item
+
+A `DEEPSEEK_API_KEY` login item was created in the `agent-secrets` collection,
+with the **item name = the env var name** and the **value in the password
+field**, per the documented contract. The helper fetched it cleanly with
+`bw get password DEEPSEEK_API_KEY` — confirming the name-based retrieval
+contract works.
+
+## One real bug found and fixed
+
+**`clawdie-vault-fetch` failed when `bw` was already logged in.**
+
+`bw config server "$SERVER"` refuses with `Logout required before server config
+update` when the CLI is already authenticated. The helper treated that as fatal
+(`exit 1`), which broke **every repeat run** on a host that is already logged in
+— including the very case the helper exists for (refresh `.env` from the vault
+on demand).
+
+The `bw login` block already tolerated the analogous "already logged in" case.
+Fix (clawdie-iso, branch `fix/vault-fetch-bw-config-when-logged-in`): mirror
+that pattern for `bw config` — capture stderr/stdout and tolerate
+`logout required` / `already configured` / `already set`, failing only on a
+real error. Verified: the fixed helper runs cleanly from the logged-in state
+(previously exited 1 at the config step).
+
+## Correction to the earlier draft
+
+An earlier draft of this doc reported `bw unlock` failing with
+`Decryption failed` and concluded the master password was wrong. That was
+incorrect: the unlock failure was a side effect of running the flow against a
+**stale logged-in session**. After `bw logout` and a clean re-run, unlock
+succeeds with the **same** master password — it was never wrong. The only
+defect was the `bw config` intolerance documented above.
+
+## Setup state on domedog
+
+- `bw` 2026.5.0 installed at `~/.nvm/versions/node/v22.22.0/bin/bw`.
+- Helper staged at `~/.colibri/clawdie-vault-fetch` (the fixed version).
+- Bootstrap env at `~/.config/vault-bootstrap.env` (0600) — `BW_CLIENTID`,
+  `BW_CLIENTSECRET`, and `BW_PASSWORD` all correct and verified by a successful
+  fetch.
+- Server set to `https://vault.smilepowered.org`.
+
+## Not wired yet (documented follow-ups)
+
+- **Runtime consumption:** the helper fetches into a `.env`, but nothing yet
+  loads that `.env` into a running agent's environment at launch. This is the
+  next milestone (soul load + harness launch).
+- **Auto-refresh:** no scheduled/firstboot caller of the helper yet — it is run
+  manually. The `bw config` bug fix is a prerequisite for auto-refresh to be
+  reliable.
+
+## PR #65 / #14 assessment
+
+**Code quality:** solid. `clawdie-vault-fetch` has trap-based lock-on-exit,
+headless `--apikey` login, tolerates "already logged in", sensible exit codes
+(0/1/3/4), and a `--write-env` upsert that preserves untouched keys at 0600.
+The one repeat-run bug (`bw config` intolerance) is fixed in a follow-up.
+
+**No blockers** to the runtime-consumption milestone. The secret→`.env` path is
+proven; what remains is having an agent read it.

docs/VAULTWARDEN-SETUP.md

@@ -163,6 +163,60 @@ clawdie-vault-fetch --write-env ~/.env
 bw lock
 ```
 
+## Runtime fetch: `clawdie-vault-fetch`
+
+The manual flow above is the operator/agent CLI path. For a host to pull its own
+provider keys **out of the box**, the image ships a small language-neutral
+helper, `clawdie-vault-fetch` (`/usr/local/bin/`), that the post-install setup
+flow shells out to and the live USB can run directly. It depends only on `bw` —
+no node module, no `jq`.
+
+### Item-naming convention (the contract)
+
+For a secret to be auto-fetchable, store it in `agent-secrets` as a **login item
+whose name is exactly the env var name**, with the value in the **password
+field**:
+
+| Item name            | Field    | Becomes                |
+| -------------------- | -------- | ---------------------- |
+| `ANTHROPIC_API_KEY`  | password | `ANTHROPIC_API_KEY=…`  |
+| `OPENAI_API_KEY`     | password | `OPENAI_API_KEY=…`     |
+| `OPENROUTER_API_KEY` | password | `OPENROUTER_API_KEY=…` |
+| `ZAI_API_KEY`        | password | `ZAI_API_KEY=…`        |
+
+The default key set mirrors clawdie-ai's `PROVIDER_KEY_BY_PROVIDER` (anthropic,
+openai, openrouter, zai, deepseek, gemini, groq). `bw get password <NAME>`
+returns the raw value, so no JSON parsing is involved.
+
+### Bootstrap drop (the one secret that can't live in the vault)
+
+The helper reads `~/.config/vault-bootstrap.env` (mode 0600) for the headless
+credentials — exactly the file from the [Bootstrap Flow](#bootstrap-flow) above:
+
+```sh
+BW_CLIENTID=user....
+BW_CLIENTSECRET=...
+BW_PASSWORD=<master-password>
+```
+
+**No bootstrap file → the helper exits cleanly and does nothing**, so a host with
+no vault access still uses the manual setup wizard. That is the floor; the vault
+fetch only ever adds.
+
+### Usage
+
+```sh
+clawdie-vault-fetch                    # print KEY=VALUE lines to stdout
+clawdie-vault-fetch --write-env FILE   # upsert results into FILE (0600), keys preserved
+clawdie-vault-fetch --bootstrap FILE   # explicit bootstrap env file
+clawdie-vault-fetch --keys "A B C"     # override the key-name list
+```
+
+Exit codes let a caller tell "skip" from "broken": `0` ran cleanly · `1` vault
+configured but login/unlock/fetch failed · `3` no bootstrap config (fall back to
+manual) · `4` `bw` not installed. The helper always `bw lock`s on exit and never
+logs secret values.
+
 ## Current items in agent-secrets
 
 | Name                 | Type  | Purpose                                                  |

infra/packages/host-baseline.txt

@@ -9,6 +9,8 @@ tmux
 btop
 bsddialog
 codex
+# python3 is 3.11 (FreeBSD PYTHON_DEFAULT); python312 available as python3.12.
+python311
 python312
 uv
 ripgrep
@@ -16,6 +18,10 @@ fd-find
 rsync
 postgresql18-client
 dnsmasq
+# hermes runtime: ffmpeg (media + voice-transcription), py311-pillow (Pillow
+# core dep; venvs use --system-site-packages so the system pkg satisfies it).
+ffmpeg
+py311-pillow
 dejavu
 rust