docs: fix write-good.So/ThereIs/Weasel lint findings

Fixes the "obvious ones first" slice of #4042 (mara: do the obvious
ones first) -- 81 hits across write-good.So, write-good.ThereIs, and
write-good.Weasel, all in docs/. Each is a genuine sentence rewrite
(lead with the real subject instead of "There is/are", drop a
sentence-initial "So ", replace a vague intensifier), not a blind
regex substitution -- read every hit in its real file context before
touching it.

3 of the 81 hits were in CI-generated CLI docs (docs/tools/{hivectl,
swarmctl,forge}-cli.md) -- fixed at the clap #[arg(...)]/doc-comment
source in hivectl/src/cli.rs, swarmctl/src/main.rs, and
hive-forge/src/verbs/repo_add_collaborator.rs, then regenerated via
each crate's `markdown-docs` subcommand so CI's freshness check stays
green.

Verified: fresh vale re-run shows 0 remaining So/ThereIs/Weasel hits
and no new hits introduced (983->982, exactly the one incidental fix
this pass also picked up at docs/scheduler/observability.md:48).
cargo fmt --check and clippy clean on the three touched crates.

Remaining write-good backlog (Passive: 726, TooWordy: 207) is
judgment-heavy and left for a follow-up slice of #4042, not bulk-
rewritten here.
This commit is contained in:
iris 2026-09-07 16:47:54 +02:00 committed by mara
commit e82a735745
35 changed files with 99 additions and 99 deletions

View file

@ -53,7 +53,7 @@ peer's name when the caller knows it's hive-local.
## Identity = socket
There are no auth tokens on the per-agent unix sockets. The socket
No auth tokens exist on the per-agent unix sockets. The socket
*path* identifies the principal; perms come from "who has the
bind-mount." A sub-agent only sees its own `/run/hive/mcp.sock`;
hive-c0re owns the host admin socket.
@ -490,7 +490,7 @@ check derivations they don't:
- **`hivectl-docs`** regenerates `docs/tools/hivectl-cli.md` from
hivectl's clap tree and **fails if the committed copy is stale**.
So **after any change to a hivectl verb or flag, regenerate it**:
**After any change to a hivectl verb or flag, regenerate it**:
```sh
nix develop -c cargo run --bin hivectl -- markdown-docs > docs/tools/hivectl-cli.md
```

View file

@ -1,7 +1,7 @@
# Gotchas
NixOS + nspawn quirks and lessons we hit the hard way. If something
here looks unmotivated in the code, there's usually a story underneath.
here looks unmotivated in the code, there's probably a story underneath.
Grouped by area — jump to the section that matches what you're
touching.
@ -64,7 +64,7 @@ path = [ "/run/wrappers" "/run/current-system/sw" ];
```
The bug is silent: `nix eval` succeeds, the unit starts, but PATH
contains a non-existent directory. The first symptom is usually
contains a non-existent directory. The first symptom is typically
`sudo: must be owned by uid 0 and have the setuid bit set` because
the setuid sudo wrapper lives at `/run/wrappers/bin/sudo` and
the path entry resolves to `/run/wrappers/bin/bin` instead.
@ -144,7 +144,7 @@ store-path _string_ coerces through `lib.toDerivation`, i.e.
`builtins.storePath`. `environment.systemPackages` and
`systemd.services.<name>.path` both do it (the latter takes plain
strings like `/run/wrappers` happily, but anything under
`builtins.storeDir` is treated as a package). So a path handed to the
`builtins.storeDir` is treated as a package). A path handed to the
container as text has to be wrapped in a real derivation — a symlink
farm built from the interpolated string — before it can go anywhere a
package is expected.