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
+  agent is two approvals. `InitConfig` creates the config repo and
-  a template so the submitting agent can edit it; once you're happy
+  seeds it from a template; `Spawn` creates the container from that
-  with what they wrote, `Spawn` actually creates the container from
+  config. Tailoring the template first is not a separate mechanism —
-  that config. Every later change goes through the config-change flow
+  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
+   tool group) **clones** `agent-configs/<name>`, edits it there (any
-   (any tracked path, but `agent.nix` is the contract entry point),
+   tracked path, but `agent.nix` is the contract entry point), commits
-   commits with its own git identity, and pushes a branch + opens a PR
+   with its own git identity, and pushes a branch + opens a PR with
-   on `agent-configs/<name>` with `hive-forge`. The parent's container
+   `hive-forge` — the same way it would change any other repo.
-   has the child's proposed config repo bind-mounted read-write at
+   The bind-mounted `/agents/<name>/config/` is a **copy for reading** a
-   `/agents/<name>/config/` (topology-driven via `set_nspawn_flags`;
+   config, not the tree to edit: authoring in place there produces no PR
-   the agent's *own* config at `/agents/<self>/config/` is read-only).
+   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.
+`InitConfig` approvals create a brand-new agent's config repo. On
-On approve, hive-c0re seeds it with a default `agent.nix` template and
+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
+in-container store. The operator then **spawns** the agent (the
-commits the template; 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
+container from that config.
-forge PR (`MergeConfigPr`) — never a fresh spawn. This gives the
+
-submitting agent (and operator) an explicit review gate on the initial
+Changing what the template seeded is not a special case: like every
-configuration before any container is created.
+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
+well as reading it. `config` and `harness` are RW too, but **nothing
-config changes for the child (the approval flow commits into the
+justifies that for `config`**: a config change is a PR on the child's
-child's config repo), and `harness` is RW for the same management
+config repo, made from a clone, so the bind-mounted `config` dir is a
-reasons. Per-child isolation still holds: a container only ever has
+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.
 

hive-agent-mcp/src/mcp/args.rs

@@ -87,11 +87,11 @@ pub struct RemindArgs {
 #[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
 pub struct RequestInitConfigArgs {
     /// New sub-agent name (≤9 chars). Queues an `InitConfig` approval; on
-    /// approval hive-c0re seeds the proposed config repo at
+    /// approval hive-c0re creates the child's config repo and seeds it with a
-    /// `/agents/<name>/config/agent.nix` with the default template. After
+    /// default `agent.nix`. Approving the follow-up `Spawn` creates the
-    /// the approval the manager edits + commits the config, then the operator
+    /// container. Config changes — including the child's first — are PRs on
-    /// spawns the agent; later config changes go through a PR on the child's
+    /// that repo, made from a clone, reviewed + approved by the operator;
-    /// `agent-configs/<name>` repo.
+    /// `/agents/<name>/config` is a read-only copy, not an editing surface.
     pub name: String,
     /// Optional description shown on the dashboard approval card.
     #[serde(default)]

hive-agent-mcp/src/mcp/mod.rs

@@ -824,13 +824,16 @@ impl AgentServer {
     // hive-c0re performs a topology check server-side: only direct children
     // of the calling agent are accepted; all other names are rejected.
     #[tool(
-        description = "Initialise a brand-new direct child agent's proposed config repo and \
+        description = "Create a brand-new direct child agent's config repo and queue an \
-            queue an `InitConfig` approval for the operator to review. Requires the `approvals` \
+            `InitConfig` approval for the operator to review. Requires the `approvals` tool \
-            tool group. `name` must be a direct child of this agent in the topology tree. \
+            group. `name` must be a direct child of this agent in the topology tree. Fails if a \
-            Fails if a config repo for that child already exists. On approval hive-c0re seeds \
+            config repo for that child already exists. This tool **creates the repo** and \
-            `/agents/<name>/config/agent.nix` with the default template; customise + commit it, \
+            nothing else: on approval hive-c0re seeds it with a default `agent.nix`, and \
-            then the operator spawns the agent. Later config changes go through a PR on the \
+            approving the follow-up `Spawn` creates the container. \
-            child's `agent-configs/<name>` repo, reviewed + approved by the operator."
+            Every config change — the child's first one included — goes through a PR on its \
+            config repo, made from a clone you take yourself, reviewed + approved by the \
+            operator. `/agents/<name>/config` is a **read-only copy** for reading a config, \
+            never an editing surface."
     )]
     async fn request_init_config(
         &self,

hive-c0re/src/lifecycle/setup.rs

@@ -1,6 +1,10 @@
-//! First-spawn provisioning: seed the manager-editable proposed repo and
+//! First-spawn provisioning: seed the agent's proposed config repo and
 //! the hive-c0re-owned applied repo, and ensure the per-agent state /
 //! claude-credentials dirs (btrfs subvolume when available) exist.
+//!
+//! Seeding is the only write either repo gets from here. Later config
+//! changes arrive as forge PRs authored in a clone — nothing edits a
+//! working tree in place.
 
 use std::path::Path;
 
@@ -10,17 +14,21 @@ use super::git::{
     git, git_command, git_commit, git_read_tree_reset, git_rev_parse, git_root_commit, git_tag,
 };
 
-/// Initialize the manager-editable proposed repo. Seeds two tracked
+/// Initialize an agent's config repo. Seeds two tracked files:
-/// files: `agent.nix` (the module the manager edits) and `flake.nix`
+/// `agent.nix` (the agent's own module) and `flake.nix` (the
-/// (the boilerplate that lets the meta flake import this repo as an
+/// boilerplate that lets the meta flake import this repo as an input —
-/// input — meta locks at a specific sha and reads
+/// meta locks at a specific sha and reads `nixosModules.default`, so
-/// `nixosModules.default`, so `flake.nix` must be in the commit). The
+/// `flake.nix` must be in the commit). `flake.nix` isn't meant to be
-/// manager shouldn't edit `flake.nix` (the prompt says so) but it's
+/// edited, but it's tracked so it can be read.
-/// visible so they can introspect.
 ///
-/// Touched by hive-c0re only on first spawn — never again — so the
+/// **Seeding is the whole of hive-c0re's write.** Changes to the repo
-/// manager can't be surprised by hive-c0re commits or working-tree
+/// arrive as PRs from a clone, via the forge, like any other code
-/// resets.
+/// change — nothing edits a working tree in place, here or in the
+/// agent's bind-mounted `config/` (which is a read-only copy).
+///
+/// Touched by hive-c0re only on first spawn — never again — so a
+/// hive-c0re commit or working-tree reset can't surprise anyone
+/// holding a clone.
 pub async fn setup_proposed(proposed_dir: &Path, name: &str) -> Result<()> {
     let fresh = !proposed_dir.join(".git").exists();
     if fresh {