punkshell/bin/AGENTS.md

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)