add bin/AGENTS.md: launch package modes (src mode) and verification-shell contracts

The dash-delimited launch package modes of built punk shells (dev/os/src/
internal, implemented in src/vfs/_config/punk_main.tcl) had no agent-facing
record. bin/AGENTS.md now documents the mode grammar and, in operational
terms, the src mode that matters for verifying working-tree changes:
exe-location-based project-root discovery, the source module paths it
prepends, package prefer latest (dev 999999.0a1.0 modules beating
kit-stamped snapshots), and how 'package present' distinguishes a src-mode
session from a plain kit launch. Also records the both-Tcl-generations
interactive verification convention (a Tcl 8.6-based shell plus the current
Tcl 9-based incarnation, deliberately not version-pinned) and the role of
the plain runtime kits under bin/runtime/ for punk-free probes.

Root AGENTS.md Child DOX Index gains the bin/ entry, and .gitignore gains
a !/bin/AGENTS.md negation alongside the other source-controlled bin items
(the /bin/* ignore is why no doc lived there before).

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

.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

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)

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)