docs: sort the top-level directories into five sections by what the reader wants
Every docs directory moves under 1-getting-started, 2-handbook, 4-implementation or 5-project; the options reference (section 3) comes from the website and has no directory here. trust-boundary stays whole under the handbook for now. web-ui, swarm and tools split between handbook and implementation, and the command-line references move to 2-handbook/reference. Links, path references in code and nix, and the docs index follow the moves; no page content changes.
This commit is contained in:
iris
mara
parent
53ccbcb4b3
commit
6739bb903d
8 changed files with 736 additions and 701 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/agent-lifecycle/persistence.md`'s "Cross-agent access to
|
||||
read-write for recovery — see `docs/2-handbook/agent-lifecycle/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
|
||||
|
|
@ -462,8 +462,8 @@ in
|
|||
|
||||
# Harness systemd unit. Unit shape (PATH wrapper-dir trick, env vars,
|
||||
# RuntimeDirectory, User=, standalone-eval fallbacks):
|
||||
# docs/turn-loop/README.md::Harness systemd unit shape. PATH /bin
|
||||
# auto-append behaviour: docs/process/gotchas.md::systemd.services.*.path
|
||||
# docs/4-implementation/turn-loop/README.md::Harness systemd unit shape. PATH /bin
|
||||
# auto-append behaviour: docs/5-project/process/gotchas.md::systemd.services.*.path
|
||||
# appends /bin to every entry.
|
||||
systemd.services.hive-agent =
|
||||
let
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@
|
|||
# Write declared dashboardLinks to the state dir so hive-c0re can
|
||||
# read them without accessing the container's /etc/ from the host.
|
||||
# Best-effort oneshot (always exit 0):
|
||||
# docs/process/conventions.md::Best-effort oneshot services.
|
||||
# docs/5-project/process/conventions.md::Best-effort oneshot services.
|
||||
systemd.services.hive-dashboard-links =
|
||||
lib.mkIf (config.services.hyperhive.agent.dashboardLinks != [ ])
|
||||
{
|
||||
|
|
|
|||
|
|
@ -199,8 +199,8 @@ in
|
|||
# `lib.mkForce` overrides nixpkgs's normal-priority `false` so
|
||||
# in-container `nix build` invocations fall back to unsandboxed
|
||||
# local builds rather than failing on the missing user-namespace.
|
||||
# See `docs/process/gotchas.md::Containerized nix-daemon needs
|
||||
# sandbox-fallback = true` + `docs/trust-boundary/security.md` for the rationale.
|
||||
# See `docs/5-project/process/gotchas.md::Containerized nix-daemon needs
|
||||
# sandbox-fallback = true` + `docs/2-handbook/trust-boundary/security.md` for the rationale.
|
||||
#
|
||||
# Note: with NIX_REMOTE=daemon below this becomes a no-op for the
|
||||
# common case — daemon-routed builds run on the host where sandboxing
|
||||
|
|
@ -264,7 +264,7 @@ in
|
|||
# to be on PATH too. Only this one is actually looked up on PATH
|
||||
# by claude/shell code inside the container:
|
||||
# `hive-metric` (agent-emitted custom metrics CLI,
|
||||
# docs/scheduler/observability.md).
|
||||
# docs/4-implementation/scheduler/observability.md).
|
||||
environment.systemPackages = [
|
||||
config.services.hyperhive.agent.packages.hive-metric
|
||||
]
|
||||
|
|
|
|||
|
|
@ -186,7 +186,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/agent-lifecycle/persistence.md::forge-avatar-sync.
|
||||
# re-run it. See docs/2-handbook/agent-lifecycle/persistence.md::forge-avatar-sync.
|
||||
#
|
||||
# PathChanged=, not PathExists=: a PathExists= condition that already
|
||||
# holds re-activates the unit immediately every time the path unit
|
||||
|
|
@ -213,7 +213,7 @@ in
|
|||
};
|
||||
|
||||
# One-shot: services.hyperhive.agent.icon → Forgejo profile avatar. Shape contract:
|
||||
# docs/process/conventions.md::Best-effort oneshot services.
|
||||
# docs/5-project/process/conventions.md::Best-effort oneshot services.
|
||||
# RemainAfterExit = false so the .path trigger above can re-fire
|
||||
# this unit when the forge-token arrives after boot. The PNG is
|
||||
# rasterized at build time (`iconPng`, shared shape with the matrix
|
||||
|
|
|
|||
|
|
@ -208,7 +208,7 @@ in
|
|||
loopback-only binding means no auth token is needed (same
|
||||
`allowed_hosts` reasoning as `services.hyperhive.agent.mcp.httpPort`). Safe as a
|
||||
single fixed default across all agents (private per-container
|
||||
network namespace — see docs/networking/network.md).
|
||||
network namespace — see docs/4-implementation/networking/network.md).
|
||||
'';
|
||||
};
|
||||
|
||||
|
|
@ -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/agent-lifecycle/persistence.md::Matrix per-agent daemon + token-arrival
|
||||
# `docs/2-handbook/agent-lifecycle/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/agent-lifecycle/persistence.md` (same section as above).
|
||||
# `docs/2-handbook/agent-lifecycle/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" ];
|
||||
|
|
|
|||
|
|
@ -213,7 +213,7 @@ in
|
|||
|
||||
Safe as a single fixed default across all agents: each container
|
||||
runs in its own private network namespace (isolation is always-on —
|
||||
see docs/networking/network.md), so `127.0.0.1:<port>` is per-container-private
|
||||
see docs/4-implementation/networking/network.md), so `127.0.0.1:<port>` is per-container-private
|
||||
and cannot collide across agents. Override only if a container-local
|
||||
service already occupies this port.
|
||||
|
||||
|
|
@ -235,7 +235,7 @@ in
|
|||
self-healing, and loopback-only binding means no auth token is
|
||||
needed (same `allowed_hosts` reasoning as `services.hyperhive.agent.mcp.httpPort`).
|
||||
Safe as a single fixed default across all agents (private
|
||||
per-container network namespace — see docs/networking/network.md).
|
||||
per-container network namespace — see docs/4-implementation/networking/network.md).
|
||||
'';
|
||||
};
|
||||
|
||||
|
|
|
|||
|
|
@ -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/agent-lifecycle/persistence.md::First-boot agent-user migration` for the
|
||||
# `docs/2-handbook/agent-lifecycle/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}
|
||||
|
|
@ -290,7 +290,7 @@ in
|
|||
# The socket dir is bind-mounted from the host, where hive-priv creates
|
||||
# it `0751 root`. The harness binds its sockets here as this user; the
|
||||
# 0751 is what lets hive-c0re and nginx dial them without listing
|
||||
# (docs/trust-boundary/boundary.md, "the per-agent socket dir"). Not
|
||||
# (docs/2-handbook/trust-boundary/boundary.md, "the per-agent socket dir"). Not
|
||||
# recursive: only the harness writes inside it. `test -d` and `chmod`
|
||||
# follow symlinks, so a link here is refused rather than handed over.
|
||||
socketDir="/run/hive-agent/$userName"
|
||||
|
|
|
|||
|
|
@ -37,8 +37,8 @@ in
|
|||
#
|
||||
# Port allocation, weston bind-address quirk, PAM service name, the
|
||||
# Type=simple choice, idle-time=0: all in
|
||||
# docs/process/gotchas.md::Weston VNC compositor.
|
||||
# Harness-side WebSocket relay shape: docs/web-ui/agent.md::Per-agent
|
||||
# docs/5-project/process/gotchas.md::Weston VNC compositor.
|
||||
# Harness-side WebSocket relay shape: docs/2-handbook/web-ui/agent.md::Per-agent
|
||||
# endpoints (`/screen` + `/screen/ws`).
|
||||
|
||||
options.services.hyperhive.agent.gui.enable = lib.mkOption {
|
||||
|
|
|
|||
Loading…
Reference in a new issue