platforms.txt: machine-readable platform discovery manifest at repo root

Raw-file consumers (punk-runtime 'platforms -remote'; third-party mirrors
using this layout) have no directory-listing capability - platforms.txt
lists the served platform folders, one canonical punkshell platform-dir
name per line ('#' comments/blanks ignored). Generated and kept current
by src/build_sha1sums.tcl (rewrite-on-change, matching the sha1sums
behaviour); os_list extended with openbsd/msys per the punkshell platform
canon, and the skip-message stale-variable reference fixed ($f ->
$dirtail). Documented in AGENTS.md Local Contracts.

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

AGENTS.md

@@ -26,12 +26,20 @@ This artifact repository is specific to the punkshell project.
 - Layout: one folder per platform (`win32-x86_64/`, `linux-x86_64/`, `linux-arm/`,
   `macosx/`, `freebsd-arm64/`, ...), optional `tools/` subfolders for build tooling
   (e.g. zig archives). `src/` holds maintenance scripts for this repository itself.
+  Platform folder names follow the punkshell canonical platform names
+  (punk::platform module / `help platforms` in the punk shell).
+- `platforms.txt` at the repo root lists the platform folders this repo serves
+  (one name per line; `#` comments and blanks ignored) - the discovery manifest
+  for raw-file consumers that have no directory-listing capability
+  (`punk-runtime.cmd platforms -remote`, and third-party mirrors using the same
+  layout should carry the same file). Regenerated by `src/build_sha1sums.tcl`.
 - Every platform folder (and tool subfolder) carries a `sha1sums.txt` with one
   `<sha1> *<filename>` line per artifact (binary-mode marker `*`).
-- `sha1sums.txt` is regenerated with `tclsh src/build_sha1sums.tcl` from the repo
+- `sha1sums.txt` (and `platforms.txt`) are regenerated with
-  root. The script only sums git-tracked files - `git add` a new artifact BEFORE
+  `tclsh src/build_sha1sums.tcl` from the repo root. The script only sums
-  running it. It reports NEW/SAME/CHANGED per file; a CHANGED line for an existing
+  git-tracked files - `git add` a new artifact BEFORE running it. It reports
-  artifact is a red flag (artifacts are immutable - investigate, don't commit).
+  NEW/SAME/CHANGED per file; a CHANGED line for an existing artifact is a red
+  flag (artifacts are immutable - investigate, don't commit).
 - Binaries are deliberately committed here - this repo is the exception to the
   punkshell source repo's no-committed-binaries direction (shellspy G-004): the
   source repo points at this one (G-006 retrieval direction) instead of carrying

platforms.txt

@@ -0,0 +1,7 @@
+#platform folders served by this artifact repo (generated by src/build_sha1sums.tcl)
+#one punkshell canonical platform-dir name per line - see 'help platforms' in the punk shell
+freebsd-x86_64
+linux-arm
+linux-x86_64
+macosx
+win32-x86_64

src/build_sha1sums.tcl

@@ -4,7 +4,7 @@ set basedir [file dirname $srcdir]
 puts stdout "processing using base folder $basedir"
 
 set rootfolders [glob -dir $basedir -types {d} -tail *]
-set os_list [list linux macosx win32 freebsd netbsd dragonflybsd]
+set os_list [list linux macosx win32 freebsd netbsd dragonflybsd openbsd msys]
 set known_skip_tails [list src test]
 set skip_extensions [list .md .txt]
 set original_cwd [pwd]
@@ -99,16 +99,50 @@ proc do_sha1_in_folder {binaryfolder level} {
 
 
 set level 0
+set platform_tails [list]
 foreach dirtail $rootfolders {
     set level 0
     set indent ""
     if {$dirtail in $known_skip_tails} {continue}
     set firstword [lindex [split $dirtail -] 0]
     if {$firstword ni $os_list} {
-        puts stderr "skipping unrecognised folder: $f"
+        puts stderr "skipping unrecognised folder: $dirtail"
         continue
     }
+    lappend platform_tails $dirtail
     set runtimefolder [file join $basedir $dirtail]
     do_sha1_in_folder $runtimefolder 0
 }
+
+#platforms.txt - the machine-readable list of platform folders this repo serves,
+#at the repo root so raw-file consumers (punk-runtime 'platforms -remote', and
+#third-party mirrors using the same layout) can discover platforms without a
+#directory-listing capability. One platform-dir name per line; '#' comment lines
+#and blanks are ignored by consumers. Names follow the punkshell canonical
+#platform names (punk::platform / 'help platforms' in the punk shell).
+set platformsfile [file join $basedir platforms.txt]
+set new_platforms [lsort $platform_tails]
+set existing_platforms [list]
+if {[file exists $platformsfile]} {
+    set fd [open $platformsfile r]
+    foreach ln [split [read $fd] \n] {
+        set trimln [string trim $ln]
+        if {$trimln eq "" || [string index $trimln 0] eq "#"} {continue}
+        lappend existing_platforms $trimln
+    }
+    close $fd
+}
+if {$new_platforms ne $existing_platforms} {
+    puts stderr "rewriting platforms file at $platformsfile ([llength $new_platforms] platforms)"
+    set fd [open $platformsfile w]
+    fconfigure $fd -translation lf
+    puts $fd "#platform folders served by this artifact repo (generated by src/build_sha1sums.tcl)"
+    puts $fd "#one punkshell canonical platform-dir name per line - see 'help platforms' in the punk shell"
+    foreach p $new_platforms {
+        puts $fd $p
+    }
+    close $fd
+} else {
+    puts stderr "platforms.txt unchanged ([llength $new_platforms] platforms)"
+}
 cd $original_cwd