Initialize Nix overlay repository with blueprint, goose-cli, and docs

Add the complete overlay structure using numtide/blueprint with:
- Two overlay strategies (default and shared-nixpkgs)
- goose-cli package with custom librusty_v8 fetcher
- Interactive package launcher via fzf
- Flake input caching utility
- Comprehensive README and AGENTS.md documentation

README.md

@@ -1,2 +1,127 @@
-# nix-overlay
+# millerson.name Nix Overlay
 
+A custom Nix overlay and flake providing additional packages not found in upstream nixpkgs, built using [numtide/blueprint](https://github.com/numtide/blueprint) for streamlined flake development.
+
+## Features
+
+- **Custom packages** - Additional software packaged for Nix
+- **Two overlay strategies** - Choose between binary-cache-friendly or dependency-sharing overlays
+- **Blueprint-based** - Uses modern Nix flake patterns with `numtide/blueprint`
+
+## Available Packages
+
+| Package | Description | Category |
+|---------|-------------|----------|
+| `goose-cli` | CLI for Goose - a local, extensible, open source AI agent that automates engineering tasks | AI Coding Agents |
+
+## Usage
+
+### As a Flake
+
+Add to your `flake.nix` inputs:
+
+```nix
+inputs.millerson-nix-overlay.url = "git+https://git.millerson.name/alex/millerson-overlay.nix.git";
+```
+
+Then use in your outputs:
+
+```nix
+outputs = { nixpkgs, millerson-nix-overlay, ... }: {
+  nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
+    system = "x86_64-linux";
+    modules = [
+      millerson-nix-overlay.nixosModules.default
+      # ... your other modules
+    ];
+  };
+};
+```
+
+### As an Overlay
+
+#### Option 1: Default Overlay (Binary Cache Friendly)
+
+Uses the packages built against this flake's nixpkgs revision. Binary cache hits work best when using the same nixpkgs revision.
+
+```nix
+nixpkgs.overlays = [ millerson-nix-overlay.overlays.default ];
+```
+
+#### Option 2: Shared Nixpkgs Overlay (Dependency Sharing)
+
+Builds packages against your system's nixpkgs, sharing dependencies with the rest of your system. No second nixpkgs evaluation, but binary cache only hits when your nixpkgs revision matches ours.
+
+```nix
+nixpkgs.overlays = [ millerson-nix-overlay.overlays.shared-nixpkgs ];
+```
+
+### Installing Packages
+
+With flakes enabled:
+
+```bash
+# Try a package
+nix run git+https://git.millerson.name/alex/millerson-overlay.nix.git#goose-cli
+
+# Install permanently
+nix profile install git+https://git.millerson.name/alex/millerson-overlay.nix.git#goose-cli
+```
+
+## Development
+
+### Prerequisites
+
+- Nix with flakes enabled
+- [treefmt-nix](https://github.com/numtide/treefmt-nix) for formatting (optional)
+
+### Building Packages
+
+```bash
+# Build all packages for current system
+nix build .#packages
+
+# Build specific package
+nix build .#goose-cli
+
+# Enter development shell
+nix develop
+```
+
+### Project Structure
+
+```
+nix-overlay/
+├── flake.nix                    # Flake definition
+├── overlays/                    # Overlay implementations
+│   ├── default.nix             # Binary-cache-friendly overlay
+│   └── shared-nixpkgs.nix      # Dependency-sharing overlay
+├── packages/                    # Package definitions
+│   ├── default/                # Meta-package listing all packages
+│   ├── goose-cli/              # Goose CLI package
+│   └── flake-inputs/           # Utility for caching flake inputs
+└── README.md
+```
+
+### Adding New Packages
+
+1. Create a new directory under `packages/<package-name>/`
+2. Add a `package.nix` with the package definition
+3. Create a `default.nix` that imports `package.nix` with proper arguments
+4. The package will be automatically picked up by blueprint
+
+Example structure:
+
+```
+packages/my-package/
+├── default.nix    # Import wrapper
+└── package.nix    # Actual package definition
+```
+
+## License
+
+See [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.