diff --git a/README.md b/README.md
new file mode 100644
index 0000000..65211fe
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# nix
+
+NixOS configurations for personal machines, managed with flakes and Home Manager.
+
+## Layout
+
+```
+├── flake.nix              # Flake entry point — defines both NixOS configurations
+├── home.nix               # Shared Home Manager module (imported by all hosts)
+├── hyprland.nix           # Shared Hyprland config
+├── thick-black-cannon/    # Host: thick-black-cannon
+│   ├── configuration.nix  #   NixOS config
+│   └── home.nix           #   Home Manager config
+├── 13-inch-thin-cannon/   # Host: 13-inch-thin-cannon
+│   ├── configuration.nix  #   NixOS config
+│   └── home.nix           #   Home Manager config
+└── .tangled/workflows/    # Spindle CI pipelines
+```
+
+## Testing
+
+```sh
+nix flake check
+```
+
+This evaluates and builds both NixOS configurations. Add `--no-build` to skip
+building (eval-only).
+
+## Applying
+
+```sh
+sudo nixos-rebuild switch --flake .#"<hostname>"
+```
+
+## CI
+
+CI is provided by [Tangled Spindle](https://docs.tangled.org/spindles.html).
+Pipelines are defined in `.tangled/workflows/` and run `nix flake check` on
+every push and pull request to `main`.