docs: add container lifecycle section to coordinator.md, trim lifecycle.rs prose

docs/coordinator.md

@@ -113,6 +113,67 @@ Key operations:
 
 ---
 
+## Container lifecycle (`lifecycle.rs`)
+
+Every container operation ultimately calls into `lifecycle.rs`. Two paths exist:
+**rebuild** (existing container) and **spawn** (first-time creation).
+
+### Rebuild path (existing container)
+
+Goal: apply the new system profile and any `EXTRA_NSPAWN_FLAGS` / drop-in changes
+in a single start, with minimum downtime.
+
+`nixos-container update` only runs `systemctl reload container@<c>` when the
+container is already up (per `isContainerRunning` in `nixos-container.pl`). Stopping
+first turns `update` into a boot-style operation: it builds + `nix-env --set`s the
+new profile and skips the in-container `switch-to-configuration`. The subsequent
+`start` then applies both the new profile and any `EXTRA_NSPAWN_FLAGS` changes in
+one go, rather than the double-bounce a live `update` would trigger.
+
+Sequence for a running container:
+
+1. `prebuild_toplevel` — build the new `system.build.toplevel` **before** stopping.
+   The container keeps serving the previous generation while eval + fetch + build
+   happen out-of-band. `nixos-container update` then finds the result cached and
+   skips straight to the profile-swap. Build failures surface here, before the
+   running container is touched.
+2. `nixos-container stop` — bring the container down.
+3. `nixos-container update --flake meta#<name>` — profile-swap (near-instant after
+   the prebuild).
+4. `nixos-container start` — boot into the new generation; the in-container
+   activation script transitions old → new.
+
+If the container is already stopped, step 1 is skipped (no downtime to shave — no
+point evaluating the flake twice).
+
+### Cold-start fallback
+
+`start` after `update` can exit non-zero when packages are **removed** between
+generations: the old-generation activation script references units that no longer
+exist in the new closure, causing systemd to exit non-zero. The container may be
+half-started at that point.
+
+Fallback: `stop` (graceful SIGTERM drain) → `kill` (SIGKILL any lingering processes)
+→ `start` (clean cold-start, no generation transition, new activation runs cleanly).
+Both errors are preserved and surfaced if the cold-start also fails.
+
+### Spawn path (new container)
+
+For a first-time `create`, `nixos-container create` is atomic: if the build fails,
+no container record is left to clean up. A separate prebuild would just duplicate
+the eval, so it's skipped. Sequence: `create --flake meta#<name>` → write nspawn
+flags → `systemctl daemon-reload` → `start`.
+
+### Prebuild attr path
+
+`nix build` does not auto-resolve `meta#<name>` against `nixosConfigurations` the
+way `nixos-container` does internally. The explicit attr path
+`<flake-root>#nixosConfigurations.<name>.config.system.build.toplevel` is required;
+using the bare `meta#<name>` ref would make nix look in `packages`, `legacyPackages`,
+or the flake root directly — none of which exist in the rendered meta flake.
+
+---
+
 ## See also
 
 - `docs/approvals.md` — approval flow + scheduled prompts