G-045 increment 2: punk 0.2.4 - i help renders aligned via -unindentedfields (project 0.12.5)

::punk::helptopic::define_docs now authors its help text at the left
margin and declares -unindentedfields {-help} on the generated @cmd line
(honoured as of punk::args 0.6.1, increment 1) and on the topic argument
line (a gate that existed all along but was never applied here).

Previously: the @cmd -help braced literal carried ~16 spaces of source
indent into the constructed definition (constructed defs get no
whole-block normalization, pinned P4 characterization), so the
Description block rendered continuations +12 right of the first line;
the \n-relative topic -help rendered its first line +4 (the injected
display prefix). Both blocks now render flush. Help text content
unchanged (manual ~70-col folding retained).

Verified in punk902z src (arg_error render + i help end-to-end);
punk::ns suite 53/53; make.tcl modules builds clean. Planning note
recorded in the goal detail file: the constructed-def normalization
increment picks its consumer proof (define_docs re-conversion vs
ensemble_subcommands_definition) when it lands.

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

CHANGELOG.md

@@ -5,6 +5,10 @@ The latest `## [X.Y.Z]` header must match the `version` field in `punkproject.to
 Entries are newest-first; one bullet per notable change. See the root `AGENTS.md`
 "Project Versioning" section for the bump policy.
 
+## [0.12.5] - 2026-07-12
+
+- G-045 (increment): 'i help' usage table alignment fixed (punk 0.2.4) - the Description block's continuations no longer render indented +12 relative to the first line, and the topic argument's help first line no longer renders +4 relative to its continuations. ::punk::helptopic::define_docs authors help text at the left margin with -unindentedfields {-help} on the @cmd and topic lines. Help text content unchanged.
+
 ## [0.12.4] - 2026-07-12
 
 - G-045 (increment): punk::args 0.6.1 - the @cmd directive now honours -unindentedfields for -help, so command help authored at the left margin renders its first line flush with continuations in help/usage displays (previously the option was accepted on @cmd but ignored). No shipped definitions used it yet, so existing help rendering is unchanged; the define documentation states where -unindentedfields is valid.

goals/G-045-punkargs-authoring-ergonomics.md

@@ -118,11 +118,28 @@ punk::imap4's {\Deleted}/{$MDNSent} choice values) have them stated, not just te
   0 fail; punk::ns suite 53/53 (arg_error consumer); make.tcl modules builds
   clean.
 
+### 2026-07-12 increment 2: 'i help' alignment via -unindentedfields (punk 0.2.4)
+
+- ::punk::helptopic::define_docs now authors its help text at the left margin
+  and declares -unindentedfields {-help} on the generated @cmd line (using
+  increment 1's gate) and on the topic argument line (a gate that existed all
+  along but was never applied here). Verified in punk902z src: the Description
+  block's +12 continuation leak and the topic Help first-line +4 are both gone;
+  'i help' renders flush end-to-end. punk::ns suite 53/53; make.tcl modules
+  clean.
+- Planning note: the constructed-def normalization increment's consumer proof
+  was to be define_docs "dropping manual pre-normalization". define_docs now
+  uses the documented -unindentedfields idiom (left-margin authoring), not a
+  hack - when normalization lands, either define_docs converts to
+  indented-plus-normalized authoring (likely nicer in a builder proc) or
+  ensemble_subcommands_definition serves as the proof; decide and record then.
+
 Remaining for acceptance:
 - record-continuation mechanism (the -& candidate): collision rules, escape
   story, parses identically to backslash-continuation equivalent, documented
 - constructed-definition whole-block normalization opt-in, with
   rendering_constructed_def_indent_characterization expectations updated and
-  ::punk::helptopic::define_docs de-hacked as the consumer proof
+  a constructed-def consumer converted as proof (see increment 2 planning note
+  on define_docs vs ensemble_subcommands_definition)
 - defquoting.test container quoting rules promoted into the punk::args::define
   -help documentation

punkproject.toml

@@ -1,4 +1,4 @@
 [project]
 name = "punkshell"
-version = "0.12.4"
+version = "0.12.5"
 license = "BSD-2-Clause"

src/modules/punk-999999.0a1.0.tm

@@ -8494,16 +8494,20 @@ namespace eval punk {
             }
             #keep help-text lines manually folded (~70 cols) - the usage tables don't yet
             #wrap to terminal width, so line lengths here directly set the table width
+            #help text is authored at the left margin and the @cmd/topic lines declare
+            #-unindentedfields {-help} (G-045): constructed definitions get no
+            #whole-block indent normalization, so source-indented authoring here would
+            #leak extra indent into the rendered help
             set basehelp {Help system for the punk shell.
-                With no arguments - an overview of some key shell
-                commands is displayed.
-                When the first argument is a recognised topic - help
-                for that topic is displayed.
-                ('help topics' lists the available topics)
-                Anything else is treated as a command name - basic
-                command info (type and synopsis) is shown for a
-                resolvable command, or the resolved path for an
-                external executable.}
+With no arguments - an overview of some key shell
+commands is displayed.
+When the first argument is a recognised topic - help
+for that topic is displayed.
+('help topics' lists the available topics)
+Anything else is treated as a command name - basic
+command info (type and synopsis) is shown for a
+resolvable command, or the resolved path for an
+external executable.}
             set topichelp "Help topic, or command words for basic command info.\nTopics accept their aliases and unique prefixes\n(some short words deliberately fall through to command lookup)."
             set specs [list]
             lappend specs ::punk::help help "Punk shell help system." ""
@@ -8511,9 +8515,9 @@ namespace eval punk {
             foreach {id name summary extra} $specs {
                 set def ""
                 append def "@id -id $id" \n
-                append def "@cmd -name $name -summary \"$summary\" -help \"$basehelp$extra\"" \n
+                append def "@cmd -name $name -summary \"$summary\" -unindentedfields {-help} -help \"$basehelp$extra\"" \n
                 append def "@leaders -min 0 -max -1" \n
-                append def "topic -optional 1 -multiple 1 -type string -choiceprefix 1 -choicerestricted 0 -choicecolumns 2 -choices {$choices} -choicealiases {$choicealiases} -choiceprefixdenylist {$topic_prefixdenylist} -choiceprefixreservelist {$topic_prefixreservelist} -choiceinfo {$choiceinfo} -choicelabels {$choicelabels} -help \"$topichelp\"" \n
+                append def "topic -optional 1 -multiple 1 -type string -choiceprefix 1 -choicerestricted 0 -choicecolumns 2 -choices {$choices} -choicealiases {$choicealiases} -choiceprefixdenylist {$topic_prefixdenylist} -choiceprefixreservelist {$topic_prefixreservelist} -choiceinfo {$choiceinfo} -choicelabels {$choicelabels} -unindentedfields {-help} -help \"$topichelp\"" \n
                 append def "@values -min 0 -max 0"
                 if {[punk::args::id_exists $id]} {
                     #quiet undefine - redefinition on registry change is expected, not noteworthy

src/modules/punk-buildversion.txt

@@ -1,6 +1,7 @@
-0.2.3
+0.2.4
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.2.4 - G-045: 'i help' usage table alignment - ::punk::helptopic::define_docs authors its help text at the left margin and declares -unindentedfields {-help} on both the generated @cmd line (honoured as of punk::args 0.6.1) and the topic argument line. Previously the @cmd -help braced literal carried ~16 spaces of source indent into the constructed definition (no whole-block normalization), rendering Description continuations +12 right of the first line, and the \n-relative topic -help rendered its first line +4 (the injected display prefix). Both blocks now render flush. Text content unchanged (manual ~70-col folding retained).
 #0.2.3 - punk::help topic definition adopts punk::args -choicealiases (G-040): choices are the four canonical topics with registry aliases folded ('i help' shows one entry per topic with an (alias:...) note), unique prefixes of topics and aliases accepted, minimum-prefix policy per user decision recorded in ::punk::helptopic (denylist {help}: h/he/hel stay command words; reservelist {c to tc}: fall through to command lookup); unrecognised words still fall through to basic command info; argless 'help' overview unchanged
 #0.2.2 - documentation-only: helptopic argdoc help texts manually folded (~70 cols) and the generated ::punk::help topic choices grid set to -choicecolumns 2 - 'i help'/'i help <topic>' tables now render at reasonable widths (61-68 cols, was ~160); usage tables don't yet wrap to terminal width so source line lengths set table width; argless 'help' overview output unchanged (strict 80-col layout preserved)
 #0.2.1 - 'help tcl' warning scan extended to the has_libbug_* check family (bundled/vendored library bugs, e.g. the G-036 tcludp detection) alongside has_tclbug_*; buginfo 'url' key supported for reference links to non tcl-core trackers; fixed latent unset-indent error when a triggered check had a bugref/url but no description