punkshell/goals/G-136-generated-project-icon-seeding.md

G-136 Generated projects are seeded with a default icon from a single punkshell-held master

Status: proposed Scope: src/assets/logo/project-default/ (the single held seed artwork); src/modules/punk/mix/commandset/project-999999.0a1.0.tm (generation-time asset injection beside bootsupport_inject); src/project_layouts/ (per-layout icon-slot declaration with no artwork stored in layout trees); src/modules/punkcheck-999999.0a1.0.tm (install records for injected assets) Goal: A newly generated project arrives with a working and inspectable icon - a readable vector master plus a ready-to-use .ico - injected from punkshell's single held copy at generation time, with no icon artwork stored in any layout payload tree, and regeneration never silently discards an owner's replacement. Acceptance: dev project.new against a layout declaring an icon slot produces src/assets/logo/ in the generated project containing icon.svg, icon.ico and icon.ico.assetorigin.toml that the G-135 checker reports as verified in that tree (artifact and recorded source both present, hashes matching), with the artwork sourced from src/assets/logo/project-default/ at generation time rather than from any file under src/project_layouts/ - verified by that tree containing no icon .svg or .ico payload; each injected file is recorded as a punkcheck install event in the same manner as bootsupport_inject; a layout declaring no icon slot generates a project with no src/assets/logo/ and no warning; and re-running generation over a project whose icon.svg or icon.ico differs from the injected original leaves the owner's file intact and reports the skip by name.

Context

A punkshell-generated project currently gets no icon at all. Its owner starts from nothing, with no indication that an icon slot exists or what shape it takes.

G-087 (achieved) established the pattern this goal follows: thin layouts carry structure rather than stored payload, and project.new injects bootsupport modules and libs from the generating shell at generation time (bootsupport_inject in project-999999.0a1.0.tm, each copy recorded as a punkcheck install event).

Storing icon artwork in the layout trees instead would reintroduce exactly what G-087 removed. There are two layouts (vendor/punk/project-0.1 and vendor/punk/basic) plus a synced copy under src/modules/punk/mix/#modpod-templates-*/ that is punkcheck-managed build output and must never be hand-edited - so layout-stored artwork means three copies with no master.

src/assets/logo/project-default/ (added 2026-07-28) holds the single copy: a frozen monochrome placeholder, a blank screen wearing the crest, deliberately unbranded so it reads "replace me" rather than as a product identity.

Approach

• Inject at generation time from the single held copy, as a sibling to bootsupport_inject, hung off the phase that already seeds punkproject.toml, CHANGELOG.md and punkorigin.toml. Reuse the punkcheck install-record approach of _bootsupport_inject_copyfile so seeded assets are tracked like every other injected file.
• Path symmetry, which is worth having deliberately: authored at punkshell's src/assets/logo/project-default/, landing at the generated project's src/assets/logo/. The same relative shape at both ends makes the structure self-explanatory to someone opening a fresh project.
• Ship BOTH the .svg master and the generated .ico. Producing an .ico needs a rasterizer, and requiring one of a fresh project would defeat the purpose; the pair also gives the owner a complete worked example of the master-to-derived relationship, which no amount of documentation prose achieves.
• The icon.ico.assetorigin.toml sidecar copies verbatim. Because G-135's record is a per-asset sidecar bound by its own filename with directory-relative source references, it needs no rewriting at the destination and reads verified there - artifact and recorded source are both present in the generated tree.
• Per-layout icon-slot declaration. A layout may decline, and declining is not a failure or a warning.
• Never clobber a replacement. Re-running generation over a project whose icon differs from the injected original leaves it alone and says which file it skipped.

Alternatives considered

• Store the artwork in each layout payload tree - rejected: three copies with no master, one of which is punkcheck-managed build output that must not be hand-edited, and it reverses G-087's thin-layout achievement.
• Ship only the .svg master - rejected: the generated project would have no usable icon until its owner installed a rasterizer.
• Seed punkshell's own punk-mark artwork - rejected: every generated project would ship punkshell's identity in its taskbar. A de-branded placeholder is what invites replacement; a neutral grey square would not, which is why the placeholder keeps the crest silhouette while dropping the colour and the brackets.
• Sync project-default/ from punk-mark.svg - rejected: it is a placeholder, not a mirror of punkshell's identity. Tracking the real mark would churn every generated project and re-date its provenance record on every logo tweak.

Notes

• Related: G-135 (achieved 2026-07-28, archived - see goals/archive/G-135-asset-provenance-records.md) - depends on, now satisfied. Consumes the sidecar record format and the checker, and relies specifically on the record being a per-asset sidecar with directory-relative references so it survives injection unchanged (and a single asset re-injected travels with its record as a pair). The dependency is concrete: src/assets/logo/project-default/icon.ico.assetorigin.toml exists and verifies (source icon.svg, same directory), so the verbatim copy this goal's Approach describes is exactly the committed pair; the checker is scriptlib/developer/assetorigin_check.tcl (format spec: src/assets/logo/AGENTS.md "Provenance records"; regeneration: tclsh src/assets/logo/make-ico.tcl all).
• Related: G-027 - consumer. Pull-based infrastructure updates for derived projects would later refresh seeded assets, and both goals record their installs through punkcheck.
• Related: G-086 - interaction. Whether the light layout declares an icon slot is decided there; this goal's acceptance is written so a layout may decline without that counting as a failure.
• Related: G-012 - sibling surface. The overwrite-on-regeneration behaviour is the same question as its explicit layout-refresh semantics.
• The placeholder's geometry carries two constraints that are easy to undo by accident, recorded in src/assets/logo/AGENTS.md: bezel and crest are ONE union path (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).