punkshell/goals/archive/G-149-punkargs-formhint-labels.md

G-149 punk::args: configurable multi-form synopsis hint labels

Status: achieved 2026-08-05 Scope: src/modules/punk/args-999999.0a1.0.tm (usage/arg_error multi-form Synopsis hint column); src/tests/modules/punk/args/testsuites/args/ Goal: The per-form hint labels rendered beside a multi-form definition's Synopsis lines (hard-coded ' i -form N ...' today) are configurable - a definition or rendering caller can supply its own hint text (parameterized by form index/name) or suppress the column - so consumers whose users cannot type 'i' (script-level definitions like make.tcl's, whose (script) ids are unreachable from any repl) show an actionable hint, while unconfigured definitions keep the current repl-oriented default. Acceptance: a punk::args mechanism (definition directive and/or usage/arg_error caller option) replaces the ' i -form N ...' hint labels with caller-supplied text and can suppress the column entirely; unconfigured definitions render byte-identical to today (existing synopsis/usage/arg_error pins pass unchanged); the mechanism is pinned in the args testsuite. make.tcl adopting it (e.g a 'make.tcl help tool ' phrasing) is recorded as consumer follow-through after a bootsupport promotion, not part of this acceptance.

Context

Identified during G-143 (achieved 2026-08-01 - goals/archive/G-143-maketcl-multiform-help.md): multi-form usage tables render ' i -form N ...' beside each form's synopsis line, hard-coded in the renderer (bootsupport args-0.13.0.tm ~5475; same code in the dev module). The wording is repl-centric and doubly inapplicable in make.tcl output - 'i' is not a make.tcl surface, and (script)-scoped ids exist only inside a running make.tcl process, so no repl can address them. make.tcl meanwhile has its own per-form navigation the hint could name ('make.tcl help ' - G-143's dry-run help).

Notes

• Related: G-050 (proposed) - synopsis argument-validity marking; same renderer surface, independent mechanism.
• Related: G-056 (proposed) - display-time word wrapping for help content; sibling render-surface work.
• Related: G-151 (proposed) - annotated success render; sibling punk::args render-surface goal drafted the same session.
• Related: G-167 (proposed) - version-delta availability; drafted 2026-08-05, touches the same multi-form synopsis renderer surface (annotated form lines beside the same hint column). Found by the activation-freshness overlap survey 2026-08-05. Composition note at achievement: this goal's template governs the LEFT label column of the Synopsis header cell; G-167's annotations mark the synopsis form lines themselves (right column) - the mechanisms compose without collision, and per G-167's Notes the shared marking vocabulary is owned by whichever of its sibling surfaces lands next.
• Origin: G-144 (achieved 2026-08-01 - goals/archive/G-144-punkargs-synopsis-name-fallback.md) shipped the @cmd -name auto-synopsis lines these hints sit beside.
• Overlap survey 2026-08-02: goals_xref paths src/modules/punk/args-999999.0a1.0.tm - the punkargs family (G-044 G-050 G-053 G-056 G-069 G-072 G-073 G-075 G-083 G-084 G-088); besides those named above the family entries are parser/spec mechanisms unrelated to the hint column. Consumer side: make.tcl's argdoc (src/AGENTS.md make.tcl bullet) after a bootsupport promotion.

Progress

Achieved 2026-08-05 in one session (activated and implemented same day; punk::args 0.17.0, punkshell 0.55.0).

Mechanism landed (both arms of the "definition directive and/or caller option" acceptance):

• Definition directive: @cmd -formhint <template>. Rides the existing @cmd arbitrary-key merge into cmd_info - no resolver change; round-trips through punk::args::resolved_def (whole-dict emission) automatically; not part of the G-046 display-deferral set (only -help defers), so the renderer reads it directly. Documented in the define -help @cmd directive-options.
• Caller option: -formhint <template> on arg_error (manual dict-for parser + PUNKARGS block); usage pulls it from arg_error's definition via its existing resolved_def opts pull and passes it through. Supplied-empty is distinct from not-supplied (formhint_received flag; the option declares no -default so an unsupplied usage call passes nothing through - proven by the byte-identity capture below running THROUGH the usage path).
• Template semantics: rendered once per form; %formindex% -> 0-based ordinal, %formname% -> form name (string map; the repo's %...% placeholder convention). Empty template (from either source) suppresses the hint lines - the cell keeps just the Synopsis: label, as single-form renders always have. Precedence: caller > definition > built-in default " i -form %formindex% <U+2026>" (substitutes to the exact prior bytes).
• Scope decisions (deliberate, pinned): single-form definitions never render hint labels (unchanged - the column is multi-form only); the -return string renderer has no hint column and is unchanged.

Verification evidence:

• Byte-identity: pre/post-change captures of punk::args::usage ::punk::args::parse (multi-form, unconfigured) via bin/punk91 src script byte-identical apart from a boot-noise threadid line outside the render.
• New suite src/tests/modules/punk/args/testsuites/args/formhint.test (9 tests): default labels, single-form scope, directive template + cmd_info round-trip, directive suppression, caller override, caller supplied-empty suppression, arg_error direct option, parse-failure path using the directive, string-renderer scope.
• Full modules/punk/args subtree: 302 tests, 0 failed (3 pre-existing skips) on BOTH tclsh90 (Tcl 9.0.3) and the punk86 kit (Tcl 8.6) - existing synopsis/usage/arg_error pins pass unchanged per acceptance.
• Adjacent consumer: modules/punk/ns subtree 115/115 on tclsh90 (cmdhelp renders through the same machinery).
• make.tcl's own help (bootsupport punk::args) is untouched until promotion; src/tests/shell/testsuites/punkexe/maketclhelp.test continues to pin the current ' i -form 0 ' hint there.

Follow-ons

Follow-on: make.tcl adopts the mechanism for its (script)::punkboot definitions (e.g a 'make.tcl help ' hint phrasing via @cmd -formhint) after a bootsupport promotion carrying punk::args 0.17.0- (maketclhelp.test formhints pin updates with it) => landed 2026-08-05 (make.tcl tool+buildsuite @cmd -formhint " make.tcl help _{%formname% <U+2026>" - trailing ellipsis marks the dry-run continuation help accepts after the action (user direction: a hint without it misrepresents the line as complete); template kept over empty-string suppression because the labels also render on dispatch usage errors, where they are the discovery route to per-action help; punkshell 0.55.1; maketclhelp.test formhints pins flipped + buildsuite hint pin added (utf-8 byte-triple matching - the harness reads the pipe binary); layout make.tcl copies + templates modpod + bootsupport templates synced same unit)}