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
hyperhive/docs
History
Repository files (latest commit first)
Filename Latest commit message Latest commit date
iris f22791b7a4 docs: clear the remaining error-level vale lints 
Per #4128 (mara: allow-everywhere false positives go in a central
list, otherwise fix in source). Testing surfaced better fixes than
the plan posted on the issue:

- 5x Microsoft.Contractions 'that is' idiom false positives: adding
  the missing comma ("that is, ...") both reads better and satisfies
  the rule's own negative-lookahead, so no suppression is needed at
  all. Fixed in docs/integrations/forge.md, docs/tools/forge.md,
  docs/tools/hivectl.md, docs/web-ui/dashboard.md, and
  swarmctl-cli.md's generated source (swarmctl/src/main.rs, doc
  comment regenerated via markdown-docs).
- persistence.md's 'is not' matching inside 'is nothing': reworded to
  'there'\''s nothing' rather than add any exception -- dodges the trap
  and is a genuine contraction besides.
- ca.md's 'it is' matching inside the already-correct 'it isn'\''t':
  tried a central .vale.ini TokenIgnores entry first per the
  allow-everywhere framing, but testing against the real file (not
  just a synthetic snippet) found it silently fails to suppress
  whenever markdown emphasis syntax appears earlier in the same
  file -- an offset-drift bug in how Vale applies TokenIgnores, not
  a config mistake. Reworded to "it'\''s not" instead, same fix
  shape as persistence.md.
- config.md's 3 genuine Microsoft.Avoid 'backend' exceptions (already
  flagged and accepted on #4139 -- an actually-pluggable LLM API
  provider, matching the nix option's own name, not one internal
  system to name): scoped inline vale suppression around just that
  section, since this one really is context-specific rather than a
  rule bug.

Verified: fresh 'vale docs/ --minAlertLevel=error' is 0 errors AND
0 warnings (was 10 errors). nix fmt 0 changed beyond the edits
themselves. pre-push lints (tracker-tag/comment-block/doc-pointer)
clean. cargo clippy -p swarmctl -- -D warnings clean. Diffed the
regenerated swarmctl-cli.md against the old copy to confirm only
the intended line moved.
2026-09-09 22:55:28 +02:00
..
agent-lifecycle docs: clear the remaining error-level vale lints 2026-09-09 22:55:28 +02:00
crates check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +02:00
getting-started check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +02:00
integrations docs: clear the remaining error-level vale lints 2026-09-09 22:55:28 +02:00
networking docs: name the specific daemon instead of the vague 'backend' 2026-09-09 17:59:10 +02:00
process check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +02:00
scheduler docs: fix genuine Microsoft.Contractions/Negative errors 2026-09-09 01:48:46 +02:00
swarm docs: clear the remaining error-level vale lints 2026-09-09 22:55:28 +02:00
tools docs: clear the remaining error-level vale lints 2026-09-09 22:55:28 +02:00
trust-boundary check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +02:00
turn-loop docs: clear the remaining error-level vale lints 2026-09-09 22:55:28 +02:00
web-ui docs: clear the remaining error-level vale lints 2026-09-09 22:55:28 +02:00
README.md check-issue-refs: catch full forge issue URLs too, drop internal links from docs entirely 2026-09-09 21:15:28 +02:00

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-run hivectl bootstrap).
  • 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

Trust boundary & security

Accounts & integrations

  • How do per-agent forge accounts work? What does forge_notify poll, and how does it format wake messages? → integrations/forge.md (the hive's own Forgejo); tools/forge.md for the hive-forge CLI verbs agents actually call.
  • How does the matrix-tuwunel container work? Multiple accounts per agent? → integrations/matrix.md (the homeserver); tools/matrix.md for the MCP tool surface and hyperhive.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; the gh/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 hivectl do? Provisioning, gateway users, container shells? → tools/hivectl.md (the curated guide); tools/hivectl-cli.md for 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 receive endpoint 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 own README.md, one level up from source; the crate itself is still the source of truth, this is just a walkable mirror.

Process & conventions