set an agent's initial agents.md at create

docs/agent-lifecycle/persistence.md

@@ -278,7 +278,8 @@ Under `/var/lib/hyperhive/agents/<name>/`:
   logs an error naming both paths: claude loads only `CLAUDE.md` while
   one exists in its cwd or above. The harness also publishes the file
   to the swarm, which reads that copy, and applies the git diffs the
-  swarm sends to edit it. This file stays the only copy that counts:
+  swarm sends to edit it. A new agent's first start writes the text given at
+  create, only when no file exists. This file stays the only copy that counts:
   [`docs/swarm/README.md`](../swarm/README.md#an-agents-agentsmd).
 - `harness/` — harness-internal ephemeral state; not intended for
   agent consumption. Bind-mounted to `/agents/<name>/harness`

docs/swarm/README.md

@@ -328,6 +328,19 @@ publishes `""`. `GET /api/agents/<name>/agents-md` answers `{content, revision}`
 from that copy, so it works while the agent isn't running. A 404 means the agent
 hasn't published one: its harness hasn't run since it began to.
 
+**Initial text.** `POST /api/agents` and `swarmctl agent create --agents-md <file>`
+take an optional `agents_md`, the text the file starts with, up to 64 KiB; a
+longer text is a 400. The controller stores it under the key `<agent>` of the
+`agents-md-initial` bucket, which only it writes, before it queues the creation.
+At start the harness reads its own key, with one direct get on
+`$JS.API.DIRECT.GET.KV_agents-md-initial.$KV.agents-md-initial.<agent>`, and
+writes the text to `AGENTS.md` only when no file exists there. It does this
+before the first mirror publish and the first turn. An existing file is never
+replaced, so a restart or a re-create keeps the agent's edits; a later change
+to the file never reaches the key. Destroying the agent deletes the key. When
+the harness can't read the key it starts without the text and logs a warning.
+The text holds no secret, so nothing goes through the secret store.
+
 **Editing.** `PUT /api/agents/<name>/agents-md` takes `{base_revision, diff}`.
 The diff is a unified diff that names `a/AGENTS.md` and `b/AGENTS.md`, made
 against the text at `base_revision`. swarm-controller sends it as a request on

docs/tools/swarmctl-cli.md

@@ -101,6 +101,9 @@ No approval gate guards this: the caller is root on the controller's host, or lo
 * `--hive <HIVE>` — Hive in this swarm to deploy the agent to.
 
    Required, and deliberately not defaulted: it's an *address* — the hive that gets the deploy message — and only the operator knows which one they mean. The controller checks it against the swarm's hive roster and names the known hives if it misses.
+* `--agents-md <FILE>` — A text file the agent's `AGENTS.md` starts with.
+
+   The agent writes it on its first start, and only when it has no `AGENTS.md` yet: re-creating an agent never replaces an existing file. The controller refuses a file over 64 KiB.
 * `--controller-socket <PATH>` — swarm-controller's unix socket.
 
    Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.