test the archetype module import in the meta flake render; update archetypes doc

docs/swarm/archetypes.md

@@ -7,8 +7,8 @@ resource caps and inference 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. 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
+own. The swarm's `internal/meta` flake 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
@@ -41,11 +41,13 @@ 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. A hive imports it
-  into each agent created from the archetype.
+- `module` is a NixOS module for the agent's container. The meta flake
+  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.
+[builder](builder.md)'s host runs, so only the built-ins appear. The meta
+flake has one archetype source too, its own `hyperhive` input, and refuses
+an archetype from any other source name.
 
 ## How the list stays current
 
@@ -110,23 +112,31 @@ Deploy `swarm-nats-auth` before the hives: every provision reads the
 agent's key, and a hive whose queue connection predates the grant gets a
 refused read, so its `Provision` nodes fail until it reconnects.
 
-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:
+swarm-controller renders `internal/meta`'s `flake.nix` with the
+`hive-meta-flake` crate, and reads each agent's archetype from the
+`agent-archetype` bucket to do so. For an archetype agent the render:
 
-- seeds no `proposed` or `applied` repo, and gives `internal/meta` 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;
+- adds no `agent-<name>` input and reads no config repo, and lists the agent
+  as `mkAgent { …; archetype = { source = "hyperhive"; name = "<name>"; }; }`;
+- makes `mkAgent` import `hyperhive.hyperhiveArchetypes.<name>.module` in
+  place of the agent's own flake, and set `HIVE_ARCHETYPE` in the harness
+  environment.
+
+The hive builds from `internal/meta` alone. It 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`. It takes the head of
+`internal/meta` only when that `flake.nix` lists the agent at the archetype
+it has now. When the read fails, a rebuild keeps the stored value. For an
+archetype agent the hive also:
+
+- seeds no `proposed` or `applied` repo;
 - 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.
+The module comes from the `hyperhive` input that `internal/meta` pins, not
+from the hive's own. When that pin predates the archetype, the agent's build
+fails with `this hive's hyperhive input has no archetype <name>; update that
+input`. Update the `hyperhive` pin in `internal/meta` to fix it.