# 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

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.

Prose documentation lives in `docs/` and is **published** to
<https://docs.lyrapup.pet/nixfiles/> by the separate `docs-site` repo, which
clones this one at build time. Two consequences when editing docs:

- A markdown file outside `docs/` (other than the root `README.md`) is not
  synced and will never appear on the site. Put new prose in `docs/`.
- Links must follow the rules in the README's "Documentation" section: absolute
  Gitea URLs to source files, relative links between `docs/` pages, and
  absolute `docs.lyrapup.pet` URLs from the root README into `docs/`. The site
  builds non-strict, so a broken link is silent.

The CI `formatting` step runs on **every** PR — including docs- and config-only
changes — so a Markdown/YAML/JSON edit is format-checked before merge, not just
after it lands on `main`. (The heavier `deadnix`/`statix`/`pre-commit` lints and
the per-host evaluation still run only when a `.nix` file, `flake.lock`, or the
workflow changed; see `.gitea/workflows/ci.yaml`.) Run `nix fmt` before you
commit and the formatting check stays green.

## 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.