diff --git a/docs/README.md b/docs/README.md index c70d715a1..ffc91892c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -36,35 +36,26 @@ The services that exist once per swarm. Start at matrix and SSO login answering the internet?** → [`2-handbook/swarm/semi-spread-deploy.md`](2-handbook/swarm/semi-spread-deploy.md) (worked example: machines, WireGuard, DNS). - **What does the swarm UI show, and what does `swarmctl` do?** → - [`2-handbook/swarm/ui.md`](2-handbook/swarm/ui.md) (the full page reference is - [`4-implementation/web-ui/swarm-ui.md`](4-implementation/web-ui/swarm-ui.md)) and + [`2-handbook/swarm/ui.md`](2-handbook/swarm/ui.md) and [`2-handbook/swarm/swarmctl-cli.md`](2-handbook/swarm/swarmctl-cli.md) (the generated flag reference). - **How do per-agent forge accounts work? What does `forge_notify` poll, and how does it format wake messages?** → [`2-handbook/swarm/forge.md`](2-handbook/swarm/forge.md) - (the swarm's Forgejo); [`4-implementation/agent-tools/forge.md`](4-implementation/agent-tools/forge.md) for the - `hive-forge` CLI verbs agents actually call. + (the swarm's Forgejo). - **How does the matrix-tuwunel container work? Multiple accounts per - agent?** → [`2-handbook/swarm/matrix.md`](2-handbook/swarm/matrix.md) (the homeserver); - [`4-implementation/agent-tools/matrix.md`](4-implementation/agent-tools/matrix.md) for the MCP tool surface and - `services.hyperhive.agent.matrixAccounts`. + agent?** → [`2-handbook/swarm/matrix.md`](2-handbook/swarm/matrix.md) (the homeserver and the + accounts an agent holds on it). - **What's `/knowledge`? How does the swarm-wide knowledge repo sync, and how to contribute a document?** → [`2-handbook/swarm/knowledge.md`](2-handbook/swarm/knowledge.md). - **Who mints each credential, who reads it, and how does it rotate?** → [`2-handbook/swarm/credentials.md`](2-handbook/swarm/credentials.md) (the - rules, where each secret goes and why, adding a secret) and - [`4-implementation/swarm/credentials-reference.md`](4-implementation/swarm/credentials-reference.md) (the - tables: each credential and where each file lives). The store's identities, - keys and login: - [`4-implementation/swarm/credentials.md`](4-implementation/swarm/credentials.md). + rules, where each secret goes and why, adding a secret). - **How does an agent get a prompt at set times, and why doesn't it fire twice after downtime?** → [`2-handbook/swarm/schedules.md`](2-handbook/swarm/schedules.md). - **How to create an agent from a ready-made set of permissions and settings?** → [`2-handbook/swarm/archetypes.md`](2-handbook/swarm/archetypes.md). - **How to log an agent in to claude from the swarm UI?** → - [`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md). Why a - stale stored copy doesn't log the agent out again, and the minter's grants: - [`4-implementation/swarm/claude-login.md`](4-implementation/swarm/claude-login.md). + [`2-handbook/swarm/claude-login.md`](2-handbook/swarm/claude-login.md). - **Where do the hives back up each agent's state, how long does it stay, and how to check it?** → [`2-handbook/swarm/archive.md`](2-handbook/swarm/archive.md). @@ -74,13 +65,11 @@ The host a hive runs on and the operator's tools for it. Start at [`2-handbook/hives/`](2-handbook/hives/README.md). - **What does the dashboard look like, and how to use it?** → - [`2-handbook/hives/`](2-handbook/hives/README.md), with the full tab-by-tab - reference in [`dashboard`](4-implementation/web-ui/dashboard.md). + [`2-handbook/hives/`](2-handbook/hives/README.md). - **What does `hivectl` do? Provisioning, gateway users, container shells?** → [`2-handbook/hives/hivectl.md`](2-handbook/hives/hivectl.md) (the curated guide); [`2-handbook/hives/hivectl-cli.md`](2-handbook/hives/hivectl-cli.md) for the exhaustive, - autogenerated flag reference. The agents' own tool surface is in - [`4-implementation/agent-tools/`](4-implementation/agent-tools/README.md). + autogenerated flag reference. - **What's the operator/agent trust boundary? What's a permission?** → [`2-handbook/hives/boundary.md`](2-handbook/hives/boundary.md). @@ -91,19 +80,12 @@ One agent: its entry in the agent list, state, config and page. Start at - **How do config changes flow from agent to operator to container?** → [`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md#config-changes). - The meta flake and system messages: - [`4-implementation/agent-state/config-changes.md`](4-implementation/agent-state/config-changes.md). - **What state survives destroy / purge / restart?** → - [`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). + [`2-handbook/agents/persistence.md`](2-handbook/agents/persistence.md). - **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). + [`2-handbook/agents/agent-permissions.md`](2-handbook/agents/agent-permissions.md). - **What does an agent's own page show?** → - [`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md); the full - reference is [`agent-page`](4-implementation/web-ui/agent-page.md). + [`2-handbook/agents/web-page.md`](2-handbook/agents/web-page.md). - **Agent trust model, prompt-injection threat model, credential isolation?** → [`2-handbook/agents/security.md`](2-handbook/agents/security.md). @@ -113,9 +95,7 @@ Accounts outside the swarm that an agent can hold. Start at [`2-handbook/external-accounts/`](2-handbook/external-accounts/README.md). - **How to give an agent a GitHub account (`gh` + `git push`)? how's - the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/github.md); - the `gh`/git-push and notification-poller mechanics are in - [`4-implementation/agent-tools/github.md`](4-implementation/agent-tools/github.md). + the PAT injected?** → [`2-handbook/external-accounts/github.md`](2-handbook/external-accounts/github.md). - **How to give an agent GitLab accounts (`glab` + `git push`, more than one instance)?** → [`2-handbook/external-accounts/gitlab.md`](2-handbook/external-accounts/gitlab.md). @@ -136,9 +116,23 @@ Nothing of it sits in this tree. - **How does the forge notification poller wake an agent, and how does it format and de-duplicate what it delivers?** → [`4-implementation/agent-tools/forge-notify.md`](4-implementation/agent-tools/forge-notify.md). +- **Which `hive-forge` verbs do agents call, and what does the swarm's forge give each + agent?** → [`4-implementation/agent-tools/forge.md`](4-implementation/agent-tools/forge.md). +- **What's the matrix MCP tool surface, and what's `services.hyperhive.agent.matrixAccounts`?** → + [`4-implementation/agent-tools/matrix.md`](4-implementation/agent-tools/matrix.md). - **How do an agent's `gh` and `git push` authenticate to GitHub?** → [`4-implementation/agent-tools/github.md`](4-implementation/agent-tools/github.md). +### Agent state + +- **How does the meta flake carry a config change, and what are the system messages?** → + [`4-implementation/agent-state/config-changes.md`](4-implementation/agent-state/config-changes.md). +- **What are the tables and the directory layout behind what survives a destroy, purge + or restart?** → + [`4-implementation/agent-state/persistence.md`](4-implementation/agent-state/persistence.md). +- **How's `topology.json` rebuilt, and what's special about the manager?** → + [`4-implementation/agent-state/roster.md`](4-implementation/agent-state/roster.md). + ### Turn loop, scheduler, CI, observability - **How does claude get its prompt, and what tools does it have?** → @@ -184,6 +178,13 @@ Nothing of it sits in this tree. - **How are the metrics store, Grafana, log store and OTEL collector wired, and who may reach each?** → [`4-implementation/swarm/telemetry.md`](4-implementation/swarm/telemetry.md). +- **Which credential lives where, and what are the store's identities, keys and login?** → + [`4-implementation/swarm/credentials-reference.md`](4-implementation/swarm/credentials-reference.md) (the + tables: each credential and where each file lives) and + [`4-implementation/swarm/credentials.md`](4-implementation/swarm/credentials.md). +- **Why doesn't a stale stored claude login log the agent out again, and what does the + minter's policy grant?** → + [`4-implementation/swarm/claude-login.md`](4-implementation/swarm/claude-login.md). ### Trust boundary mechanics @@ -200,6 +201,12 @@ Nothing of it sits in this tree. [`shape`](4-implementation/web-ui/shape.md), [`css-vars`](4-implementation/web-ui/css-vars.md), [`terminal-rendering`](4-implementation/web-ui/terminal-rendering.md). +- **What does each swarm UI page show, down to its endpoints?** → + [`swarm-ui`](4-implementation/web-ui/swarm-ui.md). +- **What's on each tab of the hive dashboard?** → + [`dashboard`](4-implementation/web-ui/dashboard.md). +- **What does an agent's own page show, in full?** → + [`agent-page`](4-implementation/web-ui/agent-page.md). ### Crate reference