an archetype's prompt prefills the new agent's agents.md in the create form

docs/2-handbook/swarm/archetypes.md

@@ -3,8 +3,8 @@
 An archetype is a named agent setup: settings to create the agent with, and
 a NixOS module its container runs. The swarm UI's create form lists the
 archetypes the swarm knows. Picking one fills the form's permissions,
-resource caps and inference fields from it, and you can still change each
-field before you create the agent.
+resource caps, inference and AGENTS.md fields from it, and you can still
+change each field before you create the agent.
 
 An agent created from an archetype has no `agent-configs/<name>` repo of its
 own. The swarm's `internal/meta` flake builds it from the archetype's module,
@@ -35,14 +35,23 @@ hyperhiveArchetypes.reviewer = {
     permissions = [ "messaging" "inbox" "execution" ];
     limits = { memory_max = "4G"; };
     inference = { effort = "high"; };
+    prompt = "You review pull requests and never push.";
   };
 };
 ```
 
+A long prompt can live in a file next to the flake. `builtins.readFile` gives a
+plain string at evaluation, so `meta` stays plain data:
+
+```nix
+hyperhiveArchetypes.reviewer.meta.prompt = builtins.readFile ./prompts/reviewer.md;
+```
+
 - `meta` is plain data: no derivation, no path, no function. The swarm
   evaluates `meta` alone.
 - Every archetype needs a `description`. `permissions`, `limits` and
-  `inference` are optional and take the shapes `POST /api/agents` takes. The swarm ignores
+  `inference` are optional and take the shapes `POST /api/agents` takes.
+  `prompt` is optional text that prefills `AGENTS.md`, [below](#the-prompt). The swarm ignores
   other keys in `meta`.
 - `module` is a NixOS module for the agent's container. The meta flake
   imports it into each agent created from the archetype.
@@ -52,6 +61,24 @@ Today the swarm reads one flake: the hyperhive source the
 flake has one archetype source too, its own `hyperhive` input, and refuses
 an archetype from any other source name.
 
+## The prompt
+
+An archetype's `meta.prompt` is starting text for the new agent's `AGENTS.md`:
+a reviewer that never pushes, a triage agent that keeps its notes in one
+place. Picking the archetype in the create form fills the form's AGENTS.md box
+with it, next to the permissions, caps and inference it fills. Edit the text
+freely; the agent starts with what the box holds when you create it. An
+archetype without `prompt` leaves the box alone.
+
+- The pick replaces the box only while the box is empty or still holds the
+  previous pick's prompt. Text you typed or edited stays.
+- The limit is 64 KiB (65536 bytes), the limit of an initial `AGENTS.md`. The
+  swarm refuses a longer `prompt` the way it refuses any bad `meta`: the
+  archetype leaves the list, and its name and the reason go into the record's
+  `refused` map. A blank `prompt` counts as none.
+- The text is a copy made at create. Editing the archetype's `prompt` later
+  changes what new agents start with, not the `AGENTS.md` of agents that exist.
+
 ## How the list stays current
 
 The swarm controller asks the builder for the list when the queue connects and