nix-playgraound/AGENTS.md

# AGENTS.md

This file provides guidance to coding agents collaborating on this repository.

## Mission

`nix-playground` is a personal learning playground for Nix and flakes.
 The goal is not production software but clear, runnable, progressively more advanced examples plus prose notes that explain them.

Priorities, in order:

1. Correctness: examples must actually evaluate and build.
2. Clarity: each example teaches one concept; names, comments, and directory structure should make that concept obvious.
3. Minimality: prefer the shortest flake or expression that demonstrates the idea.
4. Accuracy of notes: prose under `notes/` must not describe behavior the examples do not demonstrate.
5. Reproducibility: every flake commits its `flake.lock`; nothing depends on ambient state.

## Core Rules

- Use English for code, comments, and prose.
- Keep each numbered example self-contained: its own `flake.nix`, own `flake.lock`, no cross-example imports.
- Prefer small, focused changes over broad rewrites across examples.
- Add comments only when they clarify non-obvious Nix behavior (laziness, `rec`, string vs. path, `with` scoping, etc.).
- Do not describe Nix features in notes or comments as if they were implemented in an example unless the example actually uses them.
- When an example grows beyond one concept, split it into a new numbered directory rather than expanding the existing one.

Quick examples:

- Good: add `03-multi-system/` that demonstrates `forAllSystems` in isolation.
- Good: add a `checks` output to an existing flake with a one-line comment explaining what `nix flake check` will do with it.
- Bad: combine overlays, NixOS modules, and home-manager into one "comprehensive" example.
- Bad: edit `notes/` to describe an approach no example in the repo uses.

## Writing Style

- Use Oxford commas in inline lists: "a, b, and c" not "a, b, c".
- Do not use em dashes. Restructure the sentence, or use a colon or semicolon instead.
- Avoid colorful adjectives and adverbs. Write "dev shell" not "lightweight dev shell", "overlay" not "flexible overlay".
- Use noun phrases for checklist items, not imperative verbs. Write "input pinning" not "pin inputs".
- Headings in Markdown files must be in title case: "Build from Source" not "Build from source". Minor words (a, an, the, and, but, or, for, in, on, at, to, by, of) stay lowercase unless they are the first word.

## Repository Layout

- `01-devshell/`, `02-*/`, `NN-<topic>/`: self-contained numbered examples. Each directory is a flake root.
- `notes/`: prose companions numbered to match reading order.
    - `001-glossary.md`: vocabulary reference.
    - `002-nix-primer.md`: the Nix language and store model.
    - `003-flakes.md`: flake anatomy, schema, and common patterns.
- `Makefile`: discovery-based helpers that run formatting, linting, and `nix flake check` across all examples.
- `AGENTS.md`: this file.
- `.pre-commit-config.yaml`, `.editorconfig`, `.gitattributes`, `.gitignore`: repository hygiene.
- `pyproject.toml`: Python environment metadata used only to install `pre-commit`.

New examples follow `NN-<short-topic>/` where `NN` is a two-digit ordinal. Topics grow roughly from simpler to more involved: dev shell, package, multi-system, NixOS module, home-manager, overlay.

## Example Layout Constraints

- Each example owns exactly one `flake.nix` at its root and commits its `flake.lock`.
- Examples do not import each other. Copy and adapt if a pattern needs to be shown twice.
- An example may depend only on flakes it declares in its own `inputs`.
- Prefer `nixpkgs` pinned to `nixos-unstable` for consistency across examples unless the example's point is pinning strategy.
- Keep the `outputs` attrset flat enough that `nix flake show` reads as a single screen.
- If an example exposes `checks.<system>.*`, those checks must pass under `nix flake check`.

## Nix and Flake Conventions

- Target Nix with `experimental-features = nix-command flakes` enabled (already the case on this machine).
- Prefer `pkgs.mkShell` for dev shells; reach for `mkShellNoCC` only when explaining the distinction.
- Use `nixpkgs.lib.genAttrs` or `flake-utils.lib.eachDefaultSystem` for multi-system outputs; pick one per example and say which in a comment.
- Use `follows` to unify transitive `nixpkgs` inputs when pulling in ecosystem flakes.
- Prefer `inherit` over repetition in attrsets.
- Avoid top-level `with` statements; keep `with` narrowly scoped to package lists.
- Format every `.nix` file with `nixfmt` (RFC 166 style) before committing.

## Required Validation

Run these checks for any non-trivial change:

1. `make fmt-check`
2. `make lint`
3. `make check`

These map to `nixfmt --check`, `statix check` plus `deadnix`, and `nix flake check` across every numbered example.

For notes-only changes, `make fmt-check` and a manual read-through suffice.

## First Contribution Flow

Use this sequence for your first change:

1. Read the relevant `notes/` file and the nearest existing example.
2. Add the smallest possible flake or expression demonstrating the new concept.
3. Add a short header comment in the new `flake.nix` stating what the example teaches.
4. Run `nix flake check` inside the new example directory.
5. Run `make fmt-check` and `make lint` from the repository root.
6. Add or update the matching entry in `notes/` if the concept is not yet covered there.

Example scopes that are good first tasks:

- Add `02-package/` with a trivial `stdenv.mkDerivation` and one-line install phase.
- Add a `checks` output to `01-devshell/` that asserts a tool is on `$PATH`.
- Add a short section to `notes/003-flakes.md` referencing a newly added example.
- Convert an existing example from a hand-rolled `forAllSystems` to `flake-utils`, or vice versa, with a comment explaining the tradeoff.

## Testing Expectations

- This repository has no runtime test suite; "tests" are `nix flake check` outcomes and successful builds of each example's default output.
- Any example that exposes non-trivial behavior (a derivation, a module) should expose a `checks.<system>.*` attribute that `nix flake check` exercises.
- Do not merge changes that regress `make check`.

## Change Design Checklist

Before coding:

1. Identify which existing example or notes file the change belongs to, or whether it needs a new `NN-<topic>/`.
2. Confirm the change teaches one concept, not several.
3. Confirm `nixpkgs` input choice is consistent with surrounding examples.

Before submitting:

1. Verify `make fmt-check`, `make lint`, and `make check` pass.
2. Verify every modified flake's `flake.lock` is committed.
3. Verify `notes/` accurately reflects what the examples now demonstrate.

## Review Guidelines (P0/P1 Focus)

Review output should be concise and only include critical issues.

- `P0`: must-fix defects (a flake fails to evaluate, an example documents the wrong mechanism, notes contradict the code).
- `P1`: high-priority defects (eval warnings, missing `flake.lock`, unpinned or inconsistent inputs, misleading comment).

Do not include:

- style-only nitpicks,
- praise or summary of what is already good,
- exhaustive restatement of the patch.

Use this review format:

1. `Severity` (`P0`/`P1`)
2. `File:line`
3. `Issue`
4. `Why it matters`
5. `Minimal fix direction`

## Practical Notes for Agents

- Prefer targeted edits over broad mechanical rewrites across examples.
- If two examples disagree on a convention, prefer the newer one and update the older example in a dedicated commit.
- When uncertain whether a concept deserves its own example, start by expanding the notes; promote to an example once the idea stabilizes.
- Keep presentational prose in `notes/`. Keep runnable material in numbered directories. Do not cross the streams.
- Keep user-facing naming consistent with the repository name: `nix-playground`. The directory spelling `nix-playgraound` is intentional and should not be "fixed".

## Commit and PR Hygiene

- Keep commits scoped to one logical change: one example, one notes update, one convention shift.
- Commit `flake.lock` in the same commit that introduces or updates the `flake.nix` it belongs to.
- PR descriptions should include:
    1. what concept the change teaches or clarifies,
    2. which example directories or notes files are affected,
    3. any new `inputs` added and why,
    4. output of `make check` (pass/fail).

Suggested PR checklist:

- [ ] `make fmt-check` passes
- [ ] `make lint` passes
- [ ] `make check` passes
- [ ] `flake.lock` committed for every new or updated `flake.nix`
- [ ] Notes updated where the change introduces or changes a concept