# DOX framework

- DOX is highly performant AGENTS.md hierarchy installed here
- Agent must follow DOX instructions across any edits

## Core Contract

- AGENTS.md files are binding work contracts for their subtrees
- Work products, source materials, instructions, records, assets, and durable docs must stay understandable from the nearest applicable AGENTS.md plus every parent AGENTS.md above it

## Read Before Editing

1. Read the root AGENTS.md
2. Identify every file or folder you expect to touch
3. Walk from the repository root to each target path
4. Read every AGENTS.md found along each route
5. If a parent AGENTS.md lists a child AGENTS.md whose scope contains the path, read that child and continue from there
6. Use the nearest AGENTS.md as the local contract and parent docs for repo-wide rules
7. If docs conflict, the closer doc controls local work details, but no child doc may weaken DOX

Do not rely on memory. Re-read the applicable DOX chain in the current session before editing.

## Re-reading on Recheck Queries

When asked to "recheck", "re-verify", "look again at", or similar re-query language for a topic, re-read the canonical source for that topic rather than relying on session memory. Session content is a cache, not a source of truth; the canonical file may have changed since it was last read. Examples: `GOALS.md` for goals, the nearest owning `AGENTS.md` for a subtree, `punkproject.toml` for project version. Re-scanning a directory for files not yet read this session is complementary, not a substitute for re-reading the canonical index.

## Update After Editing

Every meaningful change requires a DOX pass before the task is done.

Update the closest owning AGENTS.md when a change affects:

- purpose, scope, ownership, or responsibilities
- durable structure, contracts, workflows, or operating rules
- required inputs, outputs, permissions, constraints, side effects, or artifacts
- user preferences about behavior, communication, process, organization, or quality
- AGENTS.md creation, deletion, move, rename, or index contents

Update parent docs when parent-level structure, ownership, workflow, or child index changes. Update child docs when parent changes alter local rules. Remove stale or contradictory text immediately. Small edits that do not change behavior or contracts may leave docs unchanged, but the DOX pass still must happen.

## Doc Restructures

Rules for any bulk restructure, normalisation, or migration of documentation (index reshapes, field-format normalisation, file moves/renames across many docs):

- Conservation check before committing: extract the deleted lines from the diff and account for every non-blank one - it must be relocated verbatim somewhere in the new tree, be pure boilerplate/stub text (e.g. "see index (canonical)" placeholders), or be a deliberate drop named explicitly in the commit message. A preservation claim in a commit message ("bodies preserved untouched") must be backed by this check, not intent. Mechanics: `git diff | grep '^-[^-]'` (or the VCS equivalent), then `grep -F` each deleted line against the restructured files.
- Structured-field normalisation is the highest-risk step: prose riding a structured line (a status field, a header mirror) is invisible to a "preserve bodies" intent and is exactly what normalisation deletes. Relocate such prose to a body section first, then normalise.
- Separate moves from edits: a file move/rename commit is content-identical; any reconciliation edits land in an adjacent commit. Combined move+edit diffs are where losses hide.

## Hierarchy

- Root AGENTS.md is the DOX rail: project-wide instructions, global preferences, durable workflow rules, and the top-level Child DOX Index
- Child AGENTS.md files own domain-specific instructions and their own Child DOX Index
- Each parent explains what its direct children cover and what stays owned by the parent
- The closer a doc is to the work, the more specific and practical it must be

## Child Doc Shape

- Create a child AGENTS.md when a folder becomes a durable boundary with its own purpose, rules, responsibilities, workflow, materials, or quality standards
- Work Guidance must reflect the current standards of the project or user instructions; if there are no specific standards or instructions yet, leave it empty
- Verification must reflect an existing check; if no verification framework exists yet, leave it empty and update it when one exists

Default section order:
- Purpose
- Ownership
- Local Contracts
- Work Guidance
- Verification
- Child DOX Index

## Style

- Keep docs concise, current, and operational
- Document stable contracts, not diary entries
- Put broad rules in parent docs and concrete details in child docs
- Prefer direct bullets with explicit names
- Do not duplicate rules across many files unless each scope needs a local version
- Delete stale notes instead of explaining history
- Trim obvious statements, repeated rules, misplaced detail, and warnings for risks that no longer exist

## Closeout

1. Re-check changed paths against the DOX chain
2. Update nearest owning docs and any affected parents or children
3. Refresh every affected Child DOX Index
4. Remove stale or contradictory text
5. If the change altered a mechanism described in `ARCHITECTURE.md`, update or prune the affected section in the same change-set and run `tclsh scriptlib/developer/architecture_lint.tcl`
6. Re-check modified `.tm` files for new procs lacking PUNKARGS `argdoc` blocks
7. Run existing verification when relevant
8. Report any docs intentionally left unchanged and why

## User Preferences

When the user requests a durable behavior change, record it here or in the relevant child AGENTS.md

- LF line endings are strongly preferred for all files in this repository. Converting a CRLF text file to LF when an edit touches it is correct and welcome - do not preserve CRLF for diff-minimisation. Preserve existing line endings only for files with deliberately mixed/CRLF endings (e.g. line-ending round-trip test data) or when explicitly instructed for a file.
- If the active editor is on a source-derived snapshot, bootstrap copy, or generated output path such as `src/bootsupport/`, root `modules/`, root `lib/`, `modules_tcl8/`, `modules_tcl9/`, `lib_tcl8/`, or `lib_tcl9/`, confirm the intended target before editing unless the user explicitly named that path.
- cmd.exe PATH truncation (this machine, and any Windows machine with a heavily populated PATH): cmd.exe truncates a long PATH, so a tool that resolves fine in PowerShell may be "not found" when invoked via `cmd.exe /c`. Use absolute executable paths inside any `cmd /c` command line, and prefer PowerShell-native invocation unless a console host is specifically required (e.g. hidden-console test harnesses). If a tool is missing only under cmd.exe, suspect truncation before absence.
- Windows paths under POSIX shells (WSL, msys/git-bash): a `C:/...` path passed unconverted to a POSIX file command (`mkdir -p`, `cp`, output redirects) is a RELATIVE path - it silently creates a stray directory tree in the cwd whose first component is literally named `C:` (the NTFS-illegal `:` is stored as private-use character U+F03A, so it renders as `C` plus an odd dot/glyph in Explorer, and while the tree contains only empty directories it is invisible to git and fossil). Translate at the boundary (`wslpath` for WSL, `cygpath` for msys - msys auto-conversion does NOT cover paths inside quoted command strings or when MSYS_NO_PATHCONV/MSYS2_ARG_CONV_EXCL is set), and after WSL/msys-driven work glance at the repo root for a stray `C*` entry. (Origin: G-140 WSL smokes leaked an empty temp-dir skeleton into the repo root, found and removed 2026-07-31.)
- Agent-authored text is plain ASCII by default: no em/en dashes, curly quotes, arrow or ellipsis characters, or other typographic Unicode - use ASCII equivalents (" - ", straight quotes, "->", "..."). The rule governs elements the agent generates, with extra force for outward-bound artifacts (ticket drafts, bug reports, emails, commit messages - anything likely to be pasted into an external system), which are verified before handover (e.g. grep for `[^\x00-\x7F]`). The exceptions are illustrative, not a closed list: non-ASCII subject matter (encoding/Unicode/ANSI-art test data, or documentation demonstrating such behaviour), verbatim quotes of existing material, and explicit user request are the common cases, but any good reason qualifies - state the reason when deviating. Content the agent did not author is outside the rule: existing files are never bulk-retrofitted, and while checking non-authored content (e.g. files being committed on the user's behalf) is fine, non-ASCII there is the author's prerogative - if unsure whether it is intentional, stop and ask rather than fix or block.
- Tcl has no `-e`/`-c` one-liner flag (a reflex agents carry over from perl/python/node). Stock `tclsh`/`tclsh86`/`tclsh90` recognise only `-encoding name` as a leading option; any other argument starting with `-` is NOT treated as a script file - all arguments land in `$argv` and tclsh reads commands from stdin. On a console that hangs forever at an interactive prompt; with piped/redirected stdin it exits 0 having silently ignored the supposed one-liner and executed stdin instead. (The punk kits differ since G-077, achieved 2026-08-04: `<punkexe> -e <script> ?args...?` - and `<punkexe> script -e <script> ?args...?` - run the code as a one-liner with honest exit codes, so the reflex works there; stock `tclsh` still has no such flag.) To run ad-hoc Tcl: write a temp `.tcl` file and run `tclsh path/to/file.tcl`, or pipe the script to stdin (`echo 'puts hi' | tclsh`, or a bash heredoc). Defensive habit regardless: when exec'ing tclsh non-interactively, redirect stdin (`</dev/null`, `< NUL`) so a mis-invocation exits at EOF instead of hanging.
- For ad-hoc punkshell scripts that need working-tree modules, use `bin/punk91 src script` for stdin scripts, `bin/punk91 src script path/to/file.tcl` for script files, or `bin/punk91 src script -e '<code>'` for one-liners. Do not use `bin/punk91 src` for piped/redirected snippets: `src` alone starts the live shell on the repo source tree and may execute stdin input but then remain in shell/eof handling instead of exiting cleanly. Keep `src` before `script` so the working-tree modules are loaded.
- VCS ignore rules are dual-tracked (git + fossil). An agent that changes ignore rules in one VCS must make the equivalent change in the other in the same work unit: `.gitignore` is the canonical statement of intent and `.fossil-settings/ignore-glob` is hand-derived from it, never the reverse - so a `.gitignore` edit includes deriving the ignore-glob translation, and an ignore-glob-only edit is wrong unless it is purely catching up to `.gitignore`. Fossil globs differ semantically (no negation - tracked exceptions need explicit `fossil add`; case-sensitive; `*` crosses `/`): translate per the derivation rules in `.fossil-settings/AGENTS.md` and run its verification checks before committing.
- Dual-VCS commit cadence (user, 2026-07-29): in a tree tracked by both git and fossil (this repo; git is primary), agents commit each change-set to BOTH VCS in the same work unit by default - a request to commit means both, and only an explicit single-VCS instruction narrows it. The fossil checkin mirrors the git commit (same message body; new/renamed files need explicit `fossil add` / `fossil mv`). `fossil changes` never lists untracked files: a new file git-added but missed by its mirrored checkin is invisible there and surfaces only in `fossil extras`, which is normally empty in this tree - glance at it before finishing a dual-VCS work unit and treat any entry as drift to disposition (drift instance 2026-08-01: two .test files git-added in the G-123/G-127 increments, never fossil-added). Before the fossil checkin, run `fossil changes` and look for pending material beyond the current change-set: the developer may commit to git manually and let fossil lag, and a plain `fossil commit` sweeps everything pending - when lag is present, either land a separate catch-up checkin first, or fold the lag in with a message naming the covered git commits (per-change rationale stays in git history; the catch-up message summarizes). Coexistence mechanics (ignore sync, CRLF prompt avoidance, tracked-set verification) are in `.fossil-settings/AGENTS.md`.
- Commit granularity and cadence (user, 2026-08-04): lean towards larger commits when splitting would add complexity - a new goal drafted from discussion during another goal's implementation may land in the same commit as the work that spawned it (or one goals-tier commit covering both); do not do partial-hunk staging gymnastics to keep per-goal commits "pure" (e.g. two goals' hunks in GOALS.md). Corollary: do not let the uncommitted set grow to where the natural split gets complicated - agents should OFFER to commit at appropriate points as work proceeds (a green test gate, a coherent sub-change complete, before starting a new concern), naming the proposed batch(es); committing still happens only at the user's word.
- Throwaway fossil repositories (test/experiment repos an agent creates, e.g. in a session scratchpad) must not register in the user's real global fossil config-db: `fossil init`/`fossil open` write persistent `repo:`/`ckout:` rows into `%LOCALAPPDATA%\_fossil`, which is the enumeration source for `dev projects.work` project discovery (G-016/G-017). Set `FOSSIL_HOME` to a disposable scratch directory for the duration of such fossil commands (both fossil and `punk::repo::fossil_get_configdb` honour it first). If pollution has already occurred: `fossil all ignore <repo-path>`, delete the directory, then any `fossil all` command prunes the orphaned `ckout:` row.
- Fossil checkout branch discipline: in fossil, `tip` means the newest check-in on ANY branch - not the trunk tip. A `fossil open ... tip` or `fossil update tip` run shortly after an upstream feature-branch commit silently parks the checkout on that branch, and every later plain `fossil update` keeps following it. When opening or refreshing any fossil checkout (including reference checkouts such as `TEMP_REFERENCE/tcl9`), name the branch explicitly (`fossil update trunk`), never `tip`, and confirm the `tags:` line of `fossil status` shows the intended branch afterwards.
- Do not commit new executable binaries (shared libs, .exe, native .so/.dll/.dylib, bare ELF/Mach-O, or zip-based .tm modules embedding executables) to the repository. Existing binaries in `bin/`, `src/vfs/`, `src/vendorlib/`, `src/vendormodules/`, and `src/bootsupport/` are there intentionally pending the build/retrieval infrastructure tracked by goals G-004/G-005/G-006; do not flag, "fix", or hassle the developer about these — they are known and will be removed once G-005 (zig build) or G-006 (pre-built download) provides an alternative. This rule stops agents from adding new binaries; it does not block the developer's interim commits of existing vendor/vfs binaries. It is workflow policy only - deliberately NOT enforced at the local VCS layer: fossil `binary-glob` is `*` (versioned in `.fossil-settings/`) so binary checkins proceed without warnings/prompts, here and in sub-projects like tomlish.
- International English idiom discipline (user, 2026-08-05): agent-authored prose must avoid idioms whose meaning differs or reverses across English variants (US vs UK/AU). Known traps: 'to table' something (US: postpone; UK/AU: put forward) - for table-formatted punk::args output write 'tabular usage'/'tabular help', never 'tabled' (legacy 'tabled' survives in code comments/strings and archived goal records); 'momentarily' (US: soon; UK/AU: for a moment); 'presently' (currently vs soon); 'moot' (US: irrelevant; UK/AU: debatable); 'punt' (US: defer/give up; AU: have a go/gamble); 'luck out' (US: got lucky; elsewhere often read as ran out of luck); 'out of pocket' (US slang: unreachable; elsewhere: paying one's own costs); 'bi-weekly'/'bi-monthly' (ambiguous everywhere - state the period explicitly); 'fortnight' (unfamiliar to many US readers); 'knock back' (AU: reject); 'on the nose' (US: exactly right; AU: smells off/suspect); 'quite <adjective>' (UK: mild downgrade; US: intensifier). Widely adopted technical slang (dogfooding, spike testing, smoke test) is fine. When unsure, prefer plain literal phrasing.

## Commit Conventions (any VCS)

These conventions apply to every VCS commit an agent makes - git commits and fossil checkins alike. Projects generated from punkshell layouts start fossil-only but may adopt git (punkshell itself is currently git-primary); the conventions are VCS-neutral by design and are seeded into generated projects, where the project developer may change them.

- Never add "Co-Authored-By" lines or any AI-attribution footers to commit messages.
- When an agent constructs and executes the commit command itself (`git commit`, `fossil commit` - staging, composing the message, and committing), it must append one `Assisted-by` trailer as the last line of the commit message. If the user commits manually, no trailer is required. (git parses trailers structurally; fossil checkin comments are free text - in both cases the convention is simply the last line of the message.)
- Trailer format (single line, semicolon-separated key=value):
  `Assisted-by: harness=<harness>; primary-model=<model-id>; api-location=<domain|localhost|localnet|unknown>`
  Examples:
  `Assisted-by: harness=opencode; primary-model=openrouter/z-ai/glm-5.2; api-location=openrouter.ai`
  `Assisted-by: harness=opencode; primary-model=lmstudio/qwen3-coder-next; api-location=localnet`
- `harness`: derived from the agent identity / system prompt. Values: `opencode`, `claude`, `pi`, `hermes`, `codex`, or `unknown`.
- `primary-model`: the exact model ID string from the system prompt (e.g. `openrouter/z-ai/glm-5.2`). No transformation.
- `api-location`: best-effort, derived in this order:
  1. If the provider prefix (segment before `/` in the model ID) is in the table below, use the listed domain.
  2. Else if the provider is a known local-LLM provider (`lmstudio`, `ollama`, `llamacpp`, `vllm`, `koboldcpp`, `llama.cpp`), attempt to read the harness config for the `baseURL`: RFC1918 address → `localnet`; `127.0.0.1` or `localhost` → `localhost`; otherwise the hostname from the URL.
  3. Else → `unknown`.
  Known public provider table:
  | Provider prefix | api-location |
  |---|---|
  | `openrouter` | `openrouter.ai` |
  | `anthropic` | `anthropic.com` |
  | `openai` | `openai.com` |
  | `google` | `googleapis.com` |
  | `mistral` | `mistral.ai` |
  | `groq` | `groq.com` |
  | `together` | `together.ai` |
  | `deepseek` | `deepseek.com` |
  | `huggingface` | `huggingface.co` |
  | `x-ai` / `xai` | `x.ai` |
- `secondary-models` is intentionally omitted (not reliably introspectable). May be added later if a harness surfaces subagent model info.
- The `Assisted-by` trailer describes tooling, not authorship; it does not replace or conflict with the `Co-Authored-By` ban above.
- Change-set sizing and cadence (when to split vs combine, and offering to commit at seams): see the commit-granularity bullet in User Preferences.

## Project Versioning

The punkshell project version is tracked in `punkproject.toml` (`[project] version`) at the repo root and is independent of individual module versions (those live in `src/modules/*-buildversion.txt` per `src/modules/AGENTS.md` "Versioning And Releases"). The project version describes the user-visible punkshell product, not any single module.

### Bump policy (change-driven)

An agent must bump the `punkproject.toml` version as part of its DOX closeout pass whenever its change ships user-visible shell behaviour. This is change-driven, not release-driven — the version stays honest between releases.

- **Patch** — bug fixes, internal refactors, doc-only updates that ship in baked kits without changing user-facing shell behaviour.
- **Minor** — new shell commands, new launchers, new default modules visible at the REPL, backward-compatible behaviour additions.
- **Major** — removed commands, changed default behaviour, changed launch invocation, breaking changes to the shell's user-facing contract.

Changes confined to tests, make tooling internals, or non-shipped surfaces do not require a bump. When in doubt, bump patch.

The `make.tcl` command interface is part of the product surface: new subcommands, changed subcommand behaviour, or removed subcommands warrant at least a patch bump. Internal refactors of an existing subcommand's implementation that leave its interface and output unchanged stay exempt as make tooling internals.

### Changelog

Every version bump must add a corresponding entry to `CHANGELOG.md` at the repo root. The latest `## [X.Y.Z]` header in that file must match the `version` field in `punkproject.toml`. Entries are newest-first, one bullet per notable change.

### The version is a bake input (bump BEFORE bake)

`make.tcl bake` reads `punkproject.toml` at bake time: the version is stamped into every kit's `punkkit-stamp.toml` (`project_version`, surfaced by `<kit> buildinfo`) and derives the `versioned`-scheme output names. The bump therefore belongs BEFORE the bake — release-sequence step (2) vs step (8) in `make.tcl workflow` is a data dependency, not a convention. Bumping after a bake mis-stamps every kit and costs a full re-bake to correct. Do not invert the documented order on a speculative concern without falsifying the concern first (the 2026-08-06 inversion feared `versioned`-scheme name churn that `bakelist` already showed to be moot — `default=no` entries are skipped by a bare bake).

### Enforcement

`tclsh src/make.tcl projectversion` is a read-only check (never aborts, only warns) that:
1. Verifies the `CHANGELOG.md` latest version header matches `punkproject.toml`.
2. Checks whether `src/` has git commits since the last commit touching `punkproject.toml`; if so, warns that a project-version bump may be overdue.

The check is advisory — it catches forgotten bumps, not hard errors. Agents should run it during closeout for any `src/` change that ships behaviour, alongside existing `make.tcl` verification.

The same computation gates the kit-assembling commands (`bake`, `bakehouse`, `bin`) as the **project-version gate** (2026-08-06): when a bump looks pending (`src/` commits since `punkproject.toml` last changed, none staged), an interactive terminal run is prompted (y/N, default No) and a non-interactive run aborts fast unless the intended version is asserted with `-expect-projectversion <ver>`. A supplied assertion is verified in every state — a mismatch with `punkproject.toml` always aborts before any kit work. `-confirm 0` deliberately does NOT waive this gate: agent runs pass `-confirm 0` habitually, and the gate exists to interrupt habit with a checked claim (a version to assert, not a boolean to wave through). A staged-but-uncommitted bump passes the gate — bake reads the working-tree value. `tclsh src/make.tcl check` reports the gate state and the current staleness verdict.

### Relationship to module versions

The project version is fully independent of module versions. A module bump (even a major one) does not force a project bump unless the module's change is itself user-visible at the shell level. Conversely, a project bump does not require bumping any module.

## Child DOX Index

- `src/` — Source tree root; editable source code, make.tcl tooling, tests, VFS payloads, vendor deps, docs (see src/AGENTS.md)
  - `src/modules/` — Main editable module source (see src/modules/AGENTS.md)
    - `src/modules/punk/` — Core punk namespace modules (see src/modules/punk/AGENTS.md)
    - `src/modules/test/` — Installed-module test packages (see src/modules/test/AGENTS.md)
    - `src/modules/opunk/` — Alternative punk namespace, voo-based classes (see src/modules/opunk/AGENTS.md)
    - `src/modules/punkcheck/` — Install/provenance-check system
  - `src/modules_tcl8/` — Tcl 8 specific modules (see src/modules_tcl8/AGENTS.md)
  - `src/modules_tcl9/` — Tcl 9 specific modules (see src/modules_tcl9/AGENTS.md)
  - `src/lib/` — Editable library source (see src/lib/AGENTS.md)
  - `src/lib_tcl8/` — Tcl 8 specific libraries
  - `src/lib_tcl9/` — Tcl 9 specific libraries
  - `src/bootsupport/` — Early-load bootstrap modules (see src/bootsupport/AGENTS.md)
  - `src/tests/` — Source-tree test harness and tests (see src/tests/AGENTS.md)
  - `src/vfs/` — Virtual file system images for builds (see src/vfs/AGENTS.md)
  - `src/scriptapps/` — Entry-point scripts for Punk apps (see src/scriptapps/AGENTS.md)
  - `src/vendormodules/` — Third-party bundled modules (see src/vendormodules/AGENTS.md)
  - `src/vendorlib/` — Third-party bundled libraries (see src/vendorlib/AGENTS.md)
  - `src/vendorlib_tcl8/` — Tcl 8 specific vendor libraries
  - `src/vendorlib_tcl9/` — Tcl 9 specific vendor libraries
  - `src/runtime/` — Build runtimes and VFS config (see src/runtime/AGENTS.md)
  - `src/doc/` — Generated documentation (see src/doc/AGENTS.md)
  - `src/assets/logo/` — Project logo vector masters (`punk-mark.svg`, solid-plate alternate) and the multi-resolution `.ico` files generated from them; the icon MASTER, distinct from the build-consumed copies at `src/runtime/punkshell.ico` and `src/vfs/_vfscommon.vfs/punkshell.ico`. Retired pre-2026-07 artwork kept under `legacy/` as `punk1.*` - the only place that legacy name survives (see src/assets/logo/AGENTS.md)
  - `src/testansi/` — Sample ANSI art files (do not modify)
- `bin/` — Built punk shell executables, launch package modes (incl. `src` mode for working-tree verification), plain runtime kits (see bin/AGENTS.md)
- `.fossil-settings/` — Versioned fossil settings and the git+fossil dual-VCS coexistence contract: ignore-sync rules, files neither system may track (see .fossil-settings/AGENTS.md)
- `.agents/skills/` — Project agent skills in the cross-framework Agent Skills SKILL.md format (read natively by pi, OpenCode, Codex and others). Canonical home; `.claude/skills/` holds byte-identical copies for Claude Code discovery - edit under `.agents/skills/` and re-copy, verify sync with a plain diff (no child AGENTS.md)
- `GOALS.md` — Top-level technical goal index, summary-only (ID, status, title, scope, detail pointer per goal); required read for non-trivial work (no child AGENTS.md; the file documents its own format, read workflow, the agent goal-authoring workflow, and the canonical goals-system version definition)
- `GOALS-archive.md` — Summary records of achieved goals moved out of the active index (historical context only)
- `ARCHITECTURE.md` - Descriptive current-state map of punkshell system mechanics (boot/launch, interp/thread topology, console abstraction, module loading, build/provenance/kits, test harness, shutdown/finalization). Own lane beside DOX and the goals system: AGENTS.md files say what you must do, GOALS.md/goals say what changed and why, ARCHITECTURE.md says how it works now. Read for orientation before non-trivial work in an unfamiliar subsystem. Pointer-first and current-state only - never transcribe content owned by another doc; keep sections durable and thin. Verified by `tclsh scriptlib/developer/architecture_lint.tcl` (referenced paths exist, goal references resolve, size budget) - run it after editing the file (no child AGENTS.md; the file's front matter carries its own contract)
- `goals/` — Per-goal detail files carrying the canonical Goal/Acceptance contract prose plus supporting detail (see goals/AGENTS.md)
  - `goals/archive/` — Detail files for achieved/archived goals
- `TEMP_REFERENCE/` - Reference-only material for agents, not a work folder; ignored by both git and fossil, so its contents (including its AGENTS.md) are machine-local and unversioned. Holds the nested fossil checkout of the Tcl core sources at `TEMP_REFERENCE/tcl9`, which must stay on `trunk` per the fossil branch-discipline rule in User Preferences (see TEMP_REFERENCE/AGENTS.md when present)
- Directories agents should not directly modify (no child DOX needed):
  - `callbacks/` — Experimental shellspy features, user-only
  - `scriptlib/` — Shared utilities + manual tests, user-only. EXCEPTIONS: `scriptlib/_punktest/` is test-owned (fixtures for `src/tests/shell/testsuites/punkexe/scriptexec.test`, resolved via `lib:_punktest/<name>`); agents may manage that subfolder as part of test work. `scriptlib/developer/` holds agent-authored developer showcase/demo apps and developer utility scripts (created at user request 2026-07-11, e.g `tkconsole_demo.tcl` for the G-001 tk console backend, `goals_lint.tcl` for the goals doc contracts per goals/AGENTS.md Verification, `goals_xref.tcl` goals cross-reference/scope-overlap analysis (unlinked overlap pairs, path-intersection queries, dangling refs) per goals/AGENTS.md Verification, `whatis.tcl` runtime command introspection backing the `tcl-whatis` agent skill, `nslist.tcl` runtime namespace/package discovery backing the `tcl-nslist` agent skill, `runtests_parity.tcl` comparing `runtests.tcl -report json` outputs for result parity between runner modes per src/tests/AGENTS.md Verification, `architecture_lint.tcl` validating root `ARCHITECTURE.md` references - path existence, goal-id resolution, size budget, `assetorigin_check.tcl` classifying assets against their `*.assetorigin.toml` provenance sidecars per the format in `src/assets/logo/AGENTS.md` - six advisory states, fixture selftest, plain tclsh, `cpufloor_audit.tcl` the G-172 distributed-binary CPU-floor audit instrument (disassembles a binary's .text via a located objdump, or audits a pre-disassembled excerpt, and reports AVX-register-width instructions above a declared floor; bundled real-disassembly fixtures in `scriptlib/developer/cpufloor_fixtures/` + a `-selftest`); agents may add or update entries there when the user asks for one. The rest of `scriptlib/` stays user-only.
  - `bin/` — Built binaries and helpers, build output target. This includes the polyglot `.cmd` launcher/utility scripts (e.g `bin/punk-runtime.cmd`): they are GENERATED by the punk::mix scriptwrap machinery from sources under `src/scriptapps/` — a request to "fix bin/<name>.cmd" means editing `src/scriptapps/<name>.*` + `<name>_wrap.toml` and re-wrapping (see bin/AGENTS.md), never editing the output
  - `modules/` (root) — Build output target for `tclsh src/make.tcl modules`
  - `lib/` (root) — Build output target for `tclsh src/make.tcl libs`
  - `modules_tcl8/`, `modules_tcl9/` — Tcl version-specific build output targets
  - `lib_tcl8/`, `lib_tcl9/` — Tcl version-specific build output targets
  - `src/project_layouts/` — Thin project layout payloads (structure, scripts, docs, manifests - no stored bootsupport/vfs module snapshots; G-087, achieved - see goals/archive/G-087-thin-project-layouts.md). The build's thin-layout sync step (`make.tcl modules`/`libs`/`packages`/`bakehouse`) keeps each layout's `src/make.tcl`, `src/build.tcl` and bootsupport `include_modules.config` copies current, refreshes every vendor/punk layout's inert `gitignore.in` payload from the canonical root `.gitignore` (G-012 - VCS-config payloads are stored inert and materialized to their live name at project generation; never store a literal `.gitignore` in a layout), and syncs the punk.project payload into the `punk::mix::templates` modpod source tree; `dev project.new` composes each layout's overlay chain (vendor then custom tier, `<name>@<base>` derived folders, `.anti` deletion markers - see the store README) via `layout_materialize`, injects bootsupport modules/libs from the generating shell at generation time, and seeds generated-project identity metadata (punkproject.toml, CHANGELOG.md, punkorigin.toml provenance baseline) programmatically. Agents must not directly edit files under `src/project_layouts/` unless the user explicitly names a path there or specifically requests layout changes; never hand-edit the synced copies (they are punkcheck-managed build outputs).

## Repo-wide Notes

- Punkshell (a.k.a. Punk Shell) is an experimental, alpha-level alternative Tcl shell licensed under BSD-2-Clause (see `LICENSE.txt` at the repo root); its primary language is Tcl. Note: "shellspy" (lowercase) refers only to the experimental `shellspy` subcommand available at launch — it is not the project name.
- The project extends Tcl with ANSI terminal capabilities, functional and pattern-matching language features, and a comprehensive module ecosystem.
- This root file is intentionally limited to DOX governance, global ownership boundaries, and the top-level Child DOX Index.
- Source-tree build, testing, linting, and file-resolution workflow lives in `src/AGENTS.md`.
- Runtime Tcl introspection DIRECTIVE for agents: to locate or characterize a Tcl command (definition site, calling interface, loaded module version, runtime body - including subcommand-chain resolution e.g `string is`), run `punk91 src script lib:developer/whatis ?-body? ?-doc? <command> ?subcommand?...` FIRST; to discover what a namespace/package exposes (before writing a new helper, or when starting work in a namespace), run `punk91 src script lib:developer/nslist ?-synopsis? ?-pathcommands? <nsglob>...` FIRST. Reserve grep for full-text/source-pattern searches: this repo has several coexisting copies of many modules, and grep alone cannot tell you which copy is actually loaded. Both are single sub-1s side-effect-free invocations from the repo root (`punk91` lives in `bin/`; `lib:developer/<name>` = `scriptlib/developer/<name>.tcl`). Full usage and caveats: `.agents/skills/tcl-whatis/SKILL.md` and `.agents/skills/tcl-nslist/SKILL.md`.
- Tcl module authoring conventions live in `src/modules/AGENTS.md` and closer module child docs.
- If AGENTS.md conflicts with CLAUDE.md, AGENTS.md wins.
- Technical project goals live in root `GOALS.md` (summary index: ID, status, title, scope, detail pointer per goal) with the canonical Goal/Acceptance contract prose in `goals/G-<id>-<slug>.md` detail files - read the detail file of every goal whose scope intersects paths being edited. Goals are user-owned: agents add or edit goal contract elements (in either tier) only at the user's request, proposal-first (show the proposed wording, get explicit approval before writing - see the `GOALS.md` maintenance rules); never on their own initiative. Suggesting candidate goals when work surfaces something goal-worthy is welcome and encouraged - as a flagged proposal, not a file edit. Non-contract detail-file updates from user-directed work need only be reported in the completion summary. Agents auto-flip a goal to `achieved <date>` when its detail-file acceptance criterion is met as part of the DOX closeout pass - the flip includes archiving the entry to `GOALS-archive.md` and the detail file to `goals/archive/`. `proposed` -> `active` flips follow the two-path rule in the `GOALS.md` maintenance rules: an explicit user instruction to activate (including "work on / implement G-<id>" for a proposed goal) is the confirmation - flip it as part of the work and report it; agents never activate on their own initiative, they flag the candidate instead. See `GOALS.md` for the full workflow, including how to author a new goal when asked.