# Repository Instructions

## Configuration Boundaries

- `flake.nix` exposes one `x86_64-linux` system: `chi`, the Framework 12 desktop/laptop. The Strix Halo server (`halo`) is managed by the separate `~/halo-nixos` flake — do not deploy this repository to halo.
- `modules/common.nix` and `home/` belong to chi; `hosts/chi/` owns the Framework 12 config.
- `hosts/*/hardware-configuration.nix` is generated by `nixos-generate-config` and deliberately excluded from treefmt. Keep it byte-identical unless the hardware configuration itself must change.
- `system.stateVersion` and `home.stateVersion` are compatibility pins, not release-version markers. Do not bump them during routine input updates.

## Verification

- Format and lint with `nix fmt`, then run `nix flake check`. The formatter is treefmt with Alejandra, Statix, and deadnix.
- `nix flake check` only runs the formatting check; CI separately evaluates the full chi config with `nix eval --raw .#nixosConfigurations.chi.config.system.build.toplevel.drvPath`.
- Evaluate chi after changing `flake.nix`, `flake.lock`, `modules/common.nix`, or shared inputs.
- Update inputs deliberately with `nix flake update`; review `flake.lock`, then rerun formatting, flake check, and the chi evaluation before deployment.

## Secrets And Packages

- Only encrypted SOPS YAML belongs under `secrets/`; never store plaintext there. Halo's secrets now live in `~/halo-nixos`; anything under `secrets/` here is legacy.
- Locally packaged software lives under `pkgs/`.

## Deployment

- Do not run activation commands unless deployment was explicitly requested. Use `build` or `dry-activate` instead of `switch` for a preview.
- Deploy chi locally with `sudo nixos-rebuild switch --flake .#chi`.