Add NixOS ZFS EC2 AMI builder

README.md

@@ -0,0 +1,45 @@
+# NixOS ZFS EC2 AMI Builder
+
+This project publishes a matched EC2 AMI artifact:
+
+- root volume: bootable NixOS EC2 image
+- secondary volume: preseeded ZFS pool mounted at `/nix`
+
+The root snapshot and `/nix` snapshot are registered together in one AMI block
+device mapping. Runtime deployments should consume the AMI ID directly and
+should not independently choose a `/nix` snapshot.
+
+The image is intentionally project-agnostic. It provides NixOS, ZFS, SSM,
+flakes, and systemd ordering so the Nix daemon waits for `/nix`.
+
+## Publish
+
+The smallest supported flow is:
+
+```bash
+cd tofu/ami-builder
+nix build .#packages.aarch64-linux.rootImage
+./publish-ami.sh --bucket s3://my-vm-import-bucket
+```
+
+`publish-ami.sh` builds/imports the declarative NixOS root image, boots a
+temporary seeder instance once to create/export the ZFS `/nix` volume, creates
+the final AMI from the stopped instance, and writes `artifact.json`.
+
+The OpenTofu project in this directory owns only the final AMI registration
+metadata. Its state is separate from any runtime Quixos deployment state.
+
+## Artifact Metadata
+
+The final AMI is tagged with:
+
+- `Architecture`
+- `InputHash`
+- `BuilderGitRev`
+- `FlakeLockRev`
+- `RootSnapshotId`
+- `NixSnapshotId`
+- `NixosSystemClosure`
+
+Do not deregister the AMI or delete either snapshot while runtime deployments
+use it.