# nix-overlay — package conventions

## Directory pattern (every package)
`packages/<name>/default.nix` (wrapper, receives blueprint args) + `packages/<name>/package.nix` (the derivation, `pkgs.callPackage`-style argsets).

Wrapper variants:
- Plain: `{ pkgs, ... }: pkgs.callPackage ./package.nix { }`
- Needs blueprint extras: pass `perSystem`, `inputs`, etc. through explicitly.
- Alternate nixpkgs (freetoken): wrapper ignores `pkgs` for the derivation and calls `inputs.nixpkgs-torch211.legacyPackages.${pkgs.stdenv.hostPlatform.system}.callPackage ./package.nix { }`.

## Derivedivation requirements
- Use `stdenv.mkDerivation rec { pname; version; }` or `rustPlatform.buildRustPackage` (Rust: `cargoHash`; Go/Python equivalents as needed).
- `meta.description` required (feeds the default meta-package listing).
- `meta.mainProgram` set for CLI-providing packages.
- Organizational attrs via `passthru`: `category` (e.g. "AI Coding Agents"), `hideFromDocs = true` to exclude from docs listing.
- No `with pkgs;` at top level of Nix files (scope issues).
- No hardcoded system paths/system assumptions.

## Adding a package (sequence)
mkdir → package.nix → default.nix wrapper → `git add packages/<name>/` (required for blueprint discovery) → `nix build .#<name>` → update README Available Packages table → commit (conventional-commit format).

## Naming
- Package dir name = flake output attr name (kebab-case).