punkshell/src/project_layouts

project_layouts information

This folder is the payload store for project layouts: the directory trees that dev project.new (punk::mix::commandset::project::new) copies to create a new project.

Discovery: the punk.templates capability

Layouts in this store do not show as available unless referenced by a layout ref file found via the punk.templates capability (handler: punk::cap::handlers::templates; principal provider: punk::mix::templates).

Providers register template base folders with a pathtype. Base folders are merged in priority order (lowest to highest):

module < shellproject < currentproject < absolute < adhoc

Within the shellproject/currentproject multivendor trees (src/decktemplates), vendor/ folders are added before vendor/_project, and custom/ levels override vendor/ levels. When the same visible name is produced by more than one ref, the highest-priority one keeps the bare name and later ones are suffixed #2, #3, ...

Layout refs

A layout ref is a zero-byte fauxlink file in a layout_refs/ folder under a template base (e.g. src/decktemplates/vendor/punk/layout_refs/, or a module-shipped templates/layout_refs/). The entire meaning is in the filename, which follows the standard fauxlink grammar (see the fauxlink package documentation) resolved by the vendored fauxlink module:

<alias>#<segment>+<segment>+...  .fauxlink   (or .fxlnk)

• The text before the first # is the alias - the layout's nominal name. Layout refs MUST carry a non-empty alias: punkcheck-based tooling treats leading-# filenames as hidden/aside, so an alias-less ref would silently vanish from punkcheck-driven installs. The handler warns about and skips such refs.
• The text after the first # is the fauxlink-encoded target: a + separated path relative to /src/project_layouts identifying the layout folder. Segments may contain literal @ (derived-layout folder names such as othersample@sample-0.1); other special characters use fauxlink %XX encoding. fauxlink::link_as generates conformant names programmatically.
• The visible layout name is prefixed with the vendor folder name and a dot unless the vendor is the pseudo-vendor _project (e.g. project#vendor+punk+project-0.1.fauxlink in a vendor/punk/layout_refs folder presents as layout name "punk.project").
• Only filenames whose encoded target starts at vendor+ or custom+ are recognised; files named ignore* are skipped; unresolvable fauxlink names are skipped with a warning.
• The pre-fauxlink @.ref grammar was retired 2026-07-17 (G-087 stage 2) - .ref files are no longer recognised.

The ref indirection exists to break recursion: layout payloads may embed module trees (including the punk::mix::templates module itself), so modules ship only small ref files while the layout payloads live once, here, outside any module.

Store structure

src/project_layouts/{vendor,custom}/{<vendorname>,_project}/<layoutfolder>

• vendor/ trees should not be customised directly; place overrides under custom/. The pseudo-vendor _project holds project-local staging copies.
• Overlay semantics (custom-over-vendor merging, .anti deletion markers, newname@base derived layouts, _project staging) are documented design - see custom/punk/sample-0.1/extra.txt - but are NOT yet implemented: project.new currently copies exactly one resolved layout folder.

Goal G-087 (goals/G-087-thin-project-layouts.md) tracks implementing the overlay merge, migrating refs to fauxlink files, and restructuring this store to thin layouts whose heavy infrastructure is injected at generation time (retiring the embedded module-tree snapshots currently stored here).