# 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 parent `src/modules/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.
- Follow the parent `src/modules/AGENTS.md` "Versioning And Releases" rules: bump `<modulename>-buildversion.txt` on any API or behavior change and append a changelog comment line documenting the change.

## Verification

- VS Code Tcl lint diagnostics are clean for modified `.tm` files when available.
- `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)