docs: the handbook follows the three layers: swarm, hives, agents
The handbook's sections were agent-lifecycle, integrations, swarm, tools, trust-boundary and web-ui, which do not follow how the system is built, so a reader could not tell which layer a page is about. Its pages now sit in swarm/, hives/ and agents/, with the accounts an agent can hold outside the system in external-accounts/. - swarm/: forge, matrix and the knowledge repo join the swarm pages, and so does the swarmctl reference. - hives/: the dashboard, hivectl and its reference, and the operator/agent boundary, with a README that takes over the old web-ui and tools pages. - agents/: the roster, persistence, config changes, the agent's own web page (was web-ui/agent) and the security model, with a README. - external-accounts/: GitHub and GitLab. Pages are moved whole; none is split yet. Every reference follows: relative links in the docs, `docs/2-handbook/...` paths in code comments, the nix checks that regenerate the CLI references and the ignore list, and docs/README.md, whose handbook section is now by layer.
This commit is contained in:
iris
mara
parent
263b21021a
commit
0e84fe8bc4
11 changed files with 393 additions and 363 deletions
|
|
@ -189,7 +189,7 @@ in
|
|||
not `state/` — `harness/` survives container rebuilds exactly like
|
||||
`state/` does, but is never bind-mounted into another agent's
|
||||
container (unlike `state/`, which a `ManageRootAgent` holder gets
|
||||
read-write for recovery — see `docs/2-handbook/agent-lifecycle/persistence.md`'s "Cross-agent access to
|
||||
read-write for recovery — see `docs/2-handbook/agents/persistence.md`'s "Cross-agent access to
|
||||
state"), so this credential is reachable by nothing but this agent
|
||||
and the host. Permissions should be `0600`, owned by the agent's
|
||||
unix user. Whatever owner it was installed with, the file becomes
|
||||
|
|
|
|||
|
|
@ -201,7 +201,7 @@ in
|
|||
# agent deployment the container can boot before the swarm has minted
|
||||
# the token, so the service fires too early and exits with "no
|
||||
# forge-token found". Without this path unit, nothing would ever
|
||||
# re-run it. See docs/2-handbook/agent-lifecycle/persistence.md::forge-avatar-sync.
|
||||
# re-run it. See docs/2-handbook/agents/persistence.md::forge-avatar-sync.
|
||||
#
|
||||
# PathChanged=, not PathExists=: a PathExists= condition that already
|
||||
# holds re-activates the unit immediately every time the path unit
|
||||
|
|
|
|||
|
|
@ -302,7 +302,7 @@ in
|
|||
# Long-running matrix-sdk client + sync per agent. Serves the MCP
|
||||
# tools directly over streamable-http + emits hyperhive wake
|
||||
# signals on incoming room events via `/run/hive/mcp.sock`. See
|
||||
# `docs/2-handbook/agent-lifecycle/persistence.md::Matrix per-agent daemon + token-arrival
|
||||
# `docs/2-handbook/agents/persistence.md::Matrix per-agent daemon + token-arrival
|
||||
# trigger` for the first-boot-ordering rationale.
|
||||
systemd.services.hive-matrix-daemon = lib.mkIf matrixEnabled {
|
||||
description = "long-running matrix-sdk Client + MCP daemon";
|
||||
|
|
@ -434,7 +434,7 @@ in
|
|||
# `tokenFile`, or a `main` from before the swarm minted it). Without this
|
||||
# the daemon would exit 0 silently on first boot and the MCP
|
||||
# would have no backend until next restart. See
|
||||
# `docs/2-handbook/agent-lifecycle/persistence.md` (same section as above).
|
||||
# `docs/2-handbook/agents/persistence.md` (same section as above).
|
||||
systemd.paths.hive-matrix-daemon = lib.mkIf matrixEnabled {
|
||||
description = "trigger hive-matrix-daemon when a matrix token appears";
|
||||
wantedBy = [ "multi-user.target" ];
|
||||
|
|
|
|||
|
|
@ -229,7 +229,7 @@ in
|
|||
# home dir, chowns the bind-mounted state + `~/.claude/`, and
|
||||
# (marker-guarded) moves any leftover `/root/.claude` content
|
||||
# from the previous root-run shape. See
|
||||
# `docs/2-handbook/agent-lifecycle/persistence.md::First-boot agent-user migration` for the
|
||||
# `docs/2-handbook/agents/persistence.md::First-boot agent-user migration` for the
|
||||
# step-by-step rationale; this script implements it.
|
||||
system.activationScripts.hive-agent-user-migrate = lib.stringAfter [ "users" "specialfs" ] ''
|
||||
homeDir=${lib.escapeShellArg homeDir}
|
||||
|
|
|
|||
|
|
@ -38,7 +38,7 @@ in
|
|||
# Port allocation, weston bind-address quirk, PAM service name, the
|
||||
# Type=simple choice, idle-time=0: all in
|
||||
# docs/5-project/process/gotchas.md::Weston VNC compositor.
|
||||
# Harness-side WebSocket relay shape: docs/2-handbook/web-ui/agent.md::Per-agent
|
||||
# Harness-side WebSocket relay shape: docs/2-handbook/agents/web-page.md::Per-agent
|
||||
# endpoints (`/screen` + `/screen/ws`).
|
||||
|
||||
options.services.hyperhive.agent.gui.enable = lib.mkOption {
|
||||
|
|
|
|||
|
|
@ -473,7 +473,7 @@ in
|
|||
};
|
||||
|
||||
# `hivectl` CLI reference freshness check. The committed
|
||||
# markdown at `docs/2-handbook/tools/hivectl-cli.md` is the rendered
|
||||
# markdown at `docs/2-handbook/hives/hivectl-cli.md` is the rendered
|
||||
# output of the hidden `hivectl markdown-docs` subcommand
|
||||
# (clap-markdown walks the binary's own command tree). This
|
||||
# check regenerates it from the built binary and fails if the
|
||||
|
|
@ -485,13 +485,13 @@ in
|
|||
# makes this check unsatisfiable rather than merely stale.
|
||||
# Regenerate locally with:
|
||||
# nix build .#default
|
||||
# ./result/bin/hivectl markdown-docs > docs/2-handbook/tools/hivectl-cli.md
|
||||
# ./result/bin/hivectl markdown-docs > docs/2-handbook/hives/hivectl-cli.md
|
||||
hivectl-docs = pkgs.runCommand "hivectl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
|
||||
${self.packages.${system}.default}/bin/hivectl markdown-docs > generated.md
|
||||
if ! diff -u ${../docs/2-handbook/tools/hivectl-cli.md} generated.md; then
|
||||
if ! diff -u ${../docs/2-handbook/hives/hivectl-cli.md} generated.md; then
|
||||
echo "" >&2
|
||||
echo "ERROR: docs/2-handbook/tools/hivectl-cli.md is out of date — regenerate it:" >&2
|
||||
echo " nix build .#default && ./result/bin/hivectl markdown-docs > docs/2-handbook/tools/hivectl-cli.md" >&2
|
||||
echo "ERROR: docs/2-handbook/hives/hivectl-cli.md is out of date — regenerate it:" >&2
|
||||
echo " nix build .#default && ./result/bin/hivectl markdown-docs > docs/2-handbook/hives/hivectl-cli.md" >&2
|
||||
exit 1
|
||||
fi
|
||||
touch "$out"
|
||||
|
|
@ -504,10 +504,10 @@ in
|
|||
# nix/packages/default.nix's comment on it).
|
||||
swarmctl-docs = pkgs.runCommand "swarmctl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
|
||||
${self.packages.${system}.swarmctl}/bin/swarmctl markdown-docs > generated.md
|
||||
if ! diff -u ${../docs/2-handbook/tools/swarmctl-cli.md} generated.md; then
|
||||
if ! diff -u ${../docs/2-handbook/swarm/swarmctl-cli.md} generated.md; then
|
||||
echo "" >&2
|
||||
echo "ERROR: docs/2-handbook/tools/swarmctl-cli.md is out of date — regenerate it:" >&2
|
||||
echo " nix build .#swarmctl && ./result/bin/swarmctl markdown-docs > docs/2-handbook/tools/swarmctl-cli.md" >&2
|
||||
echo "ERROR: docs/2-handbook/swarm/swarmctl-cli.md is out of date — regenerate it:" >&2
|
||||
echo " nix build .#swarmctl && ./result/bin/swarmctl markdown-docs > docs/2-handbook/swarm/swarmctl-cli.md" >&2
|
||||
exit 1
|
||||
fi
|
||||
touch "$out"
|
||||
|
|
|
|||
|
|
@ -181,7 +181,7 @@ in
|
|||
# Operators granted sudoless `hivectl`. Members of `hive-admin` can
|
||||
# connect to the host admin socket (group-owned by hive-admin via the
|
||||
# socket unit's `SocketGroup` below) without root. That socket is *full*
|
||||
# hive control (spawn/kill/destroy/deploy, docs/2-handbook/trust-boundary/boundary.md), so this is
|
||||
# hive control (spawn/kill/destroy/deploy, docs/2-handbook/hives/boundary.md), so this is
|
||||
# an explicit opt-in allowlist — empty by default (root-only).
|
||||
users.groups.hive-admin = {
|
||||
members = controllerCfg.adminUsers;
|
||||
|
|
@ -362,7 +362,7 @@ in
|
|||
# `0660 root:hive-admin` — group-owned by `hive-admin` so operators in
|
||||
# that group (services.hyperhive.deploy.hive-controller.adminUsers) drive `hivectl`
|
||||
# without root; an empty adminUsers list leaves the group memberless,
|
||||
# so it stays effectively root-only. See docs/2-handbook/trust-boundary/boundary.md.
|
||||
# so it stays effectively root-only. See docs/2-handbook/hives/boundary.md.
|
||||
SocketMode = "0660";
|
||||
SocketGroup = "hive-admin";
|
||||
# Only consulted when the directory is absent at socket-unit
|
||||
|
|
|
|||
|
|
@ -234,7 +234,7 @@ in
|
|||
`hivectl` (and thus the whole hive) without `sudo`.
|
||||
|
||||
This is a real privilege grant: the admin socket is *full* hive
|
||||
control — spawn / kill / destroy / deploy — see `docs/2-handbook/trust-boundary/boundary.md`.
|
||||
control — spawn / kill / destroy / deploy — see `docs/2-handbook/hives/boundary.md`.
|
||||
Keep the list to trusted operators. Empty (the default) keeps the
|
||||
socket root-only, as before.
|
||||
'';
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ in
|
|||
|
||||
Defaults to `https://''${cfg.domain}`, the gateway vhost. When
|
||||
`null`, the dashboard **hides** forge links rather than
|
||||
guessing one — see `docs/2-handbook/web-ui/dashboard.md::Container row` for
|
||||
guessing one — see `docs/2-handbook/hives/dashboard.md::Container row` for
|
||||
the rationale (a link built from the operator's own browser
|
||||
hostname + a container port is only an accident away from
|
||||
wrong on any deployment that isn't plain localhost).
|
||||
|
|
|
|||
|
|
@ -228,7 +228,7 @@ let
|
|||
# skips the dart web-worker compile + the emscripten native_imaging
|
||||
# build. Two derivations below cover both. Full rationale (why
|
||||
# passthru.pubspecLock.dependencySources, why `dontConfigure`, why
|
||||
# `make -C js`, why build-CWD-relative dart path): docs/2-handbook/integrations/matrix.md::
|
||||
# `make -C js`, why build-CWD-relative dart path): docs/2-handbook/swarm/matrix.md::
|
||||
# fluffychat-web build fixes.
|
||||
|
||||
fluffychat-web-imaging = pkgs.stdenv.mkDerivation {
|
||||
|
|
@ -312,7 +312,7 @@ in
|
|||
# default). Container shape,
|
||||
# serverName vs gatewayHost split, provisioning flow (registration
|
||||
# token + LoadCredential), assertion rationale, initial rollout
|
||||
# settings: docs/2-handbook/integrations/matrix.md. Vhost map + discovery flow + tuning
|
||||
# settings: docs/2-handbook/swarm/matrix.md. Vhost map + discovery flow + tuning
|
||||
# knobs: docs/4-implementation/networking/gateway.md.
|
||||
|
||||
# `swarm.matrix`, in ./hive-matrix-service.nix, is what the homeserver IS from
|
||||
|
|
@ -573,7 +573,7 @@ in
|
|||
# hive-network.nix) when not set explicitly, so no separate
|
||||
# domain/serverName assertion is needed here. gatewayHost may not be
|
||||
# "" (same footgun as forge.domain — nginx rejects an empty
|
||||
# server_name). docs/2-handbook/integrations/matrix.md::Assertion rationale.
|
||||
# server_name). docs/2-handbook/swarm/matrix.md::Assertion rationale.
|
||||
assertions = [
|
||||
{
|
||||
assertion = cfg.gatewayHost == null || cfg.gatewayHost != "";
|
||||
|
|
@ -765,7 +765,7 @@ in
|
|||
# Activation-time token generation — without this the bind-mount
|
||||
# would hand tuwunel an empty file on first boot and break every
|
||||
# registration until restart. Idempotent;
|
||||
# docs/2-handbook/integrations/matrix.md::Provisioning flow.
|
||||
# docs/2-handbook/swarm/matrix.md::Provisioning flow.
|
||||
# Tell an operator whose homeserver already exists that `serverName` is
|
||||
# unpinned, at the one moment they are looking: the rebuild.
|
||||
#
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
# hive-priv — the narrow root privileged helper hive-c0re delegates
|
||||
# to, socket-activated at /run/hive/priv.sock. See docs/2-handbook/trust-boundary/boundary.md
|
||||
# to, socket-activated at /run/hive/priv.sock. See docs/2-handbook/hives/boundary.md
|
||||
# for the operator/agent trust-boundary design.
|
||||
{
|
||||
pkgs,
|
||||
|
|
|
|||
Loading…
Reference in a new issue