diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..86d80e5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+# Flakebox agent notes
+
+## What this repo is
+
+- Flakebox is a Nix-based Rust dev-env toolkit.
+- Main library/codegen lives in `lib/`.
+- CLI lives in `flakebox-bin/`.
+- User docs live in `docs/`.
+- Example/template project lives in `templates/default/`.
+- Nix checks/examples for library behavior live in `checks/`.
+
+## Best entry points
+
+- `flake.nix` — top-level outputs, dev shells, package wiring.
+- `lib/default.nix` — evaluates modules, builds docs/options, exposes `flakeboxLib`.
+- `lib/modules/*.nix` — NixOS-style config surface and generated root files.
+- `lib/mkDevShell.nix` — dev-shell assembly and shellHook sourcing.
+- `lib/modules/rootDir.nix` + `lib/modules/env.nix` — generated repo files and shell hook script.
+- `flakebox-bin/src/main.rs` — `flakebox` CLI commands like `install`, `init`, `lint`.
+
+## Generated files: do not edit directly
+
+- `README.md` is generated from `docs/README.md`.
+- `justfile` is generated from flakebox config.
+- `.config/flakebox/*` is generated by flakebox.
+- `docs/nixos-options.md` is generated from module options.
+
+When changing generation logic, edit the source files in `lib/` or `docs/`, then regenerate.
+
+## Regeneration commands
+
+- After changing generated root files or shell hooks: `nix develop -c flakebox install`
+- After changing module options/docs: `nix build .#docs && cp result/nixos-options.md docs/nixos-options.md`
+- If formatting fails: `nix develop -c treefmt`
+
+## Validation
+
+- Before committing, run: `nix develop -c selfci check`
+- This repo enforces formatting in CI/local CI.
+- If `flakebox install` says files are stale, regenerate before finishing.
+
+## Common modification map
+
+- Add/change flakebox config options: `lib/modules/*.nix`
+- Change shell startup behavior: usually `lib/modules/*.nix`, `lib/modules/env.nix`, or `lib/mkDevShell.nix`
+- Change generated docs/options behavior: `lib/default.nix` and module option declarations
+- Change CLI behavior/messages: `flakebox-bin/src/*.rs`
+- Change template defaults for new users: `templates/default/`
+
+## Practical gotchas
+
+- `justfile` changes usually come from `lib/modules/just.nix`, not editing `justfile`.
+- Shell-hook output should avoid noisy non-interactive runs.
+- Keep checked-in generated files in sync with code changes.
+- `README.md` edits belong in `docs/README.md`, not the generated file.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file