punkshell/goals/G-144-punkargs-synopsis-name-fallback.md

G-144 punk::args auto-synopsis: @cmd -name fallback for non-command ids

Status: proposed Scope: src/modules/punk/args-999999.0a1.0.tm (synopsis renderer + usage/arg_error synopsis display); src/tests/modules/punk/args/testsuites/args/ (synopsis pins) Goal: Auto-generated synopses render their invocation name from @cmd -name whenever the definition id is not the command's invocation name (script-level ids like (script)::punkboot::modules and (shared)/(package)-style doc ids), falling back to the id only when no @cmd -name is declared - so consumers get the automatic bracket-notation synopsis with the real command name, and explicit @form -synopsis overrides become optional rather than mandatory for such ids. Acceptance: a definition with @id -id (script):❌:sub and @cmd -name 'make.tcl sub' auto-renders synopsis lines beginning 'make.tcl sub' across the punk::args::synopsis, usage and arg_error surfaces (table and string renderers), with every form line of a multi-form definition carrying the name; definitions whose id equals the invocation name render byte-identical to today (existing synopsis/usage/arg_error suites pass unchanged apart from deliberately updated pins); a definition with neither a command-path id nor @cmd -name renders the id as today; the new behaviour is pinned in the args testsuite.

Context

The synopsis generator produces the preferred bracket-notation lines but names the definition id verbatim: verified 2026-08-01 on punk::args 0.12.7 - '(script)::toy::flat [-test ] [toolname]...'. For script-level definitions (make.tcl's (script)::punkboot::_{) and shared/package doc ids, that forced the explicit @form -synopsis workaround adopted in G-030 and documented in G-045's authoring ergonomics; make.tcl hand-writes Tcl-style ?...? synopses for this reason alone, while the user-preferred style is the automatic punk::args bracket notation.}

Approach

• Display-only change: parsing, ids, get_spec and spec caching are untouched.
• Rule to settle in the work: when to prefer @cmd -name over id (candidates: ids carrying a parenthesised origin prefix like (script)/(shared)/(autodef), or any id differing from -name beyond a leading ::). Hard constraint: existing real-command definitions (id == command path) must render unchanged.
• Consumer follow-through: make.tcl drops its per-definition @form -synopsis lines once this ships (under G-143 if active, else a small follow-on edit).

Notes

• Origin: G-030 achieved 2026-07-14 (goals/archive/G-030-maketcl-punkargs.md) recorded the id-vs-name synopsis finding and mooted this exact nicety; G-045 achieved 2026-07-12 (goals/archive/G-045-punkargs-authoring-ergonomics.md) documents the explicit @form -synopsis lesson this retires for constructed/script ids.
• Related: G-050 (proposed) - synopsis validity marking; same renderer surface, independent mechanism.
• Related: G-056 (proposed) - display-time help wrapping; same renderer file, independent mechanism.
• Related: G-143 (sibling proposal) - make.tcl consumer of the fallback (auto bracket-notation synopses).
• Overlap survey 2026-08-01: goals_xref paths src/modules/punk/args-999999.0a1.0.tm lists 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 G-050/G-056 named above, these target parser/spec mechanisms, not synopsis name display.