add src/AGENTS.md

src/AGENTS.md

@@ -0,0 +1,53 @@
+# 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.
+
+## Local Contracts
+
+- `make.tcl` is the primary build entry point: `tclsh src/make.tcl <command>`.
+- Source priority: `src/modules/` > `src/modules_tcl<major>/` > bootsupport > VFS > built > installed.
+- Source priority for libraries: `src/lib/` > `src/lib_tcl<major>/` > vendorlib.
+- The `_build/` directories are build intermediates; they can be deleted and regenerated.
+
+## Work Guidance
+
+- Use `tclsh src/make.tcl project` for full builds.
+- 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.
+- Use `tclsh src/make.tcl vendorupdate` to refresh vendormodules from config.
+- Use `tclsh src/make.tcl vfscommonupdate` to rebuild `_vfscommon.vfs`.
+
+## Verification
+
+- `tclsh src/make.tcl project` completes without errors.
+- `tclsh src/tests/runtests.tcl` passes.
+
+## 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/` — Unit tests for src-hierarchy modules (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)
+- `doc/` — Generated documentation (see doc/AGENTS.md)
+- `testansi/` — Sample ANSI art files (do not modify)