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

Reviewed-on: #12

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                                                  |