add goal G-030: make.tcl dogfoods punk::args; record session observations

G-030 (proposed): make.tcl - the first surface a developer sees - parses
subcommands/options via punk::args and showcases the tabled usage for
help and argument errors; every interactive y/n prompt gains a declared
flag equivalent (interactive stdin prompts as today; flag proceeds;
non-interactive stdin without the flag fails fast with usage instead of
hanging or half-aborting) so agents drive make.tcl with arguments rather
than piped y/n; punk::args joins the bootstrap-tracked staleness set.
Degradation is a hard requirement: boot stays self-contained and the
repair commands (check/bootsupport/modules) keep working with plain
fallback help when the bootsupport punk::args or the ANSI rendering
stack is stale/unavailable - this week''s stale-fileutil and
stale-textblock incidents are the cautionary tales.

G-015 detail: recorded the runx -tcl result-shape observation (dict keyed
{result stdout stderr}, no exitcode key unlike exec mode).

G-020 detail: stamped the 2026-07-07 decision - acceptance gates on a
full testable Windows system without requiring other platforms first.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

GOALS.md

@@ -222,3 +222,9 @@ Scope: src/make.tcl (test-module packaging step), src/tests/ (source of truth),
 Detail: goals/G-029-testmodules-from-srctests.md
 Goal: src/tests is the single source of truth for module test suites - a punkcheck-tracked make.tcl step generates the packaged test::<modulename> #modpod modules from src/tests/modules/<namespacepath>/testsuites content, ending hand-maintenance of parallel copies under src/modules/test/; the packaged form is a distributable in its own right - a user who downloads a built module can optionally download the matching test::<modulename> and verify the module's behaviour on their own system (package require + RUN, or an executable's -app test) with no source tree or test harness required.
 Acceptance: a make.tcl step generates a test::<modulename> #modpod under src/modules/test/ from the corresponding src/tests testsuites (punkcheck-tracked, skipped when sources unchanged); the generated package works through the packaged path - loadable via package require test::<modulename> and runnable via its SUITE/RUN interface (e.g a built executable's -app test) - reporting the same test names and pass counts as running the same suites directly via src/tests/runtests.tcl; the consumer scenario is proven standalone: the generated package (plus the module under test and their dependencies) runs in an environment without the project source tree present; suite data files (e.g roundtrip toml files with deliberate crlf/mixed line endings) survive packaging byte-for-byte; documentation states src/tests is the source of truth and the generated modpods are build artifacts not to be hand-edited; proven end-to-end for at least one real module (tomlish, whose src/tests port and still-live modpod created the dual-copy situation, is the natural first).
+
+### G-030 [proposed] make.tcl dogfoods punk::args: tabled usage, declared subcommands, prompt-free flags
+Scope: src/make.tcl (dispatch, help, prompts), src/bootsupport/AGENTS.md + src/modules/AGENTS.md (bootstrap-tracked staleness contract), src/modules/punk/args-999999.0a1.0.tm (only as consumed)
+Detail: goals/G-030-maketcl-punkargs.md
+Goal: make.tcl - the first surface a developer sees - parses its subcommands and options via punk::args and showcases the tabled usage output for help and argument errors, every interactive y/n prompt gains a declared flag equivalent so agents can drive make.tcl with arguments instead of piped input, punk::args joins the bootstrap-tracked staleness set, and the boot phase plus the environment-repair commands keep working with degraded plain help when the bootsupport punk::args (or the table-rendering stack) is stale or unavailable.
+Acceptance: `tclsh src/make.tcl` and `-help` render punk::args tabled usage listing every subcommand with a summary, and `make.tcl help <subcommand>` (or `<subcommand> -help`) shows that subcommand's definition; invalid arguments produce a punk::args usage error rather than ad-hoc messages; every y/n prompt has a documented flag equivalent (proven at least for vfscommonupdate and the project-build confirmations: a run with the flag completes non-interactively with stdin closed) and a non-interactive stdin without the flag fails fast with usage rather than hanging or half-aborting; punk::args is added to the bootstrap-tracked buildversion set with the doc contract updated (src/bootsupport/AGENTS.md, src/modules/AGENTS.md); with bootsupport punk::args unavailable or unloadable, make.tcl still boots and `check`, `bootsupport` and `modules` remain usable with plain-text fallback help (the guarded-require degrade rule); layout make.tcl copies follow via the established sync/G-027 channels (noted, not hand-synced).

goals/G-015-script-subcommand-piped-stdin.md

@@ -78,6 +78,11 @@ punk_main.tcl's `punk` subcommand case).
 
 ## Notes
 
+- Result-shape observation (2026-07-07): `shellrun::runx -tcl` returns a dict
+  keyed {result stdout stderr} with NO exitcode key, unlike the exec-mode
+  result (exitinfo with exitcode) - callers doing `dict get $result exitcode`
+  error. Possibly by design for in-process eval, but the script-path work here
+  should document (or normalise) the result shapes agents will consume.
 - The eof policy machinery (PUNK_PIPE_EOF exit/interactive/heuristic) in
   app-punkshell (~punkshell.tcl 466-507) stays as-is for the `shell` subcommand;
   this goal does not change interactive-shell behaviour.

goals/G-020-screencap-input-module.md

@@ -55,9 +55,11 @@ the module is a separate development, not a refactor of it.
   Per-platform backend selection with capability introspection - callers ask
   what is supported rather than probing by failure. Echoes the G-001 pluggable
   pattern.
-- Windows backend first and complete (acceptance gates on it). X11 and macOS
+- Windows backend first and complete (acceptance gates on it - confirmed
-  backends are in-scope follow-ons behind the same contract; their absence on a
+  2026-07-07: a full testable system on Windows must be reachable without
-  platform must produce a clean capability-based refusal.
+  first implementing the other platforms). X11 and macOS backends are
+  in-scope follow-ons behind the same contract; their absence on a platform
+  must produce a clean capability-based refusal.
 - Output normalization: capture lands in a Tk photo; PNG via Tk's core photo
   support (Img optional for other formats). File save and in-memory (base64)
   both supported - the G-021 consumer needs both.

goals/G-030-maketcl-punkargs.md

@@ -0,0 +1,75 @@
+# G-030 make.tcl dogfoods punk::args: tabled usage, declared subcommands, prompt-free flags
+
+Status: proposed
+Scope: src/make.tcl (dispatch, help, prompts), src/bootsupport/AGENTS.md + src/modules/AGENTS.md (bootstrap-tracked staleness contract), src/modules/punk/args-999999.0a1.0.tm (only as consumed)
+Acceptance: as in root GOALS.md index (canonical).
+
+## Context
+
+make.tcl is the first surface a developer meets in a punkshell-derived project,
+but its command handling predates the ecosystem's own tooling: a hand-built
+help text, a bare `known_commands` list, ad-hoc argument handling per
+subcommand, and interactive y/n prompts (`vfscommonupdate`'s REPLACE
+confirmation, the project-build confirmations, bootsupport staleness prompts).
+Eating our own dogfood - punk::args definitions per subcommand with the tabled
+usage rendering - both showcases the ecosystem where it is most visible and
+makes the parsing declarative.
+
+The prompts are the practical payoff: agent-driven builds currently pipe `y`
+into stdin (fragile, undiscoverable - observed 2026-07-07 while rebuilding
+tomlish.exe). With punk::args parsing, prompt-free operation is just another
+declared option per subcommand, and non-interactive stdin without the flag can
+fail fast with usage instead of hanging on a read or half-aborting.
+
+Precedents already in-tree: src/tests/runtests.tcl parses via punk::args
+((script)::runtests definition), and the tomlish cmdline app presents tabled
+usage as its first surface.
+
+## Approach
+
+- One PUNKARGS definition per subcommand (@cmd -summary/-help + opts), plus a
+  top-level definition enumerating subcommands - replacing punkboot_gethelp
+  and the hand-maintained help strings. `make.tcl`, `make.tcl -help`, and
+  per-subcommand help all render through punk::args::usage.
+- Prompt policy: interactive stdin -> prompt as today (default); flag supplied
+  (e.g. -confirm 0 / -y, naming decision recorded here) -> proceed without
+  prompting; non-interactive stdin without the flag -> usage error, fast.
+  The bootsupport staleness prompt keeps its abort/prompt/proceed
+  classification but gains the same flag route.
+- **Degradation is a hard requirement** (the 2026-07-06/07 incidents are the
+  cautionary tale: a stale bundled fileutil disabled the very make.tcl step
+  needed to fix it). The boot phase stays self-contained; punk::args is
+  guarded-lazily required post-boot (the punkboot::utils pattern documented in
+  src/bootsupport/AGENTS.md); when unavailable, dispatch and the repair
+  commands (check, bootsupport, modules) keep working with plain-text fallback
+  help. Note the tabled rendering also pulls punk::ansi/textblock/punk::char -
+  exactly the modules whose same-version staleness broke shellfilter this week
+  - so rendering must degrade independently of parsing (punk::args plain
+  output when the ANSI stack is unhealthy).
+- Staleness tracking: punk::args joins the bootstrap-tracked buildversion set
+  (currently punkcheck, punk::repo, punk::mix, punk::tdl) with the same
+  bump-at-least-minor-on-call-site-API-change discipline; whether the
+  rendering stack is also tracked or left to degrade is an implementation
+  decision to record here (initial lean: track punk::args only - it is the
+  parsing contract; rendering degrades).
+- Layout copies of make.tcl follow through the existing punkcheck-tracked
+  sync (custom/_project) and the G-012/G-027 channels for the rest - noted in
+  completion reports, never hand-synced.
+
+## Alternatives considered
+
+- Ad-hoc -y flags bolted onto the current hand parsing - rejected: solves the
+  agent problem but leaves the first-surface help un-showcased and the parsing
+  divergent from the ecosystem's own conventions.
+- Requiring punk::args at boot (no fallback) - rejected: make.tcl must be able
+  to repair the very bootsupport snapshot it loads punk::args from.
+
+## Notes
+
+- Related: G-015 (agents driving punk tooling non-interactively), G-024
+  (mapvfs toml errors deserve the same declared-argument quality), G-025 (the
+  version-report subcommand should be born punk::args-defined), G-027 (pull
+  updates deliver the improved make.tcl to derived projects).
+- Observation parked here from the same session: runtests/make.tcl-adjacent
+  tooling that returns result dicts should document their key shape (see the
+  runx -tcl exitcode note in G-015's detail).