# 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.

### Generated polyglot .cmd scripts - never edit in place

The `.cmd` scripts here (e.g `punk-runtime.cmd`) are punk MULTISHELL polyglots GENERATED by
`punk::mix::commandset::scriptwrap::multishell` from scriptset sources under
`src/scriptapps/bin/` (the home for bin-deployed scriptsets, e.g `punk-runtime.*` alongside
`punk-getzig.*`) or `src/scriptapps/` itself (e.g `punk-tclargs.*`, `dtplite.*`): payload scripts
(`<name>.ps1`, `<name>.bash`, `<name>.tcl`, ...) plus a `<name>_wrap.toml`
config, spliced into the `punk.multishell.cmd` template. The polyglot structure is
deliberately fragile (mutual shell-hiding tricks, LF-only endings, cmd.exe's 512-byte
label-scanner constraints) - a hand-edit can silently break one of the participating
shells.

When asked to "fix bin/<name>.cmd":
1. Edit the payload/config sources under `src/scriptapps/bin/` (never the output file).
2. Re-wrap from the scriptset's folder: cd `src/scriptapps/bin` then
   `punk::mix::commandset::scriptwrap::multishell <name> -askme 0`
   (output defaults to `<projectroot>/bin`; requires Thread + the punk::mix modules, e.g
   a punk shell or a tclsh with project module paths).
3. The wrapper runs `checkfile` (the 512-byte label/boundary validator) automatically -
   heed ERROR output; "possibly bogus target" warnings are normal for polyglots. Payload
   growth can push a TEMPLATE label beyond the payloads (e.g `:exit_multishell`) across a
   512-byte boundary: fix by resizing the byte-alignment spacer comment at the end of the
   affected payload (see the `(512B spacer)` comment in `punk-runtime.bash`) and re-wrapping
   until checkfile is ERROR-free.
4. Commit source AND regenerated output together: the scriptwrap test suite pins that a
   re-wrap of the punk-runtime scriptset reproduces `bin/punk-runtime.cmd` byte for byte
   (`src/tests/modules/punk/mix/testsuites/scriptwrap/runtimecmd_roundtrip.test`
   scriptwrap_runtime_cmd_roundtrip_no_drift), so drift in either direction fails tests.
   `bin/dtplite.cmd` is pinned the same way
   (`src/tests/shell/testsuites/binscripts/dtplite.test` dtplite_cmd_roundtrip_no_drift).

### dtplite (`dtplite.cmd`)

`bin/dtplite.cmd` wraps tcllib's dtplite doctools processor (payload
`src/scriptapps/dtplite.tcl`, tclsh nextshell on all platforms). It exists so the punk
repl's unknown-handler can resolve the bare `dtplite` command via PATH - `dev
doc.validate` (punk::mix::commandset::doc) depends on it. The payload falls back to the
project-vendored tcllib (`src/vendorlib_tcl9/<arch>/tcllib*`) when the invoking tclsh
has no dtplite package installed.

## Local Contracts

### Utility naming policy: punk- prefix (G-096)

Punkshell-own utilities deployed to `bin/` take a `punk-` name prefix (e.g
`punk-getzig`) so a user who adds `<project>/bin` to their PATH gets
collision-resistant names. Exceptions: wrappers whose purpose is to present an
external tool under its own name (`dtplite`, `sdx`, `kettle`), and `getpunk`
(already punkshell-specific; intended future single-download cross-platform entry
point). Policy decided by the user 2026-07-20 (G-096); the remaining pre-policy names
were swept under G-097 (2026-07-21): `punk-bits`, `punk-runtime`, `punk-tclargs` and the
punk- prefixed selfsign experiment scripts. Where launchability convenience warrants it a `.ps1` twin of the generated
`.cmd` ships alongside (windows users may start from cmd.exe or powershell); the twin
is a byte-copy under the other extension - refresh both on re-wrap.

### 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.

### Runtime fetch/selection (`punk-runtime.cmd`)

`bin/punk-runtime.cmd {fetch|list|use|run}` manages the plain runtimes under
`bin/runtime/<platform>/` (retrieved from the punkbin artifact repo with sha1
verification against its `sha1sums.txt` - both the powershell payload on windows and the
bash payload on unix verify; a fetch whose checksum fails leaves only a `.tmp`).
`list -remote` compares local runtimes against the server's sha1sums (Same version /
UPDATE AVAILABLE / not-listed, plus remote-only entries; the bash payload falls back to
a cached sha1sums.txt with a warning when the server is unreachable). The artifact
server base url is overridable via `PUNKBIN_URL` (mirrors/testing) in both payloads.
Which runtime `run` launches is the per-machine "active" selection in
`bin/runtime/<platform>/active.toml` (constrained single-key toml `active = "<name>"`,
written by `punk-runtime.cmd use <name>`, marked in `list`, VCS-ignored via the existing
`bin/*` globs). Resolution order for `run`: `PUNK_ACTIVE_RUNTIME` env override, then
`active.toml`, then a sole installed candidate - with multiple runtimes and no selection
it errors listing candidates rather than guessing. The first `fetch` sets the active
runtime only when none is recorded.

G-103 runtime-family artifact metadata (both payloads): a runtime may carry a
`<rootname>.toml` metadata record beside it (emitted by the suite_tcl90
`kit-family-artifacts` step; fetched from punkbin alongside `-r<N>`-named artifacts -
absence tolerated for pre-family runtimes). `list` shows a per-runtime summary from it
(variant, tcl patchlevel, revision, piperepl policy, and - on a materialized working
copy - which immutable artifact it came from). `use <artifact-r<N>-name>` MATERIALIZES
the immutable artifact into its WORKING name (the name minus `-r<N>` - what mapvfs and
projects reference), copies the metadata toml alongside, and selects the working name;
`use <workingname>` selects as before. Root-name handling strips only a `.exe` suffix
(dotted tcl patchlevels make generic last-dot stripping wrong for extensionless unix
names). Candidate listing excludes directories and `.txt/.toml/.tm/.tmp/.log` files.

Cross-platform surface (G-105 groundwork; both payloads): `fetch`/`list`/`use` accept
`-platform <p>` where `<p>` is a punkbin platform-DIR name (`win32-x86_64`,
`linux-x86_64`, `macosx`, ... - never zig triples; the buildsuite maps triples to
platform dirs at build time). Resolution: `-platform` arg > `PUNK_RUNTIME_PLATFORM`
env > the detected local platform; validation is shape-only, lowercase (the artifact
server's URL paths are case-sensitive - the server is the truth for what exists).
Foreign-platform folders serve cross-build staging/provisioning: a foreign `fetch`
requires an explicit runtime name (no foreign defaults), `use -platform` manages that
folder's `active.toml`/materialization (the marker travels with the folder when
deployed; unix exec bits are restored at deploy time), and `list` flags a runtime
whose metadata `target` disagrees with the folder it sits in (`!TARGET-MISMATCH`).
`run` is LOCAL ONLY - it rejects a leading `-platform` and ignores the env override
(later `run` args pass through to the runtime untouched). A no-args invocation prints
a short usage block; the `help` action gives the full operator reference (actions,
options, env vars incl `PUNKBIN_URL`, examples). Platform names follow the CANONICAL
punkshell platform-dir names defined by the `punk::platform` module and surfaced as
`help platforms` in the punk shell (cpu tokens normalized: amd64->x86_64,
aarch64->arm64; the bash payload's local-platform prongs emit canonical names - the
FreeBSD dir was realigned from `freebsd-amd64` to `freebsd-x86_64` accordingly).

### 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)