| Filename | Latest commit message | Latest commit date |
|---|---|---|
c41c67c949
Fourth batch of hyperhive#4042's Passive pass (see #4098/#4099/#4100 for the first three and the read-every-hit discipline this pass uses). 44 hits across pr-review-gate.md (4), conventions.md (18), and gotchas.md (22) -- highest genuine-catch rate so far, 23/44 (~52%), because this architecture/mechanism documentation has a lot of "X does Y via Z" sentences where the actor is already named parenthetically or in a nearby clause -- the single most productive rewrite shape across every batch so far. Recurring rewrite shapes this batch: - Actor already named in the same sentence, just not as the grammatical subject: "X is configured per repo in its branch-protection settings" -> "Each repo's branch-protection settings configure X" (pr-review-gate.md); "the broker" (reserved names), "rsvg-convert" (PNG rendering), "the website repo" (HTML/CSS rendering), "systemd.globalEnvironment" (D-Bus address export), and several more -- all the same shape. - Subject already established one clause or one sentence earlier, just needs continuing rather than restarting with a new passive subject: "the harness reads HIVE_TOOL_GROUPS (...). Unrecognised tokens are logged and skipped." -> "...logging and skipping unrecognised tokens" (continues "the harness"), same pattern twice more (job_queue::templates::rebuild, HIVE_CAPABILITIES resolution). - Sibling-inconsistency: a bolded lead-in bullet was the one passive sentence in an otherwise-active paragraph/table (the read_host_journal capability row sat between two "may X" rows; the HTML+CSS bullet's own tail clauses were already active voice around the one passive lead phrase). - One caught-and-fixed authoring mistake worth noting for future passes: the first attempt at the "Nix treats X as a package" rewrite landed in the wrong sentence (a similarly-worded but unrelated passage two paragraphs up) -- caught by re-reading the diff before running vale, not by vale itself (which would have shown 0 remaining hits either way, since the intended sentence's hit just wouldn't have been touched -- a silently-wrong edit vale's own count can't catch). Re-reading the actual diff, not just trusting the before/ after hit count, is what caught it. 21 of 44 left alone -- same recurring legitimate shapes as prior batches (predicate-adjective copulas, quoted/literal text, generic- actor statements, negative-capability invariants, "is tracked/rooted/ scoped at X" property-description idioms, and two more thesis- statement headings matching the "Ownership is declared, not repaired" precedent from #4100). Verified: vale docs/process before/after -- 44 -> 21 write-good.Passive hits, exactly the 23 rewritten, re-read every changed line's full surrounding context after editing (not just the vale count) to catch exactly the kind of misplaced-edit mistake described above. |
||
| .. | ||
| agent-lifecycle | ||
| crates | ||
| getting-started | ||
| integrations | ||
| networking | ||
| process | ||
| scheduler | ||
| swarm | ||
| tools | ||
| trust-boundary | ||
| turn-loop | ||
| web-ui | ||
| README.md | ||
hyperhive docs
Depth reference for hyperhive — the substrate, not the pitch (that's the
top-level README / website).
Every page here stands alone; pick the one matching your task rather than
reading top to bottom. For the autogenerated NixOS options reference
(every services.hyperhive.* / hyperhive.* option, host and agent), see
the options site instead —
this tree is prose, that one's generated straight from the module
declarations.
Getting started
- Bringing a fresh hive online? →
getting-started/setup.md(first-runhivectlbootstrap). - What does the dashboard look like, and how do I use it? →
web-ui/— the operator-facing starting point; its own sub-pages (shape,dashboard,agent,css-vars,terminal-rendering) go deeper into implementation. - What tools does an agent (or the operator) have available? →
tools/—hivectl(yours) plus every agent's MCP tool surface (bash, forge, lifecycle, matrix, scheduling).
Agent lifecycle
- How do config changes flow from manager to operator to container? →
agent-lifecycle/approvals.md(two-step spawn, approval state machine,flake.lockvalidation). - What state survives destroy / purge / restart? →
agent-lifecycle/persistence.md. - Who can do what to whom — agent hierarchy and privilege? →
agent-lifecycle/agent-hierarchy.md. - How does claude get its prompt, and what tools does it have? →
turn-loop/— the loop, binary shape, turn outcomes; sub-pages:claude-invocation,config,mcp.
Trust boundary & security
- What's the operator/agent trust boundary? What's a capability? →
trust-boundary/boundary.md. - Agent trust model, prompt-injection threat model, credential
isolation? →
trust-boundary/security.md.
Accounts & integrations
- How do per-agent forge accounts work? What does
forge_notifypoll, and how does it format wake messages? →integrations/forge.md(the hive's own Forgejo);tools/forge.mdfor thehive-forgeCLI verbs agents actually call. - How does the matrix-tuwunel container work? Multiple accounts per
agent? →
integrations/matrix.md(the homeserver);tools/matrix.mdfor the MCP tool surface andhyperhive.matrixAccounts. - How do I give an agent a GitHub account (
gh+git push)? how's the PAT injected? →integrations/github.md(operator content up top; thegh/git-push + notification-poller mechanics are in a collapsed "Implementation" section at the bottom). - What's
/knowledge? How does the hive-wide knowledge repo sync, and how do I contribute a document? →integrations/knowledge.md. - What does
hivectldo? Provisioning, gateway users, container shells? →tools/hivectl.md(the curated guide);tools/hivectl-cli.mdfor the exhaustive, autogenerated flag reference.
Networking & swarms
- What nginx vhosts does the gateway serve? How does matrix
discovery work? →
networking/gateway.md. - How does DNS resolution work in agent containers? What's the
bridge network for? →
networking/network.md. - How do I connect two hives into a swarm? →
swarm/(peer hives, TLS trust). - Where do agent snapshots go? How does the swarm's
btrfs receiveendpoint authenticate a pushing hive? →networking/snapshot-store.md.
Scheduler, CI, observability
- what's the job queue, as a general idea (not hive-c0re specifics)? →
scheduler/jobq.md— operator-facing, no implementation detail. - How does the rebuild queue work? What are the concrete step kinds,
queue sources, scheduler internals? →
scheduler/coordinator.md. - How does the CI runner work? What's the autoregistration flow? →
scheduler/ci.md. - How do I export Claude Code metrics (tokens, cost, tool calls) to
Prometheus/Grafana? →
scheduler/observability.md.
Crate reference
- What does a specific Rust crate do, on its own terms? →
crates/— every workspace crate's ownREADME.md, one level up from source (hyperhive#3051); the crate itself is still the source of truth, this is just a walkable mirror.
Process & conventions
- Naming, commit style, wire protocol, the
data-asyncpattern? →process/conventions.md. - Why does the nspawn flag look like that? →
process/gotchas.md(bind mounts, conf flags, other NixOS/nspawn quirks). - What does a PR review verdict actually gate? →
process/pr-review-gate.md.