bin/AGENTS: record .cmd-extension invocation guideline for future user-facing docs

User policy 2026-07-22: doc examples for the polyglot bin utilities show
the .cmd extension (bin/punk-runtime.cmd ...) - extensionless windows
invocation resolves the .ps1 twin, which is ExecutionPolicy-gated and
runs under the invoking powershell edition, while .cmd always executes
via the wrap-pinned tested path. The same .cmd file runs on unix shells
unmodified, so one form serves all platforms with path-separator style
as the only remaining per-platform difference. Sweep confirmed no
existing user-facing guidance contradicts (none exists yet).

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

bin/AGENTS.md

@@ -71,6 +71,20 @@ by the wrap toml (`cmd.exe /c powershell` = Windows PowerShell) - payload code m
 be edition-portable and avoid implementation-defined behaviour (e.g. Hashtable
 enumeration order differs between the editions; sort explicitly).
 
+INVOCATION GUIDELINE for user-facing documentation (user policy 2026-07-22; no
+user-facing guidelines existed yet when recorded - apply to all future README/help/
+doc examples involving the polyglot `bin/*.cmd` utilities): show invocations WITH
+the `.cmd` extension, e.g. `bin/punk-runtime.cmd list`, even though extensionless
+invocation happens to work on windows in some cases. Rationale: extensionless
+resolution in powershell prefers the `.ps1` twin, whose direct execution is
+ExecutionPolicy-gated (Restricted/AllSigned hosts fail) and runs under the invoking
+edition, whereas the `.cmd` always executes and follows the wrap-pinned, policy-
+bypassing tested path. The SAME `.cmd` file also runs on unix shells (the polyglot
+needs no extension stripping - `./bin/punk-runtime.cmd` from bash/zsh, or
+`bash bin/punk-runtime.cmd`), so one form serves all platforms and the only
+platform-specific difference left in examples is path separator style
+(`bin/punk-runtime.cmd` vs `bin\punk-runtime.cmd`).
+
 ### 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`).