G-087 hygiene: exact punk.project layout ref, junk refs removed, README rewritten

- @vendor+punk+project-0.1.ref renamed to project@vendor+punk+project-0.1.ref:
  the alias yields the exact layout name 'punk.project', so project.new's
  defaulted -layout resolves unambiguously (previously tcl::prefix::match saw
  only punk.project-0.1 / punk.project-0.1_overrides).
- Junk/test refs removed from the selectable layout list: test2, the
  custom/_project duplicate sample-0.1 ref, and the alias-less punk.shell-0.1
  ref whose target was an a.txt-only folder (folder removed too; the real
  shell layout remains exposed as punk.shell-0.1_overrides).
- src/project_layouts/README.md rewritten to describe the implemented
  punk.templates + layout_refs mechanism including the ref filename grammar,
  the not-yet-implemented overlay semantics, and a G-087 pointer; the dead
  punk.projectlayout capability description is gone.

Layout names after this change: punk.sample-0.1 punk.project punk.minimal
punk.basic punk.shell-0.1_overrides punk.project-0.1_overrides.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com

src/project_layouts/README.md

@@ -1,20 +1,68 @@
-
+project_layouts information
-project_layout information
+===========================
-==========================
+
-
+This folder is the payload store for project layouts: the directory trees that
-project layouts don't show as available unless referenced by an entry in a layout_ref folder within the src/decktemplates structure.
+`dev project.new` (punk::mix::commandset::project::new) copies to create a new
-
+project.
-This is because some layouts may be intended for use with child projects generated from 'deck project.new' - but not directly by this parent project.
+
-
+Discovery: the punk.templates capability
-The structure of decktemplates and project_layouts is designed to avoid circular dependencies arising during creation of layouts for child projects - that may then need to in turn support the same layout if the child project creates projects.
+----------------------------------------
-
+
-Layouts are not included in the resource files of modules for the same reason. (modules may need to be included in layouts)
+Layouts in this store do not show as available unless referenced by a layout
-Instead they are pointed to via the decktemplates custom & vendor structure.
+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
-layouts within project_layouts/vendor should generally not be customised directly
+merged in priority order (lowest to highest):
-The vendor layouts should be created and updated by loading the appropriate vendor modules.
+
-These are plugin modules that are providers of the punk.projectlayout capability
+    module < shellproject < currentproject < absolute < adhoc
-(see punk::cap module documentation and the project_layouts/vendor/punk/sample-0.1 layout)
+
-
+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).