docs: add a getting-started page for the nixos flake, module import and required options

docs/README.md

@@ -11,6 +11,8 @@ declarations.
 
 ## Getting started
 
+- **Adding hyperhive to a NixOS flake? Which options does it need?** →
+  [`getting-started/nixos.md`](getting-started/nixos.md).
 - **Bringing a fresh swarm online?** → [`getting-started/setup.md`](getting-started/setup.md)
   (the hand steps after the first switch).
 - **What does the dashboard look like, and how to use it?** →

docs/getting-started/nixos.md

@@ -0,0 +1,95 @@
+# Adding hyperhive to a NixOS flake
+
+How to take a NixOS machine you already manage with a flake to the point
+where `nixos-rebuild switch` brings hyperhive up. After the switch, continue
+with [`setup.md`](setup.md) for the steps that stay by hand.
+
+## 1 · Add the flake input
+
+In your host's `flake.nix`, add hyperhive next to nixpkgs:
+
+```nix
+inputs = {
+  nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";
+  hyperhive.url = "git+https://forge.darkest.space/hyperhive/hyperhive";
+};
+```
+
+Add `hyperhive` to the arguments of `outputs` too, so the next step can
+reach it.
+
+## 2 · Import the module
+
+Import `hyperhive.nixosModules.default`. It's the whole host stack in one
+import: the hive (`hive-c0re` and its gateway, bridge and resolver) and every
+swarm service. It also wires in hyperhive's own packages, so you set no
+package options.
+
+Importing `default` turns nothing on. Every service stays off until you
+enable it, and a host that imports it and enables nothing evaluates without
+any of the options below.
+
+```nix
+nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
+  system = "x86_64-linux";
+  modules = [
+    hyperhive.nixosModules.default
+    { services.hyperhive = { /* step 3 */ }; }
+  ];
+};
+```
+
+`claude-code` is unfree. Hyperhive scopes the allowance to itself, so you
+don't set `allowUnfree`.
+
+## 3 · Set the required options
+
+All of these live under `services.hyperhive`. Evaluation fails with a message
+naming the option when one is missing. None of them has a default, because a
+guessed value here is a wrong hostname that evaluates cleanly and deploys.
+
+| option                            | what it does                                                                                                                                                                               | without it                                                                           |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| `deploy.hive-controller.enable`   | Runs a hive on this host: `hive-c0re`, which owns every agent container, plus the bridge and gateway for the agents.                                                                       | No agents can run here. Leave it off on a host that only runs shared swarm services. |
+| `swarm.domain`                    | The swarm's DNS domain. Each hive lives in a sub-domain of it. Use the same value on every host of the swarm.                                                                              | Eval fails on any host that runs a hyperhive service.                                |
+| `deploy.hive-controller.hiveName` | This hive's label inside the swarm, and the first part of its address, `<hiveName>.<swarm.domain>`. It's also the hive's identity in the secret store.                                     | Eval fails on a host that runs a hive.                                               |
+| `swarm.hives`                     | The directory of every hive in the swarm, this one included. Entries need no fields: each `domain` defaults to `<name>.<swarm.domain>`. Every host of the swarm shares one identical copy. | Eval fails, naming the missing entry for `hiveName`.                                 |
+
+An all-local swarm, with every shared service and the hive on this one box,
+adds one switch:
+
+| option                   | what it does                                                                                                                                                                        |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deploy.singleHostSwarm` | Turns on the shared swarm services, the swarm controller, and `/etc/hosts` entries so the swarm's names resolve on the box itself. Leave it off if the services run on other hosts. |
+
+The smallest working config, as in the README's
+[all-local quick start](../../README.md#quick-start-an-all-local-swarm):
+
+```nix
+services.hyperhive = {
+  deploy.singleHostSwarm = true;
+  deploy.hive-controller.enable = true;
+  swarm.domain = "hive.example";
+  deploy.hive-controller.hiveName = "pr1ma";
+  swarm.hives.pr1ma = { };
+};
+```
+
+Run `nixos-rebuild switch --flake .#my-host`. The swarm UI then answers at
+`https://<swarm.domain>/`.
+
+## Everything else is optional
+
+Leave the other options at their defaults until you need them:
+
+- Spreading a swarm over more than one host, and the credentials a split swarm
+  needs: [`swarm/README.md`](../swarm/README.md) and
+  [`swarm/credentials.md`](../swarm/credentials.md).
+- Every option, with its type and default:
+  [the options reference](https://hyperhive.darkest.space/options/).
+- The secret store's seal and the granter: [`swarm/bao.md`](../swarm/bao.md).
+
+## Next
+
+[`setup.md`](setup.md): initialize the secret store, create your SSO account
+and your first agents.

docs/getting-started/setup.md

@@ -5,7 +5,8 @@ What's left to do by hand after the first `nixos-rebuild switch` of the
 — from a freshly built host to your first agent. Do the steps in order;
 each one assumes the ones before it.
 
-Every command runs as **root on the host**.
+Every command runs as **root on the host**. The flake input, module import
+and required options are in [`nixos.md`](nixos.md).
 
 > **Not all-local?** Each step says which host it runs on. A split swarm
 > also has credentials you can't generate where they're read — each