script subcommand: core-command doc parity (i list works in piped scripts)

app-punkscript loads punk::args::moduledoc::tclcore (catch-guarded,
mirroring the punk::repl code-interp setup) so core Tcl commands are
documented in script runs as at the repl: `''i list'' | punkexe script`
now renders the doc table instead of "Undocumented command". Cost ~40ms;
kit script startup ~0.33s. REVIEW note added: the default-punk-shell
package set is now expressed in app-punkscript AND the repl codethread
setup - consolidation into one shared definition is the G-015-noted
follow-on.

punk::packagepreference 0.1.1: moduledoc auto-load success notice moved
stdout -> stderr (stdout must stay machine-clean for script/exec
contexts; the failure branch already used stderr).

Verified on both generations (punk902z, punksys): i list doc table on
stdout, notice on stderr, timing unchanged. Build-order footnote: lib
changes need make.tcl libs before vfscommonupdate - the modules-only
first rebuild shipped a stale app-punkscript payload.

Project version 0.3.1.

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

CHANGELOG.md

@@ -5,6 +5,11 @@ 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.3.1] - 2026-07-07
+
+- `script` subcommand: core-command documentation parity with the interactive shell — app-punkscript now loads `punk::args::moduledoc::tclcore` (catch-guarded, ~40ms) so e.g. `'i list' | punkexe script` renders the doc table instead of "Undocumented command". Verified on both generations; kit startup ~0.33s.
+- punk::packagepreference 0.1.1: the moduledoc auto-load success notice moved from stdout to stderr — stdout must stay clean for script/exec contexts (the failure branch already used stderr).
+
 ## [0.3.0] - 2026-07-07
 
 - `<punkexe> script` completed (goal G-015 achieved): runs a script file (`script <file> ?args?`, conventional ::argv0/::argv) or the whole of piped stdin (`<commands> | <punkexe> script` — no trailing `exit` needed) in the default punk shell module/alias environment, so one-liners like `dev projects.work *name*` work with no boilerplate. Honest exit codes (0 success, 1 error with errorInfo on stderr, script's own `exit` honoured); no shellfilter transforms or logging side effects; never falls into an interactive shell. Implemented as the lean `app-punkscript` package; the stdin form echoes the script's final result when non-empty. Verified on both Tcl generations (punk902z, punksys).

punkproject.toml

@@ -1,3 +1,3 @@
 [project]
 name = "punkshell"
-version = "0.3.0"
+version = "0.3.1"

src/lib/app-punkscript/punkscript.tcl

@@ -36,6 +36,13 @@ apply {{} {
     package require punk
     package require punk::aliascore
     punk::aliascore::init
+    #documentation parity with the interactive shell: core-command docs so e.g
+    #'i list' works in piped scripts as it does at the repl (mirrors the
+    #punk::repl code-interp setup - highly desirable, not critical).
+    #REVIEW: the 'default punk shell environment' package set is now expressed
+    #here AND in punk::repl's codethread setup - consolidation into one shared
+    #definition is the G-015-noted follow-on (G-031 territory).
+    catch {package require punk::args::moduledoc::tclcore}
 
     set arglist $::argv
     if {[llength $arglist]} {

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

@@ -321,7 +321,9 @@ tcl::namespace::eval punk::packagepreference {
                             if {[catch {thread::id} threadid]} {
                                 set threadid "unknown-threadid"
                             }
-                            puts stdout "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid"
+                            #notice goes to stderr: stdout must stay clean for script/exec contexts
+                            #(e.g the punk executable's 'script' subcommand - machine-consumed output)
+                            puts stderr "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid"
                         }
                     }
                     #---------------------------------------------------------------

src/modules/punk/packagepreference-buildversion.txt

@@ -1,3 +1,4 @@
-0.1.0
+0.1.1
 #First line must be a semantic version number
 #all other lines are ignored.
+#0.1.1 - moduledoc auto-load success notice moved from stdout to stderr (stdout must stay clean for script/exec contexts e.g the punk 'script' subcommand; failure branch already used stderr)

src/vfs/_vfscommon.vfs/lib/app-punkscript/punkscript.tcl

@@ -36,6 +36,13 @@ apply {{} {
     package require punk
     package require punk::aliascore
     punk::aliascore::init
+    #documentation parity with the interactive shell: core-command docs so e.g
+    #'i list' works in piped scripts as it does at the repl (mirrors the
+    #punk::repl code-interp setup - highly desirable, not critical).
+    #REVIEW: the 'default punk shell environment' package set is now expressed
+    #here AND in punk::repl's codethread setup - consolidation into one shared
+    #definition is the G-015-noted follow-on (G-031 territory).
+    catch {package require punk::args::moduledoc::tclcore}
 
     set arglist $::argv
     if {[llength $arglist]} {

src/vfs/_vfscommon.vfs/modules/punk/packagepreference-0.1.1.tm

@@ -8,7 +8,7 @@
 # (C) 2024
 #
 # @@ Meta Begin
-# Application punk::packagepreference 0.1.0
+# Application punk::packagepreference 0.1.1
 # Meta platform     tcl
 # Meta license      <unspecified>
 # @@ Meta End
@@ -18,7 +18,7 @@
 # doctools header
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
 #*** !doctools
-#[manpage_begin punkshell_module_punk::packagepreference 0 0.1.0]
+#[manpage_begin punkshell_module_punk::packagepreference 0 0.1.1]
 #[copyright "2024"]
 #[titledesc {punkshell package/module loading}]  [comment {-- Name section and table of contents description --}]
 #[moddesc {package/module load}]             [comment {-- Description at end of page heading --}]
@@ -321,7 +321,9 @@ tcl::namespace::eval punk::packagepreference {
                             if {[catch {thread::id} threadid]} {
                                 set threadid "unknown-threadid"
                             }
-                            puts stdout "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid"
+                            #notice goes to stderr: stdout must stay clean for script/exec contexts
+                            #(e.g the punk executable's 'script' subcommand - machine-consumed output)
+                            puts stderr "punk::packagepreference overloaded 'package require': Loaded punk::args::moduledoc::$dp for package '$pkg' threadid: $threadid"
                         }
                     }
                     #---------------------------------------------------------------
@@ -487,7 +489,7 @@ namespace eval ::punk::args::register {
 package provide punk::packagepreference [tcl::namespace::eval punk::packagepreference {
     variable pkg punk::packagepreference
     variable version
-    set version 0.1.0
+    set version 0.1.1
 }]
 return