docs: a config change is a PR from a clone, not an edit in place

Seven places described an authoring flow that does not exist: the
manager editing and committing a child's config in the bind-mounted
config dir. mara, on the snapshot issue: "the pr workflow is the main
one, anything else is legacy … the config dir in agent container is
read only copy to see own config … changes need to go through local
clone and via forge".

Two of the seven are the request_init_config MCP tool description and
its args struct, which are rendered into the system prompt of every
agent holding the approvals tool group. A wrong tool description is not
a stale comment; it is an instruction the whole hive reads as fact,
which is why the claim kept being repeated back.

The init tool creates the repo and seeds it. Nothing else. Tailoring
the seeded template is not a separate mechanism - it is the ordinary
config-change flow, a PR reviewed like any other.

Prose only; the code already implements the PR flow (an approval's
commit_ref is a PR number). Where a doc justified the parent's
read-write mount on the child's config dir with the authoring model,
the justification is removed rather than replaced: that mount is a
defect tracked on its own issue, and it should not read as intentional
while it waits.

docs/agent-hierarchy.md

@@ -143,7 +143,9 @@ can't:
 The manager container's nspawn bind set:
 
 - `HOST_AGENTS_ROOT (/var/lib/hyperhive/agents) → /agents` RW — so the
-  manager can edit any agent's proposed config repo
+  manager can manage any agent's state dir. Config is **not** authored
+  here: a config change is a PR from a clone, and `<agent>/config/` is
+  a copy for reading (its write access is a defect tracked separately)
 - `HOST_APPLIED_ROOT (/var/lib/hyperhive/applied) → /applied` RO — so
   the manager can diff against what's deployed
 - `HOST_META_ROOT (/var/lib/hyperhive/meta) → /meta` RO — so the

docs/approvals.md

@@ -25,10 +25,10 @@ CLI) before it takes effect. What you'll see, and what to do with it:
   the agent stays on its last-good config, no recovery action needed
   from you.
 - **New agent** (`InitConfig` then `Spawn`) — creating a brand-new
-  agent is two approvals. `InitConfig` seeds a fresh config repo from
-  a template so the submitting agent can edit it; once you're happy
-  with what they wrote, `Spawn` actually creates the container from
-  that config. Every later change goes through the config-change flow
+  agent is two approvals. `InitConfig` creates the config repo and
+  seeds it from a template; `Spawn` creates the container from that
+  config. Tailoring the template first is not a separate mechanism —
+  it's the config-change flow above, a PR you review like any other. Every later change goes through the config-change flow
   above — there's no repeat "spawn" for an existing agent.
 - **Meta/flake update** (`UpdateMetaInputs`) — an agent asked to bump
   one or more Nix flake inputs (or all of them). Approving runs the
@@ -60,13 +60,14 @@ There is no bespoke MCP tool for config changes: opening the PR IS the
 request.
 
 1. The submitting agent (the child's parent, holding the `approvals`
-   tool group) edits files in the child's proposed config repo
-   (any tracked path, but `agent.nix` is the contract entry point),
-   commits with its own git identity, and pushes a branch + opens a PR
-   on `agent-configs/<name>` with `hive-forge`. The parent's container
-   has the child's proposed config repo bind-mounted read-write at
-   `/agents/<name>/config/` (topology-driven via `set_nspawn_flags`;
-   the agent's *own* config at `/agents/<self>/config/` is read-only).
+   tool group) **clones** `agent-configs/<name>`, edits it there (any
+   tracked path, but `agent.nix` is the contract entry point), commits
+   with its own git identity, and pushes a branch + opens a PR with
+   `hive-forge` — the same way it would change any other repo.
+   The bind-mounted `/agents/<name>/config/` is a **copy for reading** a
+   config, not the tree to edit: authoring in place there produces no PR
+   and no approval. (It is currently mounted read-write, which is a
+   defect tracked separately, not an authoring path.)
    Branch protection (push/merge whitelist = `core`, approvals whitelist
    = operator team; see "Forge mirror" and #1787) makes the agent a
    write collaborator that **cannot merge its own config PR**.
@@ -130,16 +131,18 @@ agent that lacks the `approvals` tool group: only an agent with that
 group submits approvals (for its direct children), so an agent
 without it has nothing of its own to withdraw.
 
-`InitConfig` approvals seed a brand-new agent's proposed config repo.
-On approve, hive-c0re seeds it with a default `agent.nix` template and
+`InitConfig` approvals create a brand-new agent's config repo. On
+approve, hive-c0re seeds it with a default `agent.nix` template and
 pushes a todo (`push_todo_submitter`) into the submitting agent's
-in-container store. The submitting agent reviews, edits, and
-commits the template; the operator then **spawns** the agent (the
+in-container store. The operator then **spawns** the agent (the
 `Spawn` approval / `◆ R3QU3ST SP4WN` button), which creates the
-container from that config. From then on, config changes go through a
-forge PR (`MergeConfigPr`) — never a fresh spawn. This gives the
-submitting agent (and operator) an explicit review gate on the initial
-configuration before any container is created.
+container from that config.
+
+Changing what the template seeded is not a special case: like every
+later change, it's a PR on that config repo (`MergeConfigPr`), made
+from a clone, reviewed and approved by the operator. The PR flow is
+the one path — an operator can equally drive both steps herself
+through the web UI or the forge.
 
 ### Approval kinds (wire shapes)
 

docs/persistence.md

@@ -319,10 +319,12 @@ A parent agent gets each direct child's `state`, `harness`, and
 `lifecycle.rs`). The RW on `state` is deliberate, not an oversight: a
 parent manages its children, which includes writing into a child's
 state for recovery (e.g. seeding notes, clearing a stuck sentinel) as
-well as reading it. `config` is RW because the parent authors proposed
-config changes for the child (the approval flow commits into the
-child's config repo), and `harness` is RW for the same management
-reasons. Per-child isolation still holds: a container only ever has
+well as reading it. `config` and `harness` are RW too, but **nothing
+justifies that for `config`**: a config change is a PR on the child's
+config repo, made from a clone, so the bind-mounted `config` dir is a
+read-only *copy* for reading a child's config — not a tree anyone edits
+in place. Narrowing it is tracked separately, and depends on relocating
+where `InitConfig` seeds. Per-child isolation still holds: a container only ever has
 its *own* dirs plus its direct children's bind-mounted, never a
 sibling's.