docs/setup: name the section a cross-reference points at, not its number

`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.
This commit is contained in:
atlas 2026-09-11 13:26:45 +02:00 committed by mara
commit 108f7e17ea

View file

@ -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://<swarm.domain>/`) 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