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/<vendorname> 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 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:

    <alias>@<segment>+<segment>+...  .ref

- The text before the first @ is the alias - the layout's nominal name.
  If the alias is empty the last + separated segment is used as the name.
- The text after the first @ is a + separated path relative to
  <projectroot>/src/project_layouts identifying the layout folder.
  Segments after the first @ may themselves contain @ (derived-layout folder
  names such as othersample@sample-0.1).
- 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.ref in a vendor/punk/layout_refs
  folder presents as layout name "punk.project").
- Only filenames matching *@vendor+*.ref or *@custom+*.ref are recognised;
  files named ignore* are skipped.

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).