Project icon: punk1.ico -> punkshell.ico, artwork from the src/assets/logo master
The four build-consumed copies are renamed and their artwork replaced with
src/assets/logo/punk-mark.ico (all four byte-identical to the master):
src/runtime/punk1.ico -> src/runtime/punkshell.ico
src/vfs/_vfscommon.vfs/punk1.ico -> .../punkshell.ico
src/vfs/mkzipfix.vfs/punk1.ico -> .../punkshell.ico
src/vfs/punk8_statictwapi.vfs/punk1.ico -> .../punkshell.ico
Recorded as delete+add rather than renames: the content is entirely different,
so git's similarity detection finds no link and --follow will not trace through.
The pre-2026-07 artwork keeps its own lineage under src/assets/logo/legacy/,
now the only place the punk1 name survives.
No code referenced the old name - every mention was documentation or goal prose,
checked before renaming.
G-057's contract lines are updated for the new path (Scope in both tiers, plus
Goal and Acceptance): pure path substitution, no semantics changed. Its Context
gains a dated note recording the rename and artwork swap, and its _vfscommon.vfs
override-detection wrinkle now names punkshell.ico. goals_lint clean.
Adds src/assets/logo/project-default/, a frozen monochrome placeholder - a blank
screen wearing the crest - held as the single copy for seeding generated
projects. Unbranded so it reads "replace me" rather than as a product identity.
Bezel and crest are ONE union path (drawn as two shapes the bezel's top edge
cuts a visible line across the mohawk) and the screen is filled rather than
outlined (a solid mass survives 16px where nested thin strokes merge). It shares
only the crest with punk-mark.svg and must not be re-derived from it: tracking
the real mark would churn every generated project on every logo tweak.
Also corrects a defect introduced in 91fa500e. The Ownership bullet in
src/assets/logo/AGENTS.md said "do not repoint build consumers at this directory
on your own initiative" and then, in the next sentence, instructed re-copying
them by hand after regeneration - so whichever half an agent read first would
win. It now states the dated fact and names G-057 as the owner of future
propagation. Distribution machinery does not belong in an AGENTS instruction,
and drift wants a check rather than a standing manual obligation.
Stale punk1.ico copies were also swept from the untracked build trees
(src/_build x12, bin/test, bin/test2, scratch, testsdx) so the next bake cannot
merge both names into a kit payload.
Claude-Session: https://claude.ai/code/session_01YNjnq6oDzecknLg7AuWZgU
Assisted-by: harness=claude; primary-model=claude-opus-5[1m]; api-location=anthropic.com
@ -190,7 +190,7 @@ The project version is fully independent of module versions. A module bump (even
- `src/vendorlib_tcl9/` — Tcl 9 specific vendor libraries
- `src/runtime/` — Build runtimes and VFS config (see src/runtime/AGENTS.md)
- `src/doc/` — Generated documentation (see src/doc/AGENTS.md)
- `src/assets/logo/` — Project logo vector masters (`punk-mark.svg`, solid-plate alternate) and the multi-resolution `.ico` files generated from them; the icon MASTER, distinct from the build-consumed copies at `src/runtime/punk1.ico` and `src/vfs/_vfscommon.vfs/punk1.ico`. Retired artwork kept under `legacy/` (see src/assets/logo/AGENTS.md)
- `src/assets/logo/` — Project logo vector masters (`punk-mark.svg`, solid-plate alternate) and the multi-resolution `.ico` files generated from them; the icon MASTER, distinct from the build-consumed copies at `src/runtime/punkshell.ico` and `src/vfs/_vfscommon.vfs/punkshell.ico`. Retired pre-2026-07 artwork kept under `legacy/` as `punk1.*` - the only place that legacy name survives (see src/assets/logo/AGENTS.md)
- `src/testansi/` — Sample ANSI art files (do not modify)
- `bin/` — Built punk shell executables, launch package modes (incl. `src` mode for working-tree verification), plain runtime kits (see bin/AGENTS.md)
- `.fossil-settings/` — Versioned fossil settings and the git+fossil dual-VCS coexistence contract: ignore-sync rules, files neither system may track (see .fossil-settings/AGENTS.md)
### G-057 [proposed] Kit builds carry a configurable icon: text sidecar for every target, embedded PE resources for windows targets
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); kit icon sidecar record (emission points recorded in the work)
Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punkshell.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); kit icon sidecar record (emission points recorded in the work)
# G-057 Kit builds carry a configurable icon: text sidecar for every target, embedded PE resources for windows targets
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); kit icon sidecar record (emission points recorded in the work)
Goal: kit/zipkit builds record a build-time icon choice for every target - defaulting to the project icon src/runtime/punk1.ico and overridable per kit by its .vfs folder - in a text sidecar that ships with the kit whatever its target, and embed it as PE icon resources when the target has them and the build host can write them - 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), behind a single mechanism seam so the embedding implementation can be replaced without touching its callers.
Acceptance: a `make.tcl bake` on a windows host producing a win32-target kit 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; a target with no PE resources (linux, freebsd, macosx) skips embedding as NOT APPLICABLE rather than as degradation and still gets its sidecar, while a win32 target on a host that cannot perform the update (twapi unavailable, or a non-windows host cross-baking a windows kit) skips embedding with a DISTINCT notice naming which condition applied, still writes the sidecar, and the build otherwise completes unchanged - the cross-host case is recorded here as a known shortcoming with its remedy; the sidecar is produced for every kit on every target, carries the same icon data the PE embedding uses (source .ico identity and provenance) in a documented plain-text form, is byte-stable across rebuilds at unchanged input, and is defined so the parked RT_VERSION follow-on extends the same file rather than adding a second one; the embedding implementation sits behind a single internal entry point with the mechanism selected inside it, so a later portable replacement is a substitution rather than a rewrite; the twapi mechanism remains available INDEFINITELY as the no-toolchain windows path - the seam SELECTS between mechanisms rather than replacing one with the other - and a fresh checkout that fetches a runtime and bakes produces iconed kits with no build toolchain installed; 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 - the override is SHARED across a kit definition's targets and carries no target dimension (decided 2026-07-26): it is used where embedding applies and ignored elsewhere.
Scope: src/make.tcl (kit/zipkit wrap steps); src/runtime/punkshell.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); kit icon sidecar record (emission points recorded in the work)
Goal: kit/zipkit builds record a build-time icon choice for every target - defaulting to the project icon src/runtime/punkshell.ico and overridable per kit by its .vfs folder - in a text sidecar that ships with the kit whatever its target, and embed it as PE icon resources when the target has them and the build host can write them - 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), behind a single mechanism seam so the embedding implementation can be replaced without touching its callers.
Acceptance: a `make.tcl bake` on a windows host producing a win32-target kit produces kit executables whose embedded icon resources are the project default punkshell.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; a target with no PE resources (linux, freebsd, macosx) skips embedding as NOT APPLICABLE rather than as degradation and still gets its sidecar, while a win32 target on a host that cannot perform the update (twapi unavailable, or a non-windows host cross-baking a windows kit) skips embedding with a DISTINCT notice naming which condition applied, still writes the sidecar, and the build otherwise completes unchanged - the cross-host case is recorded here as a known shortcoming with its remedy; the sidecar is produced for every kit on every target, carries the same icon data the PE embedding uses (source .ico identity and provenance) in a documented plain-text form, is byte-stable across rebuilds at unchanged input, and is defined so the parked RT_VERSION follow-on extends the same file rather than adding a second one; the embedding implementation sits behind a single internal entry point with the mechanism selected inside it, so a later portable replacement is a substitution rather than a rewrite; the twapi mechanism remains available INDEFINITELY as the no-toolchain windows path - the seam SELECTS between mechanisms rather than replacing one with the other - and a fresh checkout that fetches a runtime and bakes produces iconed kits with no build toolchain installed; 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 - the override is SHARED across a kit definition's targets and carries no target dimension (decided 2026-07-26): it is used where embedding applies and ignored elsewhere.
## 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
stub shipped with. The project icon src/runtime/punkshell.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.
Renamed 2026-07-28 from punk1.ico, and its artwork replaced from the
src/assets/logo/ master at the same time. The four build-consumed copies
(src/runtime/, _vfscommon.vfs, mkzipfix.vfs, punk8_statictwapi.vfs) are now
punkshell.ico and are copies of src/assets/logo/punk-mark.ico; the pre-2026-07
punk1 artwork is retained at src/assets/logo/legacy/ and is the only place that
name survives.
Host/target reopened this (2026-07-26). The goal was drafted before G-122 separated
what the driving tclsh IS from what a bake is FOR, so its skip condition read as one
host-shaped test ("non-Windows platform") while its Notes used target language
@ -43,9 +50,9 @@ image directory.
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
- Default icon: src/runtime/punkshell.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
merges a punkshell.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.
Holds the vector masters for the punkshell logo and the `.ico` files generated
from them. This directory is the SOURCE of the project icon; every `punk1.ico`
from them. This directory is the SOURCE of the project icon; every `punkshell.ico`
elsewhere in the tree is a derived copy or a build input, never an original.
## Ownership
@ -13,9 +13,12 @@ elsewhere in the tree is a derived copy or a build input, never an original.
- Files under `legacy/` are retired artwork kept for provenance. Do not edit,
regenerate, or "modernise" them; they record what shipped before.
- Do not repoint build consumers at this directory on your own initiative. The
icon actually consumed by builds still lives at `src/runtime/punk1.ico` (the
G-057 default) and `src/vfs/_vfscommon.vfs/punk1.ico`; swapping those is a
user-directed step.
icon consumed by builds lives at `src/runtime/punkshell.ico` (the G-057
default) and `src/vfs/_vfscommon.vfs/punkshell.ico`, plus per-kit copies under
`src/vfs/mkzipfix.vfs/` and `src/vfs/punk8_statictwapi.vfs/`. Those four were
set from `punk-mark.ico` on 2026-07-28 at the user's direction. Propagating a
later change to them is build machinery owned by G-057 — not a manual step to
repeat from here.
## Local Contracts
@ -43,6 +46,15 @@ elsewhere in the tree is a derived copy or a build input, never an original.
regenerate with a DIB 256 entry (see Work Guidance) instead of assuming the
file is at fault.
- **`project-default/` is FROZEN placeholder artwork, not a treatment of the
mark.** It is the default icon a generated project starts with: a blank screen
wearing the crest, monochrome and deliberately unbranded so it reads "replace
me" rather than as a product identity. It shares only the crest with
`punk-mark.svg` and must NOT be re-derived from it — if it tracked the real
mark, every logo tweak would churn every generated project. Its bezel and
crest are one union path (drawn as two shapes, the bezel's top edge cuts a
line across the mohawk) and its screen is filled rather than outlined (a solid
mass survives 16px where nested thin strokes merge).
- **`web/` is a separate build with different rules.** Its `favicon.ico` is
16/32/48 and ALL-PNG (2.5KB, since it is fetched on every cold page load);
that file is web-only and must never be used as a PE resource. `web/icon.svg`
@ -97,5 +109,6 @@ elsewhere in the tree is a derived copy or a build input, never an original.
## Child DOX Index
- `alternative/` — Solid-plate treatment of the same mark (covered by this file)
- `project-default/` — Frozen monochrome placeholder seeded into generated projects; single held copy, no artwork in layout payload trees (covered by this file)
- `web/` — Favicon/webmanifest set for website use; theme-aware `icon.svg`, all-PNG `favicon.ico`, opaque apple-touch and PWA rasters (covered by this file)
- `legacy/` — Retired pre-2026-07 artwork, provenance only (covered by this file)
