archetypes: build an archetype agent from its archetype's module on the hive

The hive reads the agent-archetype key when it provisions and rebuilds an
agent and keeps it in swarm-agent-archetypes.json. For an archetype agent
the meta flake has no agent-<name> input and mkAgent imports
hyperhive.hyperhiveArchetypes.<name>.module; provisioning, rebuilds, the
meta-input cascade, a deploy's rev and the startup migration skip the
config repos. The harness gets HIVE_ARCHETYPE and the system prompt says
the agent has no config repo. The create form sends the picked archetype.
Adds the android-dev built-in.

Refs #5386

docs/agent-lifecycle/agent-roster.md

@@ -106,13 +106,16 @@ state dirs work as for every other agent.
   deploy log). Any agent holding it gets the same mounts.
   The operator dashboard's `POST /api/meta-update` is the only path
   that writes `flake.lock`.
-- **Prompt** — identical for every container: `prompts/system.md`
+- **Prompt** — identical for every container but one block (below):
+  `prompts/system.md`
   carries `<!-- role:agent -->` / `<!-- role:manager -->` marker
   blocks, and `prompt::render` filters for `"agent"` unconditionally,
   manager included ("always `agent` role — there is only one role",
   `hive-agent/src/prompt.rs`'s own module doc). The `role:manager`
   blocks are dead in production, exercised only by a unit test
-  (`filter_role_blocks(SAMPLE, "manager")`).
+  (`filter_blocks(SAMPLE, "role", "manager")`). The one block that differs
+  is `<!-- config:repo -->` vs `<!-- config:archetype -->`: an agent built
+  from an [archetype](../swarm/archetypes.md) is told it has no config repo.
 - **Tool allow-list** — the MCP tools claude sees come from the agent's
   permissions alone, the same mechanism for every agent
   ([`docs/turn-loop/mcp.md`](../turn-loop/mcp.md)). Ruth's permissions

docs/agent-lifecycle/config-changes.md

@@ -65,6 +65,8 @@ Creating a brand-new agent is swarm-level (`swarmctl agent create`,
 an agent. The swarm controller's `InitAgentConfigRepo` job seeds the
 agent's config repo with a default `agent.nix` template, then asks the
 target hive to deploy it.
+An agent created from an [archetype](../swarm/archetypes.md) gets no
+config repo: its hive builds it from the archetype's module.
 
 Changing what the template seeded isn't a special case: like every
 later change, it's a PR on that config repo, made from a clone and

docs/agent-lifecycle/persistence.md

@@ -420,6 +420,12 @@ reads it at every container start for `manage_root_agent`. Each agent gets
 its own entry from it as `swarm-permissions.json` in its runtime dir, which
 it holds until its own first read of its key succeeds.
 
+`/var/lib/hyperhive/swarm-agent-archetypes.json` holds the archetype each of
+this hive's archetype agents runs, as last read from the swarm's
+`agent-archetype` bucket at the agent's provision and each rebuild. An agent
+with an entry has no `applied/<n>` repo and no `agent-<n>` meta input; see
+[archetypes](../swarm/archetypes.md).
+
 hive-c0re renders containers onto `meta#<n>` at creation.
 
 ## Destroy vs purge

docs/swarm/archetypes.md

@@ -1,21 +1,24 @@
 # Agent archetypes
 
-An archetype is a named set of settings to create an agent from. 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.
+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.
 
-The agent you create this way is an ordinary agent: it gets its own
-`agent-configs/<name>` repo like any other, and the request carries only the
-fields as the form shows them. Nothing records which archetype you picked.
+An agent created from an archetype has no `agent-configs/<name>` repo of its
+own. Its hive builds it from the archetype's module, so every agent of that
+archetype runs the same configuration. To change what it runs, change the
+archetype. Picking "none" creates a custom agent, with its own config repo.
 
 ## The built-in archetypes
 
 The hyperhive flake ships these:
 
-| archetype  | what it sets                                                                                                                                       |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `reviewer` | permissions `messaging`, `inbox`, `execution`: the default set without `meta`. With `execution` it can run `hive-forge`, `git` and other commands. |
+| archetype     | what it sets                                                                                                                                       |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reviewer`    | permissions `messaging`, `inbox`, `execution`: the default set without `meta`. With `execution` it can run `hive-forge`, `git` and other commands. |
+| `android-dev` | installs `android-tools` (`adb`, `fastboot`), Gradle and a JDK; default permissions.                                                               |
 
 ## Where an archetype comes from
 
@@ -38,8 +41,8 @@ hyperhiveArchetypes.reviewer = {
 - Every archetype needs a `description`. `permissions`, `limits` and
   `inference` are optional and take the shapes `POST /api/agents` takes. The swarm ignores
   other keys in `meta`.
-- `module` is a NixOS module for the agent's container. The swarm doesn't
-  apply it yet.
+- `module` is a NixOS module for the agent's container. A hive imports it
+  into each agent created from the archetype.
 
 Today the swarm reads one flake: the hyperhive source the
 [builder](builder.md)'s host runs, so only the built-ins appear.
@@ -85,3 +88,42 @@ The stored value:
   "refused": { "broken": "limits: …" }
 }
 ```
+
+## Creating an agent from an archetype
+
+The create form sends the picked archetype as `archetype` on
+`POST /api/agents`, `{ "source": "hyperhive", "name": "reviewer" }`. The
+controller refuses with 400 an archetype the stored list doesn't hold, then:
+
+1. stores the choice in the `agent-archetype` KV bucket, keyed by agent name,
+   next to the agent's permissions, caps and inference;
+2. queues the creation graph without `CreateRepo`, `AddRepoMember` and
+   `InitAgentConfigRepo`. Identity, forge user, docs read, the mints and the
+   wanted state stay, and the deploy waits on those alone.
+
+Destroying the agent deletes its key.
+Every hive may read any key of the bucket
+(`$JS.API.DIRECT.GET.KV_agent-archetype.>`) and write none; only the
+controller writes it.
+
+The hive reads the agent's key when it provisions the agent and on every
+rebuild, and keeps the last value read in
+`/var/lib/hyperhive/swarm-agent-archetypes.json`, so the meta flake renders
+without the queue. When the read fails, a rebuild keeps the value
+stored there. For an archetype agent the hive:
+
+- seeds no `proposed` or `applied` repo, and gives the meta flake no
+  `agent-<name>` input. `mkAgent` imports
+  `hyperhive.hyperhiveArchetypes.<name>.module` in place of the agent's own
+  flake, and sets `HIVE_ARCHETYPE` in the harness environment;
+- relocks no agent input on a rebuild or a meta-input bump, and ignores the
+  `rev` of a swarm deploy request;
+- mounts an empty `/agents/<name>/config/`.
+
+The agent's system prompt says it has no config repo and names its
+archetype.
+
+The hive takes the module from its own `hyperhive` input. When that input
+predates the archetype, the agent's build fails with
+`this hive's hyperhive input has no archetype <name>`. Update the hive's
+`hyperhive` input to fix it.

docs/turn-loop/claude-invocation.md

@@ -255,7 +255,12 @@ needs to `chown` a bind mount), once at startup:
   `hive-agent/prompts/system.md` by `hive-agent`'s `prompt::render`:
   HTML-comment markers (`<!-- role:agent -->...<!-- /role:agent -->`,
   same for `role:manager`) gate the role-specific blocks; both flavors
-  share everything else. Five placeholders are then
+  share everything else. `<!-- config:repo -->` and
+  `<!-- config:archetype -->` blocks gate the config-repo paragraphs: an
+  agent with `HIVE_ARCHETYPE` set (the meta flake sets it on an agent built
+  from an [archetype](../swarm/archetypes.md)) gets the archetype block and
+  every other agent the repo block, with `{archetype}` filled in with the
+  archetype's name. Five placeholders are then
   substituted: `{label}` (short agent name), `{qualified_label}`
   (hive-qualified `name@domain` form),
   `{hive_identity}` (for example `` on hive `pr1ma` ``; empty when
@@ -275,14 +280,17 @@ needs to `chown` a bind mount), once at startup:
   telling the agent where the docs live.
   Passed via `--system-prompt-file`.
 
-  **Marker grammar.** `<!-- role:X -->` opens a block; any
-  `<!-- /role:X -->` closes the current block. The renderer always uses
-  role `agent`, so it elides blocks with other role tags. Nesting **isn't**
+  **Marker grammar.** `<!-- KIND:X -->` opens a block; any
+  `<!-- /KIND:X -->` closes the current block of that kind. The renderer
+  filters the two kinds one after the other. The renderer always uses
+  role `agent`, so it elides blocks with other role tags, and config `repo`
+  or `archetype` as above. Nesting **isn't**
   supported — a stray opener with no closer runs until end of file.
   The renderer tolerates whitespace inside markers (`<!--role:foo-->` parses the
   same as `<!-- role:foo -->`). Content outside any marker is always
-  included. Today's `system.md` carries no markers (single agent role) —
-  the grammar stays wired for a future manager / multi-role prompt.
+  included. Today's `system.md` carries no role markers (single agent
+  role), and the role grammar stays wired for a future manager / multi-role
+  prompt; it carries one pair of config blocks.
 
   **`hive_identity` / `swarm_identity` shape.** Each carries a
   leading space + backticked name (` on hive \`pr1ma\``,