From 5db38a596e54fc2a535ebfafd7bb85996a9f8cdd Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 26 Oct 2026 18:11:03 +0100 Subject: [PATCH] docs: rephrase the vale warnings that have a better wording Words the alex and Microsoft styles flag where a plainer one reads as well: disabled/special/invalid as a state, primitive, trap, hang, several, click, first-person FAQ questions, hyphenated adverb pairs. Left as they are: Let's Encrypt, quoted UI labels and phrases, the generated forge CLI reference, and the middle-click gesture. --- docs/README.md | 16 ++++++++-------- docs/agent-lifecycle/agent-roster.md | 4 ++-- docs/agent-lifecycle/config-changes.md | 6 +++--- docs/agent-lifecycle/persistence.md | 2 +- docs/getting-started/setup.md | 4 ++-- docs/integrations/forge.md | 4 ++-- docs/integrations/matrix.md | 2 +- docs/networking/gateway.md | 2 +- docs/networking/snapshot-store.md | 2 +- docs/process/conventions.md | 2 +- docs/process/gotchas.md | 4 ++-- docs/scheduler/ci.md | 4 ++-- docs/scheduler/coordinator.md | 6 +++--- docs/scheduler/observability.md | 6 +++--- docs/swarm/README.md | 2 +- docs/swarm/bao.md | 2 +- docs/swarm/notify-router.md | 2 +- docs/swarm/services.md | 2 +- docs/swarm/ui.md | 10 +++++----- docs/tools/forge.md | 2 +- docs/tools/matrix.md | 2 +- docs/tools/subagent.md | 6 +++--- docs/trust-boundary/security.md | 2 +- docs/turn-loop/config.md | 4 ++-- docs/web-ui/README.md | 4 ++-- docs/web-ui/agent.md | 8 ++++---- docs/web-ui/dashboard.md | 4 ++-- docs/web-ui/design-guide.md | 8 ++++---- docs/web-ui/shape.md | 2 +- 29 files changed, 62 insertions(+), 62 deletions(-) diff --git a/docs/README.md b/docs/README.md index c88c4e49..266e09c4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,7 +13,7 @@ declarations. - **Bringing a fresh swarm online?** → [`getting-started/setup.md`](getting-started/setup.md) (the hand steps after the first switch). -- **What does the dashboard look like, and how do I use it?** → +- **What does the dashboard look like, and how to use it?** → [`web-ui/`](web-ui/README.md) — the operator-facing starting point; its own sub-pages ([`shape`](web-ui/shape.md), [`dashboard`](web-ui/dashboard.md), [`agent`](web-ui/agent.md), @@ -57,9 +57,9 @@ declarations. - **How do I give an agent a GitHub account (`gh` + `git push`)? how's the PAT injected?** → [`integrations/github.md`](integrations/github.md) (operator content up top; the `gh`/git-push + notification-poller - mechanics are in a collapsed "Implementation" section at the bottom). + mechanics are in a collapsed section on how it is implemented at the bottom). - **What's `/knowledge`? How does the swarm-wide knowledge repo sync, - and how do I contribute a document?** → [`integrations/knowledge.md`](integrations/knowledge.md). + and how to contribute a document?** → [`integrations/knowledge.md`](integrations/knowledge.md). - **What does `hivectl` do? Provisioning, gateway users, container shells?** → [`tools/hivectl.md`](tools/hivectl.md) (the curated guide); [`tools/hivectl-cli.md`](tools/hivectl-cli.md) for the exhaustive, @@ -71,7 +71,7 @@ declarations. discovery work?** → [`networking/gateway.md`](networking/gateway.md). - **How does DNS resolution work in agent containers? What's the bridge network for?** → [`networking/network.md`](networking/network.md). -- **How do I connect two hives into a swarm?** → [`swarm/`](swarm/README.md) +- **How are two hives connected into a swarm?** → [`swarm/`](swarm/README.md) (peer hives, TLS trust). - **Where do agent snapshots go? How does the swarm's `btrfs receive` endpoint authenticate a pushing hive?** → @@ -86,18 +86,18 @@ declarations. sealed?** → [`swarm/bao.md`](swarm/bao.md). - **How does an agent get a prompt at set times, and why doesn't it fire twice after downtime?** → [`swarm/schedules.md`](swarm/schedules.md). -- **How do I set an agent's model or effort from the swarm, and what happens +- **How to set an agent's model or effort from the swarm, and what happens to its own pick?** → [`swarm/inference.md`](swarm/inference.md). - **How will a PR get checked against its repo's own yes/no rules before a full review?** → [`swarm/review-classifier.md`](swarm/review-classifier.md) (planned, not implemented yet). - **Does an agent config PR build before it's merged?** → [`swarm/builder.md`](swarm/builder.md). -- **How do I create an agent from a ready-made set of permissions and +- **How to create an agent from a ready-made set of permissions and settings?** → [`swarm/archetypes.md`](swarm/archetypes.md). - **How long do CI runs take, per repo and PR, and where does the board get it?** → [`swarm/ci-metrics.md`](swarm/ci-metrics.md). -- **How do I log an agent in to claude from the swarm UI, and why doesn't a +- **How to log an agent in to claude from the swarm UI, and why doesn't a stale stored copy log it out again?** → [`swarm/claude-login.md`](swarm/claude-login.md). - **How does an agent get a todo when someone assigns it an issue, and lose it @@ -111,7 +111,7 @@ declarations. queue sources, scheduler internals?** → [`scheduler/coordinator.md`](scheduler/coordinator.md). - **How does the CI runner work? How does it register?** → [`scheduler/ci.md`](scheduler/ci.md). -- **How do I export Claude Code metrics (tokens, cost, tool calls) to +- **How are Claude Code metrics (tokens, cost, tool calls) exported to Prometheus/Grafana?** → [`scheduler/observability.md`](scheduler/observability.md). ## Crate reference diff --git a/docs/agent-lifecycle/agent-roster.md b/docs/agent-lifecycle/agent-roster.md index ad493fa2..da65c1da 100644 --- a/docs/agent-lifecycle/agent-roster.md +++ b/docs/agent-lifecycle/agent-roster.md @@ -66,7 +66,7 @@ system-level facts live. degrades safely to "no agents" (covers a fresh install that hasn't synced yet). - **Reconcile** — runs alongside the periodic meta/flake regeneration. - Adds newly-spawned agents, drops removed ones. Reconcile keeps agents + Adds newly spawned agents, drops removed ones. Reconcile keeps agents whose config repo exists but that haven't spawned yet, so the gap until the container appears doesn't churn the file. @@ -118,7 +118,7 @@ state dirs work as for every other agent. permissions alone, the same mechanism for every agent ([`docs/turn-loop/mcp.md`](../turn-loop/mcp.md)). Ruth's permissions are the default plus `manage_root_agent`, stored for her like any grant. -- **State dirs** — _not_ special-cased: `HYPERHIVE_STATE_DIR` is +- **State dirs** — _not_ treated as an exception: `HYPERHIVE_STATE_DIR` is injected uniformly via `systemd.globalEnvironment` for every container including the manager, so all token/state paths resolve through it the same way everywhere. diff --git a/docs/agent-lifecycle/config-changes.md b/docs/agent-lifecycle/config-changes.md index 17d31cf0..44488632 100644 --- a/docs/agent-lifecycle/config-changes.md +++ b/docs/agent-lifecycle/config-changes.md @@ -68,7 +68,7 @@ target hive to deploy it. An agent created from an [archetype](../swarm/archetypes.md) gets no config repo: its hive builds it from the archetype's module. -Changing what the template seeded isn't a special case: like every +Changing what the template seeded isn't an exception: like every later change, it's a PR on that config repo, made from a clone and merged by an operator on the forge (see [Config changes](#config-changes)). @@ -376,7 +376,7 @@ Differences from sub-agents: authoritative applied repo (see "Root-agent view of applied" below). - Its socket comes from the generic per-agent registration, in the same per-agent runtime dir as any other agent (`/run/hyperhive/agents/ruth/`), - not a special manager-only path. + not a separate manager-only path. **Migration note** (for older hosts): drop any `containers.root = { ... }` block from your host NixOS config, and any `services.hyperhive.ruthless` @@ -406,7 +406,7 @@ and nothing in the tree constructs it; this removal dropped the push path genuinely needs to interrupt an agent's turn loop, not because anything live uses it today. -**A previously-running container crashing** used to be exactly that +**A previously running container crashing** used to be exactly that case (`ContainerCrash`, routed to the root agent via `Coordinator::notify_manager`) — it no longer drives any agent turn at all. `crash_watch` now only `tracing::warn!`s `"container crash diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index c42e2453..99edfcbe 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -4,7 +4,7 @@ Where state lives, what survives what, and how it's bounded. ## For operators -The short answer to "will I lose anything": **destroying an agent +The short answer to "does anything disappear": **destroying an agent keeps its state, purging it doesn't.** - **`DESTR0Y`** (the default action) stops and removes the container diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 8d79838d..04dc3172 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -57,7 +57,7 @@ What the granter is, why it's root-equivalent, and the store's TLS: ## 2 · Your SSO account _On the host running authelia._ Until this runs, `auth.` serves -a login page that refuses everyone: its only subject is a disabled placeholder. +a login page that refuses everyone: its only subject is an inactive placeholder. ```bash swarmctl user add mara --display-name Mara --email mara@example.com --group admins @@ -95,7 +95,7 @@ settings. Leave it empty and agents refer to you by name only. ## 4 · Ruth hive-c0re creates no agent at startup. You create ruth, the manager agent, -like any other: open the swarm UI start page and click the paperclip, which +like any other: open the swarm UI start page and select the paperclip, which opens the create form with `ruth` filled in and the `manage_root_agent` permission checked: that permission mounts the other agents into her container so she can recover them. The form declares her, creates her diff --git a/docs/integrations/forge.md b/docs/integrations/forge.md index 8517db6e..472fd6cc 100644 --- a/docs/integrations/forge.md +++ b/docs/integrations/forge.md @@ -204,7 +204,7 @@ read directly without a delivery — same `mark_read` call, no wake. ### Activation gates (graceful no-ops) -The poller starts disabled and stays that way for any of: +The poller starts switched off and stays that way for any of: - `HIVE_FORGE_URL` not set or not parseable as a URL (a hand-run harness; hive-c0re sets it from `swarm.forge.domain` on every hive). @@ -215,7 +215,7 @@ The poller starts disabled and stays that way for any of: best-effort enrichment fetches of server-provided subject URLs; both unlikely; treated as fatal-to-the-task only). -Disabled = the spawned task returns immediately. All other failure +Switched off = the spawned task returns immediately. All other failure modes (HTTP errors, parse errors, mark-read failures) are best-effort: logged at debug/warn and retried next tick. diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index e358462f..7fb3a558 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -400,7 +400,7 @@ surprising behaviour: - **`services.hyperhive.swarm.matrix.gatewayHost != ""`** — same footgun as `forge.domain`: empty string renders `.`-shaped garbage in both nginx `server_name` (treated as wildcard catch-all, surprising) and - `/etc/hosts` (invalid entry). `null` is the right opt-out shape; + `/etc/hosts` (malformed entry). `null` is the right opt-out shape; a config assertion rejects empty string explicitly. SSO is unconditional, so the three below are requirements of running a homeserver at all rather than of a setting: diff --git a/docs/networking/gateway.md b/docs/networking/gateway.md index 15b8a705..a7cba091 100644 --- a/docs/networking/gateway.md +++ b/docs/networking/gateway.md @@ -42,7 +42,7 @@ The catch-all `_` vhost answers any other `Host` with `444` (connection closed, Only the host that **runs** authelia declares `auth.`; a hive that merely uses SSO knows `swarm.authelia.url` but doesn't answer for that name. The server name must be exactly `swarm.authelia.domain` — authelia checks that `authelia_url` sits inside its session cookie domain at startup, and refuses to boot otherwise. The vhost carries no `auth_request` (that would put the login page behind the login it serves) and passes `X-Forwarded-{Proto,Host,Uri,For}`, because authelia decides by the original request. -⚠️ `auth.` answering with the **sso unavailable** page means authelia isn't answering at all — check `journalctl -M swarm-authelia -u authelia-swarm`. While the user set is empty, a disabled placeholder user keeps authelia's user store non-empty, so it boots fine and serves a login page that refuses everyone; add the first account with `swarmctl user add …` ([`setup.md`](../getting-started/setup.md)). +⚠️ `auth.` answering with the **sso unavailable** page means authelia isn't answering at all — check `journalctl -M swarm-authelia -u authelia-swarm`. While the user set is empty, an inactive placeholder user keeps authelia's user store non-empty, so it boots fine and serves a login page that refuses everyone; add the first account with `swarmctl user add …` ([`setup.md`](../getting-started/setup.md)). Per-agent UIs stay sub-path; forge and matrix get sub-domains → [Sub-domain shape](#sub-domain-shape-rationale). diff --git a/docs/networking/snapshot-store.md b/docs/networking/snapshot-store.md index 9669a765..5bbd4a8f 100644 --- a/docs/networking/snapshot-store.md +++ b/docs/networking/snapshot-store.md @@ -183,7 +183,7 @@ Which makes it the highest-value target in the swarm by a wide margin, and means it should get the treatment a backup host gets --- restricted access, and a decision (rather than an omission) on encryption at rest. -The trap is the label: this box holds backup-grade data while nobody +The pitfall is the label: this box holds backup-grade data while nobody calls it a backup, so it can end up with backup-grade _exposure_ and non-backup-grade _controls_. Nobody puts a migration staging area on the access-review list. diff --git a/docs/process/conventions.md b/docs/process/conventions.md index 8a448a3d..89617c38 100644 --- a/docs/process/conventions.md +++ b/docs/process/conventions.md @@ -88,7 +88,7 @@ namespace, not the wire surface. ## Recipient sentinels -The broker reserves a few recipient names, which have special +The broker reserves a few recipient names, which have a fixed meaning that ordinary agent labels can never collide with — agent name validation rejects any character outside `[a-z0-9_-]`, so the angle-bracket and asterisk shapes below are structurally safe. diff --git a/docs/process/gotchas.md b/docs/process/gotchas.md index bf497a93..632eccb2 100644 --- a/docs/process/gotchas.md +++ b/docs/process/gotchas.md @@ -156,7 +156,7 @@ an input only because a docs tree has no runtime dependencies. -The `storePath` trap is worth spelling out, because it's not confined +The `storePath` pitfall is worth spelling out, because it's not confined to options the operator writes: **any** option of type `package` fed a store-path _string_ coerces through `lib.toDerivation`, i.e. `builtins.storePath`. `environment.systemPackages` and @@ -465,7 +465,7 @@ connects to the compositor at `127.0.0.1:`. Same reasoning as the best-effort oneshots in `docs/process/conventions.md`. - **`[core] idle-time=0`**: disables weston's 300-second idle timeout. Without it the VNC desktop fades to black and - desktop-shell shows its click-to-unlock screen — useless for an + desktop-shell shows its unlock screen — useless for an agent desktop viewed over `/screen`. `idle-time=0` updates the idle timer with a 0ms delay, which `wl_event_source_timer_update` treats as "disarm," so the diff --git a/docs/scheduler/ci.md b/docs/scheduler/ci.md index 5330a97a..9ac02299 100644 --- a/docs/scheduler/ci.md +++ b/docs/scheduler/ci.md @@ -40,7 +40,7 @@ internals, container design, and the full security writeup. -Several jobs run on every PR (and on `workflow_dispatch` for manual +The jobs run on every PR (and on `workflow_dispatch` for manual re-triggers), defined in [`.forgejo/workflows/ci.yml`](../../.forgejo/workflows/ci.yml). The first four below are required checks (forge branch protection) — a hit on any of them @@ -270,7 +270,7 @@ A malicious `default.nix` or build script in a PR can therefore: No forge admin token enters the container: swarm-controller holds it and publishes only the registration token, which only `swarm-ci-runner-register.service` loads, so a job step can't read it. A build process can still reach the forge over the network, and it runs as the runner's own user, so it can read `.runner` and act as this runner; it can't issue admin API calls. -Note: `nix flake check --no-build` (eval-only) reduces the attack surface but doesn't eliminate it — `builtins.fetchGit`, `builtins.fetchurl`, and import-from-derivation can reach the network and filesystem during evaluation. The CI workflow's `nix flake check` job builds every check derivation, which is the higher-risk path. +Note: `nix flake check --no-build` (eval-only) reduces the exposure but doesn't eliminate it — `builtins.fetchGit`, `builtins.fetchurl`, and import-from-derivation can reach the network and filesystem during evaluation. The CI workflow's `nix flake check` job builds every check derivation, which is the higher-risk path. ### Mitigation diff --git a/docs/scheduler/coordinator.md b/docs/scheduler/coordinator.md index fb780775..8dd35e70 100644 --- a/docs/scheduler/coordinator.md +++ b/docs/scheduler/coordinator.md @@ -16,11 +16,11 @@ resource/lease semantics). hive-c0re submits every container operation (rebuild, first-spawn, power changes) to the global job-DAG queue (`hive-c0re/src/job_queue/`) -as a **DAG of primitive nodes**. One scheduler task drives all DAGs; +as a **DAG of basic nodes**. One scheduler task drives all DAGs; concurrency comes from the resource classes below, not from multiple workers. -Special cases like graceful stop, deferred starts, and the boot sweep +Exceptions like graceful stop, deferred starts, and the boot sweep need no bespoke code paths — each takes the shape of a DAG built -from the same primitive nodes. +from the same basic nodes. ### Two levels: DAG and node diff --git a/docs/scheduler/observability.md b/docs/scheduler/observability.md index e2b0aec0..a58d63a9 100644 --- a/docs/scheduler/observability.md +++ b/docs/scheduler/observability.md @@ -273,13 +273,13 @@ X" string to set, so mapping every level takes one rule each. A level button then filters on `level` **or** the matching `severity_text`, and the store answers the second half. Each enabled rule appends an `OR :""` term to the query a level button emits, beside the -`level:…` term that matches nothing here. Clicking "info" goes from +`level:…` term that matches nothing here. Selecting "info" goes from ``` level:contains_common_case("info","information","informational","notice") ``` -to that OR `severity_text:="INFO"`, which our rows do match. +to that OR `severity_text:="INFO"`, which the rows here do match. `Unspecified` is deliberately left out of those rules. It's VictoriaLogs' own rendering of an absent severity, and it's what the **Log rows with no @@ -684,6 +684,6 @@ unaffected either way; gauges have no temporality. The hive-tier collector runs a `deltatocumulative` processor ahead of export, so a delta `hive-metric` counter still lands in VictoriaMetrics as a cumulative series — the standard `rate()`/`increase()` idioms work on it exactly like -any other counter in this system, no special query needed. +any other counter in this system, no extra query needed. diff --git a/docs/swarm/README.md b/docs/swarm/README.md index 7521c8ce..ce2a5981 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -436,7 +436,7 @@ them, and the notification router, not the controller, decides what they mean. A `config-pr` delivery reporting a PR merged into `main` queues a deploy of its `merge_commit_sha` on the one hive whose wanted state places the -agent; with no such hive, or several, the controller deploys nothing. See +agent; with no such hive, or more than one, the controller deploys nothing. See [config-changes.md § Config changes](../agent-lifecycle/config-changes.md#config-changes). A merge whose `closed` delivery never arrives deploys nothing either; the operator recovers by redelivering that delivery from the forge hook page, diff --git a/docs/swarm/bao.md b/docs/swarm/bao.md index d85f1af8..4bc27926 100644 --- a/docs/swarm/bao.md +++ b/docs/swarm/bao.md @@ -91,7 +91,7 @@ constrain what a policy says. What bounds it: restart, with the keys `init` printed. ⚠️ **A sealed store still answers.** The container is up and the port -responds while every read times out — the failure looks like a hang, not like +responds while every read times out — the failure looks like a stall, not like a store that was never initialised. ## TLS diff --git a/docs/swarm/notify-router.md b/docs/swarm/notify-router.md index 1721f721..85309cde 100644 --- a/docs/swarm/notify-router.md +++ b/docs/swarm/notify-router.md @@ -72,7 +72,7 @@ A flow is a graph of nodes joined by edges: one `source` node naming the forge event types it starts from, `match` nodes that pass when every condition holds, `todo` nodes that emit one todo op per recipient, and `request_reviewer` nodes that ask for a review. A match node can have more than one child, and -each one runs, so one event can reach several leaves. A flow must be a tree: +each one runs, so one event can reach more than one leaf. A flow must be a tree: one source, one parent for every other node, every node reachable, no children under a `todo` or a `request_reviewer`. The most is 64 nodes, 16 levels deep, and 100 custom flows. A `todo` node sends to the agents an event diff --git a/docs/swarm/services.md b/docs/swarm/services.md index 58298a73..df9a47f0 100644 --- a/docs/swarm/services.md +++ b/docs/swarm/services.md @@ -128,7 +128,7 @@ publishes it as It answers only swarm-controller's OIDC client (`swarm.controller.queueClientId`) and refuses every other token `403`. -On first boot this module seeds the users database with a disabled placeholder subject, so authelia has a non-empty store to start against before any real account exists (`swarm-authelia.nix:873`). Authelia generates session and storage keys in the container on +On first boot this module seeds the users database with an inactive placeholder subject, so authelia has a non-empty store to start against before any real account exists (`swarm-authelia.nix:873`). Authelia generates session and storage keys in the container on first boot and never rotates them automatically; replacing one invalidates data already written (sessions, the encrypted store), so that's an operator action. diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md index cdbb0cff..4368290a 100644 --- a/docs/swarm/ui.md +++ b/docs/swarm/ui.md @@ -13,10 +13,10 @@ sign-out pages; the hive dashboard and the per-agent page have the same menu. Every dropdown (a form's select, the refresh interval, the history window) opens a list in the swarm UI's own theme, not the browser's, and works the same in every -current browser. Open it with a click, or with the arrow keys, **Enter** or +current browser. Open it with a press, or with the arrow keys, **Enter** or **Space** while it has focus. Then the arrow keys, **Home**, **End**, **Page Up** -and **Page Down** move through the options, and **Enter**, **Space** or a click take -the highlighted one. **Escape**, **Tab** or a click elsewhere shut the list without +and **Page Down** move through the options, and **Enter**, **Space** or a press take +the highlighted one. **Escape**, **Tab** or a press elsewhere shut the list without changing anything. Typing the start of an option's name picks it, also with the list shut. A dropdown inside a dialog opens above the dialog and the dialog doesn't cut it off. @@ -29,7 +29,7 @@ shut. A dropdown inside a dialog opens above the dialog and the dialog doesn't c | `/alerts` | the alerts the swarm's Grafana holds now: the firing ones, with a button for the pending, no-data and error ones and a link to Grafana's own alert list; read through the controller with a Viewer service-account token | | `/jobs` | the controller's job graph — where agent creation and credential mints show progress | | `/schedules` | the scheduled prompts: add, edit, pause, resume and remove | -| `/messages` | the swarm-wide message feed: every message between agents, and to them from the operator, reminders and compaction, with a history window and a filter on sender or recipient; a folded **broadcast** card above the feed sends one message to several agents at once | +| `/messages` | the swarm-wide message feed: every message between agents, and to them from the operator, reminders and compaction, with a history window and a filter on sender or recipient; a folded **broadcast** card above the feed sends one message to more than one agent at once | | `/notifications` | the notification router's flows: a switch for each built-in, every flow drawn as a graph, and an editor for custom flows | | `/issues` | a cross-repo issue report | | `/review` | the review classifier: its recent runs, a try-out on a real PR, and its settings | @@ -488,7 +488,7 @@ its newest 100 builds, so a link to an older one shows a note instead. The messages page (`/messages`) has a **broadcast** card above the message list. It starts folded; select its header to open it. The card holds a composer that sends one message -to several agents at once, and the messages show up in the list below as they +to more than one agent at once, and the messages show up in the list below as they go. Folding it again keeps what you typed and ticked. Pick the agents from a grid of their icons. **running** shows the agents that report themselves running and **all** shows every agent; the browser keeps the choice. diff --git a/docs/tools/forge.md b/docs/tools/forge.md index c82dc80e..ef4f71b6 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -146,7 +146,7 @@ distinct output shape — pick by what you need: Rule of thumb: **`view` first** when you're about to act on a thread (it shows everything and clears the unread guard so your follow-up `comment` isn't rejected); the JSON verbs (`issue`/`pr`) when a script needs one -field; `pr status` when the only question is "can I merge it." +field; `pr status` when the only question is whether it can merge. ### Contributing to a read-only repo (`clone` + `pr create --agit`) diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md index c3e8639f..1d60e6d4 100644 --- a/docs/tools/matrix.md +++ b/docs/tools/matrix.md @@ -109,7 +109,7 @@ The summary depends on the room's unread state: - **One unread message**: `[matrix] in : — use read_room to view, mark_read to clear` -- **Several unread messages**: `[matrix] N unread in — +- **Multiple unread messages**: `[matrix] N unread in — use read_room to view, mark_read to clear` **Multi-account prefix**: when the daemon serves more than one account diff --git a/docs/tools/subagent.md b/docs/tools/subagent.md index ad6ed715..35ccbe6f 100644 --- a/docs/tools/subagent.md +++ b/docs/tools/subagent.md @@ -200,7 +200,7 @@ renders it says so. Read the diff and the gate output regardless. parent that polls `status` sees the block without reading anything else. `continue` is how you answer it. -## Is it working, or is it wedged? +## Telling working from wedged `status` reporting **running** says the daemon tracks a process, which a wedged subagent satisfies as fully as a busy one. A running answer therefore @@ -209,7 +209,7 @@ an age climbing into the minutes means it's stuck. That one number replaces inferring the same thing from `ps` output and CPU-time deltas. It resets at each turn's spawn, so on a goal run it describes the turn in flight rather than the run — which is what you want, since a run that's -making progress spends several perfectly healthy minutes. +making progress spends a few perfectly healthy minutes. Every line the subagent's `claude` process writes bumps the timestamp — stream-json events, plain stdout chatter and stderr alike — and what the @@ -432,7 +432,7 @@ worktree switching. One rule worth knowing before editing any of this: **the daemon never emits an empty `--tools` value**, and asserts rather than doing so. Not -because of what an empty value does — that's exactly the point. Our own +because of what an empty value does — that's exactly the point. The hive's own measurement and the installed `claude --help` disagree about whether `--tools ""` means "no tools" or reads as the flag being absent, and the answer belongs to whichever claude release the system has installed diff --git a/docs/trust-boundary/security.md b/docs/trust-boundary/security.md index d632462c..993c2618 100644 --- a/docs/trust-boundary/security.md +++ b/docs/trust-boundary/security.md @@ -45,7 +45,7 @@ Each agent gets its own scoped credentials, never shared: _Its own_ account's scope bounds a compromised/confused agent's reach on the forge or matrix, not the swarm's. This is the main thing standing -between "one agent does something dumb" and "the whole hive is affected." +between "one agent does something unwise" and "the whole hive is affected." diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md index 7b10dfde..4b9e9937 100644 --- a/docs/turn-loop/config.md +++ b/docs/turn-loop/config.md @@ -221,7 +221,7 @@ services.hyperhive.agent.claudePluginsAutoUpdate = false; # defaul - **`claudePluginsAutoUpdate`** — when `true`, runs `claude plugin marketplace update` before installing plugins to pull - the latest index. Disabled by default to keep boot times short and + the latest index. Off by default to keep boot times short and plugin versions pinned. ## `cargo.shortMessages` @@ -265,7 +265,7 @@ is a no-op without the other: consolidated harness state file so the operator dashboard also stops reading this agent's empty `~/.claude/` as "needs login." An api-key agent that hits a real 401 (the key itself is bad) still surfaces `needs_login` — the - harness skips only the boot-time "have I ever logged in" check, not + harness skips only the boot-time check for an earlier login, not the auth-failure path. - **`backendEnvironmentFile`** points at an operator-managed file (outside the nix store, one `KEY=value` per line, systemd diff --git a/docs/web-ui/README.md b/docs/web-ui/README.md index 97276e68..dee3cb92 100644 --- a/docs/web-ui/README.md +++ b/docs/web-ui/README.md @@ -92,7 +92,7 @@ JS renders — no full-page reloads. motion, theming, error-UX, and component-first principles for the swarm-level Preact app specifically (not this page's dashboard/agent UIs). `/components` on a running swarm-ui is the companion living - demo of every primitive it references. + demo of every building block it references. ### Implementation reading paths @@ -115,6 +115,6 @@ touching the code rather than using the UI: [`agent.md`](agent.md) (Terminal-embedded prompt). - **"What are the per-agent HTTP endpoints?"** → [`agent.md`](agent.md) (Per-agent endpoints). -- **"Which CSS variable do I use / where are colours defined?"** → +- **"Which CSS variable to use / where are colours defined?"** → [`css-vars.md`](css-vars.md) (Palette, single-source `base.css` rule). diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md index 59dc82bf..33601703 100644 --- a/docs/web-ui/agent.md +++ b/docs/web-ui/agent.md @@ -128,7 +128,7 @@ and scrolls behind the fixed header + footer. `.agent-main`**, not in `log.parentElement = .terminal-wrap`: `.terminal-wrap` applies `backdrop-filter: blur` for the frost effect, which creates a CSS stacking context — anchoring the - pill inside that context would trap its `z-index` below the + pill inside that context would confine its `z-index` below the fixed composer in the root stacking context, and it'd never float. `.agent-main` has no backdrop-filter (no stacking-context creators), so the pill's `z-index` reaches the root and properly @@ -259,8 +259,8 @@ Unknown `/foo` shows an error row instead of being silently sent. ## Per-agent endpoints Successful POSTs return 200 (no 303 redirects). Error responses -use semantic status codes: **400** for missing/invalid input -(`body` required, unknown model name, invalid effort level), +use semantic status codes: **400** for missing/malformed input +(`body` required, unknown model name, unrecognised effort level), **409** for retryable state conflicts (turn in flight when `/compact` fires), **500** only for genuine server/transport failures. The matching @@ -358,7 +358,7 @@ shaped). dimensions; enabled once the server advertises the `ExtendedDesktopSize` pseudo-encoding (`-308` rect in the header). Fit-mode state persists in `localStorage` (`screen-fit`); default - is on. `sendPointer` rescales pointer coordinates so clicks + is on. `sendPointer` rescales pointer coordinates so presses land on the right pixel regardless of CSS scale. - `GET /screen/ws` — raw RFB byte relay: proxies WebSocket frames to the weston VNC server at `127.0.0.1:`. diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md index 6dfc56bb..58806c6c 100644 --- a/docs/web-ui/dashboard.md +++ b/docs/web-ui/dashboard.md @@ -449,7 +449,7 @@ on the `openDialog` core: button takes focus). Selecting the backdrop and `Esc` both cancel. - `themedToast(message, { type, ... })` — a non-blocking toast (top-right, `info` / `error` / `ok`) for transient validation + action - failures, so an error doesn't trap the operator behind a modal. + failures, so an error doesn't lock the operator behind a modal. Single-action errors autodismiss; bulk / partial-failure summaries are sticky (select to dismiss) so they aren't missed. @@ -493,7 +493,7 @@ frosted-mauve bar slides up from the bottom of the viewport - **Count + names** — "N agents selected · name1, name2, …" - **Bulk action buttons** — only enabled when ALL selected agents - support the action; disabled with a tooltip naming the blockers + support the action; greyed out with a tooltip naming the blockers when the selection is mixed: - `↺ R3ST4RT` — running agents only - `■ ST0P` — running agents only diff --git a/docs/web-ui/design-guide.md b/docs/web-ui/design-guide.md index ea367054..b704fcdb 100644 --- a/docs/web-ui/design-guide.md +++ b/docs/web-ui/design-guide.md @@ -5,7 +5,7 @@ dashboard, which has its own older visual language). This doc is the _why_: the principles behind how swarm-ui looks and behaves, and the concrete rules that follow from them. It deliberately doesn't show what things look like — that's `ComponentsPage` (`/components`), the living, -always-current demo of every primitive in `src/ui/`. Code can't go stale +always-current demo of every building block in `src/ui/`. Code can't go stale the way a doc's screenshots can, so treat `ComponentsPage` as the source of truth for appearance and this doc as the source of truth for intent. Colour variables specifically are `docs/web-ui/css-vars.md`'s job, not @@ -145,7 +145,7 @@ just bare column headers floating over nothing. ## Component-first design -Build the `src/ui/` primitive before or alongside the first real page +Build the `src/ui/` building block before or alongside the first real page that needs it, not after a contributor styles it inline and leaves it for later — a page reaching for a component that's already there has ready-made blocks to build with, instead of the next contributor duplicating @@ -157,10 +157,10 @@ option in a form uses `CheckboxField`, which sizes its row like the other fields, rather than a bare ``. **Every new `ui/` component gets a demo section on `/components` the -same day it lands** — no primitive without a place to see it. One +same day it lands** — no building block without a place to see it. One deliberate exception exists today: `FormField`, the internal label+ control wrapper `TextField`/`SelectField` share, isn't itself a -primitive a page reaches for directly, so it has no demo of its own — +building block a page reaches for directly, so it has no demo of its own — a considered exception, not an oversight this rule missed. ## Attention diff --git a/docs/web-ui/shape.md b/docs/web-ui/shape.md index bf1f75ae..30fdd0bc 100644 --- a/docs/web-ui/shape.md +++ b/docs/web-ui/shape.md @@ -128,7 +128,7 @@ regardless, for example message-bearing tool_use, are unaffected either way). **Sticky-bottom + snap animation.** `stickToBottom` is the operator's intent: true means "keep snapping to bottom on every -mutation," false means "I scrolled up, leave me alone." The flag +mutation," false means "the operator scrolled up, leave them alone." The flag flips when a scroll event lands further than `NEAR_BOTTOM_PX = 48` from the bottom. New rows then either snap to bottom (when sticky) or bump the unseen-count and surface the "↓ N new" pill. The snap