docs: suppress reviewed write-good.Passive false positives

133 hits across 38 files, all previously classified during #4548's sweep
and deliberately left un-rewritten (predicate-adjective state/necessity
description, design-intent idiom, structural/type-description idiom,
no-single-actor topology claim, parallel-triple exception, vale
substring-match artifact — see hyperhive#4548's per-PR bodies for the
per-hit reasoning).

Wraps each one in a scoped <!-- vale write-good.Passive = NO/YES -->
pair (the supported mechanism — TokenIgnores has a known offset-drift
bug) rather than a blanket per-file or per-rule silence, so a *new*
passive-voice hit anywhere in these files still fails once the rule
gates CI (next commit). Table/list false positives (docs/swarm/credentials.md's
renewal-table cells) wrap the whole block, not each cell.

Part of #4546.
This commit is contained in:
iris 2026-09-20 15:07:46 +02:00
commit 04e27c4fb6
38 changed files with 368 additions and 71 deletions

View file

@ -92,9 +92,11 @@ delegation (the latter lives in `gateway.md::Discovery flow`).
## Provisioning flow (appservice)
<!-- vale write-good.Passive = NO -->
Registration is closed. The hive's own **appservice** creates accounts:
hive-c0re holds the appservice token, agents never see
it, and an agent only ever receives its own `access_token`.
<!-- vale write-good.Passive = YES -->
The appservice has no URL (`url: null` in its registration), so the
homeserver never calls out to it and there is no service to run. What the
@ -175,6 +177,7 @@ Nothing to do, and nothing to time. The activation script mints the
appservice token and renders the registration before the homeserver
restarts, so the first boot after the switch already has both halves.
<!-- vale write-good.Passive = NO -->
- **Existing accounts keep working.** An access token lives on the
device that minted it; removing the registration token touches no
device, no account and no session. `login_with_password` stays on, so
@ -198,6 +201,7 @@ restarts, so the first boot after the switch already has both halves.
token only until the first successful read. See
[`../swarm/secrets.md`](../swarm/secrets.md) for how that mint stays
idempotent across runs.
<!-- vale write-good.Passive = YES -->
</details>
@ -239,6 +243,7 @@ into it. This gives the operator a single Space in FluffyChat or any
Matrix client that groups all agent-to-agent + operator rooms in one
place.
<!-- vale write-good.Passive = NO -->
The sweep also provisions a default **`hive-chat` room** as an
`m.space.child` of the Space. Joining a Space doesn't autojoin
child rooms — the explicit room entry ensures the operator and every
@ -246,6 +251,7 @@ agent can find a common chat room without manual setup. Room join is
restricted (any Space member including the operator can join; agents
are explicitly invited). Room version pinned to 10 for the restricted
join floor.
<!-- vale write-good.Passive = YES -->
**State**: hive-c0re persists both room IDs to `/var/lib/hyperhive/matrix/`
(mode `0600`, owned by the hive-c0re service user):
@ -270,9 +276,9 @@ services.hyperhive.swarm.matrix = {
```
**`trustedServers`** (default `[]`) — list of peer homeserver names
whose signing keys tuwunel will fetch and trust. Federation is enabled
whose signing keys tuwunel will fetch and trust. tuwunel enables federation
at the protocol level from first boot (`allow_federation = true`) but
tuwunel trusts no remote homeserver until you list it here. For a closed
trusts no remote homeserver until you list it here. For a closed
single-hive deployment the default empty list is correct — add peer
hive domains here when connecting hives into a swarm (see
[`docs/swarm/`](../swarm/README.md)).
@ -296,14 +302,14 @@ surprising behaviour:
SSO is unconditional, so the three below are requirements of running a
homeserver at all rather than of a setting:
- **`sso.clientSecretFile` is required** — fails at eval, not at boot:
- **Set `sso.clientSecretFile`** — fails at eval, not at boot:
tuwunel reads its identity providers from the config file, so a
half-configured one can stop the homeserver from starting outright
rather than merely hiding a login button. On a host that also runs
the swarm's authelia it's wired up for you.
- **`swarm.authelia.url` is required** — without a provider URL there
- **Set `swarm.authelia.url`** — without a provider URL there
is nothing to discover against.
- **`gatewayHost != null` is required** — the SSO callback URL is
- **Set `gatewayHost != null`** — the SSO callback URL is
format-locked to `<homeserver>/_matrix/client/unstable/login/sso/callback/<client_id>`,
and the identity provider needs a public name to redirect the
browser to.