🏘 QUEEN RUNBOOK

village ops · vault · spine · dashboards — copy-paste ready

Daily ritual #

Double-click from File Explorer:

C:\Users\acebu\Desktop\queen-sync.cmd

Or from Git Bash:

bash ~/projects/mcp-and-skills-framework-and-brain-v3/hooks/queen-sync.sh

Prompts master password once, renders ~/.claude/secrets.env (78 items), runs checks, shows recent sessions.

First-time install (reimage recipe) #

  1. Install Git for Windows — ships Git Bash.
  2. Install Node.js 20+ (nodejs.org, not Windows Store).
  3. Clone the repo:
git clone https://github.com/mygebruikernaam/mcp-and-skills-framework-and-brain-v3.git \
  ~/projects/mcp-and-skills-framework-and-brain-v3

Install bw CLI + copy Desktop shims:

cd ~/projects/mcp-and-skills-framework-and-brain-v3
bash hooks/install-bw.sh
cp hooks/queen-sync.cmd hooks/village-unlock-vault.cmd hooks/fix-ssh-config-perms.cmd ~/Desktop/

Then run queen-sync.cmd from Desktop — first run logs you in, subsequent runs unlock.

Fix SSH "Bad permissions" error #

Windows OpenSSH refuses .ssh/config with inherited ACEs. Run once per config file:

C:\Users\acebu\Desktop\fix-ssh-config-perms.cmd

Runs icacls /inheritance:r + /grant:r %USERNAME%:F, smoke-tests SSH to cax31.

Gotchas #

Python: use py -3 in scripts, not python3. The python3 shim in PATH hits the Microsoft Store stub.
Never use bare bash in .cmd files: WSL 2.6.3 is installed without a distro, its bash.exe stub hijacks PATH. Always use the absolute "C:\Program Files\Git\bin\bash.exe".
Box-drawing in .cmd: cmd.exe defaults to CP437 and mangles Unicode ═══. Add chcp 65001 >nul 2>&1 at the top, or use ASCII ===.

Daily ritual #

bash ~/projects/mcp-and-skills-framework-and-brain-v3/hooks/queen-sync.sh

Or with alias (add once to ~/.bashrc):

alias queen-sync="bash ~/projects/mcp-and-skills-framework-and-brain-v3/hooks/queen-sync.sh"

Then just type queen-sync from anywhere on spud2.

First-time install (bootstrap) #

Assumes repo already cloned at ~/projects/mcp-and-skills-framework-and-brain-v3 and node/npm already installed (/usr/local/bin/node).

cd ~/projects/mcp-and-skills-framework-and-brain-v3
git pull
bash hooks/install-bw.sh
bash hooks/queen-sync.sh

First run prompts bw login (email + master password + 2FA). Subsequent runs prompt master password only.

SSH to cax31 #

ssh root@100.97.123.98

Tailscale mesh. Also ssh root@204.168.163.51 via public IP.

SSH from dolphin to spud2 #

ssh nectar4362@100.64.38.99

⚠ Admin only #

Never install Claude Code on cax31. Production box. Admin via SSH from dolphin or spud2 only. Per ~/.claude/CLAUDE.md invariant.

SSH in #

ssh root@100.97.123.98

Tailscale. Public: ssh root@204.168.163.51.

Brain DB (read-only) #

Safe default — claude_ro can only SELECT from v_* views. secrets table is blocked.

ssh root@100.97.123.98 'docker exec postgres psql -U claude_ro -d brain -c "SELECT * FROM v_learnings LIMIT 10"'

Brain DB (write) #

Announce first. acebuddy role is privileged. State the SQL before running.
ssh root@100.97.123.98 'docker exec postgres psql -U acebuddy -d brain -c "..."'

Health check #

Row counts across the v2 spine:

ssh root@100.97.123.98 'docker exec postgres psql -U acebuddy -d brain -c "
SELECT '\''sessions'\'', COUNT(*) FROM v2.sessions
UNION ALL SELECT '\''turns'\'', COUNT(*) FROM v2.turns
UNION ALL SELECT '\''personas'\'', COUNT(*) FROM v2.personas
UNION ALL SELECT '\''hook_fires'\'', COUNT(*) FROM v2.hook_fires
UNION ALL SELECT '\''repos'\'', COUNT(*) FROM v2.repos
UNION ALL SELECT '\''narrations'\'', COUNT(*) FROM v2.narrations;"'

Vaultwarden #

Add a secret to Vaultwarden #

  1. Open vault.acebuddy.quest in a browser, log in.
  2. New item → type: Login.
  3. Name: api/<provider> (e.g. api/openai-prod). The api/ prefix is required — sync-secrets.sh filters by it.
  4. Username: <ENV_VAR_NAME> (e.g. OPENAI_API_KEY). Must be SCREAMING_SNAKE_CASE or it gets skipped.
  5. Password: the actual secret value.
  6. Save.
  7. On each machine, re-run queen-sync to pick it up.

Rotate a secret #

  1. Update the item's password field in Vaultwarden web UI.
  2. On each machine: queen-sync → re-renders ~/.claude/secrets.env.
  3. Restart any long-running process that cached the old value (Claude Code sessions pick up fresh env on session-start).

How scripts access secrets #

Vault is source of truth, ~/.claude/secrets.env is the rendered cache (0600).

# In ~/.bashrc (once):
[ -f ~/.claude/secrets.env ] && source ~/.claude/secrets.env

Then in Python:

import os
key = os.environ["OPENAI_API_KEY"]  # microseconds. No network call.

Live-checkout (rare, for the most sensitive secrets, never cached to disk):

key = subprocess.run(["bw", "get", "password", "api/nuclear-codes"],
                     capture_output=True, text=True, check=True).stdout.strip()

~500 ms per call. Requires bw unlocked.

Recent Claude Code sessions #

ssh root@100.97.123.98 'docker exec postgres psql -U claude_ro -d brain -c "
SELECT to_char(started_at, '\''MM-DD HH24:MI'\''), metadata->>'\''host'\'', turn_count, substring(id::text, 1, 8)
FROM v2.sessions
ORDER BY started_at DESC LIMIT 10"'

Troubleshoot #

Vault says "unauthenticated"

Run queen-sync. It'll route through bw login (email + master password + 2FA on first machine ever).

Vault says "locked"

Run queen-sync. It'll prompt master password and cache the session.

sync-secrets shows "0 items"

Vault session expired or vault empty. Re-unlock via queen-sync. If still 0, check Vaultwarden has api/*-prefixed items.

Invalid API Key; Organization API Key currently not supported

You're trying bw login --apikey with an org key. Vaultwarden server keys (stored in /opt/acebuddy/.env) are org keys and can't log you in as a user. Use email + master password instead — that's what queen-sync does.

Node install fails with rxjs range.js error

Node 18 + @bitwarden/cli have a known dep graph bug. Use Node 20+ (NodeSource on Linux, nodejs.org on Windows).