diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..564a913
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,63 @@
+# Working on this flake
+
+Project notes for changes to this repository. Persona and memory rules live in
+the user-global config; this file is about the flake's checks and conventions.
+
+## Before you commit: run the formatter
+
+Formatting and linting are driven by the flake. CI (`.gitea/workflows/ci.yaml`)
+runs `nix flake check`, which fails the build if any file is unformatted or trips
+a lint. From the repo root:
+
+- `nix fmt` — format the whole tree (writes changes).
+- `nix flake check` — run every check read-only (what CI runs).
+- `nix develop` — dev shell; its `shellHook` installs the git pre-commit hooks so
+  the same gates run on `git commit`.
+
+Never commit with `--no-verify`. A bypassed commit ships unformatted content and
+turns CI red on the next push to `main` (see "Docs are checked too").
+
+## What gets checked
+
+Defined in `flake.nix` (the `treefmt`, `pre-commit`, and `checks` blocks) and
+`statix.toml`:
+
+| Check        | Tool                              | Covers                                                  |
+| ------------ | --------------------------------- | ------------------------------------------------------- |
+| `formatting` | treefmt → `nixfmt`                | all `*.nix`                                             |
+| `formatting` | treefmt → `shfmt`                 | shell scripts                                           |
+| `formatting` | treefmt → `prettier`              | **Markdown, YAML, JSON** (incl. `README.md`, this file) |
+| `deadnix`    | deadnix                           | dead Nix bindings (`--no-lambda-pattern-names`)         |
+| `statix`     | statix                            | Nix antipatterns (config in `statix.toml`)              |
+| pre-commit   | nixfmt-rfc-style, deadnix, statix | the same gates, run on commit                           |
+
+Excluded from formatting: `*/hardware-configuration.nix` (generated by
+`nixos-generate-config`) and `flake.lock`. Editor defaults (indent, EOL, final
+newline) are in `.editorconfig`; note Markdown keeps trailing whitespace, which
+encodes hard line breaks.
+
+## Docs are checked too — the common trap
+
+prettier formats `*.md`, so **documentation edits must be run through `nix fmt`**
+exactly like code. prettier re-aligns Markdown tables in particular; hand-editing
+a table almost always leaves it non-conformant and fails the `formatting` check.
+
+Beware a false green: the CI `detect` step skips the heavy checks on a pull
+request that touches **no** `.nix`, `flake.lock`, or the workflow file — so a
+docs-only PR reports success without ever running prettier. The failure then
+surfaces on the push-to-`main` run (which always runs the full check) or on the
+next unrelated PR that does touch Nix. Run `nix flake check` locally before
+merging a docs change, regardless of what the PR check shows.
+
+## Host evaluation
+
+CI also evaluates every `nixosConfigurations` / `darwinConfigurations` host's
+toplevel (eval only, no build) on an x86_64 runner, so eval errors fail cheaply.
+Reproduce locally:
+
+```sh
+nix eval --raw ".#nixosConfigurations.<host>.config.system.build.toplevel.drvPath"
+```
+
+Host lists are discovered from the flake, so adding or removing a host needs no
+change to the workflow.