nix-manager

name	nix-manager
description	Manage Nix package, profile, flake, and diagnostic work in this dotfiles repository. Use when changing flake.nix, troubleshooting Nix, applying profile changes, or explaining the locked Nix setup.

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.