diff --git a/docs/agent-lifecycle/agent-hierarchy.md b/docs/agent-lifecycle/agent-hierarchy.md index 49989168..8ecb791a 100644 --- a/docs/agent-lifecycle/agent-hierarchy.md +++ b/docs/agent-lifecycle/agent-hierarchy.md @@ -123,7 +123,7 @@ other agents don't: a root-only capability even post-milestone, not a topology rule. One exception: `Wake` (inject a `from: ` message into the 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. - **Storage/mounts** — only the manager container gets `/var/lib/hyperhive/agents` bind-mounted RW at `/agents` (so it can diff --git a/docs/agent-lifecycle/approvals.md b/docs/agent-lifecycle/approvals.md index 4d6877f6..3dfedc69 100644 --- a/docs/agent-lifecycle/approvals.md +++ b/docs/agent-lifecycle/approvals.md @@ -246,7 +246,7 @@ Transient broker errors (sqlite lock contention, etc.) get the same ### Reminder delivery: file-path semantics A reminder may carry a `file_path` (the agent-visible path inside its -container, e.g. `/agents//state/foo.md`). On delivery hive-c0re: +container, for example `/agents//state/foo.md`). On delivery hive-c0re: 1. **Translates** the container path to the host path (`/var/lib/hyperhive/agents//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 file: `/var/lib/hyperhive/applied/..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. The dashboard surfaces pending updates per agent: a clickable diff --git a/docs/agent-lifecycle/persistence.md b/docs/agent-lifecycle/persistence.md index 046982bd..0cdc420b 100644 --- a/docs/agent-lifecycle/persistence.md +++ b/docs/agent-lifecycle/persistence.md @@ -337,7 +337,7 @@ A parent agent gets each direct child's `state` dir bind-mounted **read-write** and its `config` dir **read-only** (`bind_child_agent_dirs` in `lifecycle/host_config.rs`). The RW on `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. **`harness` isn't mounted at all.** It holds the child's own runtime diff --git a/docs/integrations/forge.md b/docs/integrations/forge.md index 3e25fc94..f6f00191 100644 --- a/docs/integrations/forge.md +++ b/docs/integrations/forge.md @@ -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: 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` -(`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 `comment by : ` block before the meta suffix (`fresh_post_close_comment_tail`). So the wake carries **both** `[PR merged]` diff --git a/docs/integrations/knowledge.md b/docs/integrations/knowledge.md index ffc2a068..023b6af7 100644 --- a/docs/integrations/knowledge.md +++ b/docs/integrations/knowledge.md @@ -69,7 +69,7 @@ each call site. ### Change notice 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: sender `system`, body `[system] /knowledge updated:` followed by a `git diff --stat ..` summary of what changed (or a generic diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index 66b1f4b4..4a88d05f 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -125,7 +125,7 @@ see it. The agent only receives the resulting `access_token`. 6. **hive-c0re restarts `hive-matrix-daemon`** for the agent immediately after writing the token so the daemon picks up the 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 (`hive-matrix-daemon.path` watching for `matrix-token` appearance) 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 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 diff --git a/docs/networking/gateway.md b/docs/networking/gateway.md index cd9a5a88..99d60376 100644 --- a/docs/networking/gateway.md +++ b/docs/networking/gateway.md @@ -382,7 +382,7 @@ The gateway always terminates TLS, so the `behindGateway = true` case is always advertised over `https://`; only the direct (`behindGateway = false`) shape stays `http://`. Set `rootUrl` explicitly when `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 enforces this). @@ -450,7 +450,7 @@ store path baked in at hive-c0re build time, and c0re (writing so they see the same store. **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 daemon as before. @@ -575,7 +575,7 @@ vhost (`_`, `forge.`, `chat.`): nginx's `add_header` inheritance rule: a `location` block that sets its 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 with no `add_header` of their own pick the security headers up automatically. diff --git a/docs/networking/network.md b/docs/networking/network.md index d850a3f6..cf9a3e47 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -180,7 +180,7 @@ namespace. ### Reaching host services (`exposeHostPorts`) 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 needs none of this: `otel.enable` opens its collector's port itself, and `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 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 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 diff --git a/docs/process/conventions.md b/docs/process/conventions.md index d174153f..e590e86f 100644 --- a/docs/process/conventions.md +++ b/docs/process/conventions.md @@ -26,7 +26,7 @@ Four env vars cover the identity surface, read by - `HYPERHIVE_HIVE_DOMAIN` — the hive's canonical DNS domain (e.g. `darkest.space`), set by `nix/host-modules/hive-c0re/environment.nix` 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 the short label so existing callers see no change. 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. `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 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, **don't assume a transient builder problem** — reproduce the real 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`. ## Best-effort oneshot services diff --git a/docs/process/gotchas.md b/docs/process/gotchas.md index 8d5f2882..7938d7f8 100644 --- a/docs/process/gotchas.md +++ b/docs/process/gotchas.md @@ -309,7 +309,7 @@ nix develop -c cargo run -p hive-c0re --bin hivectl -- ``` 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 CI on drift). @@ -389,7 +389,7 @@ connects to the compositor at `127.0.0.1:`. fixed `/run/gui` (systemd `RuntimeDirectory=gui`, `0700`, `RuntimeDirectoryPreserve=yes` so it survives weston restarts for the 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`. - **One shared D-Bus session bus (`gui-dbus.service`)**: a single persistent `dbus-daemon --session` bound at `/run/gui/bus`, run as the diff --git a/docs/process/pr-review-gate.md b/docs/process/pr-review-gate.md index f02560cf..f4a38db0 100644 --- a/docs/process/pr-review-gate.md +++ b/docs/process/pr-review-gate.md @@ -31,7 +31,7 @@ is someone else's call. Submit `hive-forge pr-reviews --approve` or `--request-changes` 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 -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 signal a reviewer waits on, it's a separate condition that resolves independently. diff --git a/docs/scheduler/ci.md b/docs/scheduler/ci.md index 88724f75..84a70bd7 100644 --- a/docs/scheduler/ci.md +++ b/docs/scheduler/ci.md @@ -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 admin panel), `concurrency` (parallel job capacity), `labels` (workflow 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). ## 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_ 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. diff --git a/docs/scheduler/observability.md b/docs/scheduler/observability.md index 0f5125c0..57c2f327 100644 --- a/docs/scheduler/observability.md +++ b/docs/scheduler/observability.md @@ -199,7 +199,7 @@ automatically: | Attribute | Value | | -------------- | ------------------------------------------------------------ | | `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`) | | `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 [--type counter|gauge] [--temporality delta|cumulative] [--labels key=value...] ``` -- `` — metric name (e.g. `tasks_completed`, `latency_ms`). +- `` — metric name (for example `tasks_completed`, `latency_ms`). - `` — numeric value (f64; integers and floats both accepted). - `--type counter|gauge` — metric kind: `counter` (increasing sum, default) or `gauge` (instantaneous point-in-time value). diff --git a/docs/swarm/ui.md b/docs/swarm/ui.md index 9cff8e28..d98f15c1 100644 --- a/docs/swarm/ui.md +++ b/docs/swarm/ui.md @@ -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 a container": -| site | file | -| ---------------------------- | --------------------------------------------------------------- | -| vhost + `gateway.localNames` | the service's own module (e.g. `nix/host-modules/swarm-ui.nix`) | -| **certificate name** | `nix/host-modules/swarm.nix` (`serviceDomains`) | +| site | file | +| ---------------------------- | ---------------------------------------------------------------------- | +| vhost + `gateway.localNames` | the service's own module (for example `nix/host-modules/swarm-ui.nix`) | +| **certificate name** | `nix/host-modules/swarm.nix` (`serviceDomains`) | The DNS record and the local-dev `/etc/hosts` entry need no separate edit: both are derived from `services.hyperhive.gateway.localNames`, diff --git a/docs/tools/forge-cli.md b/docs/tools/forge-cli.md index a9e27554..a6a20585 100644 --- a/docs/tools/forge-cli.md +++ b/docs/tools/forge-cli.md @@ -173,7 +173,7 @@ Create an issue * `--body ` — Inline body text * `--body-file ` — Read body from a file. `-` means stdin * `--assignee ` — Initial assignee login -* `--label ` — 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 ` — 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:** * `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 ###### **Arguments:** @@ -425,7 +425,7 @@ List reactions (default when no action is given) ## `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 ` @@ -540,7 +540,7 @@ Create a pull request * `--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 * `--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 ` — 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 ` — 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:** * `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 ###### **Arguments:** @@ -884,7 +884,7 @@ List reactions (default when no action is given) ## `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 ` @@ -962,7 +962,7 @@ Clone a forge repo (default `-r`/`HIVE_FORGE_REPO`) with credentials auto-inject ###### **Arguments:** -* `` — Destination directory. Defaults to the repo's basename (e.g. `internal/knowledge` → `knowledge`) +* `` — Destination directory. Defaults to the repo's basename (for example `internal/knowledge` → `knowledge`) ###### **Options:** @@ -985,7 +985,7 @@ Create a forge repo under the current user (or `--org`). Prints the repo URL * `--description ` — Repository description * `--private` — Create the repo as private (default: public) -* `--default-branch ` — Default branch name (e.g. `main`). Only takes effect with `--auto-init` +* `--default-branch ` — Default branch name (for example `main`). Only takes effect with `--auto-init` * `--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 @@ -1059,7 +1059,7 @@ Triage lint queries (unassigned / no-reviewer / stale-branches / assignments / u * `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) * `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` -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 ` ###### **Options:** -* `--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 ` — 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 ` — Filter by item kind Default value: `all` @@ -1322,7 +1322,7 @@ Download an attachment by UUID or URL. Saves to a temp file and prints the path ###### **Options:** -* `-o`, `--output ` — Output path. Defaults to `/tmp/forge-attachment-`. Pass `-` to write raw bytes to stdout (e.g. for piping to an image viewer) +* `-o`, `--output ` — Output path. Defaults to `/tmp/forge-attachment-`. 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 (` --run `). Saves a zip, or ###### **Arguments:** -* `` — Artifact name, as shown on the run page (e.g. `pr1ma-paper-pdf`) +* `` — Artifact name, as shown on the run page (for example `pr1ma-paper-pdf`) ###### **Options:** @@ -1387,7 +1387,7 @@ List CI Actions runs, newest first (`--workflow`, `--branch`, `--limit`, `--page ###### **Options:** -* `--workflow ` — Only runs of this workflow file (e.g. `ci.yml`) +* `--workflow ` — Only runs of this workflow file (for example `ci.yml`) * `--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/` * `--limit ` — How many runs to print (default 20) diff --git a/docs/tools/forge.md b/docs/tools/forge.md index 9757c077..0bb34374 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -25,7 +25,7 @@ markdown-docs > docs/tools/forge-cli.md`. **Kind-namespaced commands (preferred):** issue/PR operations are grouped under `issue` and `pr` parent commands — `hive-forge pr close 42`, `hive-forge issue create --title …`, `hive-forge pr status --pr 42`. The -`pr ` / `issue ` forms validate the number's kind (e.g. `pr close` +`pr ` / `issue ` forms validate the number's kind (for example `pr close` refuses an issue number, which the old generic `close` couldn't). Run `hive-forge pr --help` / `hive-forge issue --help` for the full subcommand 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 ` | 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 ` / `pr view ` do the same when you already know the kind | | Just the structured metadata of one item (state, labels, assignees, head sha…) | `issue ` / `pr ` | 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 ` [`--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 ` [`--tail N`] | comment + review-body list; **marks read** | | One specific comment by its id | `comment-show ` | single comment | | The audit trail — closes, label/assignee changes, commit refs, merges (no comment bodies) | `timeline ` | event list | | The code change | `diff ` | unified diff | @@ -257,7 +257,7 @@ to discover valid label names before triaging or to audit the label set. ## Notes - **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 seeing the new context. Read the thread with `hive-forge view ` or `hive-forge comments ` (which mark the notification read and clear the diff --git a/docs/tools/hivectl-cli.md b/docs/tools/hivectl-cli.md index aa2474c6..adddd52e 100644 --- a/docs/tools/hivectl-cli.md +++ b/docs/tools/hivectl-cli.md @@ -209,7 +209,7 @@ Promote a matrix user to homeserver admin ###### **Arguments:** -* `` — Matrix localpart of the user to promote (e.g. `argus`) +* `` — 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:** -* `` — Matrix localpart of the account to reset (e.g. `argus`) +* `` — 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:** -* `` — Agent name (e.g. `damocles`, `iris`) +* `` — 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:** -* `--cpu-quota ` — systemd `CPUQuota=` value, e.g. `400%` (100% = one full core) -* `--memory-max ` — systemd `MemoryMax=` value, e.g. `8G`, `50%`, or `infinity` +* `--cpu-quota ` — systemd `CPUQuota=` value, for example `400%` (100% = one full core) +* `--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 @@ -753,7 +753,7 @@ Generate this hive's WireGuard key (if absent) and print its public key plus the ###### **Options:** -* `--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
` — 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:** * `--pubkey ` — Peer's WireGuard public key (from its `hivectl wg init`) -* `--address
` — Peer's mesh address (e.g. `10.42.0.2/32`) -* `--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) +* `--address
` — Peer's mesh address (for example `10.42.0.2/32`) +* `--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:** -* `--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 ` — This hive's WireGuard mesh address (for example `10.42.0.1/32`), emitted as `wireguardAddress`. Omit when not running the mesh * `--wg-endpoint ` — This hive's public WireGuard endpoint (`host:port`), emitted as `wireguardEndpoint`. Omit when peers dial in / no mesh diff --git a/docs/tools/hivectl.md b/docs/tools/hivectl.md index 601696e8..47a584da 100644 --- a/docs/tools/hivectl.md +++ b/docs/tools/hivectl.md @@ -236,7 +236,7 @@ Bare `choom` starts a fresh blank session. `--resume ` passes through as `claude --resume ` to rejoin a prior session by its 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 -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, 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 diff --git a/docs/tools/lifecycle.md b/docs/tools/lifecycle.md index fa8bc563..beef184c 100644 --- a/docs/tools/lifecycle.md +++ b/docs/tools/lifecycle.md @@ -3,7 +3,7 @@ Two tool groups govern agent lifecycle management and config changes. Both are scoped to **direct children only** (topology-enforced: the 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. ## `lifecycle` tool group @@ -60,7 +60,7 @@ Fails if a proposed config repo for `name` already exists. ### `request_update_meta_inputs(inputs?, description?)` 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 on operator approval. diff --git a/docs/tools/matrix.md b/docs/tools/matrix.md index d2634d7c..58c67d3e 100644 --- a/docs/tools/matrix.md +++ b/docs/tools/matrix.md @@ -22,7 +22,7 @@ room you haven't read yet. `user_id` and return its room id **without sending anything**. Use the returned id with room-based tools (`send_message`, `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 event - `send_reaction(room, event_id, key)` — react to a message with an @@ -70,7 +70,7 @@ room you haven't read yet. ## Multiple accounts `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 keyed by account name and specifies `tokenFile` (bearer token, provisioned out-of-band; basename must start with `matrix-token`), diff --git a/docs/tools/scheduling.md b/docs/tools/scheduling.md index 71e30228..32797043 100644 --- a/docs/tools/scheduling.md +++ b/docs/tools/scheduling.md @@ -60,7 +60,7 @@ Fetch recent journal lines for a sub-agent container. Useful for diagnosing MCP-registration failures, startup crashes, plugin install 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-`). `lines` defaults to 50, host-capped at 500. ## `read_host_journal` capability @@ -76,17 +76,17 @@ Fetch recent lines from the **host** journal (requires outside your own container — infrastructure services, hive-c0re 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 - the `h-` prefix (e.g. `h-iris`); infrastructure containers - use their full name (e.g. `hive-ci`, `hive-forge`, `hive-matrix`). + the `h-` prefix (for example `h-iris`); infrastructure containers + use their full name (for example `hive-ci`, `hive-forge`, `hive-matrix`). 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 `container`. - `lines` — how many lines to return (default 30, max 100). - `priority` — minimum syslog level (`emerg` … `debug`). - `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 diff --git a/docs/tools/swarmctl-cli.md b/docs/tools/swarmctl-cli.md index 6c208578..cc43dda5 100644 --- a/docs/tools/swarmctl-cli.md +++ b/docs/tools/swarmctl-cli.md @@ -25,7 +25,7 @@ swarm-level operator CLI ###### **Options:** * `--authelia-bin ` — 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 ` — Host-side path of authelia's users database — i.e. the path inside the container, prefixed with the container's root. +* `--users-file ` — 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. diff --git a/docs/trust-boundary/security.md b/docs/trust-boundary/security.md index 27492f6f..2ba3962d 100644 --- a/docs/trust-boundary/security.md +++ b/docs/trust-boundary/security.md @@ -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 goal**: an agent can read its own tokens, its own `/home//.claude`, and 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 state-file endpoint stops one agent proxying another's files. Those harden the boundary; they don't sandbox the agent from itself.) diff --git a/docs/turn-loop/claude-invocation.md b/docs/turn-loop/claude-invocation.md index 34d2ddf5..cb82eaf0 100644 --- a/docs/turn-loop/claude-invocation.md +++ b/docs/turn-loop/claude-invocation.md @@ -238,7 +238,7 @@ needs to `chown` a bind mount), once at startup: else is shared. Five placeholders are then substituted: `{label}` (short agent name), `{qualified_label}` (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 shape for the swarm). Pronouns come from `HIVE_OPERATOR_PRONOUNS` env (set by the meta flake from diff --git a/docs/turn-loop/config.md b/docs/turn-loop/config.md index 0c4ba294..61bd3d81 100644 --- a/docs/turn-loop/config.md +++ b/docs/turn-loop/config.md @@ -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` 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 -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`. **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 ``` -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 is a no-op without the other: diff --git a/docs/turn-loop/mcp.md b/docs/turn-loop/mcp.md index 62f2fb10..cd6d090c 100644 --- a/docs/turn-loop/mcp.md +++ b/docs/turn-loop/mcp.md @@ -78,7 +78,7 @@ at_unix_timestamp?)`. - `get_loose_ends(agent?)` — list scheduled reminders, pending 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 `cancel_loose_end`. Omit `agent` to list your own threads. Pass `agent: ""` to inspect a direct child agent (always accessible diff --git a/docs/web-ui/agent.md b/docs/web-ui/agent.md index 1a4e5eca..5982e4b8 100644 --- a/docs/web-ui/agent.md +++ b/docs/web-ui/agent.md @@ -392,7 +392,7 @@ shaped). The `/extra/` namespace ensures user-declared proxies can never conflict with native agent endpoints. Upstream values are either an `http(s)://` URL (forwarded via `reqwest`) or a Unix domain socket, - spelled `unix:` (e.g. `unix:/run/myapp/http.sock`) — dialed + spelled `unix:` (for example `unix:/run/myapp/http.sock`) — dialed directly with a raw HTTP/1.1 client per request, since `reqwest` has no UDS transport. Implemented in `web_ui/proxy.rs`. diff --git a/docs/web-ui/css-vars.md b/docs/web-ui/css-vars.md index 36d54669..f7724f46 100644 --- a/docs/web-ui/css-vars.md +++ b/docs/web-ui/css-vars.md @@ -4,7 +4,7 @@ Colour variables live in **two standalone stylesheets**, split so a theme swap touches only the first: 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 file_. 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 -**Floating menus and dropdowns** (e.g. agent context menu, tabbar overflow): +**Floating menus and dropdowns** (for example agent context menu, tabbar overflow): ```css background: var(--bg-elev); @@ -124,7 +124,7 @@ color: var(--green); /* ok */ ## Theme swapping — the base16 contract **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` derives everything else, so the whole UI re-themes with nothing else to template or regenerate. The base16 slot → semantic mapping is _internal_ @@ -136,7 +136,7 @@ untouched. (Catppuccin Mocha, unconditional) and a light default (Catppuccin Latte, behind `@media (prefers-color-scheme: light)`), plus a per-user override 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 `[data-theme]` blocks) supersedes all of it at once, same as today. diff --git a/docs/web-ui/dashboard.md b/docs/web-ui/dashboard.md index 435e0a80..7b4d471e 100644 --- a/docs/web-ui/dashboard.md +++ b/docs/web-ui/dashboard.md @@ -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::MANAGER_DEFAULT` — `messaging`, `meta`, `inbox`, `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 page-level **save all** button (below) commits it. Columns come from `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 active transient** (replaces buttons during operator-initiated 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 renders as its own independent badge rather than being collapsed 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 (parent = null); disabled when all selected are already at root. 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. - `⇢ M0V3 → [select]` — inline picker available for any selection size. The dropdown lists every container that isn't IN @@ -1328,7 +1328,7 @@ payload): emitted by `Coordinator::rescan_containers_and_emit` from many mutation sites — post-spawn approval bookkeeping (`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 `crash_watch` poll. Client upserts/removes by name; the pending overlay is read from `transientsState` since the diff --git a/docs/web-ui/shape.md b/docs/web-ui/shape.md index 91e8c452..65dee983 100644 --- a/docs/web-ui/shape.md +++ b/docs/web-ui/shape.md @@ -72,7 +72,7 @@ each subscribed tab via `MessagePort`; on bfcache restore the page re-subscribes (gets a synthetic `open` event immediately 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 "idle" SharedWorkers under memory pressure with no client-side 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 than captured once — lets a page default otherwise-collapsed panels 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 operator's intent: true means "keep snapping to bottom on every