docs: fix genuine passive-voice hits in getting-started/setup.md

First doc-directory of hyperhive#4042's Passive pass (705+ hits across
docs/, genuinely mixed unlike TooWordy -- needs a real per-hit read,
not a dictionary shortcut, so this is going doc-directory by
doc-directory in small PRs, per the plan posted on the issue).

Read all 13 flagged hits in this file in context, not just the flagged
word. 3 were genuine catches with a real active-voice improvement and
a nameable actor:

- "the human operator's own forge/matrix account is created via swarm
  SSO" -> "swarm SSO creates the human operator's own forge/matrix
  account" (x2, identical sentence shape for both accounts) -- swarm
  SSO is a nameable, specific actor already named later in the same
  sentence, so naming it as the subject too is strictly clearer, not
  just different.
- "Do this before anything is pointed at it" -> "Do this before you
  point anything at it" -- matches the doc's own established
  second-person imperative voice used throughout ("Do this", "Put the
  token's value", "Delete the file"); the passive here was the odd one
  out, not the house style.

The other 10 are legitimate passives, left alone:
- Generic/unspecified-actor statements ("is needed", "is bound", "is
  issued", "been run") where forcing a subject would either invent an
  actor the doc never established or read worse than the original.
- Security/architecture invariants ("No forge admin token is stored in
  any agent state dir", "Telemetry ingest is authenticated per hive")
  -- "No X is Y" / "X is Y" is the standard idiom for a guarantee
  statement in security docs, not a clarity problem to fix.
- "operator-only surfaces ... are gated on that group" -- borderline
  (could name the group as subject), judged idiomatic access-control
  phrasing rather than genuinely clearer active, but flagged as the
  closest call in this batch.

Verified: vale docs/getting-started/setup.md before/after -- 13 -> 10
write-good.Passive hits (exactly the 3 rewritten), the pre-existing
unrelated alex.Suicide hit on "hang" (line 51, untouched) still
present and correctly out of scope for this pass.
This commit is contained in:
iris 2026-09-08 11:57:41 +02:00 committed by mara
commit bfb9636d52

View file

@ -31,7 +31,7 @@ hivectl forge create-user ruth
# forge accounts auto-provisioned — nothing to run here for them. # forge accounts auto-provisioned — nothing to run here for them.
``` ```
The human operator's own forge account is created via swarm SSO instead of 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 step 3 (`swarmctl user add`).
### 2 · Gateway (HTTP Basic auth) ### 2 · Gateway (HTTP Basic auth)
@ -49,7 +49,7 @@ hivectl gateway list-users
⚠️ **A sealed store still answers.** OpenBao starts uninitialised and ⚠️ **A sealed store still answers.** OpenBao starts uninitialised and
sealed, so the container is up and the port responds while every read sealed, so the container is up and the port responds while every read
times out — the failure looks like a hang, not like a store that was times out — the failure looks like a hang, not like a store that was
never initialised. Do this before anything is pointed at it. never initialised. Do this before you point anything at it.
```bash ```bash
# On the host that RUNS the store, once. # On the host that RUNS the store, once.
@ -192,7 +192,7 @@ hivectl matrix invite @mara:yourserver --room '#hive-chat:yourserver'
hivectl matrix promote-user mara hivectl matrix promote-user mara
``` ```
The human operator's own matrix account is created via swarm SSO instead of 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 step 3 (`swarmctl user add`).
### 7 · Spawn sub-agents ### 7 · Spawn sub-agents