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

@ -46,7 +46,7 @@ structurally rather than for one specific trigger. Two columns:
- **Pills cluster** (`.agent-header-pills`, right-aligned): status
badges (`StatusChips.tsx`) and flyout triggers together in one row —
a deliberate choice (not the historical default) so the header reads
as one identity zone + one status/actions zone rather than several
as one identity zone + one status/actions zone rather than multiple
separate clusters:
- **Alive badge**: `● alive` (green) / `⊘ rate limited` (red) /
`◌ needs login` / `◌ logging in` / `○ offline` / `… connecting`.
@ -83,7 +83,7 @@ structurally rather than for one specific trigger. Two columns:
(`GET /api/state`'s `links` field) also feeds
`DashboardState.links` for the dashboard card's icon strip —
`agent_links()` in hive-agent is the single source of truth for
both. There is no separate overflow (`⋯`) menu any more — it used
both. No separate overflow (`⋯`) menu exists any more — it used
to hold exactly this dashboard link plus a rebuild-container action
(mara, hyperhive#3704: "remove rebuild button, move link to
dashboards into links menu") — rebuild had no real discoverability

View file

@ -141,7 +141,7 @@ dirs; `POST /api/purge-tombstone/{name}`).
⚠️ **Not only *destroyed* agents.** Nothing records a destroy: every
definition-side artifact (state subvolume, proposed + applied repos,
meta registration, topology entry) is written by `Provision` *before*
the container exists and survives `lifecycle::destroy`. So an agent
the container exists and survives `lifecycle::destroy`. An agent
part-way through a spawn is byte-identical on disk to a tombstone, and
both are listed. The pane carries a standing warning to that effect, and
the row badge says `offline` rather than `destroyed` — the absence of a
@ -474,8 +474,8 @@ Both tables share the same visual shape: `.cap-table-wrap` /
and its checkbox cells, where each checkbox carries `data-baseline` (its
render-time state) and the row carries `data-agent` for dirty-tracking.
**Saving — one button for the whole page.** There are no per-row save
buttons. A single page-level `.perm-save-bar` with a **save all (N
**Saving — one button for the whole page.** No per-row save
buttons exist. A single page-level `.perm-save-bar` with a **save all (N
agents)** button sits at the bottom of the pane, enabled only when some
checkbox diverges from its baseline. Clicking it diffs every checkbox
across *both* matrices and POSTs one batch to `POST /api/permissions` as
@ -826,7 +826,7 @@ limited` (red, while the harness is parked after a 429), `needs
login`, `needs update` — plus **one `◐ pending-state…` pill per
active transient** (replaces buttons during operator-initiated
start / stop / restart / rebuild / destroy). An agent can carry
**several transients at once** — for example a lease-exempt `prebuild`
**multiple transients at once** — for example a lease-exempt `prebuild`
running alongside a `stop_for_update` on the same agent — and each
renders as its own independent badge rather than being collapsed
into one label, matching the existing multi-badge convention this
@ -1337,8 +1337,8 @@ payload):
every queue mutation (enqueue, state transition, dedup collapse,
terminal-history trim). Unlike the snapshot events below it ships
no state at all: the client re-fetches `GET /api/jobq/graph`, which
is where it reads the queue from cold too. There is no
`/api/state.rebuild_queue` — it went with the typed projection.
is where it reads the queue from cold too. No
`/api/state.rebuild_queue` exists — it went with the typed projection.
- `schedules_changed` (seq, schedules: `Vec<WireSchedule>`) —
full snapshot of all scheduled prompts. Emitted after every
operator mutation via the `/api/schedules` surface (new /

View file

@ -16,7 +16,7 @@ repeated here.
- **Frosted / tinted glass** where it fits — translucency over flat
panels, not a hard rule for every surface.
- **Playful use of the multiple accent colours**, without tipping into
visual noise — the base16 palette has several accent slots
visual noise — the base16 palette has multiple accent slots
(`--purple`, `--cyan`, `--pink`, …); use more than one where it adds
distinction, not decoration for its own sake.
- **Whimsy** — small, delightful touches are welcome (the per-hive
@ -110,7 +110,7 @@ UI later. Concretely: full untruncated `detail`, a copy button, no
"something went wrong, try reloading."
This follows from **power-user-first**, one of the standing principles:
swarm-ui instances are mostly self-hosted and operators are techies, so
swarm-ui instances are typically self-hosted and operators are techies, so
errors should give them what they need to actually diagnose a problem
rather than a friendly wall. Power-user-first doesn't mean
newcomer-hostile — the UI should still be self-explanatory, warn or ask