From 4ef981e45670cd2b893451f338fa00af7748bc63 Mon Sep 17 00:00:00 2001
From: Aaron Wood <aaron.wood@mac.lan>
Date: Sat, 11 Apr 2026 16:44:59 -0400
Subject: [PATCH] docs: fix handbook setup instructions and clarity issues

---
 docs/HANDBOOK.md | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/docs/HANDBOOK.md b/docs/HANDBOOK.md
index a608abf..2048d58 100644
--- a/docs/HANDBOOK.md
+++ b/docs/HANDBOOK.md
@@ -104,7 +104,7 @@ Combat state persists to the database. If the server restarts mid-fight, the tra
 
 ### DM View
 
-The DM sees all characters in a compact 3-up card grid showing: HP (current/max), AC, luck token state, torch timer, and all stat modifiers at a glance. The full character detail is one click away.
+The DM sees all characters in a compact three-column card grid showing: HP (current/max), AC, luck token state, torch timer, and all stat modifiers at a glance. The full character detail is one click away.
 
 ## What's coming next
 
@@ -167,7 +167,19 @@ docker run -d --name darkwatch-maria \
 
 **2. Set up environment**
 
-Copy `server/.env.example` to `server/.env` (or ensure `server/.env` exists with DB credentials pointing to port 3307).
+Create `server/.env` with these variables:
+
+```
+DB_HOST=127.0.0.1
+DB_PORT=3307
+DB_NAME=darkwatch
+DB_USER=darkwatch
+DB_PASSWORD=darkwatch
+JWT_SECRET=devsecret
+CLIENT_URL=http://localhost:5173
+PORT=3000
+NODE_ENV=development
+```
 
 **3. Start the server**
 
@@ -187,9 +199,9 @@ npm install
 npm run dev -- --host
 ```
 
-The client runs on `http://localhost:5173` (or the next available port). The `--host` flag exposes it on the local network (useful for testing on a phone via ngrok).
+The client runs on `http://localhost:5173` (or the next available port). The `--host` flag exposes it on the local network for device testing.
 
-**Dev seed accounts:**
+**Dev seed accounts** (created automatically on first server startup):
 - DM: `dm@darkwatch.test` / `password`
 - Player: `player@darkwatch.test` / `password`
 
@@ -266,7 +278,7 @@ Auth uses JWT stored in httpOnly cookies. The token contains `{ userId }`. On so
 Campaign roles (DM or player) are stored in the `campaign_members` table. Role enforcement happens:
 - REST routes: middleware checks `campaign_members` before handling requests
 - Socket handlers: `checkDM()` queries `campaign_members` for DM-only events
-- Frontend: `role === "dm"` gates DM-only UI elements
+- Frontend: `role === "dm"` gates DM-only UI elements — role comes from `AuthContext` and is passed as a prop to campaign view components
 
 ### All imports use `.js` extensions
 
@@ -284,6 +296,9 @@ Vite and tsx resolve `.js` to the TypeScript source at build/dev time.
 We use a structured approach: **brainstorm → spec → plan → implement**.
 
 1. **Brainstorm** (`/brainstorm` skill) — collaborative design session; produces a spec doc
+
+> Skills are Claude Code slash commands defined in `.claude/skills/` — invoke them inside a Claude Code session.
+
 2. **Spec** saved to `docs/superpowers/specs/YYYY-MM-DD-feature-design.md`
 3. **Plan** (`/writing-plans` skill) — detailed implementation plan with code in every step
 4. **Plan** saved to `docs/superpowers/plans/YYYY-MM-DD-feature.md`