docs: fix genuine passive-voice hits in docs/tools (hand-written files)

Read all 62 write-good.Passive hits across the 6 hand-written files in
docs/tools/ (bash.md, lifecycle.md, forge.md, hivectl.md, matrix.md,
scheduling.md) in context. Excludes forge-cli.md/hivectl-cli.md/
swarmctl-cli.md (57 more hits) -- those are CI-generated from the
clap doc-comment strings in hive-forge/hivectl/swarmctl, freshness-
checked against the committed markdown, so a fix there has to go in
the Rust source and get regenerated -- separate batch.

33 rewritten to active, actor usually already established in the same
paragraph or given via a 'by X' clause (the daemon, hive-c0re,
hive-forge, hivectl, hyperhive itself, or an established module name
like nix/agent-modules/mcp.nix). Several sibling-inconsistency fixes:
a passive clause next to an already-active sibling stating the same
fact (lifecycle.md's server-scoping sentence, forge.md's clone-derives
sentence, hivectl.md's daemon-hashes-passwords sentence, matrix.md's
daemon-upserts-a-todo paragraph).

29 left alone: no-X-is-Y / no-X-is-needed invariant idioms, config-state
conditionals (whenever/when X is set/configured/given), requirement-
list idiom, a false-positive tokenization (vale matching 'are read'
inside 'read-only'), definitional facts about CLI/attrset structure
with no real actor, hypothetical/counterfactual clauses describing a
rejected design alternative, a forward-looking not-yet-real removal,
compressed bullet-fragment conventions, and one deliberately-parallel
sentence structure left both halves alone to avoid breaking the
symmetry.

Verified via vale on the 6 touched files, diffed against main's exact
baseline (not just the Passive count): write-good.Passive 62 -> 29
exactly, every other category unchanged in count AND location
(TooWordy 16, Microsoft.We 1, Microsoft.FirstPerson 1, and the same
4 pre-existing Microsoft.Contractions errors at the same 4 lines).
This commit is contained in:
iris 2026-09-08 14:21:11 +02:00 committed by mara
commit 97e2a993e3
6 changed files with 49 additions and 49 deletions

View file

@ -40,13 +40,13 @@ hivectl forge reconcile-config iris --verbose # include the full diff, not
```
- For **agents** (name has a state dir under `/var/lib/hyperhive/agents/`):
token is persisted to `<state>/forge-token`. Re-running refreshes the
`create-user` persists the token to `<state>/forge-token`. Re-running refreshes the
token (idempotent — scope always matches current `TOKEN_SCOPES`).
- For **non-agents** (humans): creates the account and prints the token to
stdout; no state dir is created. Re-running after account already exists
re-mints the token and prints it again — safe for password resets.
- Without `--password` / `--password-stdin` a random throwaway password
is used (fine for agents — they auth by token).
- Without `--password` / `--password-stdin` `create-user` uses a random
throwaway password (fine for agents — they auth by token).
- `reconcile-config <agent>` shows the divergence between the agent's local
applied config checkout and its forge `agent-configs/<agent>` `main`, then
reconciles. `--from forge` resets the local checkout to forge `main` (takes
@ -125,8 +125,8 @@ hivectl gateway delete-user bob # remove user
hivectl gateway list-users # list all usernames, one per line
```
Passwords are hashed with BCrypt (cost 12) by the daemon. The file is
created if it doesn't exist. Re-running `create-user` with the same
The daemon hashes passwords with BCrypt (cost 12). It creates the file
if it doesn't exist. Re-running `create-user` with the same
username updates the password hash in place.
## Agents
@ -175,8 +175,8 @@ resume drains the backlog rather than dropping it. Points worth knowing:
_stopped_ agent makes it come up parked.
- **Not a DAG.** Unlike `restart`/`stop`, there's no container operation
to sequence, so it applies immediately with nothing to wait on.
- **Stopping a paused agent is still fast.** The graceful-stop
handshake is skipped for a paused agent (it would never answer), which
- **Stopping a paused agent is still fast.** hivectl skips the graceful-stop
handshake for a paused agent (it would never answer), which
is safe precisely because the pause check sits at the top of the loop:
a paused agent has no turn in flight to checkpoint.
- Visible as ` paused` in `list-agents`'s STATUS column, as a `paused`
@ -196,15 +196,15 @@ Overrides the hive-wide `services.hyperhive.c0re.agentCpuQuota` /
[`persistence.md`](../agent-lifecycle/persistence.md)). Values are systemd's
`CPUQuota=` / `MemoryMax=` syntax: a percentage (`400%` = four full
cores) for CPU; a size (`8G`), a percentage of physical RAM, or
`infinity` for memory. Both are validated before they're persisted
`infinity` for memory. `set-limits` validates both before persisting them
they go into a systemd drop-in verbatim, and a typo there makes the
unit fail to start.
**Declarative, not incremental**: each invocation replaces the agent's
whole entry. `set-limits sock --memory-max 8G` leaves `sock` with _only_
a memory override, reverting any previously set CPU quota to the hive
default. To avoid a forgotten flag silently wiping an override, a bare
`set-limits <name>` with no flags is rejected — clearing requires the
default. To avoid a forgotten flag silently wiping an override, hivectl
rejects a bare `set-limits <name>` with no flags — clearing requires the
explicit `--reset`.
The command rewrites the container's drop-in and reloads systemd, so
@ -226,7 +226,7 @@ before you were added to `hive-admin` won't see it until you log back in
It also needs the daemon socket, unlike the other exec-into-a-container
paths: the "is this actually an agent?" pre-flight reads the agents root,
which is owned by the daemon's user and not group-readable, so the check
which the daemon's user owns and which isn't group-readable, so the check
is a `HostRequest` rather than a local `stat`. A rootless `choom` therefore
tells you it needs root, instead of reporting a permission problem with
the state dir.
@ -308,13 +308,13 @@ hivectl open forge # the forge (Forgejo) web UI
hivectl open matrix # the matrix GUI (fluffychat)
```
The URL is resolved from the running daemon (`HostRequest::Urls`), which
hivectl resolves the URL from the running daemon (`HostRequest::Urls`), which
reads the per-surface public URLs from c0re's service env — so custom
forge / matrix domains resolve correctly instead of assuming
`forge.<domain>`. The URL is **always printed** (the reliable core, since
the host is typically headless / driven over SSH), then `xdg-open` is tried
as a convenience — a missing or failing opener is reported as a note, not
an error.
the host is typically headless / driven over SSH), then hivectl tries
`xdg-open` as a convenience, reporting a missing or failing opener as a
note, not an error.
A surface has no URL when it isn't browser-reachable: `home` needs
`services.hyperhive.domain`; `forge` needs