feat: add sibling showcase/ tree and shipping-crate piece

[TMHSDigital]

Summary

Sibling showcase/ is a different content kind from examples/. Nesting would have listed a container as an example and inflated the example count. This PR adds the schema slot, the conventions, and one budget-gated crate so the category is real.

Squash-merge subject should stay feat: (minor bump). Three commits, all -s.

Type

• feat — new skill / rule / snippet / template / example (minor bump)

Task 1 — six infrastructure changes (commit f828299)

1. plugin.json showcase key. Alongside skills / rules / snippets / templates / examples. Why: the manifest is the closed list of shipped content; a sibling tree that is not an example cannot live under examples.
2. validate-manifest. Schema slot + glob showcase/* directories; every dir must be listed. Why: a decorative key would not catch a missing or extra piece.
3. validate-counts. Counts showcase/<dir>/README.md separately. README needle is {n} showcase piece(s), not folded into examples. Why: the example total must stay a count of examples.
4. pages.yml. showcase/** added to the path filter; nothing else in that file. Why: gallery/site rebuilds when a piece or showcase/gallery.json changes.
5. Site + gallery JSON. Not awkward — proceeded. scripts/build_gallery.py merges showcase/gallery.json pieces[] into docs/gallery/ and tags showcase. scripts/site/build_site.py reads the same file for a landing #showcase panel. Each tree owns its index.
6. gallery_framing import. Helper not moved. The crate resolves repo root and imports from examples/ with a comment naming why. inspection-only that gallery_framing.py is byte-identical to main.

catalog.json / run_example.py take opaque paths — no change. blender-smoke.yml has no path filter — no change; the new catalog row is enough.

Task 2 — conventions (commit 93ba58b)

showcase/README.md: deterministic (no RNG here; DECIMATE COLLAPSE named as the cross-series non-match), budgets declared and recomputed, falsifier breaks one stage, file-local exits including 9, still + gallery (pathology exemption does not apply), composition list. "It rendered without error" is not an assertion.

Task 3 — showcase/shipping-crate/ (commit 6ba9a44)

Procedural beveled body, lid + four-wall slats, iron corner wraps, two materials. Pipeline: unique-cell UVs, Cycles cage bake 256² samples=1, LOD COLLAPSE, convex hull, Unity glTF (export_yup, export_apply).

Composes skills mesh-editing-and-bmesh, bake-high-to-low, depsgraph-and-evaluated-data, engine-export-presets and snippets bake_normal_high_to_low.py, setup_bake_target_image.py, lod_chain.py / decimate_to_budget.py, convex_hull_collider.py, export_preset_unity.py (copied, not imported as a package).

Declared vs measured — live-run-proven

Binaries (each printed its own version line):

Binary	Reports
.scratch/blender-4.5.11-windows-x64/blender.exe	Blender 4.5.11 LTS hash 4db51e9d1e1e
.scratch/blender-5.1.2-windows-x64/blender.exe	Blender 5.1.2 hash ec6e62d40fa9
.scratch/blender-5.2.1-windows-x64/blender.exe	Blender 5.2.1 LTS hash 9e2066aef7ef

Axis	Declared	4.5.11	5.1.2	5.2.1
Base tris	500–620	552	552	552
LOD1 ratio	0.32–0.62	0.5000 (276)	0.5000 (276)	0.4239 (234)
LOD2 ratio	0.10–0.35	0.2174 (120)	0.2174 (120)	0.1558 (86)
Materials	2 distinct	2	2	2
UVs	[0,1], overlap ≤ 1e-5	in range, 0	in range, 0	in range, 0
Outer AABB m	(1.256, 0.856, 0.748) ± 0.01	match, zmin 0	match	match
Collider tris	≤ 48	20	20	20
Export bytes	> 0	42092	42092	42088

DECIMATE COLLAPSE is the named cross-series non-match — ratio band, not exact count. Bake pixels are stochastic — gate is FINISHED + has_data, not byte-identity. Construction uses no RNG. Two consecutive 5.2.1 defaults printed identical 552 / 234 / 86.

Default and falsifier exits — live-run-proven

	4.5.11	5.1.2	5.2.1
default	0	0	0
--skip-decimate	9	9	9

Falsifier skips the LOD DECIMATE stage. Named budget: LOD1 ratio (1.0000 not in [0.32, 0.62]). The same bands that pass all three binaries fail the falsifier — not a design problem.

--output on 5.2.1, no deviation=: framing_fill y=0.755 in 0.70–0.90, margins ≥ 0.038, framing_ok, still written. live-run-proven.

Task 4 — added smoke wall-clock — live-run-proven

Check-only (what CI runs). First invocation this session / later warm:

Series	First (s)	Warm (s)
4.5.11	7.39	1.06
5.1.2	7.13	0.99–1.42
5.2.1	5.62	1.14

All well under ~90 s. Catalog order puts bake-normal-high-to-low before this row, so CI will already have compiled Cycles kernels. Recommendation: keep showcase on the default PR smoke path. A separate job / needs-5.1-style label / cron-only gate is not justified at this cost. Revisit when the second and third pieces land if their sum crosses 90 s.

blender-smoke.yml unchanged.

Task 5 — canaries — live-run-proven

Local copies of the validate.yml inline Python. Windows glob prints backslashes; CI Linux will print showcase/shipping-crate. Canaries deleted; clean pass after.

===== CANARY 1 remove showcase/shipping-crate from plugin.json exit=1 =====
--- stderr ---
::error::showcase: showcase\shipping-crate on disk but not in manifest

===== CANARY 2 unlisted directory showcase/_canary_orphan exit=1 =====
--- stderr ---
::error::showcase: showcase\_canary_orphan on disk but not in manifest

===== CANARY 3 README showcase count disagrees with tree exit=1 =====
--- stderr ---
::error::README showcase count mismatch (expected "1 showcase piece" substring)

===== CANARY 4a validate-manifest clean exit=0 =====
--- stdout ---
Manifest verified at v0.63.0: {'skills': 16, 'rules': 9, 'snippets': 27, 'templates': 3, 'examples': 59, 'showcase': 1}

===== CANARY 4b validate-counts clean exit=0 =====
--- stdout ---
Counts verified: 16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, 1 showcase piece

Inspection-only

• Generated gallery HTML: card alt is the full first sentence (no split(".")[0] truncation); data-tags includes showcase; witnesses callout matches gallery.json.
• Contact-sheet / asset-sheet composites were not committed. showcase/README.md requires framing + still, not those example-run gates. Framing was enforced live. If the crate is the least-designed object next to collision-hull-proxy / custom-normals-shade, that is a follow-up, not a silent pass.
• use_nodes deprecation warning on 5.2 — same as existing examples; not addressed here.

Checklist

• Explicit paths only. CLAUDE.md count line is a deliberate edit.
• README 1 showcase piece (examples stay 59).
• Manifest showcase lists showcase/shipping-crate. Version line untouched.
• showcase/gallery.json, catalog row, README preview, hero/preview webp, python scripts/build_gallery.py, framing gate.
• Falsifier --skip-decimate → exit 9 on all three binaries.
• DCO on every commit.
• No credentials.

Test plan

• Default + --skip-decimate on 4.5.11, 5.1.2, 5.2.1.
• --output still + framing on 5.2.1.
• Two consecutive 5.2.1 defaults identical.
• Four validate canaries, then clean restore.
• CI: Validate, drift-check, Blender 5.2 smoke, Blender 4.5 smoke, Blender 5.1 smoke (needs-5.1 via REST). Socket Security pending as usual.

Do not merge from this PR.