vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs: fix Microsoft.Foreign hits (e.g./i.e. -> for example/that is)

Browse source 
Substitutes 'for example' for 'e.g.' and 'that is' for 'i.e.' per
Microsoft style, with no comma after the replacement -- this repo
never puts a comma after e.g./i.e. either, so the substituted phrase
matches that house style instead of vale's literal 'for example,'
suggestion.

Covers all 77 real hits (72 from the initial vale pass + 5 more of the
same pattern found on a follow-up vale run). None of the flagged
instances were sentence-initial, so there's no capitalization concern
here.

Verified via a fresh vale run: 0 remaining Microsoft.Foreign hits.
Full accounting in /agents/iris/state/haiku-batches/foreign-report.md.
This commit is contained in:
iris 2026-09-07 14:56:24 +02:00 • committed by mara
commit 4f2d1d281a
30 changed files with 80 additions and 80 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/agent-lifecycle/agent-hierarchy.md
View file

@ -123,7 +123,7 @@ other agents don't:
a root-only capability even post-milestone, not a topology rule. a root-only capability even post-milestone, not a topology rule.
One exception: `Wake` (inject a `from: <X>` message into the One exception: `Wake` (inject a `from: <X>` message into the
caller's own inbox) isn't really privileged — every per-agent daemon caller's own inbox) isn't really privileged — every per-agent daemon
(e.g. `hive-forge-notify`) needs it, and sub-agents already have the (for example `hive-forge-notify`) needs it, and sub-agents already have the
equivalent on their own socket. equivalent on their own socket.
- **Storage/mounts** — only the manager container gets - **Storage/mounts** — only the manager container gets
`/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can `/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can

4
docs/agent-lifecycle/approvals.md
View file

@ -246,7 +246,7 @@ Transient broker errors (sqlite lock contention, etc.) get the same
### Reminder delivery: file-path semantics ### Reminder delivery: file-path semantics
A reminder may carry a `file_path` (the agent-visible path inside its A reminder may carry a `file_path` (the agent-visible path inside its
container, e.g. `/agents/<name>/state/foo.md`). On delivery hive-c0re: container, for example `/agents/<name>/state/foo.md`). On delivery hive-c0re:
1. **Translates** the container path to the host path 1. **Translates** the container path to the host path
(`/var/lib/hyperhive/agents/<name>/state/foo.md`) so c0re can write (`/var/lib/hyperhive/agents/<name>/state/foo.md`) so c0re can write
@ -667,7 +667,7 @@ one — sub-agents and the root agent go through the same
"Rev" = canonical filesystem path of `cfg.hyperhiveFlake`. Marker "Rev" = canonical filesystem path of `cfg.hyperhiveFlake`. Marker
file: `/var/lib/hyperhive/applied/.<name>.hyperhive-rev`. If the file: `/var/lib/hyperhive/applied/.<name>.hyperhive-rev`. If the
flake input has no canonical path (e.g. a `github:` URL), flake input has no canonical path (for example a `github:` URL),
auto-update is a no-op — rebuild manually. auto-update is a no-op — rebuild manually.
The dashboard surfaces pending updates per agent: a clickable The dashboard surfaces pending updates per agent: a clickable

2
docs/agent-lifecycle/persistence.md
View file

@ -337,7 +337,7 @@ A parent agent gets each direct child's `state` dir bind-mounted
**read-write** and its `config` dir **read-only** **read-write** and its `config` dir **read-only**
(`bind_child_agent_dirs` in `lifecycle/host_config.rs`). The RW on (`bind_child_agent_dirs` in `lifecycle/host_config.rs`). The RW on
`state` is deliberate, not an oversight: a parent manages its children, `state` is deliberate, not an oversight: a parent manages its children,
which includes writing into a child's state for recovery (e.g. seeding which includes writing into a child's state for recovery (for example seeding
notes, clearing a stuck sentinel) as well as reading it. notes, clearing a stuck sentinel) as well as reading it.
**`harness` isn't mounted at all.** It holds the child's own runtime **`harness` isn't mounted at all.** It holds the child's own runtime

2
docs/integrations/forge.md
View file

@ -278,7 +278,7 @@ to `closed_at` that `state_change_is_current` returns `true` — so it takes
the state-change path and its body would be dropped. Best of both worlds: the state-change path and its body would be dropped. Best of both worlds:
on the merge/close path we fetch the `latest_comment_url` comment and, when on the merge/close path we fetch the `latest_comment_url` comment and, when
its `created_at` is strictly **after** the subject's `closed_at` its `created_at` is strictly **after** the subject's `closed_at`
(`comment_is_after_close`) — i.e. it raced the merge rather than being the (`comment_is_after_close`) — that is it raced the merge rather than being the
pre-merge last comment the subject keeps — append it as a pre-merge last comment the subject keeps — append it as a
`comment by <author>: <excerpt>` block before the meta suffix `comment by <author>: <excerpt>` block before the meta suffix
(`fresh_post_close_comment_tail`). So the wake carries **both** `[PR merged]` (`fresh_post_close_comment_tail`). So the wake carries **both** `[PR merged]`

2
docs/integrations/knowledge.md
View file

@ -69,7 +69,7 @@ each call site.
### Change notice ### Change notice
When a pull actually moves the local clone's `HEAD` (a real change, When a pull actually moves the local clone's `HEAD` (a real change,
not a no-op — e.g. the periodic pull finding nothing new), hive-c0re not a no-op — for example the periodic pull finding nothing new), hive-c0re
broadcasts a short notice to every currently-registered agent's inbox: broadcasts a short notice to every currently-registered agent's inbox:
sender `system`, body `[system] /knowledge updated:` followed by a sender `system`, body `[system] /knowledge updated:` followed by a
`git diff --stat <old>..<new>` summary of what changed (or a generic `git diff --stat <old>..<new>` summary of what changed (or a generic

4
docs/integrations/matrix.md
View file

@ -125,7 +125,7 @@ see it. The agent only receives the resulting `access_token`.
6. **hive-c0re restarts `hive-matrix-daemon`** for the agent 6. **hive-c0re restarts `hive-matrix-daemon`** for the agent
immediately after writing the token so the daemon picks up the immediately after writing the token so the daemon picks up the
new credential without waiting for a full container restart. If new credential without waiting for a full container restart. If
the restart fails (e.g. daemon not yet running on first boot) the the restart fails (for example daemon not yet running on first boot) the
error is logged as a warning and the `.path`-trigger sibling error is logged as a warning and the `.path`-trigger sibling
(`hive-matrix-daemon.path` watching for `matrix-token` appearance) (`hive-matrix-daemon.path` watching for `matrix-token` appearance)
brings the daemon up on the same boot cycle anyway. brings the daemon up on the same boot cycle anyway.
@ -185,7 +185,7 @@ are reused on re-provision.
**Idempotent**: if the files exist and are non-empty, the Space and **Idempotent**: if the files exist and are non-empty, the Space and
room are considered already created. Delete the files to force room are considered already created. Delete the files to force
re-creation (e.g. after a homeserver wipe). re-creation (for example after a homeserver wipe).
## Configuration tuning ## Configuration tuning

6
docs/networking/gateway.md
View file

@ -382,7 +382,7 @@ The gateway always terminates TLS, so the `behindGateway = true` case is
always advertised over `https://`; only the direct (`behindGateway = always advertised over `https://`; only the direct (`behindGateway =
false`) shape stays `http://`. Set `rootUrl` explicitly when false`) shape stays `http://`. Set `rootUrl` explicitly when
`forge.domain` resolves differently from the public URL, or for a `forge.domain` resolves differently from the public URL, or for a
genuinely bespoke shape (e.g. an external reverse proxy on a different genuinely bespoke shape (for example an external reverse proxy on a different
host/path). Must end with `/` (Forgejo requirement; an assertion host/path). Must end with `/` (Forgejo requirement; an assertion
enforces this). enforces this).
@ -450,7 +450,7 @@ store path baked in at hive-c0re build time, and c0re (writing
so they see the same store. so they see the same store.
**Graceful degradation**: if `HIVE_AGENT_FRONTEND_DIR` is empty or **Graceful degradation**: if `HIVE_AGENT_FRONTEND_DIR` is empty or
unset (e.g. a build that predates `cfg.frontend`), each agent gets the unset (for example a build that predates `cfg.frontend`), each agent gets the
legacy single-proxy block and all traffic is forwarded to the agent legacy single-proxy block and all traffic is forwarded to the agent
daemon as before. daemon as before.
@ -575,7 +575,7 @@ vhost (`_`, `forge.<swarm-domain>`, `chat.<swarm-domain>`):
nginx's `add_header` inheritance rule: a `location` block that sets its nginx's `add_header` inheritance rule: a `location` block that sets its
own `add_header` does **not** inherit server-scope headers. API locations own `add_header` does **not** inherit server-scope headers. API locations
that carry their own CORS headers (e.g. `/.well-known/matrix/client`, that carry their own CORS headers (for example `/.well-known/matrix/client`,
`/_matrix/`) are therefore unaffected. HTML-serving and proxy locations `/_matrix/`) are therefore unaffected. HTML-serving and proxy locations
with no `add_header` of their own pick the security headers up with no `add_header` of their own pick the security headers up
automatically. automatically.

4
docs/networking/network.md
View file

@ -180,7 +180,7 @@ namespace.
### Reaching host services (`exposeHostPorts`) ### Reaching host services (`exposeHostPorts`)
By default agents can only reach the host on 80/443 (+53 DNS), so a By default agents can only reach the host on 80/443 (+53 DNS), so a
host-side service on another port — e.g. a dev OTLP collector you want host-side service on another port — for example a dev OTLP collector you want
agents to reach directly — is unreachable. (hyperhive's own telemetry agents to reach directly — is unreachable. (hyperhive's own telemetry
needs none of this: `otel.enable` opens its collector's port itself, and needs none of this: `otel.enable` opens its collector's port itself, and
`otel.endpoint` is the _upstream_, which no agent ever dials. See `otel.endpoint` is the _upstream_, which no agent ever dials. See
@ -246,7 +246,7 @@ but no path off the bridge subnet (no internet, no `api.anthropic.com`).
### How the isolated container gets its resolver ### How the isolated container gets its resolver
nixos-container copies the **host's** `/etc/resolv.conf` into the container nixos-container copies the **host's** `/etc/resolv.conf` into the container
at every start. The host resolver (e.g. `127.0.0.53` from systemd-resolved, at every start. The host resolver (for example `127.0.0.53` from systemd-resolved,
or a LAN router) is unreachable from a private netns and isn't or a LAN router) is unreachable from a private netns and isn't
authoritative for the hive's own zones, so it's replaced with the authoritative for the hive's own zones, so it's replaced with the
bridge dnsmasq at boot. Because the copy happens on every start, a bridge dnsmasq at boot. Because the copy happens on every start, a

6
docs/process/conventions.md
View file

@ -26,7 +26,7 @@ Four env vars cover the identity surface, read by
- `HYPERHIVE_HIVE_DOMAIN` — the hive's canonical DNS domain (e.g. - `HYPERHIVE_HIVE_DOMAIN` — the hive's canonical DNS domain (e.g.
`darkest.space`), set by `nix/host-modules/hive-c0re/environment.nix` `darkest.space`), set by `nix/host-modules/hive-c0re/environment.nix`
from `services.hyperhive.domain`. When configured, `qualified_label()` from `services.hyperhive.domain`. When configured, `qualified_label()`
returns `${label}@${domain}` (e.g. `iris@darkest.space`); when returns `${label}@${domain}` (for example `iris@darkest.space`); when
unset (single-hive deployments, dev/test) it degrades to just unset (single-hive deployments, dev/test) it degrades to just
the short label so existing callers see no change. The the short label so existing callers see no change. The
qualified form surfaces in the per-agent web UI title, the qualified form surfaces in the per-agent web UI title, the
@ -47,7 +47,7 @@ can share a swarm name. Humans want both: the address
still use the domain-based convention untouched. still use the domain-based convention untouched.
`qualify(label)` is the same shape as `qualified_label()` but `qualify(label)` is the same shape as `qualified_label()` but
applies to an arbitrary label the caller already has (e.g. a peer applies to an arbitrary label the caller already has (for example a peer
name from the broker); it's the right surface when rendering a name from the broker); it's the right surface when rendering a
peer's name when the caller knows it's hive-local. peer's name when the caller knows it's hive-local.
@ -509,7 +509,7 @@ check derivations they don't:
When local clippy/fmt/test pass but CI's `nix flake check` fails, When local clippy/fmt/test pass but CI's `nix flake check` fails,
**don't assume a transient builder problem** — reproduce the real **don't assume a transient builder problem** — reproduce the real
gate locally: `nix flake check` (shares the build farm, use gate locally: `nix flake check` (shares the build farm, use
sparingly) or build just the suspect check, e.g. `nix build sparingly) or build just the suspect check, for example `nix build
.#checks.x86_64-linux.hivectl-docs`. .#checks.x86_64-linux.hivectl-docs`.
## Best-effort oneshot services ## Best-effort oneshot services

4
docs/process/gotchas.md
View file

@ -309,7 +309,7 @@ nix develop -c cargo run -p hive-c0re --bin hivectl -- <args>
``` ```
This is also how you regenerate committed generated docs locally — This is also how you regenerate committed generated docs locally —
e.g. `docs/tools/hivectl-cli.md` via the `hivectl markdown-docs` for example `docs/tools/hivectl-cli.md` via the `hivectl markdown-docs`
subcommand (its `hivectl-docs` flake check otherwise only fails in subcommand (its `hivectl-docs` flake check otherwise only fails in
CI on drift). CI on drift).
@ -389,7 +389,7 @@ connects to the compositor at `127.0.0.1:<vnc_port>`.
fixed `/run/gui` (systemd `RuntimeDirectory=gui`, `0700`, fixed `/run/gui` (systemd `RuntimeDirectory=gui`, `0700`,
`RuntimeDirectoryPreserve=yes` so it survives weston restarts for the `RuntimeDirectoryPreserve=yes` so it survives weston restarts for the
wayland client sharing the `/run/gui/wayland-0` socket). Wayland wayland client sharing the `/run/gui/wayland-0` socket). Wayland
clients in the agent's config (e.g. bitburner electron) must run as the clients in the agent's config (for example bitburner electron) must run as the
same user with `XDG_RUNTIME_DIR=/run/gui`. same user with `XDG_RUNTIME_DIR=/run/gui`.
- **One shared D-Bus session bus (`gui-dbus.service`)**: a single - **One shared D-Bus session bus (`gui-dbus.service`)**: a single
persistent `dbus-daemon --session` bound at `/run/gui/bus`, run as the persistent `dbus-daemon --session` bound at `/run/gui/bus`, run as the

2
docs/process/pr-review-gate.md
View file

@ -31,7 +31,7 @@ is someone else's call.
Submit `hive-forge pr-reviews <pr> --approve` or `--request-changes` Submit `hive-forge pr-reviews <pr> --approve` or `--request-changes`
as soon as you've finished checking the diff — don't hold it back as soon as you've finished checking the diff — don't hold it back
waiting for CI to go green first. Mention CI's current state in the waiting for CI to go green first. Mention CI's current state in the
review body if it's relevant (e.g. "approving; `nix flake check` is review body if it's relevant (for example "approving; `nix flake check` is
still running"), but don't gate the formal verdict on it: CI isn't a still running"), but don't gate the formal verdict on it: CI isn't a
signal a reviewer waits on, it's a separate condition that resolves signal a reviewer waits on, it's a separate condition that resolves
independently. independently.

4
docs/scheduler/ci.md
View file

@ -95,7 +95,7 @@ hive-forge instance to register against — nothing extra to enable beyond
Optional tuning: `services.hyperhive.deploy.forgejo.ci.name` (runner name in forge Optional tuning: `services.hyperhive.deploy.forgejo.ci.name` (runner name in forge
admin panel), `concurrency` (parallel job capacity), `labels` (workflow admin panel), `concurrency` (parallel job capacity), `labels` (workflow
targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration targeting), `jobTimeout` (per-job wall-clock cap, default `"1h"`, Go duration
string e.g. `"3h"` — a job that exceeds it's killed so a hung or runaway string for example `"3h"` — a job that exceeds it's killed so a hung or runaway
build can't hold the runner's single slot indefinitely). build can't hold the runner's single slot indefinitely).
## Container design ## Container design
@ -234,7 +234,7 @@ following to your host config:
} }
``` ```
**Remote builders:** if CI dispatches builds to a remote builder (e.g. via **Remote builders:** if CI dispatches builds to a remote builder (for example via
`nix.buildMachines` / `ssh-ng://`), the build outputs land in _that host's_ `nix.buildMachines` / `ssh-ng://`), the build outputs land in _that host's_
store, so the same GC config should be applied wherever the builder runs — store, so the same GC config should be applied wherever the builder runs —
GC on the coordinator host won't reclaim space on the builder. GC on the coordinator host won't reclaim space on the builder.

4
docs/scheduler/observability.md
View file

@ -199,7 +199,7 @@ automatically:
| Attribute | Value | | Attribute | Value |
| -------------- | ------------------------------------------------------------ | | -------------- | ------------------------------------------------------------ |
| `service.name` | `hyperhive-agent` (constant) | | `service.name` | `hyperhive-agent` (constant) |
| `agent` | agent logical name (e.g. `iris`) | | `agent` | agent logical name (for example `iris`) |
| `hive` | hive display name (`services.hyperhive.hiveName`) | | `hive` | hive display name (`services.hyperhive.hiveName`) |
| `swarm` | swarm display name (`services.hyperhive.swarm.name`, if set) | | `swarm` | swarm display name (`services.hyperhive.swarm.name`, if set) |
@ -330,7 +330,7 @@ Agents can push arbitrary labeled metrics to the same OTEL collector via the
hive-metric <name> <value> [--type counter|gauge] [--temporality delta|cumulative] [--labels key=value...] hive-metric <name> <value> [--type counter|gauge] [--temporality delta|cumulative] [--labels key=value...]
``` ```
- `<name>` — metric name (e.g. `tasks_completed`, `latency_ms`). - `<name>` — metric name (for example `tasks_completed`, `latency_ms`).
- `<value>` — numeric value (f64; integers and floats both accepted). - `<value>` — numeric value (f64; integers and floats both accepted).
- `--type counter|gauge` — metric kind: `counter` (increasing sum, default) or - `--type counter|gauge` — metric kind: `counter` (increasing sum, default) or
`gauge` (instantaneous point-in-time value). `gauge` (instantaneous point-in-time value).

8
docs/swarm/ui.md
View file

@ -68,10 +68,10 @@ Adding a swarm service name means touching two things. Missing the
second ships as a different flavour of "works from the host, broken from second ships as a different flavour of "works from the host, broken from
a container": a container":
| site | file | | site | file |
| ---------------------------- | --------------------------------------------------------------- | | ---------------------------- | ---------------------------------------------------------------------- |
| vhost + `gateway.localNames` | the service's own module (e.g. `nix/host-modules/swarm-ui.nix`) | | vhost + `gateway.localNames` | the service's own module (for example `nix/host-modules/swarm-ui.nix`) |
| **certificate name** | `nix/host-modules/swarm.nix` (`serviceDomains`) | | **certificate name** | `nix/host-modules/swarm.nix` (`serviceDomains`) |
The DNS record and the local-dev `/etc/hosts` entry need no separate The DNS record and the local-dev `/etc/hosts` entry need no separate
edit: both are derived from `services.hyperhive.gateway.localNames`, edit: both are derived from `services.hyperhive.gateway.localNames`,

28
docs/tools/forge-cli.md
View file

@ -173,7 +173,7 @@ Create an issue
* `--body <BODY>` — Inline body text * `--body <BODY>` — Inline body text
* `--body-file <BODY_FILE>` — Read body from a file. `-` means stdin * `--body-file <BODY_FILE>` — Read body from a file. `-` means stdin
* `--assignee <ASSIGNEE>` — Initial assignee login * `--assignee <ASSIGNEE>` — Initial assignee login
* `--label <LABELS>` — Label name to attach, repeatable (e.g. `--label area/ops --label type/bug`). Same spelling `labels add` accepts. An unresolved name errors out (before the issue is created) rather than silently attaching fewer labels than asked for * `--label <LABELS>` — Label name to attach, repeatable (for example `--label area/ops --label type/bug`). Same spelling `labels add` accepts. An unresolved name errors out (before the issue is created) rather than silently attaching fewer labels than asked for
@ -401,7 +401,7 @@ List / add / remove emoji reactions on the issue, or on one of its comments with
###### **Subcommands:** ###### **Subcommands:**
* `list` — List reactions (default when no action is given) * `list` — List reactions (default when no action is given)
* `add` — Add a reaction — a Forgejo shortcode, e.g. `+1`, `heart`, `rocket` * `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
* `remove` — Remove your own reaction with this content * `remove` — Remove your own reaction with this content
###### **Arguments:** ###### **Arguments:**
@ -425,7 +425,7 @@ List reactions (default when no action is given)
## `hive-forge issue reaction add` ## `hive-forge issue reaction add`
Add a reaction — a Forgejo shortcode, e.g. `+1`, `heart`, `rocket` Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
**Usage:** `hive-forge issue reaction add <CONTENT>` **Usage:** `hive-forge issue reaction add <CONTENT>`
@ -540,7 +540,7 @@ Create a pull request
* `--remote <REMOTE>` — Remote to push to (default: `forge`, or `origin` in `--agit` mode) * `--remote <REMOTE>` — Remote to push to (default: `forge`, or `origin` in `--agit` mode)
* `--agit` — Open the PR via Forgejo's `AGit` flow instead of pushing a branch — works for read-only collaborators. Run from inside a cloned repo * `--agit` — Open the PR via Forgejo's `AGit` flow instead of pushing a branch — works for read-only collaborators. Run from inside a cloned repo
* `--topic <TOPIC>` — `AGit` topic — groups repeated pushes into one PR (re-run with the same topic to update it). Defaults to the branch name. Only meaningful with `--agit` * `--topic <TOPIC>` — `AGit` topic — groups repeated pushes into one PR (re-run with the same topic to update it). Defaults to the branch name. Only meaningful with `--agit`
* `--label <LABELS>` — Label name to attach, repeatable (e.g. `--label area/ops --label type/bug`). Same spelling `labels add` accepts — an unresolved name errors out rather than silently attaching fewer labels than asked for. In `--agit` mode this is applied as a follow-up call once the PR number is known (the `AGit` push itself has no label field), so it's silently skipped (not a label-resolution error) if the PR URL couldn't be parsed back out of the push output — same fallback as the deferred multi-line body * `--label <LABELS>` — Label name to attach, repeatable (for example `--label area/ops --label type/bug`). Same spelling `labels add` accepts — an unresolved name errors out rather than silently attaching fewer labels than asked for. In `--agit` mode this is applied as a follow-up call once the PR number is known (the `AGit` push itself has no label field), so it's silently skipped (not a label-resolution error) if the PR URL couldn't be parsed back out of the push output — same fallback as the deferred multi-line body
@ -860,7 +860,7 @@ List / add / remove emoji reactions on the PR, or on one of its comments with `-
###### **Subcommands:** ###### **Subcommands:**
* `list` — List reactions (default when no action is given) * `list` — List reactions (default when no action is given)
* `add` — Add a reaction — a Forgejo shortcode, e.g. `+1`, `heart`, `rocket` * `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
* `remove` — Remove your own reaction with this content * `remove` — Remove your own reaction with this content
###### **Arguments:** ###### **Arguments:**
@ -884,7 +884,7 @@ List reactions (default when no action is given)
## `hive-forge pr reaction add` ## `hive-forge pr reaction add`
Add a reaction — a Forgejo shortcode, e.g. `+1`, `heart`, `rocket` Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
**Usage:** `hive-forge pr reaction add <CONTENT>` **Usage:** `hive-forge pr reaction add <CONTENT>`
@ -962,7 +962,7 @@ Clone a forge repo (default `-r`/`HIVE_FORGE_REPO`) with credentials auto-inject
###### **Arguments:** ###### **Arguments:**
* `<DEST>` — Destination directory. Defaults to the repo's basename (e.g. `internal/knowledge` → `knowledge`) * `<DEST>` — Destination directory. Defaults to the repo's basename (for example `internal/knowledge` → `knowledge`)
###### **Options:** ###### **Options:**
@ -985,7 +985,7 @@ Create a forge repo under the current user (or `--org`). Prints the repo URL
* `--description <DESCRIPTION>` — Repository description * `--description <DESCRIPTION>` — Repository description
* `--private` — Create the repo as private (default: public) * `--private` — Create the repo as private (default: public)
* `--default-branch <DEFAULT_BRANCH>` — Default branch name (e.g. `main`). Only takes effect with `--auto-init` * `--default-branch <DEFAULT_BRANCH>` — Default branch name (for example `main`). Only takes effect with `--auto-init`
* `--org <ORG>` — Create under this organisation instead of your own namespace * `--org <ORG>` — Create under this organisation instead of your own namespace
* `--auto-init` — Seed an initial commit (README) so the repo is non-empty and can be cloned immediately. Omit to create a bare repo you push into * `--auto-init` — Seed an initial commit (README) so the repo is non-empty and can be cloned immediately. Omit to create a bare repo you push into
@ -1059,7 +1059,7 @@ Triage lint queries (unassigned / no-reviewer / stale-branches / assignments / u
* `no-reviewer` — List PRs with no formally requested reviewer * `no-reviewer` — List PRs with no formally requested reviewer
* `stale-branches` — List remote branches with no commits in N days, each with its merge outcome (skips branches that are heads of open PRs) * `stale-branches` — List remote branches with no commits in N days, each with its merge outcome (skips branches that are heads of open PRs)
* `assignments` — Group open issues + PRs by assignee * `assignments` — Group open issues + PRs by assignee
* `unlabeled` — List issues/PRs with no exclusive scoped label in `--scope` (e.g. `--scope type` flags items missing any `type/*` label). Generic — the scope is whatever the repo's label taxonomy actually uses, nothing hardcoded here * `unlabeled` — List issues/PRs with no exclusive scoped label in `--scope` (for example `--scope type` flags items missing any `type/*` label). Generic — the scope is whatever the repo's label taxonomy actually uses, nothing hardcoded here
@ -1132,13 +1132,13 @@ Group open issues + PRs by assignee
## `hive-forge lint unlabeled` ## `hive-forge lint unlabeled`
List issues/PRs with no exclusive scoped label in `--scope` (e.g. `--scope type` flags items missing any `type/*` label). Generic — the scope is whatever the repo's label taxonomy actually uses, nothing hardcoded here List issues/PRs with no exclusive scoped label in `--scope` (for example `--scope type` flags items missing any `type/*` label). Generic — the scope is whatever the repo's label taxonomy actually uses, nothing hardcoded here
**Usage:** `hive-forge lint unlabeled [OPTIONS] --scope <SCOPE>` **Usage:** `hive-forge lint unlabeled [OPTIONS] --scope <SCOPE>`
###### **Options:** ###### **Options:**
* `--scope <SCOPE>` — Label scope to check for — the part of a scoped label's name before the `/` (e.g. `type` for `type/bug`, `type/feature`). Required: this command has no built-in notion of a repo's label taxonomy, so there's no sane default to fall back to * `--scope <SCOPE>` — Label scope to check for — the part of a scoped label's name before the `/` (for example `type` for `type/bug`, `type/feature`). Required: this command has no built-in notion of a repo's label taxonomy, so there's no sane default to fall back to
* `--type <TYPE>` — Filter by item kind * `--type <TYPE>` — Filter by item kind
Default value: `all` Default value: `all`
@ -1322,7 +1322,7 @@ Download an attachment by UUID or URL. Saves to a temp file and prints the path
###### **Options:** ###### **Options:**
* `-o`, `--output <OUTPUT>` — Output path. Defaults to `/tmp/forge-attachment-<uuid>`. Pass `-` to write raw bytes to stdout (e.g. for piping to an image viewer) * `-o`, `--output <OUTPUT>` — Output path. Defaults to `/tmp/forge-attachment-<uuid>`. Pass `-` to write raw bytes to stdout (for example for piping to an image viewer)
@ -1334,7 +1334,7 @@ Download a CI Actions artifact from a run (`<name> --run <n>`). Saves a zip, or
###### **Arguments:** ###### **Arguments:**
* `<NAME>` — Artifact name, as shown on the run page (e.g. `pr1ma-paper-pdf`) * `<NAME>` — Artifact name, as shown on the run page (for example `pr1ma-paper-pdf`)
###### **Options:** ###### **Options:**
@ -1387,7 +1387,7 @@ List CI Actions runs, newest first (`--workflow`, `--branch`, `--limit`, `--page
###### **Options:** ###### **Options:**
* `--workflow <WORKFLOW>` — Only runs of this workflow file (e.g. `ci.yml`) * `--workflow <WORKFLOW>` — Only runs of this workflow file (for example `ci.yml`)
* `--branch <BRANCH>` — Only runs on this ref. A branch name (`main`, `damocles/foo`) or a PR (`#N`) is qualified for you; a `refs/…` value is used as given. An all-digit value is read as a PR number — to filter a branch literally named that, pass `refs/heads/<name>` * `--branch <BRANCH>` — Only runs on this ref. A branch name (`main`, `damocles/foo`) or a PR (`#N`) is qualified for you; a `refs/…` value is used as given. An all-digit value is read as a PR number — to filter a branch literally named that, pass `refs/heads/<name>`
* `--limit <LIMIT>` — How many runs to print (default 20) * `--limit <LIMIT>` — How many runs to print (default 20)

6
docs/tools/forge.md
View file

@ -25,7 +25,7 @@ markdown-docs > docs/tools/forge-cli.md`.
**Kind-namespaced commands (preferred):** issue/PR operations are grouped **Kind-namespaced commands (preferred):** issue/PR operations are grouped
under `issue` and `pr` parent commands — `hive-forge pr close 42`, under `issue` and `pr` parent commands — `hive-forge pr close 42`,
`hive-forge issue create --title …`, `hive-forge pr status --pr 42`. The `hive-forge issue create --title …`, `hive-forge pr status --pr 42`. The
`pr <verb>` / `issue <verb>` forms validate the number's kind (e.g. `pr close` `pr <verb>` / `issue <verb>` forms validate the number's kind (for example `pr close`
refuses an issue number, which the old generic `close` couldn't). Run refuses an issue number, which the old generic `close` couldn't). Run
`hive-forge pr --help` / `hive-forge issue --help` for the full subcommand `hive-forge pr --help` / `hive-forge issue --help` for the full subcommand
list (show/create/edit/status/merge/reviews/commits/diff/view/comment/ list (show/create/edit/status/merge/reviews/commits/diff/view/comment/
@ -141,7 +141,7 @@ distinct output shape — pick by what you need:
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The full human view of one item — title, body, **and** every comment in order | `view <n>` | prose dump; **marks the thread read** (clears the read-before-comment guard). Top-level `view` auto-detects issue-or-PR by number; scoped `issue view <n>` / `pr view <n>` do the same when you already know the kind | | The full human view of one item — title, body, **and** every comment in order | `view <n>` | prose dump; **marks the thread read** (clears the read-before-comment guard). Top-level `view` auto-detects issue-or-PR by number; scoped `issue view <n>` / `pr view <n>` do the same when you already know the kind |
| Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue <n>` / `pr <n>` | JSON object | | Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue <n>` / `pr <n>` | JSON object |
| Only the comments (skip the body), e.g. to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) are merged in too | `comments <n>` [`--tail N`] | comment + review-body list; **marks read** | | Only the comments (skip the body), for example to catch up a long thread; for PRs, review bodies (approve/request-changes/comment summaries) are merged in too | `comments <n>` [`--tail N`] | comment + review-body list; **marks read** |
| One specific comment by its id | `comment-show <id>` | single comment | | One specific comment by its id | `comment-show <id>` | single comment |
| The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list | | The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline <n>` | event list |
| The code change | `diff <n>` | unified diff | | The code change | `diff <n>` | unified diff |
@ -257,7 +257,7 @@ to discover valid label names before triaging or to audit the label set.
## Notes ## Notes
- **Read-before-comment guard:** `comment` refuses to post when forge still - **Read-before-comment guard:** `comment` refuses to post when forge still
has an unread notification for the thread (i.e. someone commented since you has an unread notification for the thread (that is someone commented since you
last read it). This prevents accidentally replying to old activity without last read it). This prevents accidentally replying to old activity without
seeing the new context. Read the thread with `hive-forge view <n>` or seeing the new context. Read the thread with `hive-forge view <n>` or
`hive-forge comments <n>` (which mark the notification read and clear the `hive-forge comments <n>` (which mark the notification read and clear the

18
docs/tools/hivectl-cli.md
View file

@ -209,7 +209,7 @@ Promote a matrix user to homeserver admin
###### **Arguments:** ###### **Arguments:**
* `<NAME>` — Matrix localpart of the user to promote (e.g. `argus`) * `<NAME>` — Matrix localpart of the user to promote (for example `argus`)
@ -223,7 +223,7 @@ Persists the new password so a later `create-user` can re-login.
###### **Arguments:** ###### **Arguments:**
* `<NAME>` — Matrix localpart of the account to reset (e.g. `argus`) * `<NAME>` — Matrix localpart of the account to reset (for example `argus`)
@ -360,7 +360,7 @@ Everything here targets a single named agent (`hivectl agent foo restart`, `hive
###### **Arguments:** ###### **Arguments:**
* `<NAME>` — Agent name (e.g. `damocles`, `iris`) * `<NAME>` — Agent name (for example `damocles`, `iris`)
@ -487,8 +487,8 @@ Replaces the agent's whole override entry rather than merging into it: any limit
###### **Options:** ###### **Options:**
* `--cpu-quota <CPU_QUOTA>` — systemd `CPUQuota=` value, e.g. `400%` (100% = one full core) * `--cpu-quota <CPU_QUOTA>` — systemd `CPUQuota=` value, for example `400%` (100% = one full core)
* `--memory-max <MEMORY_MAX>` — systemd `MemoryMax=` value, e.g. `8G`, `50%`, or `infinity` * `--memory-max <MEMORY_MAX>` — systemd `MemoryMax=` value, for example `8G`, `50%`, or `infinity`
* `--reset` — Drop all overrides — the agent returns to the hive-wide defaults. Required to clear limits, so that a `set-limits` with a forgotten value can't silently reset the agent * `--reset` — Drop all overrides — the agent returns to the hive-wide defaults. Required to clear limits, so that a `set-limits` with a forgotten value can't silently reset the agent
@ -753,7 +753,7 @@ Generate this hive's WireGuard key (if absent) and print its public key plus the
###### **Options:** ###### **Options:**
* `--address <ADDRESS>` — This hive's mesh address (e.g. `10.42.0.1/32`) to bake into the printed snippet. Omit to get a placeholder you fill in * `--address <ADDRESS>` — This hive's mesh address (for example `10.42.0.1/32`) to bake into the printed snippet. Omit to get a placeholder you fill in
@ -770,8 +770,8 @@ Print the nix to add a peer hive to the mesh
###### **Options:** ###### **Options:**
* `--pubkey <PUBKEY>` — Peer's WireGuard public key (from its `hivectl wg init`) * `--pubkey <PUBKEY>` — Peer's WireGuard public key (from its `hivectl wg init`)
* `--address <ADDRESS>` — Peer's mesh address (e.g. `10.42.0.2/32`) * `--address <ADDRESS>` — Peer's mesh address (for example `10.42.0.2/32`)
* `--endpoint <ENDPOINT>` — Peer's `host:port` endpoint (omit for a peer that only dials out, e.g. one behind NAT — it must set an endpoint pointing back here) * `--endpoint <ENDPOINT>` — Peer's `host:port` endpoint (omit for a peer that only dials out, for example one behind NAT — it must set an endpoint pointing back here)
@ -793,7 +793,7 @@ Prints the nix a peer operator pastes into their swarm config to trust and reach
###### **Options:** ###### **Options:**
* `--wg-address <WG_ADDRESS>` — This hive's WireGuard mesh address (e.g. `10.42.0.1/32`), emitted as `wireguardAddress`. Omit when not running the mesh * `--wg-address <WG_ADDRESS>` — This hive's WireGuard mesh address (for example `10.42.0.1/32`), emitted as `wireguardAddress`. Omit when not running the mesh
* `--wg-endpoint <WG_ENDPOINT>` — This hive's public WireGuard endpoint (`host:port`), emitted as `wireguardEndpoint`. Omit when peers dial in / no mesh * `--wg-endpoint <WG_ENDPOINT>` — This hive's public WireGuard endpoint (`host:port`), emitted as `wireguardEndpoint`. Omit when peers dial in / no mesh

2
docs/tools/hivectl.md
View file

@ -236,7 +236,7 @@ Bare `choom` starts a fresh blank session. `--resume <value>` passes
through as `claude --resume <value>` to rejoin a prior session by its through as `claude --resume <value>` to rejoin a prior session by its
session id — the flag name deliberately matches the claude flag it maps session id — the flag name deliberately matches the claude flag it maps
to. (choom never uses claude's `--continue`: that's a bare flag that to. (choom never uses claude's `--continue`: that's a bare flag that
takes no argument and resumes the cwd's _latest_ session, i.e. the takes no argument and resumes the cwd's _latest_ session, that is the
harness's; a value after it would be consumed as the first prompt, harness's; a value after it would be consumed as the first prompt,
silently poking the live harness session.) A value is required when the silently poking the live harness session.) A value is required when the
flag is given. Either way choom never collides with the harness's live flag is given. Either way choom never collides with the harness's live

4
docs/tools/lifecycle.md
View file

@ -3,7 +3,7 @@
Two tool groups govern agent lifecycle management and config changes. Two tool groups govern agent lifecycle management and config changes.
Both are scoped to **direct children only** (topology-enforced: the Both are scoped to **direct children only** (topology-enforced: the
server rejects any name that's not a direct child of the calling server rejects any name that's not a direct child of the calling
agent per `topology.json`). Privileged agents (e.g. ruth) may operate agent per `topology.json`). Privileged agents (for example ruth) may operate
on any sub-agent — the topology scope applies to all others. on any sub-agent — the topology scope applies to all others.
## `lifecycle` tool group ## `lifecycle` tool group
@ -60,7 +60,7 @@ Fails if a proposed config repo for `name` already exists.
### `request_update_meta_inputs(inputs?, description?)` ### `request_update_meta_inputs(inputs?, description?)`
Queue an approval to run `nix flake update [inputs...]` on the meta Queue an approval to run `nix flake update [inputs...]` on the meta
flake. Pass specific input names (e.g. `["bitburner-agent"]`) or omit flake. Pass specific input names (for example `["bitburner-agent"]`) or omit
/ pass `[]` for all inputs. Returns immediately; the lock update runs / pass `[]` for all inputs. Returns immediately; the lock update runs
on operator approval. on operator approval.

4
docs/tools/matrix.md
View file

@ -22,7 +22,7 @@ room you haven't read yet.
`user_id` and return its room id **without sending anything**. `user_id` and return its room id **without sending anything**.
Use the returned id with room-based tools (`send_message`, Use the returned id with room-based tools (`send_message`,
`send_file`, …) to deliver into a DM when `send_dm`'s body `send_file`, …) to deliver into a DM when `send_dm`'s body
parameter is inconvenient (e.g. for file attachments) parameter is inconvenient (for example for file attachments)
- `send_reply(room, event_id, body)` — threaded reply to a specific - `send_reply(room, event_id, body)` — threaded reply to a specific
event event
- `send_reaction(room, event_id, key)` — react to a message with an - `send_reaction(room, event_id, key)` — react to a message with an
@ -70,7 +70,7 @@ room you haven't read yet.
## Multiple accounts ## Multiple accounts
`hyperhive.matrixAccounts` (declared in `agent.nix`) gives an agent `hyperhive.matrixAccounts` (declared in `agent.nix`) gives an agent
*additional* matrix identities beyond the hive-internal one — e.g. an *additional* matrix identities beyond the hive-internal one — for example an
external-facing account alongside the internal one. Each entry is external-facing account alongside the internal one. Each entry is
keyed by account name and specifies `tokenFile` (bearer token, keyed by account name and specifies `tokenFile` (bearer token,
provisioned out-of-band; basename must start with `matrix-token`), provisioned out-of-band; basename must start with `matrix-token`),

10
docs/tools/scheduling.md
View file

@ -60,7 +60,7 @@ Fetch recent journal lines for a sub-agent container. Useful for
diagnosing MCP-registration failures, startup crashes, plugin install diagnosing MCP-registration failures, startup crashes, plugin install
errors, or any harness issue you can't see from inside the container. errors, or any harness issue you can't see from inside the container.
Pass the plain logical agent name (e.g. `"gui"`) — hive-c0re resolves Pass the plain logical agent name (for example `"gui"`) — hive-c0re resolves
the machine name (`h-<name>`). `lines` defaults to 50, host-capped at 500. the machine name (`h-<name>`). `lines` defaults to 50, host-capped at 500.
## `read_host_journal` capability ## `read_host_journal` capability
@ -76,17 +76,17 @@ Fetch recent lines from the **host** journal (requires
outside your own container — infrastructure services, hive-c0re outside your own container — infrastructure services, hive-c0re
lifecycle events, or another container's boot log. lifecycle events, or another container's boot log.
- `unit` — filter to a systemd unit (e.g. `hive-c0re.service`). - `unit` — filter to a systemd unit (for example `hive-c0re.service`).
- `container` — nspawn machine name verbatim. Agent containers use - `container` — nspawn machine name verbatim. Agent containers use
the `h-<name>` prefix (e.g. `h-iris`); infrastructure containers the `h-<name>` prefix (for example `h-iris`); infrastructure containers
use their full name (e.g. `hive-ci`, `hive-forge`, `hive-matrix`). use their full name (for example `hive-ci`, `hive-forge`, `hive-matrix`).
Omit for the host journal. The gateway has no machine — its nginx Omit for the host journal. The gateway has no machine — its nginx
runs on the host, so read it with `unit: nginx.service` and no runs on the host, so read it with `unit: nginx.service` and no
`container`. `container`.
- `lines` — how many lines to return (default 30, max 100). - `lines` — how many lines to return (default 30, max 100).
- `priority` — minimum syslog level (`emerg` … `debug`). - `priority` — minimum syslog level (`emerg` … `debug`).
- `grep` — regex matched against log message fields (`journalctl --grep`). - `grep` — regex matched against log message fields (`journalctl --grep`).
- `since` / `until` — time bounds (e.g. `-1h`, `2024-01-01 12:00:00`). - `since` / `until` — time bounds (for example `-1h`, `2024-01-01 12:00:00`).
## See also ## See also

2
docs/tools/swarmctl-cli.md
View file

@ -25,7 +25,7 @@ swarm-level operator CLI
###### **Options:** ###### **Options:**
* `--authelia-bin <PATH>` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the *configured* package rather than whatever is on `PATH` * `--authelia-bin <PATH>` — authelia binary used to hash passwords. The argon2 parameters must match the verifier's, so this has to be the *configured* package rather than whatever is on `PATH`
* `--users-file <PATH>` — Host-side path of authelia's users database — i.e. the path inside the container, prefixed with the container's root. * `--users-file <PATH>` — Host-side path of authelia's users database — that is the path inside the container, prefixed with the container's root.
This is the only user store: it's read before every change and written in place, and `swarm-authelia-bridge` writes the same file. This is the only user store: it's read before every change and written in place, and `swarm-authelia-bridge` writes the same file.

2
docs/trust-boundary/security.md
View file

@ -17,7 +17,7 @@ own container the agent is privileged — it has **passwordless `sudo` by
default**. Isolating credentials _from the agent itself_ is therefore **not a default**. Isolating credentials _from the agent itself_ is therefore **not a
goal**: an agent can read its own tokens, its own `/home/<name>/.claude`, and goal**: an agent can read its own tokens, its own `/home/<name>/.claude`, and
run arbitrary commands as root inside its container. (The narrow exception is run arbitrary commands as root inside its container. (The narrow exception is
_cross-tenant_ leakage — e.g. the unsandboxed-nix-build `0600` token policy _cross-tenant_ leakage — for example the unsandboxed-nix-build `0600` token policy
below stops a build's nixbld user reading the agent's own forge token, and the below stops a build's nixbld user reading the agent's own forge token, and the
state-file endpoint stops one agent proxying another's files. Those harden the state-file endpoint stops one agent proxying another's files. Those harden the
boundary; they don't sandbox the agent from itself.) boundary; they don't sandbox the agent from itself.)

2
docs/turn-loop/claude-invocation.md
View file

@ -238,7 +238,7 @@ needs to `chown` a bind mount), once at startup:
else is shared. Five placeholders are then else is shared. Five placeholders are then
substituted: `{label}` (short agent name), `{qualified_label}` substituted: `{label}` (short agent name), `{qualified_label}`
(hive-qualified `name@domain` form), `{operator_pronouns}`, (hive-qualified `name@domain` form), `{operator_pronouns}`,
`{hive_identity}` (e.g. `` on hive `pr1ma` ``; empty when `{hive_identity}` (for example `` on hive `pr1ma` ``; empty when
`hyperhive.hiveName` is unset), and `{swarm_identity}` (same `hyperhive.hiveName` is unset), and `{swarm_identity}` (same
shape for the swarm). Pronouns come from `HIVE_OPERATOR_PRONOUNS` shape for the swarm). Pronouns come from `HIVE_OPERATOR_PRONOUNS`
env (set by the meta flake from env (set by the meta flake from

4
docs/turn-loop/config.md
View file

@ -142,7 +142,7 @@ a one-shot boot unit (`tea-login`) that writes `~/.config/tea/config.yml`
directly from the agent's `forge-token`, so `tea` and `hive-forge` directly from the agent's `forge-token`, so `tea` and `hive-forge`
work without an interactive auth step. The unit is a no-op when work without an interactive auth step. The unit is a no-op when
`forge-token` is absent. Override when the agent should connect to a `forge-token` is absent. Override when the agent should connect to a
Forgejo on a different host or port (e.g. a swarm peer's forge). Forgejo on a different host or port (for example a swarm peer's forge).
Validated: must be an `http://` or `https://` URL, or `null`. Validated: must be an `http://` or `https://` URL, or `null`.
**Defaults to `null`, meaning "no forge" — not a guessed address.** A **Defaults to `null`, meaning "no forge" — not a guessed address.** A
@ -249,7 +249,7 @@ hyperhive.backendEnvironmentFile =
hyperhive.model = "anthropic/claude-3.5-sonnet"; # provider-specific model string hyperhive.model = "anthropic/claude-3.5-sonnet"; # provider-specific model string
``` ```
Runs this agent's `claude` against an API-key backend (e.g. OpenRouter) Runs this agent's `claude` against an API-key backend (for example OpenRouter)
instead of a Claude subscription via OAuth. Two options, paired — each instead of a Claude subscription via OAuth. Two options, paired — each
is a no-op without the other: is a no-op without the other:

2
docs/turn-loop/mcp.md
View file

@ -78,7 +78,7 @@ at_unix_timestamp?)`.
- `get_loose_ends(agent?)` — list scheduled reminders, pending - `get_loose_ends(agent?)` — list scheduled reminders, pending
approvals you submitted, and active local tasks published by approvals you submitted, and active local tasks published by
external MCP daemons (e.g. running bash tasks from external MCP daemons (for example running bash tasks from
`hive-bash-daemon`). Each row carries an id + kind for `hive-bash-daemon`). Each row carries an id + kind for
`cancel_loose_end`. Omit `agent` to list your own threads. Pass `cancel_loose_end`. Omit `agent` to list your own threads. Pass
`agent: "<name>"` to inspect a direct child agent (always accessible `agent: "<name>"` to inspect a direct child agent (always accessible

2
docs/web-ui/agent.md
View file

@ -392,7 +392,7 @@ shaped).
The `/extra/` namespace ensures user-declared proxies can never The `/extra/` namespace ensures user-declared proxies can never
conflict with native agent endpoints. Upstream values are either an conflict with native agent endpoints. Upstream values are either an
`http(s)://` URL (forwarded via `reqwest`) or a Unix domain socket, `http(s)://` URL (forwarded via `reqwest`) or a Unix domain socket,
spelled `unix:<path>` (e.g. `unix:/run/myapp/http.sock`) — dialed spelled `unix:<path>` (for example `unix:/run/myapp/http.sock`) — dialed
directly with a raw HTTP/1.1 client per request, since `reqwest` has directly with a raw HTTP/1.1 client per request, since `reqwest` has
no UDS transport. Implemented in `web_ui/proxy.rs`. no UDS transport. Implemented in `web_ui/proxy.rs`.

8
docs/web-ui/css-vars.md
View file

@ -4,7 +4,7 @@ Colour variables live in **two standalone stylesheets**, split so a theme
swap touches only the first: swap touches only the first:
1. **`colors.css`** — the 16 `--base00`…`--base0F` base16 slots. **This is 1. **`colors.css`** — the 16 `--base00`…`--base0F` base16 slots. **This is
the entire theme swap contract.** A generator (e.g. one fed a stylix the entire theme swap contract.** A generator (for example one fed a stylix
base16 scheme, which is natively base00–base0F) replaces _only this base16 scheme, which is natively base00–base0F) replaces _only this
file_. file_.
2. **`theme.css`** — the semantic layer: `--bg`, `--fg`, `--purple`, … 2. **`theme.css`** — the semantic layer: `--bg`, `--fg`, `--purple`, …
@ -88,7 +88,7 @@ Variables to avoid (undefined — they will silently resolve to transparent / in
## Usage guide ## Usage guide
**Floating menus and dropdowns** (e.g. agent context menu, tabbar overflow): **Floating menus and dropdowns** (for example agent context menu, tabbar overflow):
```css ```css
background: var(--bg-elev); background: var(--bg-elev);
@ -124,7 +124,7 @@ color: var(--green); /* ok */
## Theme swapping — the base16 contract ## Theme swapping — the base16 contract
**The swap interface is `colors.css` — the 16 base16 slots, not our **The swap interface is `colors.css` — the 16 base16 slots, not our
semantic names.** A theme generator (e.g. one reading a stylix base16 semantic names.** A theme generator (for example one reading a stylix base16
scheme) overrides only `colors.css`; the semantic layer in `theme.css` scheme) overrides only `colors.css`; the semantic layer in `theme.css`
derives everything else, so the whole UI re-themes with nothing else to derives everything else, so the whole UI re-themes with nothing else to
template or regenerate. The base16 slot → semantic mapping is _internal_ template or regenerate. The base16 slot → semantic mapping is _internal_
@ -136,7 +136,7 @@ untouched.
(Catppuccin Mocha, unconditional) and a light default (Catppuccin Latte, (Catppuccin Mocha, unconditional) and a light default (Catppuccin Latte,
behind `@media (prefers-color-scheme: light)`), plus a per-user override behind `@media (prefers-color-scheme: light)`), plus a per-user override
path (`:root[data-theme]`) — a theme generator that overrides the file path (`:root[data-theme]`) — a theme generator that overrides the file
wholesale (e.g. the stylix path, which writes a single unconditional wholesale (for example the stylix path, which writes a single unconditional
`:root` block with no media query, no `--mocha-*`/`--latte-*` vars, no `:root` block with no media query, no `--mocha-*`/`--latte-*` vars, no
`[data-theme]` blocks) supersedes all of it at once, same as today. `[data-theme]` blocks) supersedes all of it at once, same as today.

8
docs/web-ui/dashboard.md
View file

@ -454,7 +454,7 @@ named buckets of MCP tools; each agent starts with a role default
`ToolGroup::AGENT_DEFAULT`; root agent is seeded to `ToolGroup::AGENT_DEFAULT`; root agent is seeded to
`ToolGroup::MANAGER_DEFAULT` — `messaging`, `meta`, `inbox`, `ToolGroup::MANAGER_DEFAULT` — `messaging`, `meta`, `inbox`,
`lifecycle`, `approvals`, `scheduling`, `diagnostics`, `execution`, `lifecycle`, `approvals`, `scheduling`, `diagnostics`, `execution`,
i.e. every group except `forge` and `web_tools`). Checking / that is every group except `forge` and `web_tools`). Checking /
unchecking stages which groups are active for the agent; the unchecking stages which groups are active for the agent; the
page-level **save all** button (below) commits it. Columns come from page-level **save all** button (below) commits it. Columns come from
`GET /api/tool-groups`. A rebuild is queued so `HIVE_TOOL_GROUPS` `GET /api/tool-groups`. A rebuild is queued so `HIVE_TOOL_GROUPS`
@ -826,7 +826,7 @@ limited` (red, while the harness is parked after a 429), `needs
login`, `needs update` — plus **one `◐ pending-state…` pill per login`, `needs update` — plus **one `◐ pending-state…` pill per
active transient** (replaces buttons during operator-initiated active transient** (replaces buttons during operator-initiated
start / stop / restart / rebuild / destroy). An agent can carry start / stop / restart / rebuild / destroy). An agent can carry
**several transients at once** — e.g. a lease-exempt `prebuild` **several transients at once** — for example a lease-exempt `prebuild`
running alongside a `stop_for_update` on the same agent — and each running alongside a `stop_for_update` on the same agent — and each
renders as its own independent badge rather than being collapsed renders as its own independent badge rather than being collapsed
into one label, matching the existing multi-badge convention this into one label, matching the existing multi-badge convention this
@ -1025,7 +1025,7 @@ frosted-mauve bar slides up from the bottom of the viewport
- `⇡ M0V3 → ROOT` — promote selected agents to top-level - `⇡ M0V3 → ROOT` — promote selected agents to top-level
(parent = null); disabled when all selected are already at root. (parent = null); disabled when all selected are already at root.
Backend `topology::set_parent` refuses moves it can't satisfy Backend `topology::set_parent` refuses moves it can't satisfy
(e.g. a move that would create a cycle) and the refusal surfaces (for example a move that would create a cycle) and the refusal surfaces
in the failure roll-up. in the failure roll-up.
- `⇢ M0V3 → [select]` — inline picker available for any - `⇢ M0V3 → [select]` — inline picker available for any
selection size. The dropdown lists every container that isn't IN selection size. The dropdown lists every container that isn't IN
@ -1328,7 +1328,7 @@ payload):
emitted by `Coordinator::rescan_containers_and_emit` from emitted by `Coordinator::rescan_containers_and_emit` from
many mutation sites — post-spawn approval bookkeeping many mutation sites — post-spawn approval bookkeeping
(`actions::approve`), the job queue's own node execution (`actions::approve`), the job queue's own node execution
(`job_queue::exec`, e.g. after a rebuild's stop/swap/start (`job_queue::exec`, for example after a rebuild's stop/swap/start
steps or a destroy's teardown step) — and from the 10s steps or a destroy's teardown step) — and from the 10s
`crash_watch` poll. Client upserts/removes by name; the `crash_watch` poll. Client upserts/removes by name; the
pending overlay is read from `transientsState` since the pending overlay is read from `transientsState` since the

4
docs/web-ui/shape.md
View file

@ -72,7 +72,7 @@
each subscribed tab via `MessagePort`; on bfcache restore the each subscribed tab via `MessagePort`; on bfcache restore the
page re-subscribes (gets a synthetic `open` event immediately page re-subscribes (gets a synthetic `open` event immediately
if the upstream is already connected). Falls back gracefully if the upstream is already connected). Falls back gracefully
when `SharedWorker` is unavailable (e.g. some private-mode when `SharedWorker` is unavailable (for example some private-mode
browsers). **Worker-death self-heal**: Firefox kills browsers). **Worker-death self-heal**: Firefox kills
"idle" SharedWorkers under memory pressure with no client-side "idle" SharedWorkers under memory pressure with no client-side
signal — the port silently goes no-op. The worker now pings signal — the port silently goes no-op. The worker now pings
@ -124,7 +124,7 @@ failed/skipped fetch), `onStreamOpen?()` (fires on every EventSource
returning one, re-read on every `api.details`/`api.detailsDiff` call rather returning one, re-read on every `api.details`/`api.detailsDiff` call rather
than captured once — lets a page default otherwise-collapsed panels open than captured once — lets a page default otherwise-collapsed panels open
per a live browser-local preference; renderers that force a row open per a live browser-local preference; renderers that force a row open
regardless, e.g. message-bearing tool_use, are unaffected either way). regardless, for example message-bearing tool_use, are unaffected either way).
**Sticky-bottom + snap animation.** `stickToBottom` is the **Sticky-bottom + snap animation.** `stickToBottom` is the
operator's intent: true means "keep snapping to bottom on every operator's intent: true means "keep snapping to bottom on every