docs(#2012): add first-run setup guide + link from index

CLAUDE.md

@@ -68,6 +68,8 @@ hand-maintained per-file tree drifts out of sync with the code.
 Pick the doc that matches your task. None depend on the others —
 read them à la carte.
 
+- **"How do I bring a fresh hive online (first-run hivectl
+  bootstrap)?"** → [`docs/setup.md`](docs/setup.md).
 - **"What does the dashboard look like?"** →
   [`docs/web-ui.md`](docs/web-ui.md) (index; sub-pages:
   [`shape`](docs/web-ui/shape.md),

docs/setup.md

@@ -0,0 +1,105 @@
+# First-run setup (fresh-deploy bootstrap)
+
+How to bring a fresh hyperhive hive online: provision accounts, open
+the gateway, make matrix reachable, and spawn the first sub-agents.
+
+Aimed at `ruth` (the root/manager agent) on a fresh deploy, but it's a
+plain reference doc — read it whenever you need the bootstrap command
+sequence. All `hivectl` commands below run as **root on the host** (not
+inside an agent container); the `request_*` steps run from ruth's own
+turn via the MCP tools.
+
+## Step-by-step
+
+### 1 · Forge
+
+```bash
+# Provision (or refresh) ruth's own forge account — do this first
+hivectl forge create-user ruth
+
+# Create a human operator account (prints the token to stdout)
+hivectl forge create-user mara --password hunter2
+
+# Provision forge accounts for any sub-agents spawned later
+hivectl forge create-user <agent>
+```
+
+### 2 · Gateway (HTTP Basic auth)
+
+```bash
+# Add an operator login to the gateway (reads password from stdin)
+echo "hunter2" | hivectl gateway create-user mara --password-stdin
+
+# List existing users
+hivectl gateway list-users
+```
+
+### 3 · Matrix
+
+```bash
+# 3a. Ensure the hive-internal admin account exists first
+hivectl matrix sync-admin
+
+# 3b. Provision ruth's own matrix account
+hivectl matrix create-user ruth
+
+# 3c. Create a human matrix account
+hivectl matrix create-user mara --password hunter2
+
+# 3d. Invite the operator to the hive Space (and optionally to rooms)
+hivectl matrix invite mara
+hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'
+
+# 3e. Promote the operator to homeserver admin if needed
+hivectl matrix promote-user mara
+```
+
+### 4 · Spawn sub-agents
+
+Sub-agent creation goes through the approval queue — ruth proposes, the
+operator approves, the container builds. From ruth's own turn (inside
+the container, via MCP tools):
+
+```
+# Step 1: initialise a new agent's config repo
+request_init_config(name: "iris")
+# → operator approves → config_ready event lands in the inbox
+
+# Step 2: edit /agents/iris/config/agent.nix, commit it, then:
+request_apply_commit(agent: "iris", commit_ref: "<sha>")
+# → operator approves → container built + started
+```
+
+See [`approvals.md`](approvals.md) for the full two-step flow.
+
+### 5 · Useful host commands
+
+```bash
+# Roster: all agents, status, rev, parent, pending reminders
+hivectl agents list
+
+# Restart a stuck container (no rebuild)
+hivectl agents restart <agent>
+
+# Open a Claude session inside an agent's container
+hivectl choom <agent>
+
+# Open hive web surfaces in a browser (or just print the URLs)
+hivectl open           # operator dashboard
+hivectl open forge     # Forgejo
+hivectl open matrix    # Matrix GUI (fluffychat)
+```
+
+See [`tools/hivectl.md`](tools/hivectl.md) for every `hivectl` verb.
+
+## Security notes
+
+- **No forge admin token is stored in any agent state dir.** Agents
+  hold a regular agent token in their `forge-token` file; sensitive
+  creds (the core token, the matrix admin token) live on the host.
+- All config changes (`request_apply_commit`) go through operator
+  approval — agents can't unilaterally rebuild containers, by design.
+  See [`boundary.md`](boundary.md) and [`security.md`](security.md).
+
+Once the hive is running, ruth records anything it needs to remember
+across restarts in `/agents/ruth/state/notes.md`.