# nix-overlay — core

Nix flake overlay (numtide/blueprint-based) exposing extra packages for Nix/NixOS.
Repo: `git+https://git.millerson.name/alex/millerson-overlay.nix.git`

## Source map
- `flake.nix` — inputs + outputs; blueprint drives perSystem outputs; overlays/modules added manually on top.
- `overlays/default.nix` — binary-cache-friendly: maps blueprint's pre-built `packages` under namespace `millerson-nix-overlay`.
- `overlays/shared-nixpkgs.nix` — builds `packages/` tree against consumer's `final` via `mkPackagesFor`; shares deps, cache only hits on matching nixpkgs rev.
- `packages/<name>/default.nix` + `package.nix` — every package follows this wrapper/derivation split. See `mem:conventions` for patterns.
- `packages/default/` — meta-package; generates name\tdesc list from `perSystem.self`, filtering `passthru.hideFromDocs`.
- `packages/flake-inputs/` — dummy derivation referencing all flake inputs so they get cached. `hideFromDocs = true`.
- `treefmt.toml` — nixfmt for `*.nix`, flake.lock excluded.
- `AGENTS.md` — agent workflow rules (beads tracking, mandatory skills, caveman comms).

## Project-wide invariants
- All overlay packages live under the single attrset `millerson-nix-overlay` (not top-level attrs).
- Blueprint discovers packages from the **git index**, not the working dir: new `packages/<name>/` must be `git add`-ed before `nix build .#<name>` sees it.
- Three nixpkgs inputs; some packages deliberately build against non-default ones. See pins in `mem:tech_stack`.
- Everything under `packages/` uses `pkgs.callPackage ./package.nix { }` wrapper pattern; `default.nix` receives blueprint args (pkgs, perSystem, inputs, ...).

## Task workflow (from AGENTS.md, enforced)
Runnable commands (build/format/update/bd/push): `mem:suggested_commands`. Exact done-checklist: `mem:task_completion`.


- ALL task tracking via `bd` (beads): `bd ready`, `bd update <id> --claim`, `bd close <id>`. NEVER TodoWrite/markdown TODOs.
- `bd prime` before starting work; `bd remember` for persistent knowledge (no MEMORY.md files).
- Session not complete until `git push` succeeds (`bd dolt push` skipping with "No remote is configured" is expected, not a failure).
- Commits use conventional-commit format.
- For nixpkgs/option lookups use the `nix` skill; for flake/devShell ops the `nix-flakes` skill; comms in caveman mode.