From 30c8459add631ae1251c14cd98eeba39ac38abda Mon Sep 17 00:00:00 2001 From: iris Date: Tue, 2 Jun 2026 11:09:10 +0200 Subject: [PATCH] docs(persistence): expand meta/ dir section to list config JSON files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The meta/ section only described the flake. Added entries for topology.json, tool-groups.json, and capabilities.json — the three system-level config files also committed there — with their writers, readers, and injected env vars. --- docs/persistence.md | 30 +++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/docs/persistence.md b/docs/persistence.md index 94fb1cdf..ae3cb8ee 100644 --- a/docs/persistence.md +++ b/docs/persistence.md @@ -192,13 +192,29 @@ manager's edits land here via the approval flow) + any other files the manager committed. `.git/` carries the proposal / approved / building / deployed / failed / denied tag history. -Under `/var/lib/hyperhive/meta/` — the swarm-wide deploy flake. -Single repo for the whole host; `flake.nix` declares one input -per agent + one `nixosConfigurations.` output per agent; -`flake.lock` is the canonical "what's deployed where." The git -log is the deploy audit trail (one commit per successful -deploy or hyperhive bump). Manager has this RO-mounted at -`/meta/`. +Under `/var/lib/hyperhive/meta/` — the swarm-wide deploy flake plus +system-level config files. Single git repo for the whole host; every +hive-c0re mutation that should survive a restart is committed here. +Contents: + +- `flake.nix` — declares one `nixpkgs` input per agent + one + `nixosConfigurations.` output per agent. `flake.lock` is the + canonical "what's deployed where." The git log is the deploy + audit trail (one commit per successful deploy or hyperhive bump). +- `topology.json` — parent/child agent graph + (`{ "alice": "manager", "bob": "alice", "manager": null }`). + Written by `topology::set_parent`; read by the dashboard, the + renderer, and `` / `` recipient resolution. +- `tool-groups.json` — per-agent MCP tool group grants + (`{ "alice": ["messaging", "inbox", "execution"] }`). Written by + `tool_groups::set_groups`; injected as `HIVE_TOOL_GROUPS` env + var into each agent's container. +- `capabilities.json` — per-agent capability grants + (`{ "atlas": ["read_host_journal"] }`). Written by + `capabilities::set_caps`; injected as `HIVE_CAPABILITIES` env + var. Absent agents have no extra capabilities. + +Manager has the meta dir RO-mounted at `/meta/`. Marker file `/var/lib/hyperhive/.meta-migration-done` is written by the startup migration after every container has