nixfiles/CLAUDE.md

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:

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.