From 108f7e17ea111b064516e43c7549e85c5a78a177 Mon Sep 17 00:00:00 2001 From: atlas Date: Fri, 11 Sep 2026 13:26:45 +0200 Subject: [PATCH] docs/setup: name the section a cross-reference points at, not its number MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `c1b7be11` inserted `### 3 · Secret store` and renumbered every heading below it — SSO 3→4, UI 4→5, Matrix 5→6, Spawn 6→7, Host commands 7→8 — without touching a single cross-reference. Five were left pointing one section short: line 25 "see step 6" -> §6 Matrix, meant §7 Spawn sub-agents line 30 "in step 6" -> §6 Matrix, meant §7 Spawn sub-agents line 35 "see step 3" -> §3 Secret store, meant §4 Swarm SSO line 217 "(step 3)" -> §3 Secret store, meant §4 Swarm SSO line 246 "see step 3" -> §3 Secret store, meant §4 Swarm SSO Both `step 3` targets are account-creation instructions and §3 is the secret store, which is `only when deploy.bao` — so an operator without a store follows the pointer into a section that does not apply and finds no `swarmctl` in it. Renumbering to 4/7 would rot on the next insertion. These name the section instead, the form `approvals.md:87` and `dashboard.md:906` already use. The Matrix block's `# 5a.`–`# 5d.` comments lose their prefixes for the same reason: they numbered themselves against that section's old position, and the page's other code blocks carry unnumbered comments anyway. Closes #4212. --- docs/getting-started/setup.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 7443e2ee..9d7998d3 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -22,17 +22,17 @@ operator has to place, and where. ```bash # 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. +# bootstrap bypasses the normal spawn-approval flow ("Spawn sub-agents" +# below), 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 -# Sub-agents spawned later (via the approval flow in step 6) get their -# forge accounts auto-provisioned — nothing to run here for them. +# Sub-agents spawned later (via the approval flow in "Spawn sub-agents") +# get their forge accounts auto-provisioned — nothing to run here for them. ``` Swarm SSO creates the human operator's own forge account instead of -a manual `hivectl` step — see step 3 (`swarmctl user add`). +a manual `hivectl` step — see *Swarm SSO* below (`swarmctl user add`). ### 2 · Gateway (HTTP Basic auth) @@ -214,7 +214,7 @@ Nothing to run — it's served on the swarm apex (`https:///`) as soon as the host rebuilds. Two things decide whether you can actually open it: -- **You are in `admins`** (step 3). The gateway asks authelia whether +- **You are in `admins`** (*Swarm SSO* above). The gateway asks authelia whether you have a session; the rule that makes it mean _operator_ wants the group. Without it you log in and still get bounced. - **The name resolves to this host.** it's published to the hive's own @@ -227,23 +227,23 @@ control: [`swarm/ui.md`](../swarm/ui.md). ### 6 · Matrix ```bash -# 5a. Ensure the hive-internal admin account exists first +# Ensure the hive-internal admin account exists first hivectl matrix sync-admin -# 5b. Provision ruth's own matrix account — same bootstrap-bypass reasoning +# Provision ruth's own matrix account — same bootstrap-bypass reasoning # as forge above, still a required manual step. hivectl matrix create-user ruth -# 5c. Invite the operator to the hive Space (and optionally to rooms) +# Invite the operator to the hive Space (and optionally to rooms) hivectl matrix invite mara hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver' -# 5d. Promote the operator to homeserver admin if needed +# Promote the operator to homeserver admin if needed hivectl matrix promote-user mara ``` Swarm SSO creates the human operator's own matrix account instead of -a manual `hivectl` step — see step 3 (`swarmctl user add`). +a manual `hivectl` step — see *Swarm SSO* above (`swarmctl user add`). ### 7 · Spawn sub-agents