Put the guide where the agent actually looks: miakapp agent-pack

docs/agent-guide.md

@@ -30,6 +30,25 @@ temperature — with the three files already in the right relationship, and its
 own `README.md` covering the mechanics of copying it out. This guide covers the
 judgment the template cannot.
 
+### Leave the repository readable by the next agent
+
+You are probably not the last agent to open this repository, and the next one
+will not have this conversation. Run the pack once, in the repository root:
+
+```bash
+miakapp agent-pack
+```
+
+It copies this guide to `.miakapp/agent-guide.md`, points `AGENTS.md` and
+`CLAUDE.md` at it, and registers `miakapp mcp` in `.mcp.json` so the tools are
+wired rather than described. It edits instead of replacing: prose outside the
+`<!-- miakapp:begin -->` markers is kept, other MCP servers are kept by name,
+and running it twice changes nothing.
+
+If you are reading this file *as* `.miakapp/agent-guide.md`, someone already
+ran it. Run it again after upgrading the CLI, and commit what changes — a guide
+that contradicts the CLI installed beside it is worse than no guide.
+
 ## 2. The division of responsibility
 
 **The coordinator authorizes everything.** The relay proves *who* is calling and
@@ -286,6 +305,7 @@ writes no history, rewrites no source it did not generate, and invents no
 control-plane endpoint. The repository is the owner's.
 
 ```bash
+miakapp agent-pack                                             # once, per repository
 miakapp init --home <homeId> --control-plane <https url>
 miakapp check
 miakapp publish  --expected-generation <n>
@@ -375,6 +395,8 @@ that is the failure this design exists to prevent.
 
 ## Where to read further
 
+- `packages/cli/README.md` — every command and every tool, including what the
+  pack writes and what it refuses to overwrite.
 - `templates/home/README.md` — the mechanics of the template itself.
 - `docs/rfcs/0001` (Miakapp-V3) — wire protocol: ownership, collisions, `4409`.
 - `docs/rfcs/0002` — component runtime and the staleness rule. **The broker is

packages/cli/README.md

@@ -56,6 +56,7 @@ duplicate keys — is rejected with the offending line rather than guessed at.
 | Command | What it does |
 | --- | --- |
 | `init` | Writes `miakapp.yaml`. Never overwrites an existing one. |
+| `agent-pack` | Offline. Installs the guide and the MCP wiring into a repository. |
 | `discover` | Offline. Inventories a Node-RED installation from its flows export. |
 | `check` | Offline. Parses the project, verifies the artifact, prints the digest. |
 | `publish` | Capability → delivery → finalization → activation, in one run. |
@@ -84,6 +85,39 @@ not model, so the reader knows what the inventory missed. It reports that a
 coordinator secret is present in the export; it never prints the secret itself.
 `docs/agent-guide.md` §3 explains what to do with each finding.
 
+## The agent pack
+
+`agent-pack` is the command to run *once* in a home repository, so that the next
+agent to open it arrives already knowing the rules:
+
+```
+miakapp agent-pack            # or --dir /path/to/the/repository
+```
+
+It writes four files and reports what it did to each one:
+
+| File | Why |
+| --- | --- |
+| `.miakapp/agent-guide.md` | The full guide, copied out of this package. No network, no stale bookmark. |
+| `AGENTS.md` | The instruction file Codex reads. |
+| `CLAUDE.md` | The instruction file Claude Code reads. |
+| `.mcp.json` | Project-scope MCP configuration, registering `miakapp mcp`. |
+
+The repository is yours, so the pack edits rather than replaces. The guide is a
+file it owns outright. The instruction files are touched only between
+`<!-- miakapp:begin -->` and `<!-- miakapp:end -->`: prose above and below the
+markers is copied through byte for byte, and a second run rewrites the block in
+place instead of appending another copy. `.mcp.json` is merged as a structure —
+one key, by name — so every other server in it survives, and a file that does
+not parse is refused rather than replaced with a valid one.
+
+The server is registered as the bare `miakapp` command rather than an absolute
+path, because the file is committed and the next machine to check it out will
+not have this one's directory layout.
+
+Run it again whenever the CLI is upgraded: an unchanged file is reported
+`unchanged`, and a guide that moved on is reported `updated`.
+
 ## MCP
 
 An agent that already runs a shell does not need this. An agent that speaks the
@@ -109,6 +143,7 @@ tools over newline-delimited JSON-RPC on stdio.
 | `miakapp_release` | `release` | read-only |
 | `miakapp_upload` | `upload` | read-only |
 | `miakapp_init` | `init` | writes `miakapp.yaml`, never overwrites |
+| `miakapp_agent_pack` | `agent-pack` | offline, writes the pack into a repository |
 | `miakapp_publish` | `publish` | **moves the pointer — needs `confirm: true`** |
 | `miakapp_activate` | `activate` | **moves the pointer — needs `confirm: true`** |
 | `miakapp_rollback` | `rollback` | **moves the pointer — needs `confirm: true`** |