From fe2b2191ca65978d1eec91a78d659b44b35e3e30 Mon Sep 17 00:00:00 2001
From: Sam & Hermes <hello@clawdie.si>
Date: Fri, 29 May 2026 14:48:00 +0200
Subject: [PATCH] docs: self-serve Vaultwarden setup guide for agents (Sam &
 Hermes)

---
 docs/VAULTWARDEN-SETUP.md | 89 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
 create mode 100644 docs/VAULTWARDEN-SETUP.md

diff --git a/docs/VAULTWARDEN-SETUP.md b/docs/VAULTWARDEN-SETUP.md
new file mode 100644
index 0000000..cee1dc1
--- /dev/null
+++ b/docs/VAULTWARDEN-SETUP.md
@@ -0,0 +1,89 @@
+# Vaultwarden Setup for Agents
+
+Secrets store: `vault.smilepowered.org` (Vaultwarden, self-hosted).  
+Organization: **Clawdie** (39727691-3403-4c50-89b8-d5f24310e79c).  
+Collection: `agent-secrets` (94ba61b8-633c-454e-b749-f115617eeac3).
+
+Agents use the `bw` CLI to retrieve secrets programmatically — no passwords in chat.
+
+## Prerequisites
+
+- Node.js (for npm install) or a pre-built `bw` binary
+- Org API key from the operator (Samo or Hermes on debby)
+
+## Setup
+
+### 1. Install bw CLI
+
+```sh
+npm install -g @bitwarden/cli
+# or download binary from https://github.com/bitwarden/clients/releases
+```
+
+### 2. Configure server
+
+```sh
+bw config server https://vault.smilepowered.org
+```
+
+### 3. Get API key from operator
+
+Ask Samo or Hermes to generate an org API key scoped to the `agent-secrets` collection.
+You'll receive:
+- `BW_CLIENTID` (starts with `organization.`)
+- `BW_CLIENTSECRET`
+
+The operator also provides the master password for unlocking. This is shared
+across the org — handle it like any other secret.
+
+### 4. Login and unlock
+
+```sh
+# One-time login
+bw login --apikey
+# → paste client_id and client_secret when prompted
+
+# Every session: unlock
+bw unlock --passwordenv BW_PASSWORD
+# → copy the BW_SESSION value from output
+
+export BW_SESSION="..."
+```
+
+Alternative for scripting (no prompts):
+
+```sh
+export BW_CLIENTID="organization...."
+export BW_CLIENTSECRET="..."
+
+bw login --apikey          # uses env vars if set
+bw unlock --passwordenv BW_PASSWORD
+# → export BW_SESSION from output
+```
+
+### 5. Retrieve a secret
+
+```sh
+bw list items --session "$BW_SESSION" --search "hermes-debby" | jq '.[0].login'
+# or get by ID
+bw get item <item-id> --session "$BW_SESSION"
+```
+
+### 6. Lock when done
+
+```sh
+bw lock
+```
+
+## Current items in agent-secrets
+
+| Name | Type | Purpose |
+|------|------|---------|
+| hermes-debby Forgejo | login | Hermes's code.smilepowered.org password (browser access) |
+
+## 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.
+- 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`.
-- 
2.45.3