docs: turn into custom, and the capabilities in the hive status

docs/swarm/archetypes.md

@@ -9,7 +9,9 @@ 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,
 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.
+archetype. Picking "none" creates a custom agent, with its own config repo. The
+swarm can also turn an archetype agent into a custom one later
+([below](#turn-into-custom)).
 
 ## The built-in archetypes
 
@@ -139,3 +141,57 @@ 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.
+
+## Turn into custom
+
+An archetype agent can become a custom agent with its own
+`agent-configs/<name>` repo, either from the agent's overview in the swarm UI
+(the "turn into custom" button asks first) or with `POST /api/agents/{name}/custom`.
+The agent keeps its state, permissions, caps, inference settings and accounts.
+Its configuration stays the same, except that it no longer has `HIVE_ARCHETYPE`
+in its environment. Keeping the config current is then up to the repo's owner.
+Nothing here undoes it.
+
+The controller refuses with 409 an agent that no hive or more than one hive
+places, and one whose hive doesn't list the
+`no-config-checkout` capability (see below). Otherwise it queues a job graph:
+
+1. `CreateRepo`, `CreateForgeUser` and `AddRepoMember`: the repo and the
+   agent's access to the repo, as for any custom agent. Each is a no-op for what
+   exists.
+2. `SeedArchetypeConfig` commits two files to the repo. It copies nothing from
+   the archetype:
+   - `flake.nix` declares the archetype's source as an input, at the URL
+     `internal/meta` holds for that source today (a pinned rev, which is the input's only pin: the repo has no lock, and a source meta doesn't pin to a commit fails the node), and imports
+     `inputs.<source>.hyperhiveArchetypes.<name>.module` next to `./agent.nix`;
+   - `agent.nix` is an empty module for the owner's edits.
+
+   The node leaves a repo whose `flake.nix` already is this file alone, whatever
+   URL it pins. Any other `flake.nix` fails the node.
+
+3. `DropArchetype` deletes the agent's `agent-archetype` key, only after the
+   seed and the member grant succeeded. A failure before it leaves the agent
+   archetype-built and working, and you can send the same request again.
+4. `UpdateMeta`, then the build and the deploy, as for a merged config PR.
+   If the build fails, the agent is custom and has no key. Sending the request
+   again then queues only this step, as the earlier ones have run.
+
+When the source is `hyperhive`, the meta flake sets
+`agent-<name>.inputs.hyperhive.follows = "hyperhive"` for an agent whose
+`flake.nix` or `flake.lock` declares a `hyperhive` input, so the lock holds one
+hyperhive, and the module comes from the pin `internal/meta` holds. Any other
+source keeps the pinned URL from its seeded `flake.nix`, and the meta lock
+records that rev. The `follows` applies to every custom agent whose `flake.nix`
+declares a `hyperhive` input, not only converted ones. A `hyperhive` node left
+in a lock doesn't count.
+
+### Which hives may convert
+
+A hive that keeps a checkout of a custom agent's config would create one for
+the converted agent, under the container's running mount. A hive that lists
+`no-config-checkout` under `capabilities` in the status it publishes (the
+document `GET /api/hives/status` serves as `snapshot`) keeps none: it builds a
+custom agent from `internal/meta` alone, and the agent clones its own repo from
+the forge. The controller reads the agent's hive's latest status and refuses
+unless it's `fresh` and lists the capability; an older hive lists none. Deploy
+the release to every hive that places archetype agents before converting theirs.