From 1d9a06482a5dd8b1a1fb577742a9e63be808883b Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Mon, 17 Aug 2026 18:39:34 +0200
Subject: [PATCH] docs(setup): point operator forge/matrix account creation at
 swarm SSO

---
 docs/setup.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/docs/setup.md b/docs/setup.md
index 9af3819f..d5ec447c 100644
--- a/docs/setup.md
+++ b/docs/setup.md
@@ -21,16 +21,19 @@ operator has to place, and where.
 ### 1 · Forge
 
 ```bash
-# Provision (or refresh) ruth's own forge account — do this first
+# Provision (or refresh) ruth's own forge account — do this first. Ruth's
+# bootstrap bypasses the normal spawn-approval flow (see step 6), so unlike
+# every other agent it does not get its forge account auto-provisioned —
+# this manual step is still load-bearing.
 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>
+# Sub-agents spawned later (via the approval flow in step 6) get their
+# forge accounts auto-provisioned — nothing to run here for them.
 ```
 
+The human operator's own forge account is created via swarm SSO instead of
+a manual `hivectl` step — see step 3 (`swarmctl user add`).
+
 ### 2 · Gateway (HTTP Basic auth)
 
 ```bash
@@ -89,20 +92,21 @@ control: [`swarm/ui.md`](swarm/ui.md).
 # 5a. Ensure the hive-internal admin account exists first
 hivectl matrix sync-admin
 
-# 5b. Provision ruth's own matrix account
+# 5b. Provision ruth's own matrix account — same bootstrap-bypass reasoning
+# as forge above, still a required manual step.
 hivectl matrix create-user ruth
 
-# 5c. Create a human matrix account
-hivectl matrix create-user mara --password hunter2
-
-# 5d. Invite the operator to the hive Space (and optionally to rooms)
+# 5c. Invite the operator to the hive Space (and optionally to rooms)
 hivectl matrix invite mara
 hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'
 
-# 5e. Promote the operator to homeserver admin if needed
+# 5d. Promote the operator to homeserver admin if needed
 hivectl matrix promote-user mara
 ```
 
+The human operator's own matrix account is created via swarm SSO instead of
+a manual `hivectl` step — see step 3 (`swarmctl user add`).
+
 ### 6 · Spawn sub-agents
 
 Sub-agent creation goes through the approval queue — ruth proposes, the