diff --git a/AGENTS.md b/AGENTS.md
index e9ddb07..88b508f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,8 @@ This project uses `numtide/blueprint` which:
 - Handles formatting, checking, and devShell generation
 - Exposes `mkPackagesFor` function to build packages against any nixpkgs instance
 
+**Important**: Blueprint's package discovery reads from the git index, not the working directory. New package directories must be staged with `git add` before they appear in flake outputs. Unstaged files are invisible to `nix build`, `nix flake show`, and `nix run`.
+
 ### Two Overlay Strategies
 
 1. **`overlays.default`** - Binary-cache-friendly
@@ -159,6 +161,10 @@ When adding a new package:
    pkgs.callPackage ./package.nix { }
    ```
 
+3.5. **Stage the package**: `git add packages/<package-name>/`
+   Blueprint discovers packages from the git index, not the working directory.
+   Without this step, the package won't appear in flake outputs.
+
 4. **Test the package**:
    ```bash
    nix build .#<package-name>