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.
• 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 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.
• Use punk make.tcl project or punk902z make.tcl project inside Punk shell when building binaries through Punk.
• 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.
• 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), 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.

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 project 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)
• doc/ — Generated documentation (see doc/AGENTS.md)
• testansi/ — Sample ANSI art files (do not modify)