diff --git a/bin/AGENTS.md b/bin/AGENTS.md
index 4117cba6..4bb815b6 100644
--- a/bin/AGENTS.md
+++ b/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`).