diff --git a/.gitignore b/.gitignore
index 53d438d..83b47af 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,6 @@
 **/result
 
-# Devenv
+# devenv
 .devenv*
 devenv.local.nix
 devenv.local.yaml
@@ -10,3 +10,6 @@ devenv.local.yaml
 
 # pre-commit
 .pre-commit-config.yaml
+
+# llm harness junk
+.pi
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e6871ca
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+# NixOS Flake Configuration
+
+Personal NixOS configuration, managed as a flake. Deploys to NixOS, macOS (nix-darwin), and home-manager.
+
+## Machines
+
+| Hostname | Nix Target | Purpose |
+|------|----|-------------|
+| **nero** | NixOS | Personal desktop - KDE, gaming (Steam), VR (WiVRn), Flatpak apps |
+| **vergil** | NixOS | Server - Jellyfin, Pi-hole, nginx, remote build node |
+| **pdw-frankiel** | NixOS | Work desktop - KDE, flatpak apps |
+| **franks-macbook-pro** | macOS (nix-darwin) | General-purpose laptop |
+
+## Directory Structure
+
+```
+flake.nix
+hosts/                 <- Host specific confirugration, each host gets its own subdirectory matching it's hostname.
+  shared/              <- Shared components specific to hosts (Trusted SSH keys, shared pkgs, disk layouts).
+features/              <- Portable software feature modules (KDE, Podman, Wine, vim, etc.).
+home/                  <- Home-manager configuration and drop-in config files.
+packages/              <- Custom pkgs outside of nixpkgs or external flakes.
+secrets/               <- SOPS secret store
+assets/                <- Static assets like graphics.
+keys/                  <- SSH and GPG public keys.
+```
+
+### Building and useful commands
+
+```bash
+# Build and switch.
+sudo nixos-rebuild switch --flake .#<HOSTNAME>
+
+# Build and switch if using nix-darwin.
+sudo darwin-rebuild switch --flake .#<HOSTNAME>
+
+# Build but do not switch.
+nix build .#nixosConfigurations.nero.config.system.build.toplevel
+
+# Format all .nix files.
+nixfmt
+```
+
+## Secrets
+
+Secrets are managed with SOPS. The `secrets/` directory contains encrypted files that get decrypted at build time (or when using `sops edit secrets/<NAME>.yaml`. **Never** commit the decrypted versions. In order to successfully build a configuration with secrets, place the correct private age key file in `/persist/sops/age/keys.txt` with the file mask of `0400` prior to building. You can also drop in the `keys.txt` file using nixos-anywhere or other deployment tools. In order to edit sops encrypted files without being root, place the same key file in the user's home directory at `$HOME/.config/sops/age/keys.txt` with the file mask of `0400`. Ensure that you **always** edit secret files with `sops edit secrets/<NAME>.yaml` and that you don't accidentally commit unencrypted secrets.