From bfb9636d52eaa887aeb080e2db443093cc9b939b Mon Sep 17 00:00:00 2001 From: iris Date: Tue, 8 Sep 2026 11:57:41 +0200 Subject: [PATCH] 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. --- docs/getting-started/setup.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 42248604..025ba9cd 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -31,7 +31,7 @@ hivectl forge create-user ruth # 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`). ### 2 · Gateway (HTTP Basic auth) @@ -49,7 +49,7 @@ hivectl gateway list-users ⚠️ **A sealed store still answers.** OpenBao starts uninitialised and 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 -never initialised. Do this before anything is pointed at it. +never initialised. Do this before you point anything at it. ```bash # 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 ``` -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`). ### 7 · Spawn sub-agents