Nix Manager

Outcome

Keep this repository's Nix package profile reproducible across macOS, Ubuntu, Fedora, and Linux/WSL. The repository defines the package closure; Nix profile state is a user-owned result of the supported setup flow.

Route First

Use $dotfiles-operations for every repository Nix task. Add the matching specialist when the task crosses one of these boundaries:

• $nix-update for any flake.lock update or package-version comparison.
• $cross-platform-guardian for bootstrap, package, platform, or profile behavior that can differ across supported systems.
• $config-change for a configuration change that also needs a package.

Do not treat this skill's examples as a substitute for the current flake.nix, Makefile, or operations validation matrix.

Inspect

Before changing Nix-owned files, read the current flake.nix, Makefile, and the relevant module under src/dotfiles_setup/. Inspect the worktree first:

git status --short
git diff -- flake.nix flake.lock

For a live profile, installation, or verification request, also inspect the supported state rather than ambient PATH:

./bootstrap.sh doctor
./bootstrap.sh verify
nix profile list --json

Boundaries

• flake.nix is the source of package selection and declared systems; flake.lock pins its inputs.
• bootstrap.sh is the only root setup entry point. Profile installation and upgrade use ./bootstrap.sh profile; normal consumers keep committed locks unchanged.
• make update is the explicit all-input update path. It is the only normal workflow here that changes flake.lock; use $nix-update before running it.
• nix profile rollback is the recovery path for an already-applied profile generation. It is a user-state mutation and requires explicit authority.
• Read the actual flake input when its branch, package version, or supported output matters. Do not encode a copied branch name or package inventory in agent guidance.

Workflows

Package change

1. Edit only flake.nix, retaining its existing package grouping and supported systems. Do not update flake.lock for a package-list change.

2. Run make test-pre, then make test-eval for the four-system contract.

3. After authority to mutate the user profile, run:

   ./bootstrap.sh profile
   ./bootstrap.sh verify
   

4. Report evaluation evidence separately from installed-profile and platform evidence.

Input update

Use $nix-update. It owns the lock diff, package-version comparison, and validation sequence. Run make update only for an explicit update request; then verify the profile and confirm no unrelated lockfile changed.

Diagnosis

Start at the first failed boundary: pending recovery or mutation lock, Nix availability, exact profile origin, profile store outputs, then managed links. Use ./bootstrap.sh recover only to inspect; applying recovery needs explicit authority. Do not repair an exact-profile failure by changing the global Nix configuration or trusting a binary found on ambient PATH.

Validation and Handoff

Use the validation matrix in $dotfiles-operations; Nix package or system changes require make test-pre and make test-eval. Cross-platform bootstrap work also requires Docker and affected-platform evidence. Before finishing:

git diff --check
git diff --exit-code -- flake.lock uv.lock
git status --short

Report the files changed, lockfile intent, commands and results, platform evidence, profile/recovery state, rollback path, and commit/push status.

References

• Repository architecture and the validation matrix: $dotfiles-operations.
• Advanced Nix language patterns and standalone-project examples: REFERENCE.md. They are not the dotfiles repository contract; load them only when the current flake and operations guidance do not answer the Nix-language question.