diff --git a/.gitignore b/.gitignore
index 5665e616..565334d5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 
 #while bin is primarily an output - some items here are for bootstrapping - so while they aren't the source - we install and source-control them.
 /bin/*
+!/bin/AGENTS.md
 !/bin/*.cmd
 !/bin/*.kit
 !/bin/*.tcl
diff --git a/AGENTS.md b/AGENTS.md
index c0f30483..f41c9c6b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -137,6 +137,7 @@ When the user requests a durable behavior change, record it here or in the relev
   - `src/runtime/` — Build runtimes and VFS config (see src/runtime/AGENTS.md)
   - `src/doc/` — Generated documentation (see src/doc/AGENTS.md)
   - `src/testansi/` — Sample ANSI art files (do not modify)
+- `bin/` — Built punk shell executables, launch package modes (incl. `src` mode for working-tree verification), plain runtime kits (see bin/AGENTS.md)
 - `GOALS.md` — Top-level technical goal index; required read for non-trivial work (no child AGENTS.md; the file documents its own format and the agent goal-authoring workflow)
 - `GOALS-archive.md` — One-line records of achieved goals moved out of the active index (historical context only)
 - `goals/` — Optional detail prose for goals needing more than a one-line summary (see goals/AGENTS.md)
diff --git a/bin/AGENTS.md b/bin/AGENTS.md
new file mode 100644
index 00000000..2bb98e38
--- /dev/null
+++ b/bin/AGENTS.md
@@ -0,0 +1,32 @@
+# bin/
+
+## Purpose
+
+Built punk shell executables (kits with the punk boot layer), assorted build/experiment tooling, and plain runtime kits under `runtime/`. Executables here are build outputs - agents do not hand-edit binaries.
+
+## Local Contracts
+
+### Launch package modes (built punk shells)
+
+The first argument to a built punk shell may be a dash-delimited package mode composed of tokens from `dev`, `os`, `src`, `internal` (e.g. `punksys src`, `punk902z dev-os`). `internal` is the default and is always appended when absent. A first argument that is not a valid mode list is treated as a subcommand instead. Implementation: `src/vfs/_config/punk_main.tcl` (search `all_package_modes`).
+
+`src` mode is the one that matters for verifying working-tree changes:
+
+- Discovers the project root from the executable's location (exe in `bin/` -> parent directory), not from the cwd - it works from any working directory as long as the executable resides in the project's `bin/`.
+- Prepends `src/modules`, `src/modules_tcl<N>`, `src/bootsupport/modules{,_tcl<N>}` and `src/vendormodules{,_tcl<N>}` to the module path, sets `package prefer latest` so dev-numbered `999999.0a1.0` source modules beat kit-stamped snapshots on unversioned `package require`, and registers `#modpod` modules from `src/modules` (startup notice: `src mode: registered N #modpod modules from .../src/modules`).
+- Consequence: `punksys src` / `punk902z src` exercises current working-tree source with no kit rebuild; a plain launch (`punksys`) exercises the module snapshots baked into the kit at build time. `package present <pkg>` reporting `999999.0a1.0` (vs a release version like `0.7.1`) tells you which set a session is running - runbooks with version expectations must state the intended launch mode.
+
+### Interactive verification shells
+
+- Interactive console/repl verification should cover both Tcl generations - behaviour can differ materially (e.g. the Tcl 8.6 windows console channel driver vs the Tcl 9 rewrite). Use a Tcl 8.6-based punk shell (`punksys.exe`) and a current Tcl 9-based punk shell (named for the Tcl release it embeds, e.g. `punk902z.exe` at the time of writing - ask the user which is current rather than assuming). `info patchlevel` in-session confirms the runtime.
+- `runtime/win32-x86_64/` holds plain tclkits/tclsh runtimes without the punk boot layer - use these for clean-environment probes isolating Tcl-level behaviour from punk (they may lack extensions such as twapi; add an external lib dir to `auto_path` when a probe needs one).
+
+## Work Guidance
+
+## Verification
+
+None - build outputs; behaviour is verified via `src/tests/` and interactive runbooks.
+
+## Child DOX Index
+
+- `runtime/win32-x86_64/` - plain runtime kits (no child AGENTS.md needed; covered by this file's contracts)