AGENTS.md with DOX framework

AGENTS.md

@@ -80,7 +80,36 @@ When the user requests a durable behavior change, record it here or in the relev
 
 ## Child DOX Index
 
-This project is not yet indexed. Before continuing you must scan the project, build the DOX tree and replace this message with the actual index. Go deep and scan files recursively to properly evaluate complexity and create nested DOX files where needed.
+- `src/` — Source tree root; editable source code, build scripts, tests, VFS payloads, vendor deps, docs (see src/AGENTS.md)
+  - `src/modules/` — Main editable module source (see src/modules/AGENTS.md)
+    - `src/modules/punk/` — Core punk namespace modules (see src/modules/punk/AGENTS.md)
+    - `src/modules/test/` — Installed-module test packages (see src/modules/test/AGENTS.md)
+    - `src/modules/opunk/` — Alternative punk namespace
+    - `src/modules/punkcheck/` — Build/check system
+  - `src/modules_tcl8/` — Tcl 8 specific modules (see src/modules_tcl8/AGENTS.md)
+  - `src/modules_tcl9/` — Tcl 9 specific modules (see src/modules_tcl9/AGENTS.md)
+  - `src/lib/` — Editable library source (see src/lib/AGENTS.md)
+  - `src/lib_tcl8/` — Tcl 8 specific libraries
+  - `src/lib_tcl9/` — Tcl 9 specific libraries
+  - `src/bootsupport/` — Early-load bootstrap modules (see src/bootsupport/AGENTS.md)
+  - `src/tests/` — Unit tests for src-hierarchy modules (see src/tests/AGENTS.md)
+  - `src/vfs/` — Virtual file system images for builds (see src/vfs/AGENTS.md)
+  - `src/scriptapps/` — Entry-point scripts for Punk apps (see src/scriptapps/AGENTS.md)
+  - `src/vendormodules/` — Third-party bundled modules (see src/vendormodules/AGENTS.md)
+  - `src/vendorlib/` — Third-party bundled libraries (see src/vendorlib/AGENTS.md)
+  - `src/vendorlib_tcl8/` — Tcl 8 specific vendor libraries
+  - `src/vendorlib_tcl9/` — Tcl 9 specific vendor libraries
+  - `src/runtime/` — Build runtimes and VFS config (see src/runtime/AGENTS.md)
+  - `src/doc/` — Generated documentation (see src/doc/AGENTS.md)
+  - `src/testansi/` — Sample ANSI art files (do not modify)
+- Directories agents should not directly modify (no child DOX needed):
+  - `callbacks/` — Experimental shellspy features, user-only
+  - `scriptlib/` — Shared utilities + manual tests, user-only
+  - `bin/` — Built binaries and helpers, build output target
+  - `modules/` (root) — Build output target for `tclsh src/make.tcl modules`
+  - `lib/` (root) — Build output target for `tclsh src/make.tcl libs`
+  - `modules_tcl8/`, `modules_tcl9/` — Tcl version-specific build output targets
+  - `lib_tcl8/`, `lib_tcl9/` — Tcl version-specific build output targets
 
 
 
@@ -221,6 +250,8 @@ Do not skip a stronger anchor for a weaker one.
         c C       {*}{
     }   d $DVAL   {*}{
   }
+- test files may commonly use line continuations - which is ok in this instance outside of proc definitions.
+- For test files that include tcl expand syntax based structures - these should not be refactored into line continuations.
 - Keep pipelines readable by aligning `% var = ...` and `pipecase` segments vertically when possible.
 - Document non-trivial procedures and exports with the standard header template (see below).
 

src/bootsupport/AGENTS.md

@@ -0,0 +1,34 @@
+# src/bootsupport — Early-Load Bootstrap Modules
+
+## Purpose
+
+Modules and libraries required during the build/bootstrap/make process before the full Punk module set is available. These are analogous to npm devDependencies — they must be self-contained with minimal dependencies.
+
+## Ownership
+
+- Agents should not directly modify files in this tree unless the task specifically targets boot behaviour.
+- Bootsupport modules are snapshots that may lag behind or diverge from the corresponding `src/modules/` versions intentionally.
+- The `dev lib.copyasmodule` command is the prescribed way to update bootsupport modules.
+
+## Local Contracts
+
+- Modules here are loaded by initialisation scripts via `tcl::tm::path`.
+- Each `.tm` file must work standalone without requiring Punk's full module loading infrastructure.
+- The `include_modules.config` file controls which vendormodules are pulled into bootsupport.
+
+## Work Guidance
+
+- Verify boot functionality by running `tclsh src/make.tcl packages` after any change.
+- Do not add compiled extensions or packages requiring dynamic loading to bootsupport.
+- Check `src/bootsupport/modules/README.md` for the copy-as-module workflow.
+
+## Verification
+
+- `tclsh src/make.tcl packages` succeeds after any modification.
+
+## Child DOX Index
+
+- `modules/` — Bootstrap .tm module snapshots
+- `lib/` — Bootstrap library snapshots
+- `modules_tcl8/` — Tcl 8-specific bootstrap modules
+- `modules_tcl9/` — Tcl 9-specific bootstrap modules

src/doc/AGENTS.md

@@ -0,0 +1,32 @@
+# src/doc — Generated Documentation
+
+## Purpose
+
+Houses generated documentation files (man pages, module docs) produced by the Kettle build system and Punk's docgen module. Also contains the Kettle configuration for controlling documentation generation.
+
+## Ownership
+
+- Most content under `src/doc/` is auto-generated. Agents should not edit generated `.man` files directly.
+- The `main.man`, `project_changes.man`, and `project_intro.man` are hand-maintained Kettle source files.
+- `punk/` holds Punk-specific doc configuration.
+
+## Local Contracts
+
+- Documentation is generated via `pmix KettleShell` or `tclsh src/build.tcl`.
+- `.man` files use Kettle's doctools format.
+- `_module_*.man` files are generated from module source annotations.
+
+## Work Guidance
+
+- To add module documentation, update the `punk::args` / PUNKARGS definitions in the module source, then regenerate.
+- Do not manually edit `_module_*.man` files — they will be overwritten on regeneration.
+
+## Verification
+
+- Generated docs render correctly with Kettle's doc viewer.
+
+## Child DOX Index
+
+- `punk/` — Punk-specific doc configuration
+- `include/` — Kettle include files
+- `files/` — Static doc assets

src/lib/AGENTS.md

@@ -1,10 +1,44 @@
+# src/lib — Editable Tcl Library Source
 
-## Library Source Selection
+## Purpose
 
-- Treat implementation `.tcl` files in `src/lib/` as the source of truth for generic editable library behavior.
+Source of truth for all editable `pkgIndex.tcl`-based library packages. These are larger libraries that use the Tcl package index system rather than the `.tm` module format.
-- Treat `src/lib_tcl<major>/` as Tcl-major-version-specific source trees.
-- Prefer `src/lib/` unless version-specific behavior is relevant or the package exists only in a version-specific tree.
-- Treat `pkgIndex.tcl` as a loader map unless the task is about package loading, registration, or load-path behavior.
-- If a request begins from `pkgIndex.tcl`, resolve the mapped implementation file before analyzing or editing a proc.
-- Prefer generic or version-specific source trees over built, installed, VFS, project layout, or generated copies unless the user explicitly targets those copies.
 
+## Ownership
+
+- Agents should edit implementation `.tcl` files in `src/lib/` subdirectories as the source of truth for library behaviour.
+- `pkgIndex.tcl` files are loader maps — treat them as such unless the task is about package loading or registration.
+
+## Local Contracts
+
+- Treat `src/lib/` as the generic source tree; prefer it over `src/lib_tcl<major>/` unless version-specific.
+- If a request starts from `pkgIndex.tcl`, resolve the mapped implementation file before analyzing or editing a proc.
+- Libraries here include:
+  - `app-punk/` — Punk REPL app entry (`app-punk::repl`)
+  - `app-punkshell/` — Punkshell app entry (`app-punkshell`)
+  - `app-shellspy/` — ShellSpy app entry (`app-shellspy`)
+  - `app_shell/` — Shell app helpers (`app_shell`)
+  - `app_shellrun/` — Shell run helpers (`app_shellrun`)
+  - `app_project/` — Project app helpers (`app_project`)
+  - `vfszip/` — VFS zip utilities
+
+## Work Guidance
+
+- Prefer generic or version-specific source trees over built, installed, VFS, or generated copies unless explicitly targeting those.
+- After editing a library, run `tclsh src/make.tcl libs` to rebuild, then `tclsh src/make.tcl project` for a full rebuild.
+- New libraries should include a `pkgIndex.tcl` that correctly references the implementation file.
+
+## Verification
+
+- `tclsh src/make.tcl libs` completes without errors.
+- `package require <libraryname>` resolves in the Punk shell after build.
+
+## Child DOX Index
+
+- `app-punk/` — Punk REPL app entry
+- `app-punkshell/` — Punkshell app entry
+- `app-shellspy/` — ShellSpy app entry
+- `app_shell/` — Shell app helpers
+- `app_shellrun/` — Shell run helpers
+- `app_project/` — Project app helpers
+- `vfszip/` — VFS zip utilities

src/lib_tcl8/AGENTS.md

@@ -1,5 +1,29 @@
-## Version-Specific Source
+# src/lib_tcl8 — Tcl 8 Specific Library Source
+
+## Purpose
+
+Holds library packages specific to Tcl major version 8. Use only when a package is specific to Tcl 8 or only exists in this tree.
+
+## Ownership
+
+- Agents should prefer `src/lib/` over this tree unless the task explicitly involves Tcl 8-specific behaviour.
+- Files here follow the same `pkgIndex.tcl`-based structure as `src/lib/`.
+
+## Local Contracts
 
 - This tree holds source specific to Tcl major version 8.
 - Prefer this tree only when the package or proc is specific to Tcl major version 8 or only exists here.
-- Do not prefer this tree when an equivalent generic source exists in the corresponding non-version-specific tree unless version-specific behavior is relevant.
+- Do not prefer this tree when an equivalent generic source exists in `src/lib/` unless version-specific behavior is relevant.
+
+## Work Guidance
+
+- Tcl 8 compatibility gates should use `if {$tcl_version < 9} { ... }` or `package require Tcl 8`.
+- Use `punk::lib::compat` functions where available instead of raw version checks.
+
+## Verification
+
+- `package require <libraryname>` resolves under a Tcl 8.6+ interpreter.
+
+## Child DOX Index
+
+(None — currently empty)

src/lib_tcl9/AGENTS.md

@@ -1,5 +1,29 @@
-## Version-Specific Source
+# src/lib_tcl9 — Tcl 9 Specific Library Source
+
+## Purpose
+
+Holds library packages specific to Tcl major version 9. Use only when a package is specific to Tcl 9 or only exists in this tree.
+
+## Ownership
+
+- Agents should prefer `src/lib/` over this tree unless the task explicitly involves Tcl 9-specific behaviour.
+- Files here follow the same `pkgIndex.tcl`-based structure as `src/lib/`.
+
+## Local Contracts
 
 - This tree holds source specific to Tcl major version 9.
 - Prefer this tree only when the package or proc is specific to Tcl major version 9 or only exists here.
-- Do not prefer this tree when an equivalent generic source exists in the corresponding non-version-specific tree unless version-specific behavior is relevant.
+- Do not prefer this tree when an equivalent generic source exists in `src/lib/` unless version-specific behavior is relevant.
+
+## Work Guidance
+
+- Tcl 9 compatibility gates should use `if {$tcl_version >= 9} { ... }` or `package require Tcl 9`.
+- Use `punk::lib::compat` functions where available instead of raw version checks.
+
+## Verification
+
+- `package require <libraryname>` resolves under a Tcl 9.0+ interpreter.
+
+## Child DOX Index
+
+(None — currently empty)

src/modules/AGENTS.md

@@ -1,7 +1,40 @@
-## Module Source Selection
+# src/modules — Main Editable Module Source
+
+## Purpose
+
+Source of truth for all editable Punk project modules. This is where agents should make module source edits. Each `.tm` file is a Tcl module belonging to a named package.
+
+## Ownership
+
+- Agents should edit files here as the primary development area.
+- The top-level modules (non-punk namespace) include shellfilter, shellrun, overtype, textblock, patternpunk, etc.
+- The `punk/` subdirectory holds all `punk::*` namespace modules.
+
+## Local Contracts
+
+- Module filenames use the literal suffix `-999999.0a1.0.tm`.
+- Corresponding `<modulename>-buildversion.txt` files hold the real version number.
+- The exception is `punk::libunknown` which uses its own version `0.1`.
+- `#modpod-*` directories contain internal files packed into `.tm` archives during build — do not flatten or edit without understanding the modpod format.
+- `_build/` directory holds build intermediates and should not be manually edited.
+
+## Work Guidance
 
 - Treat `src/modules/` as the source of truth for generic editable Punk modules.
 - Expect the literal suffix `-999999.0a1.0.tm`.
-- Treat `src/modules_tcl<major>/` as Tcl-major-version-specific source trees.
 - If the same proc exists in both `src/modules/` and `src/modules_tcl<major>/`, prefer `src/modules/` unless version-specific behavior is relevant or only the version-specific file is active.
-- Treat bootstrap, VFS, project layout, built, and installed copies as downstream unless the user explicitly targets them or the task is about bootstrap or packaging behavior.
+- Use `deck module.new <name>` or `punk::mix::commandset::module::new` to scaffold new modules.
+- Run `tclsh src/make.tcl modules` to build modules, or `tclsh src/make.tcl project` for a full build.
+
+## Verification
+
+- `tclint` passes on modified `.tm` files.
+- `tclsh src/make.tcl modules` completes without errors.
+- Module tests pass: `tclsh src/tests/modules/<path>/tests/all.tcl`
+
+## Child DOX Index
+
+- `punk/` — Core punk namespace modules (see punk/AGENTS.md)
+- `opunk/` — Alternative punk namespace (opunk::str)
+- `punkcheck/` — Build/check system (punkcheck + punkcheck::cli)
+- `test/` — Installed-module test packages (see test/AGENTS.md)

src/modules/punk/AGENTS.md

@@ -0,0 +1,50 @@
+# src/modules/punk — Core Punk Module Namespace
+
+## Purpose
+
+Source of truth for all modules under the `punk::*` namespace. This is the primary development area for the Punk Shell project, containing the core shell, REPL, pipeline, ANSI, navigation, networking, and utility modules.
+
+## Ownership
+
+- Agents should edit files here when modifying Punk module behaviour.
+- Follow the module structure conventions from the root AGENTS.md strictly.
+- Each subdirectory represents a sub-namespace (e.g., `punk::ansi` = `ansi/`, `punk::mix` = `mix/`).
+
+## Local Contracts
+
+- Module filenames must use the literal suffix `-999999.0a1.0.tm`.
+- Corresponding version files use `<modulename>-buildversion.txt` for the real version.
+- The top-level `punk-999999.0a1.0.tm` is the main Punk module entry point.
+- `punk::lib` (`lib-999999.0a1.0.tm`) provides core compatibility and utility functions.
+- `punk::args` (`args-999999.0a1.0.tm` + `args/`) is the argument processing and documentation system.
+- `punk::repl` (`repl-999999.0a1.0.tm` + `repl/`) is the interactive REPL engine.
+- `punk::mix` (`mix/`) is the project/template/build system (mix CLI, commandset, templates).
+- `punk::cap` (`cap/` + `cap-handlers/`) is the capability/capture system.
+- `punk::nav` (`nav/`) provides filesystem and namespace navigation (nav::fs, nav::ns).
+- `punk::ansi` (`ansi/`) provides ANSI colour and terminal control.
+- `punk::net` (`net/`) provides networking utilities (net::vxlan).
+- `punk::netbox` (`netbox/`) provides the netbox client library (includes netbox::man).
+
+## Work Guidance
+
+- New modules under `punk::*` should be created as `<subpath>/<modulename>-999999.0a1.0.tm` following the namespace-to-path convention.
+- Use `punk::args::parse` with `@id` references in `argdoc` namespaces for public API procs.
+- Private helpers go in `namespace eval private { ... }` blocks.
+- Keep `namespace export` lists alphabetized.
+- The `#modpod-*` folders contain files that get packed into `.tm` module archives during build — do not flatten them.
+
+## Verification
+
+- `tclint` passes on modified `.tm` files.
+- `tclsh src/tests/modules/punk/<subpath>/tests/all.tcl` passes for relevant tests.
+
+## Child DOX Index
+
+- `ansi/` — punk::ansi sub-namespace (colour, sauce, colourmap)
+- `args/` — punk::args sub-namespace (argument processing, moduledoc, testcmd)
+- `cap/` — punk::cap sub-namespace (capability handlers, templates)
+- `mix/` — punk::mix sub-namespace (CLI, commandset, templates for project/module building)
+- `nav/` — punk::nav sub-namespace (filesystem and namespace navigation)
+- `net/` — punk::net sub-namespace (networking utilities)
+- `netbox/` — punk::netbox sub-namespace (netbox client, man pages)
+- `repl/` — punk::repl sub-namespace (code thread management)

src/modules/test/AGENTS.md

@@ -1,14 +1,30 @@
-# test module information
+# src/modules/test — Installed-Module Test Packages
----
-subfolders (that don't begin with a # or _ character) within this test folder form part of the Tcl namespace of the resulting modules that are produced from running '<tclshbinary> src/make.tcl modules'
 
-The #modpod- folder for a module contain files that will stored in the final module's .tm file (zip based) which is built by make.tcl into the <projectroot>/modules/test folder (again with further subfolders depending on whether the module is namespaced)
+## Purpose
 
-The final version of the built modules are determined from corresponding <tailname>-buildversion.txt files placed at the same level as the corresponding #modpod-<tailname>-999999.0a1.0 folder
+Test modules bundled into `.tm` module packages with namespace/folder matching the module being tested. These packages are generated from `src/tests/` or manually updated by the user, and test the installed module/library state (after running `tclsh src/make.tcl packages|modules|lib`).
 
-example: A final installed module <projectroot>/modules/test/foo/baz/foobazzer-1.1.tm corresponds to the tcl module test::foo::baz::foobazzer and will have its source tests and associated files in the folder <projectroot>/src/modules/test/foo/baz/#modpod-foobazzer-999999.0a1.0 with a corresponding version number file at <projectroot>/src/modules/test/foo/baz/foobazzer-buildversion.txt
+## Ownership
 
-A new testmodule for a package can be generated from the template template_test  built into the punk::mix::templates package which is referenced as 'punk.test' when creating a new module using the 'dev module.new' command. This command is an alias for punk::mix::commandset::module::new.
+- Agents should generally not update this area aside from updating version numbers in `<modulename>-buildversion.txt` files.
+- Test content is sourced from `src/tests/`; this area is a packaging layer, not the primary test authoring location.
 
+## Local Contracts
 
+- Subfolders (not starting with `#` or `_`) form part of the Tcl namespace of resulting modules.
+- `#modpod-<name>-999999.0a1.0/` folders contain files packed into the final `.tm` module.
+- Final module versions are determined by `<tailname>-buildversion.txt` files at the same level as the corresponding `#modpod-` folder.
+- Example: `<projectroot>/modules/test/foo/baz/foobazzer-1.1.tm` corresponds to `test::foo::baz::foobazzer` with source in `src/modules/test/foo/baz/#modpod-foobazzer-999999.0a1.0/`.
 
+## Work Guidance
+
+- New test modules can be generated from the `punk.test` template via `dev module.new` / `punk::mix::commandset::module::new`.
+- Do not create test modules manually without the template system unless explicitly asked.
+
+## Verification
+
+- `package require test::<modulename>` resolves after `tclsh src/make.tcl modules`.
+
+## Child DOX Index
+
+- `punk/` — Test packages for `punk::*` modules

src/modules_tcl8/AGENTS.md

@@ -1,5 +1,29 @@
-## Version-Specific Source
+# src/modules_tcl8 — Tcl 8 Specific Module Source
+
+## Purpose
+
+Holds source modules specific to Tcl major version 8. Use only when a package or proc is specific to Tcl 8 or only exists in this tree.
+
+## Ownership
+
+- Agents should prefer `src/modules/` over this tree unless the task explicitly involves Tcl 8-specific behaviour.
+- Files here follow the same naming and structure conventions as `src/modules/`.
+
+## Local Contracts
 
 - This tree holds source specific to Tcl major version 8.
 - Prefer this tree only when the package or proc is specific to Tcl major version 8 or only exists here.
-- Do not prefer this tree when an equivalent generic source exists in the corresponding non-version-specific tree unless version-specific behavior is relevant.
+- Do not prefer this tree when an equivalent generic source exists in `src/modules/` unless version-specific behavior is relevant.
+
+## Work Guidance
+
+- Tcl 8 compatibility gates should use `if {$tcl_version < 9} { ... }` or `package require Tcl 8`.
+- Use `punk::lib::compat` functions where available instead of raw version checks.
+
+## Verification
+
+- Tests pass under a Tcl 8.6+ interpreter.
+
+## Child DOX Index
+
+(None — currently empty of module files)

src/modules_tcl9/AGENTS.md

@@ -1,5 +1,29 @@
-## Version-Specific Source
+# src/modules_tcl9 — Tcl 9 Specific Module Source
+
+## Purpose
+
+Holds source modules specific to Tcl major version 9. Use only when a package or proc is specific to Tcl 9 or only exists in this tree.
+
+## Ownership
+
+- Agents should prefer `src/modules/` over this tree unless the task explicitly involves Tcl 9-specific behaviour.
+- Files here follow the same naming and structure conventions as `src/modules/`.
+
+## Local Contracts
 
 - This tree holds source specific to Tcl major version 9.
 - Prefer this tree only when the package or proc is specific to Tcl major version 9 or only exists here.
-- Do not prefer this tree when an equivalent generic source exists in the corresponding non-version-specific tree unless version-specific behavior is relevant.
+- Do not prefer this tree when an equivalent generic source exists in `src/modules/` unless version-specific behavior is relevant.
+
+## Work Guidance
+
+- Tcl 9 compatibility gates should use `if {$tcl_version >= 9} { ... }` or `package require Tcl 9`.
+- Use `punk::lib::compat` functions where available instead of raw version checks.
+
+## Verification
+
+- Tests pass under a Tcl 9.0+ interpreter.
+
+## Child DOX Index
+
+(None — currently empty of module files)

src/runtime/AGENTS.md

@@ -0,0 +1,30 @@
+# src/runtime — Build Runtimes and VFS Configuration
+
+## Purpose
+
+Houses the `mapvfs.config` that maps VFS payloads to platform runtimes, plus the Tcl runtime executables and support files consumed during binary builds.
+
+## Ownership
+
+- Agents must not modify runtime executables or `mapvfs.config` unless explicitly asked.
+- Runtime `.exe` files are platform binaries installed via `bin/runtime.cmd` and must not be edited.
+
+## Local Contracts
+
+- `mapvfs.config` defines which `src/vfs/*.vfs` folders combine with which runtime binaries.
+- Runtime executables are placed here by the `bin/runtime.cmd` helper or manually.
+- The `_build/` subdirectory holds build intermediates; it can be safely deleted.
+
+## Work Guidance
+
+- When adding a new platform: create the runtime directory under `bin/runtime/<platform>/`, add a VFS under `src/vfs/`, and update `mapvfs.config`.
+- Do not commit large binary runtimes to version control unless specifically required.
+
+## Verification
+
+- `tclsh src/make.tcl project` uses `mapvfs.config` correctly.
+- Built binaries launch and boot the Punk REPL.
+
+## Child DOX Index
+
+(None — flat directory with executables and config)

src/scriptapps/AGENTS.md

@@ -0,0 +1,34 @@
+# src/scriptapps — Entry-Point Scripts for Punk Apps
+
+## Purpose
+
+Standalone Tcl scripts that serve as entry points for Punk applications and utilities. Includes wrapper generators, runtime fetchers, build helpers, and test scripts for external languages.
+
+## Ownership
+
+- Shared between maintainer and agents. Agents may edit when asked but should preserve the existing entry-point contract of each script.
+- The `wrappers/` subdirectory contains TOML configuration and generated wrapper scripts.
+
+## Local Contracts
+
+- Scripts here are invoked directly by the user or by build tools, not loaded as packages.
+- Wrapper configs (`.toml` files) define how scripts are packaged as platform executables.
+- The `spud/` directory holds the spud build tool's app scripts.
+- The `tools/` directory holds miscellaneous build and deployment utilities.
+
+## Work Guidance
+
+- When adding a new script app, follow the naming pattern: `<name>.tcl` with optional `<name>_wrap.toml`.
+- Test scripts for non-Tcl languages (bash, PowerShell, Perl, Python) live in `test_bash/`, `test_pwsh/`, etc.
+- The `bin/` subdirectory is not the same as the project root `bin/`; it holds app-specific launchers.
+
+## Verification
+
+- Existing scripts run without import errors in the project environment.
+
+## Child DOX Index
+
+- `wrappers/` — TOML wrapper configs and generated wrappers
+- `spud/` — Spud build tool app scripts
+- `tools/` — Build and deployment utilities
+- `bin/` — App-specific launchers

src/tests/AGENTS.md

@@ -0,0 +1,32 @@
+# src/tests — Unit Tests for src-Hierarchy Modules
+
+## Purpose
+
+Unit tests that run against modules in the `src/` source tree, prior to installation. These tests use the `tcltest` package and target the uninstalled module source code.
+
+## Ownership
+
+- Owned by the project maintainer; agents should add new tests here when modifying modules but must not delete or silently skip existing failing tests.
+
+## Local Contracts
+
+- Test files use `.tcl` extension and must `package require punk` (plus any extra packages explicitly).
+- The directory hierarchy under `src/tests/modules/` mirrors namespace paths of the modules being tested.
+- Tests run against source modules in the `src/` tree, not installed packages.
+- Prefer `try { ... } on error {result options} { ... }` for structured error capture in test bodies.
+- New test files go in `src/tests/modules/<namespacepath>/tests/` mirroring the module namespace.
+
+## Work Guidance
+
+- Run a single test: `tclsh src/tests/modules/<namespacepath>/tests/all.tcl`
+- Run the full suite: `tclsh src/tests/runtests.tcl`
+- When adding a test, mirror the namespace path of the module under test.
+- Do not add tests for vendormodules or bootsupport here unless explicitly requested.
+
+## Verification
+
+- `tclsh src/tests/<path>/all.tcl` exits cleanly with pass/fail summary.
+
+## Child DOX Index
+
+- `modules/` — Per-namespace test directories mirroring `src/modules/` structure

src/vendorlib/AGENTS.md

@@ -0,0 +1,28 @@
+# src/vendorlib — Third-Party Bundled Libraries
+
+## Purpose
+
+Third-party `pkgIndex.tcl`-based library packages bundled with the repo. These are library dependencies (larger packages, often with multiple files) that Punk modules depend on at runtime.
+
+## Ownership
+
+- Agents should not directly modify vendorlib packages unless the task is to upgrade a vendor dependency.
+- Each library subdirectory is self-contained with its own `pkgIndex.tcl`.
+
+## Local Contracts
+
+- Vendor libraries use real version numbers, not the magic version scheme.
+- Vendor libraries must not be edited to add Punk-specific functionality — create a new module under `src/modules/` instead.
+
+## Work Guidance
+
+- To add a new vendor library: place it in its own subdirectory under `src/vendorlib/` with a `pkgIndex.tcl`.
+- To upgrade: replace the library subdirectory entirely, preserving the `pkgIndex.tcl` convention.
+
+## Verification
+
+- `package require <vendrolibname>` resolves after `tcl::tm::path` and `auto_path` are configured.
+
+## Child DOX Index
+
+- `base64/`, `BWidget*`, `control/`, `debug/`, `iwidgets*/`, `kettle1/`, `pdf4tcl*/`, `pluginmgr/`, `publisher-*`, `tdot*/`, `term/`, `virtchannel_*/` — Individual vendor libraries

src/vendormodules/AGENTS.md

@@ -0,0 +1,32 @@
+# src/vendormodules — Third-Party Bundled Modules
+
+## Purpose
+
+Third-party `.tm` module files bundled with the repo. These are dependency modules sourced from tcllib and other origins, required by Punk modules at runtime.
+
+## Ownership
+
+- Agents should not directly modify vendormodules unless the task is to upgrade a vendor dependency.
+- The `include_modules.config` file controls which modules are pulled in during `vendorupdate`.
+- Vendormodules are refreshed using `tclsh src/make.tcl vendorupdate` — do not manually place files unless instructed.
+
+## Local Contracts
+
+- Vendor modules must not use the magic version number `999999.0a1.0` — they carry their own real version numbers.
+- Vendor modules should not appear in output paths like `<projectdir>/modules`.
+- Prefer importing functionality from vendormodules over adding new external dependencies.
+
+## Work Guidance
+
+- To upgrade a vendor module: replace the `.tm` file and update `include_modules.config` if needed.
+- Run `tclsh src/make.tcl vendorupdate` to refresh from configured sources.
+- Check `src/vendormodules/README.md` for module listing notes.
+
+## Verification
+
+- `tclsh src/make.tcl vendorupdate` runs cleanly.
+- `package require <vendormodulename>` resolves in the Punk shell.
+
+## Child DOX Index
+
+(None — flat module directory)

src/vfs/AGENTS.md

@@ -0,0 +1,34 @@
+# src/vfs — Virtual File System Images for Builds
+
+## Purpose
+
+VFS (Virtual File System) folders define the runtime payloads that get wrapped into Punk executables. Each `*.vfs` folder becomes a built binary with its associated runtime from `bin/runtime/`.
+
+## Ownership
+
+- These are manually maintained by the project owner. Agents must not modify VFS content unless explicitly asked to update runtime payloads.
+- `_vfscommon.vfs/` is completely regenerated by `tclsh src/make.tcl vfscommonupdate` — never edit directly.
+- `_config/` holds entry-point `.tcl` files; edit only when intentionally changing binary startup behaviour.
+
+## Local Contracts
+
+- `*.vfs` folders are build artifacts consumed by `tclsh src/make.tcl project`.
+- VFS content must be compatible with the target platform runtime.
+- `_vfscommon.vfs/` is an auto-generated merge of common libraries; manually editing it will be overwritten.
+
+## Work Guidance
+
+- To add a module to a VFS build, update the VFS folder's module set, then run `tclsh src/make.tcl project`.
+- The `src/runtime/mapvfs.config` file maps VFS folders to platform runtimes.
+- Describe regeneration steps in commit messages when touching VFS payloads.
+
+## Verification
+
+- `tclsh src/make.tcl project` builds without errors.
+- Built binary starts and loads the expected module set.
+
+## Child DOX Index
+
+- `_config/` — Entry-point .tcl files for built executables
+- `_vfscommon.vfs/` — Auto-generated common VFS libraries (do not edit)
+- Various `*.vfs/` — Platform-specific VFS images