From 640d53f7cb3e096246a5b8b9650f92149ffd7232 Mon Sep 17 00:00:00 2001
From: Julian Noble <julian@precisium.com.au>
Date: Wed, 22 Jul 2026 14:44:34 +1000
Subject: [PATCH] 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 | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

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`).