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.

For refs found via a module-pathtype template base (a provider module's own templates/layout_refs/), the target resolves against the module's own templates/project_layouts/ store instead of /src/project_layouts (punk::cap::handlers::templates >= 0.3.0). The punk::mix::templates modpod ships the thin punk.project layout this way, so a bare kit outside any project can list and generate it.

Thin layouts + generation-time injection (G-087 stage 3)

Layouts in this store are THIN: structure, scripts (make.tcl/build.tcl), docs, fossil/git settings and manifests only - no stored bootsupport or vfs module snapshot trees.

• src/bootsupport in a layout carries only modules*/include_modules.config manifests (plus READMEs). At generation time dev project.new injects the manifest-listed modules from the generating shell's own current trees (punk::mix::commandset::project::lib::bootsupport_inject): the shell project's src/bootsupport tree when the shell belongs to one, otherwise (standalone kit) per-module resolution from the shell's module paths. Adjacent non-.tm support files (struct sets_*.tcl, textutil .tex data) are carried along. bootsupport lib trees (pkgIndex.tcl packages e.g fileutil) are tree-copied from a shell project; standalone kits emit a notice (the lib set has no manifest yet) - a project generated by a bare kit runs its make.tcl via the kit executable, or lib is populated manually.
• The build's thin-layout sync step (part of make.tcl modules/libs/ packages/project) keeps each layout's src/make.tcl, src/build.tcl and bootsupport manifest copies current from the canonical src/ files, then syncs the punk.project payload into the punk::mix::templates modpod source tree (excluding bin/sdx.kit). Records live in src/project_layouts/.punkcheck. Never hand-edit the synced copies or the modpod copy - edit the canonical files/store layout and rebuild.
• A manifest edit (src/bootsupport/modules*/include_modules.config) reaches the layouts and the modpod only on the next such build - make.tcl bootsupport alone updates the checkout's own bootsupport, not the layouts.
• Alongside the layout copy and injection, dev project.new seeds the generated project's own identity metadata programmatically (each only-if-missing, never shipped inside a payload): punkproject.toml ([project] name + starting version 0.1.0), a matching CHANGELOG.md ## [0.1.0] header, and punkorigin.toml - a generation provenance baseline (layout name + resolved store target, punk::mix::templates version, punkshell version when derivable) that is the interim carrier for the G-027 pull-update design.

Overlay composition (G-087 stage 4)

A layout's effective content is composed from an ordered chain of store folders by punk::mix::commandset::layout::lib::layout_materialize (used by dev project.new and the layout listing/scanning commands):

<base chain - when the folder is named <name>@<base>>
vendor/<vendorname>/<name>
custom/<vendorname>/<name>

• Same-name files in a higher layer replace lower-layer files; folders merge recursively.
• A marker named .anti (zero-byte file recommended; a marker folder is also accepted) deletes as contributed by lower layers, and never appears in the composed output. A marker paired with a same-name folder in the same layer replaces the folder instead of merging.
• A folder named @ is a derived layout: it presents under its own name (via its own layout ref) and starts from the base layout's full chain. See custom/punk/othersample@sample-0.1 (with its ref in src/decktemplates/custom/punk/layout_refs/) for a working example of custom-over-vendor override, a .anti deletion and derivation; semantics detail in custom/punk/sample-0.1/extra.txt.
• Chains of one folder with no .anti markers (e.g the thin punk.project layout, module-carried layouts) are used in place - no copying. Anything else is composed into a disposable staging directory (deterministic per-layout path under the system temp dir, marked with a #layout_staging file) which project.new removes after use.

Store structure

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

• vendor/ trees should not be customised directly; place overrides under custom/ - the one override level.
• The former _project pseudo-vendor store level is retired for layouts (G-087 stage 5 decision): its store content was deleted as redundant by stage 3 (generation-time injection replaced the fat staging fragments), and _project folders take no part in overlay chains. The _project concept remains in use for decktemplates module/utility templates only.
• The unimplemented child-side src/PROJECT_LAYOUTS_CREATE_FROM_... marker folder was likewise retired (G-087 stage 5): with thin layouts, generated projects need only refs + thin payloads, and post-generation refresh belongs to the G-027 pull design.

G-087 (thin layouts, fauxlink refs, overlay merge - achieved 2026-07-19) is recorded in goals/archive/G-087-thin-project-layouts.md.