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

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.