docs(#1251): split MCP tool docs into docs/tools/ sub-mds by feature

docs/tools/bash.md

@@ -0,0 +1,49 @@
+# Bash execution tools (`execution` tool group)
+
+Background shell execution via `hive-bash-mcp`. Tools land as
+`mcp__bash__<tool>` (the MCP server name is `bash`, not `hyperhive`).
+Enabled for any agent whose tool groups include `execution` — the
+default preset (`AGENT_DEFAULT`) includes it.
+
+## Tools
+
+### `run(cmd, timeout_secs?)`
+
+Submit a shell command for background execution (`sh -c <cmd>`).
+Returns a task ID immediately; the command runs asynchronously in a
+harness-managed tokio task. Stdout and stderr stream to
+`harness/bash-tasks/<id>.{out,err}`. When the task completes (or
+times out, or the process errors), the harness wakes the agent with a
+summary body — handle on a future turn. Optional `timeout_secs`: pass
+a value for a deadline, or omit for no timeout (runs until natural exit).
+
+Exposed as `mcp__bash__run`.
+
+### `status(id)`
+
+Poll the status of a task submitted with `run`. Returns:
+
+- `status` — `pending` / `running` / `done` / `timed_out` / `interrupted`
+- `exit_code` — set when done
+- run duration
+- last 4 KiB of stdout and stderr (full output in the `.out` / `.err` files)
+
+Tasks marked `interrupted` had their process killed by a harness
+restart; a best-effort wake was still sent so the agent is not
+silently blocked.
+
+Exposed as `mcp__bash__status`.
+
+## Namespace note
+
+`run` and `status` live in the `bash` MCP server, not `hyperhive`. So
+the tool names in claude are `mcp__bash__run` and `mcp__bash__status`.
+The `Bash` built-in tool is blocked — all shell execution goes through
+this structured path so tasks get task-id tracking and structured output.
+
+## Tool whitelist cross-reference
+
+`mcp__bash__run` and `mcp__bash__status` are unconditionally in
+`--allowedTools` whenever the harness spawns claude (they are not
+gated by the `execution` group at the `--allowedTools` level — the
+group only gates whether the MCP server registers the tools at all).

docs/tools/lifecycle.md

@@ -0,0 +1,91 @@
+# Lifecycle and approvals tools
+
+Two tool groups govern agent lifecycle management and config changes.
+Both are scoped to **direct children only** (topology-enforced: the
+server rejects any name that is not a direct child of the calling
+agent per `topology.json`). Privileged agents (e.g. ruth) may operate
+on any sub-agent — the topology scope applies to all others.
+
+## `lifecycle` tool group
+
+No operator approval required. Direct children only.
+
+### `kill(name)`
+
+Graceful stop. Container state is preserved; recreating the agent
+reuses prior config and credentials.
+
+### `start(name)`
+
+Start a stopped sub-agent.
+
+### `restart(name)`
+
+Stop + start in one call.
+
+### `update(name)`
+
+Rebuild: re-applies the current hyperhive flake + `agent.nix`,
+then restarts. Idempotent — safe to call repeatedly. Used in response
+to `needs_update` system events.
+
+### `list_containers()`
+
+List all **descendant** containers (children + their subtrees) with
+running status. Topology-scoped to descendants only.
+
+## `approvals` tool group
+
+Config changes and new-agent spawns route through the operator
+approval queue. Direct children only (topology-enforced).
+
+### `request_init_config(name, description?)`
+
+Step 1 of spawning a new direct child agent. Queues an `InitConfig`
+approval; on operator approve, hive-c0re seeds the proposed config
+repo at `/agents/<name>/config/agent.nix` with a default template and
+delivers a `config_ready` system event. Then edit `agent.nix`, commit,
+and call `request_apply_commit` with the commit sha — the first
+`ApplyCommit` on a freshly-init'd config creates the container.
+
+Fails if a proposed config repo for `name` already exists.
+`name` is ≤ 9 characters. The operator can also spawn an empty agent
+via the dashboard `◆ R3QU3ST SP4WN` button, which routes via
+`HostRequest::RequestSpawn`.
+
+### `request_apply_commit(agent, commit_ref, description?)`
+
+Step 2 of spawning (or updating an existing child's config). Submit a
+commit sha from the child's proposed config repo for operator
+approval. On approve, hive-c0re rebuilds the container with the
+pinned commit.
+
+`commit_ref` must be a 7-40 char hex sha (branch/tag names are
+rejected — the approval pins the exact commit). `agent` must be a
+direct child. Topology-enforced.
+
+### `request_update_meta_inputs(inputs?, description?)`
+
+Queue an approval to run `nix flake update [inputs...]` on the meta
+flake. Pass specific input names (e.g. `["bitburner-agent"]`) or omit
+/ pass `[]` for all inputs. Returns immediately; the lock update runs
+on operator approval.
+
+Does NOT trigger container rebuilds — call `update(name)` on affected
+agents after the approval resolves.
+
+## Boundary summary
+
+| Operation | Requires approval? | Scope |
+|---|---|---|
+| `kill` / `start` / `restart` / `update` | No | Direct children |
+| `list_containers` | No | All descendants |
+| `request_init_config` | Yes (InitConfig) | New direct child only |
+| `request_apply_commit` | Yes (ApplyCommit) | Direct children |
+| `request_update_meta_inputs` | Yes (MetaUpdate) | Meta flake (global) |
+
+## See also
+
+- [`docs/approvals.md`](../approvals.md) — full approval flow, kinds,
+  helper events (`config_ready`, `approval_resolved`), flake.lock
+  validation.

docs/tools/matrix.md

@@ -0,0 +1,62 @@
+# Matrix MCP tools and extra MCP servers
+
+## Built-in matrix MCP (`mcp__matrix__*`)
+
+When `hyperhive.matrix.enable = true` and the host-level matrix
+tuwunel is configured, the harness auto-injects `hive-matrix-mcp` as
+a second stdio MCP server. Tools land as `mcp__matrix__<name>`:
+
+### Messaging
+
+- `send_message(room, body)` — send a markdown message; `room`
+  accepts `!id:server` or `#alias:server`, daemon resolves either
+- `send_dm(user_id, body)` — send a direct message to a matrix user
+- `send_reply(room, event_id, body)` — threaded reply to a specific
+  event
+- `send_reaction(room, event_id, key)` — react to a message with an
+  emoji key
+
+### Reading
+
+- `read_room(room, limit?)` — recent timeline events
+- `list_rooms()` — enumerate joined rooms
+  (`{ id, canonical_alias, name, member_count }` per room)
+- `list_room_members(room)` — members of a room
+
+### Receipts
+
+- `mark_read(room, event_id)` — advance the read receipt
+
+## Architecture
+
+The daemon (`hive-matrix-daemon`) holds the long-running matrix-sdk
+`Client` + sync loop; the stdio bridge (`hive-matrix-mcp`) is spawned
+per turn and forwards tool calls over `/run/hive-matrix.sock`. Both
+silently exit when `<state>/matrix-token` is absent (account not yet
+provisioned).
+
+Incoming room events wake the agent via `AgentRequest::Wake` with
+`from: "matrix"` and a teaser body
+(`[matrix] <sender> in <room>: <first-100c>…`).
+
+See [`docs/matrix.md`](../matrix.md) for the homeserver setup,
+provisioning flow, and federation config.
+
+## Extra MCP servers (per-agent)
+
+Each agent's NixOS config can declare additional MCP servers via
+`hyperhive.extraMcpServers.<key> = { command, args, env,
+allowedTools }`. The module writes the map to
+`/etc/hyperhive/extra-mcp.json`; the harness reads it at boot and
+merges every entry into `--mcp-config` (under `mcpServers.<key>`)
+and `--allowedTools` (as `mcp__<key>__<pattern>`).
+
+The agent's `flake.nix` forwards every flake input to `agent.nix` as
+the `flakeInputs` module arg, so external MCP-server flakes are pulled
+in by adding them to `inputs.*` and referenced as
+`flakeInputs.<name>.packages.${pkgs.system}.default` — the resolved
+sha lands in the agent's own `flake.lock` and rolls up to meta's.
+
+`allowedTools` defaults to `["*"]`, which expands to
+`mcp__<key>__*` (every tool from that server auto-approved). Restrict
+to specific tool names when you want finer control.

docs/tools/scheduling.md

@@ -0,0 +1,68 @@
+# Scheduling and diagnostics tools
+
+## `scheduling` tool group
+
+Scheduled prompts fan a message body out to one or more agent inboxes
+at a future time, optionally recurring. All scheduling ops go through
+the operator approval queue (even self-targeted schedules — use
+`remind` for unapproved self-wake). Authorization for read/cancel/edit
+ops: you can act on schedules you own or any owned by a sub-agent in
+your topology subtree.
+
+### `request_schedule_prompt(targets, body, first_fire_at_unix, interval_seconds?, description?)`
+
+Queue an operator-approval for a scheduled prompt. On approve,
+`body` is fanned out to each agent in `targets` at
+`first_fire_at_unix` (Unix timestamp). Recurring when `interval_seconds`
+is set, one-shot otherwise.
+
+Catch-up clamp: if hive-c0re is down across multiple intervals, only
+ONE delayed fire happens on resume (per recurring schedule). The
+skipped-cycle count surfaces in the per-target `last_result` for
+audit.
+
+### `edit_schedule(id, body?, description?, interval_seconds?, next_fire_at_unix?, targets_add?, targets_remove?)`
+
+Partial-update a schedule. Pass only the fields to change; absent
+fields are left alone. `targets_add` / `targets_remove` mutate the
+recipient list in the same transaction — re-adding a previously
+cancelled target drops its tombstone and starts fresh. Clearing
+`interval_seconds` to null flips recurring → one-shot. Refuses
+cancelled rows (terminal state).
+
+### `cancel_schedule(id, targets?)`
+
+Cancel a schedule. Omit `targets` / pass empty to cancel the whole
+schedule; pass a list to cancel just those recipients (the schedule
+auto-cancels when every target is removed).
+
+### `fire_schedule_now(id)`
+
+Fire a scheduled prompt out of band immediately. Recurring schedules
+keep their cadence — the manual fire is additive. One-shot schedules
+are consumed by the manual fire and cancelled afterwards.
+
+### `list_schedules()`
+
+Snapshot every schedule (active + cancelled-but-not-reaped): id,
+owner, body, per-target `last_fired_at` + `last_result`,
+`next_fire_at_unix`, `interval_seconds`. Use to look up an id before
+cancelling, or to audit upcoming wake-ups across the swarm.
+
+## `diagnostics` tool group
+
+### `get_logs(agent, lines?)`
+
+Fetch recent journal lines for a sub-agent container. Useful for
+diagnosing MCP-registration failures, startup crashes, plugin install
+errors, or any harness issue you can't see from inside the container.
+
+Pass the plain logical agent name (e.g. `"gui"`) — hive-c0re resolves
+the machine name (`h-<name>`). `lines` defaults to 50, host-capped at 500.
+
+## See also
+
+- `remind` (no-approval self-wake path) — documented in
+  [`docs/turn-loop.md`](../turn-loop.md).
+- [`docs/approvals.md`](../approvals.md) — approval flow for
+  `request_schedule_prompt`.