AGENTS.md is the source of truth for this repository, including for Claude harnesses.
Before working, read and follow the root `AGENTS.md`, then read and follow any nested `AGENTS.md` files that apply to the paths being inspected or edited.
If this file conflicts with `AGENTS.md`, `AGENTS.md` wins.
@ -13,6 +13,8 @@ The source tree root contains all editable source code, build scripts, test suit
## Local Contracts
## Local Contracts
- `make.tcl` is the primary build entry point: `tclsh src/make.tcl <command>`.
- `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.
- 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.
- 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.
- 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.
@ -25,6 +25,15 @@ Source of truth for all editable Punk project modules. This is where agents shou
- For optional features, probe with `if {[catch {package require foo}]} { ... }` and degrade gracefully.
- For optional features, probe with `if {[catch {package require foo}]} { ... }` and degrade gracefully.
- Vendormodules, bootsupport snapshots, VFS modules, and built output modules do not use the magic version scheme unless their own local docs explicitly say otherwise.
- Vendormodules, bootsupport snapshots, VFS modules, and built output modules do not use the magic version scheme unless their own local docs explicitly say otherwise.
### Module Subsystems
- Terminal/display modules include `punk::ansi` for ANSI codes, cp437, and Sixel support; `punk::console`; `textblock` for text composition and framing; and `overtype` for text overlay.
- Shell modules include `punk::repl`, `punk::shellrun` for `run`/`runout`/`runerr`/`runx`, and `punk::nav::ns` for namespace browsing.
- Functional and pattern modules include `pattern` and `patterncmd`; treat them as experimental and use them only with user instruction or confirmation.
- Argument handling uses `punk::args` for processing, validation, and documentation generation; prefer it for public APIs and user-facing utilities unless the code path is performance critical.
- Networking modules include `punk::imap4`, `punk::netbox`, `punk::basictelnet`, and `punk::net::vxlan`.
- Plugin and capability provider/handler support uses `punk::cap`.
## Work Guidance
## Work Guidance
- Treat `src/modules/` as the source of truth for generic editable Punk modules.
- Treat `src/modules/` as the source of truth for generic editable Punk modules.
@ -155,6 +164,10 @@ if {[catch {some_command} result]} {
### Pipeline And Functional Style Notes
### Pipeline And Functional Style Notes
- Punk Pipeline functionality is experimental and should usually be avoided in agent-generated code unless the user specifically requests it.
- Punk Pipeline functionality is experimental and should usually be avoided in agent-generated code unless the user specifically requests it.
- Pipeline syntax includes forms such as `var.= command1 |> command2 |> command3`.
- Pattern-match assignment syntax includes forms such as `x@0,y@1,z@2.= list a b c`, where `@` targets an index and `/` is range-safe.
- Destructuring examples include `x@end/@@k1.= list {k1 aaa} {k1 bb}`.
- `.=` means following args form a command; `=` accepts a single value.
- Use `% var = ...` bindings to capture intermediate values; keep names meaningful.
- Use `% var = ...` bindings to capture intermediate values; keep names meaningful.
- `pipecase` should list specific patterns before catch-alls to avoid hidden matches.
- `pipecase` should list specific patterns before catch-alls to avoid hidden matches.
- `fun name pattern { ... }` definitions should remain side-effect light; treat them as pure functions unless otherwise documented.
- `fun name pattern { ... }` definitions should remain side-effect light; treat them as pure functions unless otherwise documented.
