punkshell/src/AGENTS.md

src — Source Tree Root

Purpose

The source tree root contains all editable source code, build scripts, test suites, VFS payloads, vendor dependencies, and documentation. This is the primary development area.

Ownership

• The src/ tree is where agents perform development work.
• Generated/output directories at the project root (modules/, lib/, lib_tcl8/, lib_tcl9/, modules_tcl8/, modules_tcl9/) are build targets — agents must not directly modify them.
• VFS payloads, runtime mappings, vendored dependencies, generated docs, and entry-point scripts have child AGENTS.md files with local ownership rules.

Local Contracts

• make.tcl is the primary build entry point: tclsh src/make.tcl <command>.
• The build system handles bootstrap loading, version assignment, module/library packaging, and VFS packaging.
• Shell launcher entry points include tclsh src/make.tcl shell, built launchers under the project bin/ directory, scripts sourced from src/scriptapps/, and executable entry scripts under src/vfs/_config/.
• Tcl 8.6+ is required and Tcl 9.0 is supported; gate 9.0-specific behavior behind version checks or existing punk::lib::compat helpers.
• Primary target is Windows (win32-x86_64); Linux, macOS, and FreeBSD are secondary targets.
• Tcl linting is available only through the VS Code Tcl lint plugin configured by tclint.toml; do not try to run tclint or tcllint as shell commands, except at explicit user request.
• Lint coverage is .tcl and .tm; extend config if new Tcl-related extensions appear.
• Shared Tcl source formatting defaults are a 400-character line cap, no more than 10 consecutive blank lines, 4-space indentation, and no tabs except inside string literals.
• Source priority for editable modules: src/modules/ > src/modules_tcl<major>/ > bootsupport > VFS > built > installed.
• Source priority for editable libraries: src/lib/ > src/lib_tcl<major>/ > vendorlib > VFS > built > installed.
• Treat pkgIndex.tcl as a loader map unless the task is about package loading or registration.
• Prefer vendored dependencies under src/vendor* before fetching new dependencies.
• Guard optional compiled extensions such as twapi or tdom with fallback behavior or actionable messages.

File Resolution Policy

Use the strongest available anchor first and do not broaden scope until that anchor is checked.

Treat active-editor anchors in source-derived or generated trees as ambiguous unless the user explicitly named that path. In particular, confirm the intended target before editing files opened under src/bootsupport/, root modules/, root lib/, modules_tcl8/, modules_tcl9/, lib_tcl8/, or lib_tcl9/; for generic module/library work, the usual target is src/modules/, src/modules_tcl<major>/, src/lib/, or src/lib_tcl<major>/.

Anchor order:

1. Exact path named by the user.
2. Active editor file, when the environment provides one.
3. Exact proc, symbol, or identifier named by the user.
4. Repository naming and source-precedence rules.

Proc inspection order:

1. Read the exact file named by the user, if provided.
2. Otherwise read the active editor file, if provided and relevant.
3. Otherwise search once for the exact proc name.
4. Prefer editable source under src/modules/, src/modules_tcl<major>/, src/lib/, or src/lib_tcl<major>/.
5. If multiple matches exist, prefer the generic source tree unless version-specific behavior is relevant or only a version-specific definition exists.
6. If the best hit is pkgIndex.tcl, use it to resolve the implementation file.
7. Once the owning source file is identified, continue locally from that file.

Recovery after a wrong path guess:

• Re-check the user-provided path.
• Re-check the active editor file, if available.
• Re-check repo naming conventions.
• Use one exact symbol search instead of probing more filename variants.

Work Guidance

• Run tclsh src/make.tcl packages once after cloning to populate generated module and library assets.
• Use tclsh src/make.tcl bakehouse for full builds from a clean checkout (packages + bake; refuses uncommitted src by default - -dirty-abort 0 overrides). The deprecated project alias maps to it with a notice.
• Use tclsh src/make.tcl modules to build just the module packages.
• Use tclsh src/make.tcl libs to build just the library packages.
• Use tclsh src/make.tcl packages to build both modules and libraries.
• make.tcl colour is terminal-aware (G-113): piped/redirected runs (agent harnesses, CI, log capture) automatically produce fully ESC-free output with no caller action required - an ansistrip channel transform on stdout+stderr guarantees zero ESC bytes for every emitter, including module-side ones (punkcheck summaries, punk::args tables). Interactive terminal runs keep colour (stdout tty probe via the -winsize channel option, Tcl 8.7+/9). Precedence: NO_COLOR (any value) always suppresses colour; PUNK_FORCE_COLOR/FORCE_COLOR (value other than 0/false/no/off) re-enables ANSI on piped output; otherwise the probe decides. Tcl 8.6 terminals are auto-detected without dependencies: windows consoles via the console channel's utf-16 encoding signature (-encoding unicode - only 8.6 console channels report it; the byte-level strip transform is never pushed onto a utf-16-class channel, which it would corrupt - per-channel push, so > file from an 8.6 console wraps stdout only), and unix-class hosts (linux/WSL/mac, plus msys2/cygwin-runtime tclsh builds that report platform unix on windows) via the tty channel signature (real ttys expose -mode etc; pipes/files lack them). The force vars remain for exotic environments. stderr follows the stdout decision; make.tcl shell pops the transform (repl colour is the shell's own concern). tclsh src/make.tcl check reports the active policy (colour policy (G-113): mode=... line; modes tty|forced|nocolor|piped-plain|tcl86-plain). Pinned by src/tests/shell/testsuites/punkexe/maketclcolour.test. Agents no longer need to set NO_COLOR for captured runs (setting it remains harmless).
• Use tclsh src/make.tcl vendorupdate to refresh vendormodules from config. It warns (non-fatal) for each source project whose fossil/git checkout is dirty - vendored artifacts built from a dirty tree have no committed provenance; commit in the source project to clear the warning (enforcement policy tracked by goal G-026).
• All build/promotion commands (bakehouse, packages, modules, libs, bake, vfslibs, bin, bootsupport, vfscommonupdate) warn similarly when this project's own src/ has uncommitted fossil/git changes (dirt outside src/ is ignored). Warn-only by default EXCEPT bakehouse (aborts by default; -dirty-abort 0 overrides); pass -dirty-abort elsewhere to make the check aborting. For evaluating uncommitted source without a build, prefer <builtexe> src / <builtexe> src shell. The check is punkboot::utils::vcs_dirty_warnings (optional scope argument) loaded guardedly from bootsupport - if the snapshot is stale/missing the check degrades to a skip notice (but -dirty-abort then aborts rather than silently losing the requested strictness).
• Provenance warnings (dirty-src gate + vendorupdate source-project check) print with a plain column-0 PROVENANCE-WARNING: token (grep for it in captured build output) and are recapped at the end of the run via make.tcl's wrapped ::exit. Interactive terminal runs get a 3-second ctrl-c grace countdown before a dirty build proceeds; piped/agent runs skip it. tclsh src/make.tcl check reports the current src provenance status and what the build commands would do.
• Use tclsh src/make.tcl vfscommonupdate to rebuild _vfscommon.vfs. The REPLACE confirmation prompts on an interactive terminal; unattended/agent runs must pass -confirm 0 (with the default -confirm 1 and a piped/closed stdin, make.tcl aborts fast with guidance instead of reading stdin - do not pipe y).
• tclsh src/make.tcl workflow prints an embedded ASCII data-flow overview of the build/release workflow (release-ready command sequence, source→outputs folder flow, kit assembly, keyed notes). The text lives in ::punkboot::workflow_text in src/make.tcl - embedded rather than a data file so it travels with the make.tcl copies seeded into generated projects. Update contract (agents): whenever build data flow changes - a make.tcl subcommand added/removed/repurposed, a source or output folder added or rerouted, a propagation target added, a gate (staleness/provenance/confirm) or deploy behaviour changed - update the workflow text in the same change-set. Keep it plain ASCII, max line width 100, and preserve the RELEASE SEQUENCE / DIAGRAM / KEY-NOTES / MAINTENANCE structure; verify by running tclsh src/make.tcl workflow (and once under PUNKBOOT_PLAIN=1). Adding/changing a subcommand also means: SUMMARIES + HELPTEXTS + SUBOPTS (+ SUBGROUPS) in ::punkboot::argdoc, known_commands, the plain punkboot_gethelp text, and a project-version bump (make.tcl interface is product surface per root AGENTS.md). Layout make.tcl copies pick the change up via make.tcl bootsupport - do not hand-sync them.
• make.tcl subcommands and flags are punk::args-declared (G-030): tclsh src/make.tcl help ?subcommand? or <subcommand> -help shows tabled usage; invalid arguments produce punk::args usage errors. The dispatch degrades to plain scan/help when the bootsupport punk::args (or its rendering stack) is stale or unavailable; PUNKBOOT_PLAIN=1 forces the degraded mode for troubleshooting. The ::punkboot::argdoc definitions are constructed (string-built) and use the G-045 authoring mechanisms — block-form help values + @normalize, explicit @form -synopsis — see src/modules/AGENTS.md "punk::args definition authoring ergonomics" before editing them or authoring similar definitions.
• Uncommitted make.tcl-generated outputs may be batched into one commit, regardless of how many make.tcl invocations produced them. This covers punkcheck-managed build outputs that are VCS-tracked: src/bootsupport/, _vfscommon.vfs/modules + /lib, declared per-kit *.vfs/lib_tcl<N>/<pkg> subfolders, the thin-layout sync copies (src/project_layouts/vendor/punk/<layout>/src/{make.tcl,build.tcl} + bootsupport manifest copies), and the module-shipped layout payload under src/modules/punk/mix/#modpod-templates-*/templates/project_layouts/ (G-087: synced from src/project_layouts - never hand-edit the modpod copy). (Root modules/, lib/, modules_tcl<N>/, lib_tcl<N>/ are gitignored and never committed.) Each module's old→new version rename is atomic; a regeneration reflects one build-output refresh, not independent hand-edits. This is a carve-out from generic "split aggressively" commit guidance for punkcheck-managed build outputs only — it does not cover user-curated VFS content (_config/, per-kit *.vfs/ outside declared lib_tcl<N> subfolders, _aside/, mkzipfix.vfs, _vfscommon.vfs/doc), which commits separately per its own concerns.
• Boot-precondition gate (G-125). A bake refuses any kit whose merged .vfs supplies no tcl library: the kit is listed under FAILED KITS with a reason naming the cause, and NOTHING is written - no src/_build/<kit>, no deploy, and the previously deployed bin/<kit> is left byte-identical. This is deliberately a failure rather than a warning: the deploy step deletes the old kit before copying the new one, so the pre-gate behaviour replaced a working shell with an artifact that died at startup with application-specific initialization failed: Cannot find a usable init.tcl. The check is structural and non-executing (so it covers cross-target kits too): init.tcl in tcl_library/, lib/tcl<major>.<minor>/ or tcl<major>.<minor>/ - the third for runtimes whose archive mounts at the executable's own path rather than //zipfs:/app, so [info library] is <exe>/tcl8.6 (the androwish/undroidwish zipfs backport for 8.6 does this) - plus one companion file a real Tcl library carries beside it (tm.tcl, package.tcl, auto.tcl, clock.tcl, history.tcl, word.tcl) or an encoding/ directory - without that second test the lib/BWidget1.10.1/init.tcl every punkshell kit carries would answer for a tcl library it cannot provide. It reads the MERGED tree rather than asking whether extraction ran, so a .vfs that legitimately supplies its own tcl library (src/vfs/punk8_statictwapi.vfs, src/vfs/punk9test.vfs) builds and deploys unchanged. Remedy when a kit is refused: the usual cause is that the runtime's own payload could not be extracted - read the recapped BUILD-WARNING naming what was tried, then either fix extraction (a driving tclsh with no zipfs needs punk::zip >= 0.2.0 in bootsupport - see the extraction bullet above), point the kit at a runtime that carries a payload, or have the kit's .vfs supply a tcl library itself. The predicate is punkboot::utils::vfs_boot_library_report called through a guarded require, exactly as the dirty-src provenance check is: a stale or missing bootsupport snapshot degrades the gate to a NOTE rather than failing every kit. tclsh src/make.tcl check reports whether the gate is ACTIVE or UNAVAILABLE.
• Payload/target consistency checks (G-133), both ADVISORY - warnings are recapped BUILD-WARNINGs and the kit still builds and deploys (unlike the G-125 gate). (a) Binary-arch scan, at the same post-merge seam as the gate: every binary library (*.dll/*.so/*.dylib) in the merged tree is classified by header bytes (punkboot::utils::binary_arch_classify - PE Machine field, ELF e_machine, Mach-O incl. universal; unclassifiable content is honestly unknown and never warned about) against the kit's target platform. Structural and non-executing, so it runs for cross-target kits too (measured ~30-140ms per kit, avg ~93ms across the 12 assembled trees). Libraries under a platform-discriminated subdir - canonical <os>-<cpu> platform-dir names, the universal macosx folder, or a recognised vendor spelling (win-x64 etc; the lists are namespace variables in punkboot::utils) - are exempt: multi-arch payloads are legitimate there. First real sweep (2026-07-27) found a true latent instance: zint.dll 2.13.0 in src/vfs/punk8win.vfs/lib_tcl8/ is 32-bit (i386) and can never load in the x64 tcl8 kits (punk86/punkbi/punksys) that carry it - those bakes warn until the payload is fixed. (b) Smoke-require probe: a kit declaring packages in src/runtime/mapvfs.config (5th entry element - see src/runtime/AGENTS.md) has each one plain-package required INSIDE the freshly built artifact via its tclsh subcommand, which exits cleanly even on runtimes whose full repl teardown is fragile. This is the only check that observes actual package RESOLUTION - the punkluck86 2026-07-27 incident class (a higher-versioned wrong-arch Thread shadowing the runtime's working copy on plain require) is invisible to structural checks because the working file exists too. Failures are recapped naming kit, package and the actual error; cross-target kits skip with a stated reason; undeclared kits run nothing new; the probe only runs when the kit actually rebuilds. What the checks do NOT guarantee: statically linked packages, pure-tcl packages whose binary dependency lives elsewhere, and version-preference outcomes are visible only to the smoke probe - and only for the declared package set; the arch scan proves nothing about loadability beyond architecture, and an unknown classification is silence, not a pass. Both degrade to a NOTE when the bootsupport punkboot::utils snapshot is stale (same guarded require as the G-125 gate); tclsh src/make.tcl check reports the scan's ACTIVE/UNAVAILABLE state and the currently declared smoke-require kits.
• Kit bakes consume the punk-runtime WORKING COPIES under bin/runtime/<platform>/: make.tcl bake/bakehouse emit a BUILD-WARNING: (recapped at end of run) when a wrapped runtime's beside-toml revision is older than an -r<N> artifact present in the same folder - the forgot-to-switch-back guard for deliberate punk-runtime use <old-rN> testing excursions. Heed it before trusting freshly baked family kits; bin/punk-runtime.cmd use <artifact-r<N>> (.exe suffix optional) re-materializes the working copy.
• tclsh src/make.tcl bakelist ?kitname ...? (G-121) reports the kit outputs configured in src/runtime/mapvfs.config: kit name, kit type, runtime (with presence in the runtime store), vfs folder, and the deployed state of bin/<kit> vs the src/_build build product (current|stale|absent|nobuild), with anomalies (runtime=missing, vfs=missing, rtrev=r<cur><r<max> materialization staleness) and the cross-target marker target=<platform> in a trailing notes column. A nonexistent store tier is flagged loudly per tier actually referenced (header (FOLDER MISSING) for the default tier + stderr derivation; bake's no-runtimes exit self-diagnoses the same way). Name arguments filter the report and add a per-kit detail block (resolved store tier, target and provenance of the target, paths/sizes/mtimes). make.tcl bake ?kitname ...? bakes and deploys only the named kits - other kits' _build/bin artifacts and punkcheck records are untouched and the vfslibs phase narrows to the named kits' vfs folders; an unknown name errors before any build, listing the configured names; flags go before kit names (make.tcl bake -confirm 0 punk91). Bare bake processes all configured kits as before. Both surfaces consume the shared parsed-mapping helpers (::punkboot::lib::mapvfs_*) rather than the file format, so the G-024 config-format work swaps the reader underneath. Piped characterization: src/tests/shell/testsuites/punkexe/maketclbakelist.test.
• Host vs target platform (G-122). Everything a bake EMITS is keyed by the artifact's TARGET platform, never by the driving tclsh's personality: the bin/runtime/<tier> store the runtime is read from, .exe suffixing of runtime files and kit outputs, the presence checks behind runtime=missing, and whether the pre-deploy process sweep uses tasklist/taskkill or ps/kill. Host semantics - copy commands, path handling, filesystem case rules, prompts - stay keyed to the host. The default target is the host's own platform canon, EXCEPT a cygwin-family host (an msys2/cygwin-runtime tclsh, which reports tcl_platform(platform) unix on windows and canonizes as msys-x86_64/cygwin-x86_64), which targets win32-x86_64: such a host now drives the identical kit set, names and store addressing as a native tclsh. tclsh src/make.tcl check prints the derivation on one platform (G-122): host=... target=... store=... exe-suffix=... process-tooling=... line. A mapvfs entry may declare its own target platform (4th element - see src/runtime/AGENTS.md), which is then read from that platform's tier, named with that platform's executable convention, and skipped by the process sweep (its processes are not visible to this host). Traps this closes, all field-verified 2026-07-26: msys ps cannot see a natively-launched kit (only tasklist can), and msys2 rewrites arguments that look like absolute posix paths when spawning a native windows program - so taskkill /PID <n> arrived as taskkill C:/<msysroot>/PID <n>; native-windows command lines therefore go through ::punkboot::exec_nativeargs (sets MSYS2_ARG_CONV_EXCL=*, inert elsewhere). Also note a cygwin-family tclsh is a POSIX Tcl: name the script the way that shell spells paths (tclsh /c/repo/.../src/make.tcl, not C:/repo/..., which it resolves relative to the cwd) - make.tcl diagnoses the windows-spelling case. Piped characterization: src/tests/shell/testsuites/punkexe/maketclplatform.test (the cygwin-host tests self-gate on finding and probing a real msys/cygwin tclsh; PUNK_MSYS_TCLSH names one explicitly).
• Zip-type kit assembly does not require zipfs in the driving tcl (G-122): with tcl::zipfs::mkimg present it is used as before, otherwise the image is assembled by concatenation (raw-runtime split + punk::zip::mkzip + append, the same ::punkboot::assemble_zipcat_image helper the zipcat kit type uses). Both mount identically - tcl zipfs reads the archive with archive-start-relative offsets.
• Neither is EXTRACTING the runtime's own attached zip (needed to carry its tcl_library into the kit): punk::zip >= 0.2.0 reads a zip with stock Tcl only - no zipfs, no vfs::zip, no tcllib (G-124, the former tcllib zipfile::decode dependency is gone). The zipfs-less bake path splits off the executable prefix with punk::zip::extract_preamble and then reads the MEMBERS from the original runtime with punk::zip::unzip, never from the split-off intermediate: a runtime whose zip offsets are file-relative (the historical zipfs mkimg convention - tclsh90b4_piperepl.exe in the store is one) splits into a .zip whose offsets still count from the removed prefix, which plain zip readers reject. Reading the whole file at the derived base offset makes the two offset conventions indistinguishable to callers; punk::zip::archive_info <file> reports which one a given artifact uses. Verified 2026-07-26 by baking a zip kit from msys2's /usr/bin/tclsh8.6 (no zipfs, no vfs::zip, no tcllib) and booting the result with its tcl_library present.
• What the RUNTIME must provide to be zip-kit-wrappable - which zipfs commands, mount conventions and startup hooks are supported - is documented in bin/AGENTS.md "Kit-wrappable runtime requirements (G-129)". Short form: tcl::zipfs::mount with pairwise no-arg output (tcl::zipfs::root NOT required), any attached-archive mount point (the boot derives it from the runtime's own mount table - the androwish/undroidwish 8.6 backport mounts at the executable's own path), a main.tcl/app/main.tcl startup hook, and a liftable library payload for the G-125 gate. The bake's runtime capability probe keys has_zipfs on tcl::zipfs::mount accordingly.
• Use punk make.tcl bakehouse or punk902z make.tcl bakehouse inside Punk shell when building binaries through Punk (the deprecated project alias still maps). Driving make.tcl from a built punk executable is supported for informational/update subcommands and for kit builds of other kits — the kit whose deployed executable is running the build is skipped with a warning (it cannot be replaced while running, and the pre-deploy process sweep must not kill the build itself; the sweep also excludes the build's own pid in all cases). Rebuild that kit from tclsh or a different kit.
• Punk-exe-hosted make.tcl runs in a pre-loaded interp, not a virgin one — the kit's script-mode boot has already loaded much of the punk stack (punk, punk::lib, punk::repl, punk::console, punk::du, flagfilter, struct::set ...) and set process state (app-punkscript forces ::tcl_interactive 0 for script semantics; libunknown/packagepreference are active). Consequences make.tcl must (and now does) handle explicitly: package require of an already-provided package is a no-op, so anything make.tcl breaks in the interp (the accelerator-reload block forgets+destroys sha1/md5/struct::* — it re-requires what was loaded), and anything computed at package-load time (punk::repl's ::tcl_interactive probe — the shell branch recomputes it before repl::start), must be restored deliberately rather than relying on later loads to re-fire. Also note the copies that run in this mode are the kit's pre-loaded modules, not the bootsupport snapshots make.tcl's paths would otherwise prefer — silent provenance mixing when versions diverge. When adding interp-surgery or load-time-state assumptions to make.tcl, test under both tclsh src/make.tcl ... and <punkexe> src/make.tcl ....
• Binary images are platform-specific; build on each target platform rather than expecting a cross-platform flag.
• Remove _build/ artifacts only when a clean/resync is needed, then rerun the relevant make.tcl command. Avoid partial cleans that break boot modules.
• Superseded module intermediates are pruned automatically so payload wrapping inherits clean trees:
  • punk::mix::cli::lib::prune_superseded_target_modules runs inside build_modules_from_source_to_base after each module install/skip (covers root modules/, modules_tcl8/, modules_tcl9/), and from make.tcl bootsupport for non-glob include_modules.config entries (glob entries may intentionally track multiple versions and are never pruned).
  • punk::mix::cli::lib::prune_sourcevanished_targets mirror-prunes recorded targets whose recorded source files no longer exist: root modules*/ vendormodule copies (installer make.tcl) and the thin-layout/modpod sync copies recorded in src/project_layouts/.punkcheck (installer make.tcl, all file types).
  • Every deletion is recorded as a punkcheck DELETE event in the owning .punkcheck, so change detection stays consistent. Files without a qualifying punkcheck install record (e.g placed manually) are never deleted — they are reported to stderr and must be removed by hand if unwanted.
  • Install records carry virtual module_name/module_version SOURCE entries (punkcheck targetset_addsource_virtual, punkcheck >= 0.3.0) identifying which product of a source fileset a target is — needed because successive versions are typically built from the same physical source files. Prune trusts this identity; for legacy records it falls back to requiring the candidate's recorded sources to share the keep-version's source folder(s) and module-name prefix.
  • The make.tcl call sites are guarded with info commands checks: after changing this tooling itself, the first make.tcl modules + make.tcl bootsupport pass builds/propagates the new tooling (prune skipped with a stderr note) and the next pass prunes.
• Use tcl::tm::path add <dir> to surface project modules when writing focused tooling.
• Review VS Code Tcl lint diagnostics before submitting new agent-produced Tcl code, but do not use lint tooling to reformat existing code.
• When touching VFS payloads, describe regeneration steps in durable docs if the workflow changes.
• When a tool summary reports cleanup issues such as git diff --check whitespace errors, verify against exact command output and exit code before running secondary scans or reporting the issue.
• make.tcl performs version-aware bootsupport staleness detection: major bumps abort, minor bumps prompt (y/N; -confirm 0 proceeds without prompting, non-interactive stdin without it aborts fast), patch bumps warn-and-proceed. See src/bootsupport/AGENTS.md "Bootsupport Staleness Handling" for the full contract and the version-bump discipline agents must follow.
• Project-level version bumps are governed by the root AGENTS.md "Project Versioning" section. Any src/ change that ships user-visible shell behaviour requires a punkproject.toml version bump and a CHANGELOG.md entry as part of the DOX closeout pass. Run tclsh src/make.tcl projectversion to verify.

Verification

• VS Code Tcl lint diagnostics are reviewed for modified Tcl files when available.
• Relevant tests pass, either tclsh src/tests/runtests.tcl or a specific tclsh src/tests/modules/<modulehierarchypath>/tests/all.tcl.
• tclsh src/make.tcl packages is verified when touching build-critical code.
• tclsh src/make.tcl bakehouse (with -dirty-abort 0 when verifying a deliberately dirty tree) completes without errors when changing build, runtime, or VFS behavior.
• Documentation/comments are updated for new behavior, flags, workflow, or ownership rules.
• Diffs are reviewed so no stray whitespace or debugging output remains.

Child DOX Index

• modules/ — Main editable module source (see modules/AGENTS.md)
• modules/punk/ — Core punk namespace modules (see modules/punk/AGENTS.md)
• modules/test/ — Installed-module test packages (see modules/test/AGENTS.md)
• modules_tcl8/ — Tcl 8 specific modules (see modules_tcl8/AGENTS.md)
• modules_tcl9/ — Tcl 9 specific modules (see modules_tcl9/AGENTS.md)
• lib/ — Editable library source (see lib/AGENTS.md)
• lib_tcl8/ — Tcl 8 specific libraries
• lib_tcl9/ — Tcl 9 specific libraries
• bootsupport/ — Early-load bootstrap modules (see bootsupport/AGENTS.md)
• tests/ — Source-tree test harness and tests (see tests/AGENTS.md)
• vfs/ — Virtual file system images for builds (see vfs/AGENTS.md)
• scriptapps/ — Entry-point scripts for Punk apps (see scriptapps/AGENTS.md)
• vendormodules/ — Third-party bundled modules (see vendormodules/AGENTS.md)
• vendorlib/ — Third-party bundled libraries (see vendorlib/AGENTS.md)
• vendorlib_tcl8/ — Tcl 8 specific vendor libraries
• vendorlib_tcl9/ — Tcl 9 specific vendor libraries
• runtime/ — Build runtimes and VFS config (see runtime/AGENTS.md)
• buildsuites/ — Zig-built runtime factory: suites building Tcl runtimes from external sources with the pinned zig toolchain; surfaced via make.tcl buildsuite list/info/build; suite self-description contract in buildsuites/README.md (see buildsuites/AGENTS.md)
• tools/ — Vendored first-party build tools (zig; punkzip now, the G-128 tool later) built into bin/ by the make.tcl tool step; upstream-first editing with per-tree PROVENANCE.md provenance/licence records (see tools/AGENTS.md)
• doc/ — Generated documentation (see doc/AGENTS.md)
• assets/logo/ — Project logo vector masters and the .ico files generated from them; source of the project icon, with the pre-2026-07 artwork retained under legacy/ (see assets/logo/AGENTS.md)
• testansi/ — Sample ANSI art files (do not modify)