punkshell/src/doc/AGENTS.md

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