GOALS: add G-057 [proposed] Windows kit icon embedding (twapi resource replacement, per-vfs override)

- default icon src/runtime/punk1.ico, per-kit override from the kit's .vfs; mechanism per tcl-sfe (TEMP_REFERENCE/tcl-sfe, Ashok P. Nadkarni): RT_ICON/RT_GROUP_ICON replacement via twapi resource-update APIs, ordered so the appended vfs payload stays intact (icon stub before append, or sfe-style split/update/reattach)
- detail file records the _vfscommon.vfs override-detection wrinkle (common punk1.ico merges into every built vfs - consult the custom pre-merge folder or an explicit mapvfs.config element), idempotence via delete-then-write, twapi/non-Windows skip path, and resource-inspection acceptance
- follow-on candidate flagged (detail file only): RT_VERSION stamping - copyright defaulting to the input runtime's own version-resource copyright, Product Name indicating the core Tcl version by default, both configurable via punkproject.toml and/or per-vfs config

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

GOALS.md

@@ -385,3 +385,9 @@ Scope: src/modules/punk/args-999999.0a1.0.tm (arg_error table and string rendere
 Detail: goals/G-056-punkargs-word-wrapping.md
 Goal: punk::args help display (@cmd -help, argument -help, choicelabels) word-wraps over-width lines to the effective display width at render time - ANSI/grapheme aware, splitting long logical lines but never joining existing ones, so deliberately structured content (hand-folded blocks, choice tables, art choicelabels, indented continuations) is preserved by construction - letting definitions store unfolded verbatim text (retiring the G-055 re-folding exception for new work) while usage output stays terminal-width friendly.
 Acceptance: a definition whose -help/choicelabel contains a single long unfolded line renders fully within the effective display width in both the table and -return string renderers (no truncation, no overflow, wrapped continuations indented to match the field's existing paramindent alignment); wrap-point calculation is ANSI-aware (SGR sequences measure zero width; styling in effect carries across the wrap) and grapheme/double-width aware to the same standard as existing punk::ansi/textblock width handling; existing hand-folded and structured help renders byte-identical (full existing args rendering/usagemarking/deferredhelp suites pass unchanged - never-join semantics verified by characterization tests); effective width derives from the terminal when available with the current -maxwidth 80 table default as fallback, and an explicit width option overrides; the chosen mechanism (punk::args-side pre-wrap of field text vs textblock table column wrap support) and its rationale are recorded in the detail file; G-055's folding exception is marked lapsed for new work once this ships.
+
+### G-057 [proposed] Windows kit builds embed a configurable icon (twapi resource replacement, per-vfs override)
+Scope: src/make.tcl (kit/zipkit wrap steps), src/runtime/punk1.ico (project default, existing), src/vfs/*.vfs (override placement convention), src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism), TEMP_REFERENCE/tcl-sfe (read-only reference), helper proc location decided in the work (make.tcl inline vs punk::mix lib)
+Detail: goals/G-057-kit-icon-embedding.md
+Goal: Windows kit/zipkit builds produce executables carrying an embedded icon chosen at build time - defaulting to the project icon src/runtime/punk1.ico, overridable per kit by its .vfs folder - by replacing the icon resources in the built executable using the twapi-based mechanism demonstrated in tcl-sfe (TEMP_REFERENCE/tcl-sfe, by twapi author and Tcl core member Ashok P. Nadkarni): RT_ICON/RT_GROUP_ICON replacement via twapi resource-update APIs, applied so the appended vfs payload stays intact (icon the stub before appending, or sfe-style split/update/reattach).
+Acceptance: a Windows `make.tcl project` build produces kit executables whose embedded icon resources are the project default punk1.ico, and a kit whose .vfs supplies an override icon gets that icon instead (verified by resource inspection, e.g twapi::extract_resources, not just Explorer eyeballing); the icon-replaced executables still boot to a working punk shell reading their vfs payload for the kit types we build (kit, zip, zipcat per mapvfs.config); runtimes under src/runtime are never modified - replacement applies to the built copies only; twapi unavailable or non-Windows platform skips the icon step with a notice and the build otherwise completes unchanged; rebuilds are idempotent (re-wrapping an already-iconed build copy converges, no resource accumulation); the override convention (filename/location in the kit's custom .vfs folder vs a mapvfs.config element) and the stub-vs-split ordering decision are recorded in the detail file with the tcl-sfe attribution.

goals/G-057-kit-icon-embedding.md

@@ -0,0 +1,72 @@
+# G-057 Windows kit builds embed a configurable icon (twapi resource replacement, per-vfs override)
+
+Status: proposed
+Scope: src/make.tcl (kit/zipkit wrap steps), src/runtime/punk1.ico (project default, existing), src/vfs/*.vfs (override placement convention), src/runtime/mapvfs.config (only if an explicit config element is the chosen override mechanism), TEMP_REFERENCE/tcl-sfe (read-only reference), helper proc location decided in the work (make.tcl inline vs punk::mix lib)
+Acceptance: see GOALS.md index entry (canonical).
+
+## Context
+
+Built punk kit executables currently carry whatever icon resource their runtime
+stub shipped with. The project icon src/runtime/punk1.ico exists and is COPIED
+into vfs trees (a tclkit-era convention), but nothing embeds it into the produced
+executable's Windows resources - so all kits look like their runtime in Explorer
+and the taskbar.
+
+The reference mechanism is tcl-sfe (TEMP_REFERENCE/tcl-sfe, read-only), written by
+twapi author and Tcl core member Ashok P. Nadkarni: library/sfe-0.2.tm method
+replaceIcon / ReplaceIconInStub replaces RT_ICON (type 3) and the icon group
+(RT_GROUP_ICON, type 14) via twapi::extract_resources /
+twapi::begin_resource_update / twapi::delete_resource / twapi::update_resource /
+twapi::end_resource_update, building the group entry from the .ico file's own
+image directory.
+
+## Approach
+
+- Hook the icon step into make.tcl's kit wrap processing (driven by
+  src/runtime/mapvfs.config), operating on the BUILD COPY of the runtime stub -
+  never on the originals under src/runtime.
+- Payload integrity is the critical ordering constraint: a Windows resource
+  update rewrites the PE image and corrupts any already-appended vfs payload.
+  Either icon the stub copy BEFORE appending the zip/metakit payload, or use the
+  sfe approach of splitting payload off, updating resources, and reattaching
+  (sfe-0.2.tm does the split/update/reattach dance for exactly this reason).
+  Chosen ordering to be recorded here.
+- Default icon: src/runtime/punk1.ico. Per-kit override supplied by the kit's
+  .vfs. IMPORTANT wrinkle for the override convention: _vfscommon.vfs already
+  merges a punk1.ico into every built vfs tree, so override detection must
+  consult the kit's own CUSTOM .vfs folder (pre-merge, under src/vfs/) - or use
+  an explicit mapvfs.config element - otherwise every kit would appear to
+  "override" with the same common file. Chosen convention to be recorded here.
+- Graceful degradation: twapi unavailable, or non-Windows build, skips the icon
+  step with an actionable notice; the build otherwise proceeds unchanged (per the
+  src/AGENTS.md optional-extension guidance).
+- Idempotence: re-running a wrap on an already-processed build copy must converge
+  (sfe deletes existing icon/group resources before writing - follow that).
+
+## Follow-on candidate goal (flagged, not yet a GOALS.md entry)
+
+Version-information resource stamping (RT_VERSION, type 16) - sfe-0.2.tm already
+demonstrates the resource construction (BuildVersionResource, string tables,
+delete-then-write). Requirements sketch agreed 2026-07-10:
+
+- **Copyright**: defaults to the copyright already present in the INPUT kit
+  runtime executable's version resource (carry it over - the runtime authors'
+  copyright is not ours to silently drop), while being easily configurable -
+  initially from punkproject.toml and/or per-vfs config.
+- **Product Name**: should indicate the core Tcl version of the runtime by
+  default (e.g. carrying the Tcl major.minor the kit embeds), similarly
+  configurable via punkproject.toml / per-vfs config.
+- Other fields (FileVersion/ProductVersion from the project version,
+  FileDescription etc.) to be settled when the goal is drafted.
+- Config surface should anticipate the toml direction already agreed for build
+  configs (punkproject.toml now; buildsuites toml era later).
+
+## Notes
+
+- tclsfe-x64.exe is already one of our mapped runtimes (mapvfs.config) - the same
+  author's stub and the reference mechanism, so it makes a good first test
+  subject alongside a tclkit-style runtime.
+- Resource inspection for acceptance: twapi::extract_resources on the built exe
+  (compare icon group/images against the source .ico), not visual inspection.
+- Linux/other-platform kit outputs have no PE resources - explicitly out of
+  scope; the skip path covers them.