# Nix agent lab

Companion starter for https://courses.thefocus.ai/nix-agent-lab/.

Read and execute the course gates in order. This directory is a starter, not a pre-locked release: generate and commit devenv.lock in Chapter 02. Preserve that lock on subsequent machines. No model or cloud credentials are included.

## Stages

1. Install Nix/devenv and create a learning Git repository.
2. Start with the small environment in Chapter 02 and generate the lock.
3. Copy taskboard.py, tests/, exercises/, scripts/, and the full devenv.nix. Run devenv test: six unit tests plus formatting/lint should pass. The completion feature is intentionally missing.
4. Add `imports = [ ./postgres.nix ];` to devenv.nix after copying postgres.nix. Run devenv test twice: it starts PostgreSQL and runs the transaction check. The SQL check is separate from the Python library; no application persistence is implied.
5. Follow the tasks and optional direnv gate.
6. Copy AGENTS.md, specs/, IMPLEMENTATION_PLAN.md and PROMPT.md. Copy exercises/test_completion.py to tests/ and add an owner-written extra-field-preservation test. This is an intentionally failing exercise baseline; commit it on a learning branch.
7. Pin and build the agent CLI as documented; run a supervised change. Review before committing.
8. Read scripts/loop.py. It is a teaching controller, not an OS security boundary. Run only after the disposable VM gate in Chapter 09, with scoped credentials and external teardown. Never run it merely by setting its acknowledgement environment variable on your ordinary laptop.
9. Compare the reviewed green commit and lock on Mac and Linux, then add CI.
10. Lock and run nixos/flake.nix on x86 Linux with KVM. It tests Nginx across two VMs, separately from the Python project.

## Validation scope

The starter's Python tests and controller failure paths can be tested without Nix or paid calls. Nix evaluation, PostgreSQL lifecycle, cloud parity, and NixOS boot require their actual runtimes. A website build does not establish those results. Record source, lock, host, CLI versions, command, exit status, and observed output at each gate.

Ignore .agent-cli, logs, .env files, and generated runtime state. Commit actual lockfiles and the reviewed agent revision. Read every script and dependency trust prompt before execution.