From 7ba684a1da918e48b213273bd14a6178af272db3 Mon Sep 17 00:00:00 2001 From: iris Date: Wed, 11 Nov 2026 23:02:31 +0100 Subject: [PATCH] docs: the agent roster page is Agent permissions, and the docs say agent list Roster named the permissions page, the hive's topology file and the swarm's list of agents without saying which. The page and its links are renamed; the implementation docs and UI text follow separately. --- docs/1-getting-started/setup.md | 2 +- docs/2-handbook/agents/README.md | 4 ++-- .../agents/{agent-roster.md => agent-permissions.md} | 6 +++--- docs/2-handbook/agents/security.md | 2 +- docs/2-handbook/hives/dashboard.md | 2 +- docs/2-handbook/hives/hivectl.md | 4 ++-- docs/2-handbook/swarm/README.md | 8 ++++---- docs/4-implementation/agent-state/roster.md | 2 +- docs/README.md | 6 +++--- 9 files changed, 18 insertions(+), 18 deletions(-) rename docs/2-handbook/agents/{agent-roster.md => agent-permissions.md} (88%) diff --git a/docs/1-getting-started/setup.md b/docs/1-getting-started/setup.md index 526d57898..c22f0943d 100644 --- a/docs/1-getting-started/setup.md +++ b/docs/1-getting-started/setup.md @@ -206,7 +206,7 @@ container keeps starting with the hive meanwhile. From here on, ask ruth. Open her card on `/agents` in the swarm UI and use the message box under her terminal. She is the manager agent: her MCP surface is the privileged one that configures agents, and she can recover the others. Changes to -an agent's config arrive as PRs you merge. → [`2-handbook/agents/agent-roster.md`](../2-handbook/agents/agent-roster.md) +an agent's config arrive as PRs you merge. → [`2-handbook/agents/agent-permissions.md`](../2-handbook/agents/agent-permissions.md) To create an agent yourself instead, use the swarm UI, or: diff --git a/docs/2-handbook/agents/README.md b/docs/2-handbook/agents/README.md index d89ee52d7..56c8bf55e 100644 --- a/docs/2-handbook/agents/README.md +++ b/docs/2-handbook/agents/README.md @@ -6,8 +6,8 @@ runtime (Claude Code or any Agent Client Protocol agent) and its model. This section covers running one: its identity, what survives a restart, how its config changes, what its own page shows and how far you can trust it. -- **[Roster](agent-roster.md)** — the agents of a hive, and who may do what - to whom. +- **[Agent permissions](agent-permissions.md)** — the hive's list of agents, and + who may do what to whom. - **[Persistence and config changes](persistence.md)** — what survives a restart, a destroy and a purge, and how a change to an agent's config flows from a pull request to its container. diff --git a/docs/2-handbook/agents/agent-roster.md b/docs/2-handbook/agents/agent-permissions.md similarity index 88% rename from docs/2-handbook/agents/agent-roster.md rename to docs/2-handbook/agents/agent-permissions.md index 01ba87dc7..888635aed 100644 --- a/docs/2-handbook/agents/agent-roster.md +++ b/docs/2-handbook/agents/agent-permissions.md @@ -1,4 +1,4 @@ -# Agent roster and privileges +# Agent permissions Agents are a **flat set**: no agent manages another by position. The `manage_root_agent` permission is the one grant that reaches another agent. @@ -6,7 +6,7 @@ Agents are a **flat set**: no agent manages another by position. The ## The hive's list of agents Which agents exist is the swarm's to decide: -[who is on the roster](../swarm/README.md#who-is-on-the-roster). Each hive also +[which agents exist](../swarm/README.md#which-agents-exist). Each hive also keeps a small file of its own, `topology.json`, with the agents this hive has state or config for. You never edit it: the hive rebuilds it from what it sees locally, so a hand edit is overwritten, and one that doesn't parse stops the @@ -19,7 +19,7 @@ agent holding `manage_root_agent` gets every other agent's `state` directory on this hive mounted read-write at `/agents//state`, never `config` or `harness`. It's the only grant that reaches another agent's state. Ruth, the root agent, holds it (the swarm creates her from the `ruth` archetype, see -[who is on the roster](../swarm/README.md#who-is-on-the-roster)). The mounts +[which agents exist](../swarm/README.md#which-agents-exist)). The mounts follow the hive's list: an empty file means no mounts until the next rebuild. ## The manager is a normal agent diff --git a/docs/2-handbook/agents/security.md b/docs/2-handbook/agents/security.md index 9c03ffa91..61067a4f1 100644 --- a/docs/2-handbook/agents/security.md +++ b/docs/2-handbook/agents/security.md @@ -68,7 +68,7 @@ agent's whole encrypted history, not only messages from then on. That's deliberate and it's the interim state, not the intent. An agent's credential path doesn't name the hive hosting it (agents move between hives), so a per-hive grant has to be an enumeration the controller re-emits whenever -the roster changes — and an enumeration that can drift or land out of order +the agent list changes — and an enumeration that can drift or land out of order advertises a boundary it doesn't actually hold. A wide grant that says what it is beats a narrow one that only looks narrow. diff --git a/docs/2-handbook/hives/dashboard.md b/docs/2-handbook/hives/dashboard.md index e22efefeb..62c1286f3 100644 --- a/docs/2-handbook/hives/dashboard.md +++ b/docs/2-handbook/hives/dashboard.md @@ -3,7 +3,7 @@ > Part of [Hives](README.md). See also: [Per-agent page](../agents/web-page.md) The hive dashboard is the per-hive UI that hive-c0re serves at `/`. The -[swarm UI](../swarm/ui.md) holds everything swarm-wide (the agent roster, agent +[swarm UI](../swarm/ui.md) holds everything swarm-wide (the agent list, agent creation, linking external forge and matrix accounts, the controller's job graph) and is where you do day-to-day work. The hive dashboard keeps shrinking: parts of it go, bit by bit. diff --git a/docs/2-handbook/hives/hivectl.md b/docs/2-handbook/hives/hivectl.md index fb0680e8c..6396aede9 100644 --- a/docs/2-handbook/hives/hivectl.md +++ b/docs/2-handbook/hives/hivectl.md @@ -29,7 +29,7 @@ single agent lives under `hivectl agent ` — `hivectl` hoists the name onto the parent command, so none of the verbs below repeat it. ```bash -hivectl list-agents # roster: every agent's status + technical state +hivectl list-agents # every agent's status + technical state hivectl list-agents --json # same data as raw JSON rows (for scripting) hivectl agent agent1 restart # stop + start the `agent1` container (no rebuild) hivectl agent agent1 pause # park agent1's turn loop, leave the container running @@ -41,7 +41,7 @@ hivectl agent agent1 resume # let it drive turns again, draining what que (`running` / `stopped`, plus ` paused` / ` needs-login` when set — `paused` is orthogonal to running, see below); REMIND is the count of pending reminders. It reuses the same per-agent aggregation the dashboard -renders, so the CLI roster and the web UI never drift. `--json` emits the +renders, so the CLI list and the web UI never drift. `--json` emits the raw rows instead of the table. `agent restart` is the manual equivalent of the MCP `restart` diff --git a/docs/2-handbook/swarm/README.md b/docs/2-handbook/swarm/README.md index 6d055cc89..84f8d81ce 100644 --- a/docs/2-handbook/swarm/README.md +++ b/docs/2-handbook/swarm/README.md @@ -19,7 +19,7 @@ grafana, the controller, authelia, …) → ## Where each piece lives -- **control plane** — `swarm-controller`: hive directory, agent roster, job +- **control plane** — `swarm-controller`: hive directory, agent list, job graph, agent creation. → [below](#swarm-controller) - **scheduled prompts** — named prompts for one or more agents at set times, kept by the swarm and fired in each agent's container. → [`schedules.md`](schedules.md) @@ -62,7 +62,7 @@ grafana, the controller, authelia, …) → ## Swarm controller `swarm-controller` is the swarm's control plane: it holds the hive directory, -the agent roster and their wanted state, and the job graph. Creating an agent — +the agent list and their wanted state, and the job graph. Creating an agent — from the swarm UI or `swarmctl agent create --hive ` — queues its SSO identity, forge user, config repo, store identity and matrix account, then sends the hive a deploy message. A new agent starts `paused`. A store identity @@ -100,7 +100,7 @@ socket-directory constraint that governs where `socketPath` may point: The options, wire formats and failure modes of each: [`controller.md`](../../4-implementation/swarm/controller.md). -### Who is on the roster +### Which agents exist The swarm decides. An agent exists in the swarm if and only if it has an identity in the swarm's authelia identity store, which `swarmctl agent create` @@ -114,7 +114,7 @@ The swarm UI's setup assistant creates `ruth` from the `manage_root_agent` and sets her model to `sonnet`. A ruth created before the archetype keeps her model; set `sonnet` in her inference settings in the swarm UI if you want it. What that grant lets an agent reach on a hive is on the -[agent roster page](../agents/agent-roster.md). +[agent permissions page](../agents/agent-permissions.md). ## Hives: the substrate diff --git a/docs/4-implementation/agent-state/roster.md b/docs/4-implementation/agent-state/roster.md index 710b1e7f9..347ed0e8e 100644 --- a/docs/4-implementation/agent-state/roster.md +++ b/docs/4-implementation/agent-state/roster.md @@ -2,7 +2,7 @@ The hive-local `topology.json`, how the hive derives it, and what's special about the manager (`ruth`). The operator's overview is -[the agent roster page](../../2-handbook/agents/agent-roster.md). +[the agent permissions page](../../2-handbook/agents/agent-permissions.md). diff --git a/docs/README.md b/docs/README.md index c5ff3f95f..c70d715a1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -86,7 +86,7 @@ The host a hive runs on and the operator's tools for it. Start at ### Agents -One agent: its roster entry, state, config and page. Start at +One agent: its entry in the agent list, state, config and page. Start at [`2-handbook/agents/`](2-handbook/agents/README.md). - **How do config changes flow from agent to operator to container?** → @@ -97,8 +97,8 @@ One agent: its roster entry, state, config and page. Start at [`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md); the tables and directory layout: [`4-implementation/agent-state/persistence.md`](4-implementation/agent-state/persistence.md). -- **Who can do what to whom — the agent roster and privilege?** → - [`2-handbook/agents/agent-roster.md`](2-handbook/agents/agent-roster.md); how +- **Who can do what to whom — the agent list and privilege?** → + [`2-handbook/agents/agent-permissions.md`](2-handbook/agents/agent-permissions.md); how `topology.json` is rebuilt and what's special about the manager: [`4-implementation/agent-state/roster.md`](4-implementation/agent-state/roster.md). - **What does an agent's own page show?** →