punkshell/goals/G-170-launcher-help-depth.md

G-170 Launcher help depth: form narrowing, parse-true dry-run, actionable form hints

Status: proposed Scope: src/vfs/_config/punkboot_core.tcl (help arm, + synced copies via established channels); punkexe launch definitions wherever homed after G-168/G-169 (formhint un-suppression); src/tests/shell/testsuites/punkexe/launcherhelp.test Goal: Launcher help gains per-form depth without breaking the prepend-help idiom: 'help _{<formname|index>' narrows any multi-form definition to that form's usage (the G-150 cmdhelp/usage -form precedent); for parse-true subcommands (G-168 built-ins; project registrations with parse=1) the help tail MAY dry-run make.tcl-style - accepted lines render the matched form plus the received-args report, rejected lines emit dispatch's own diagnosis - while passthrough subcommands keep ignored tails exactly as today; and the 0.6.1 interim -formhint suppression is replaced with actionable ' help %formname%' templates, resolving the circularity objection (the hint names real navigation). Acceptance: 'help script oneliner' (and an index form) renders only that form's usage; a non-form trailing word on a passthrough subcommand keeps today's ignored behaviour (prepend-help pinned unchanged); for a parse-true subcommand the dry-run's accept/reject agrees with dispatch on the same words (parity pinned); the form-word-vs-scriptfile collision rule (a script literally named 'oneliner') is decided and documented; the multi-form definitions' -formhint suppression flips to real templates and the hint labels render them; every increment has a working degraded/plain twin; all pinned in launcherhelp.test.}

Context

The G-149 make.tcl adoption (2026-08-05 - goals/archive/G-149-punkargs-formhint-labels.md) showed the hint pattern; the launcher suppressed instead (punkexe moduledoc 0.6.1) because subject-only help offered no per-form destination. This goal builds the destination, then points at it.

Notes

• Depends on G-168 (proposed) for the dry-run arm (narrowing arm is standalone).
• Related: G-169 (proposed) - the defs' home determines where templates land.
• Related: G-151 (proposed) - the dry-run arm's received-args report is G-151's punk::args-level annotated success render; landing G-151 first lets the launcher consume it instead of hand-assembling a second interim make.tcl-style one-liner (which G-151 already earmarks for retirement). Cross-link added 2026-08-05: the drafting overlap survey was path-based and could not surface G-151's args-module scope.
• Related: G-044 (proposed) - completion later consumes the same candidacy data.
• Archived precedents: G-143 (achieved - goals/archive/G-143-maketcl-multiform-help.md, make.tcl dry-run), G-150 (achieved - goals/archive/G-150-cmdhelp-form-narrowing.md, usage -form narrowing), G-032 (achieved - goals/archive/G-032-launcher-punkargs.md, launcher help mechanism), G-149 (achieved - goals/archive/G-149-punkargs-formhint-labels.md, formhint mechanism + suppression).
• Overlap survey 2026-08-05: shared with the G-168/G-169 survey; no additional live intersections beyond those named.