fix: showcase quality pass — stone-well and cart (#171)

* fix: rebuild stone-well so the joints meet and the bucket opens

Quality pass on the stone-well generator after an inspection-sheet
review found the curb floating above the masonry, windlass stubs buried
in the posts, a crank that was a capped stub, an open pit at the roof
peak, a sealed bucket with hoops that ignored the taper, a bail handle
floating off the rim, and a rope that ended above the handle.

Structural fixes in the generator: curb Z derived from the masonry top,
windlass lengthened to pass through both posts, a real crank arm and
grip, a peak cap, a manifold open bucket with tapered walls and hoops
that follow it, bail legs pinned at the rim, rope terminated at the
bail bar. Deterministic per-stone jitter, bevels on structural wood,
noise/wear on all three materials, cap_tris everywhere to kill n-gons.

New budgets: hygiene (loose/non-manifold/zero-area/doubles/ngons all
zero, exit 15), grounded zmin (exit 16, --lift-z falsifier), BVH
material-island gaps (exit 17), per-material face floors (exit 5) that
catch the materials.clear() index-wipe class. Slot assignment is now
index-preserving. Hero re-rendered; framing gate passes.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: rebuild cart so the axle carries the bed and the wheels read

Quality pass on the cart generator after an inspection-sheet review
found the axle interpenetrating the bed floor, shafts poking through
the bed, corner plates buried inside the wall corners, shaft straps
floating off the bed, inconsistent wall heights, torus-profile wheels
with round pipe treads, and spokes floating at both ends.

Structural fixes in the generator: bed Z derived from the axle top via
real bolster beams, shafts dropped to run beside the bed edge and angle
down, corner plates moved onto the bed top, straps aligned to the bed
bottom, a lower tailgate, flat-tread felloes and iron tyres built as
rings, spokes embedded at hub and felloe. Noise/wear on both materials,
cap_tris everywhere to kill n-gons.

New budgets: hygiene (loose/non-manifold/zero-area/doubles/ngons all
zero, exit 15), grounded zmin (exit 16, --lift-z falsifier), BVH
metal-wood gap (exit 17), wood face floor (exit 5). Hero re-rendered;
framing gate passes.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* docs: add material face-floor convention and refresh showcase gallery

Adds the material face-floor convention to the showcase README: every
declared material asserts a named minimum polygon count recomputed from
polygon.material_index, which catches the slot-assignment wipe class
(materials.clear() resets material_index to 0 on some versions while
the slot count still passes). Slot assignment must be index-preserving.

Refreshes the stone-well and cart witness strings in
showcase/gallery.json for the quality-pass numbers and regenerates
docs/gallery. The regeneration also picks up iron-cauldron detail-page
drift whose README landed without a gallery rebuild.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TMHSDigital

docs/gallery/assets/cart-hero.webp

@@ -903,7 +903,7 @@ <h2><a href="shipping-crate/">shipping-crate</a></h2>
         <div class="card-body">
           <h2><a href="stone-well/">stone-well</a></h2>
           <p class="teaches">A procedural stone well through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract.</p>
-          <p class="witnesses"><span class="tag">witnesses</span> Recomputed: 8388 tris, three materials, UVs in 0..1 with zero AABB overlap, outer AABB 1.640×1.640×1.688 m, LOD ratios in band, convex collider 230 tris, non-empty glTF. --skip-decimate exits 9 on the LOD1 ratio budget.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> Recomputed: 9380 tris, three materials with face floors, UVs in 0..1 with zero AABB overlap, outer AABB 1.640×1.640×1.761 m, LOD ratios in band, convex collider 306 tris, hygiene zero (loose, non-manifold, doubles, n-gons), grounded zmin, non-empty glTF. --skip-decimate exits 9 on the LOD1 ratio budget; --lift-z exits 16 on the grounded budget.</p>
           <a class="card-link" href="stone-well/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
@@ -1002,7 +1002,7 @@ <h2><a href="watchtower/">watchtower</a></h2>
         <div class="card-body">
           <h2><a href="cart/">cart</a></h2>
           <p class="teaches">A procedural two-wheel wooden cart through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract.</p>
-          <p class="witnesses"><span class="tag">witnesses</span> Recomputed: 2572 tris, two materials with 100 metal faces, UVs in 0..1 with zero AABB overlap, outer AABB 1.547×0.749×0.656 m, LOD ratios in band, convex collider 306 tris, non-empty glTF. --skip-decimate exits 9 on the LOD1 ratio budget.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> Recomputed: 2600 tris, two materials with metal and wood face floors, UVs in 0..1 with zero AABB overlap, outer AABB 1.539×0.749×0.640 m, LOD ratios in band, convex collider 122 tris, hygiene zero (loose, non-manifold, doubles, n-gons), grounded zmin, non-empty glTF. --skip-decimate exits 9 on the LOD1 ratio budget; --lift-z exits 16 on the grounded budget.</p>
           <a class="card-link" href="cart/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>

docs/gallery/assets/stone-well-hero.webp

@@ -265,7 +265,7 @@ <h1>iron-cauldron</h1>
 <h2>Budgets</h2>
 <p>Declared as named constants; every gate <strong>recomputes</strong> from the mesh, materials, UVs, evaluated LOD, collider, or export file.</p>
 <p>| Axis | Declared | Measured (4.5.11 / 5.1.2 / 5.2.1) | | --- | --- | --- | | Base triangles | 3280–3520 | 3388 / 3388 / 3388 | | LOD1 ratio | 0.32–0.62 of base | 0.5000 / 0.5000 / 0.5000 | | LOD2 ratio | 0.10–0.35 of base | 0.2196 / 0.2196 / 0.2172 | | Materials | exactly 2 distinct, ≥12 wood, ≥24 metal | 2 slots, 450 wood, 1198 metal | | UVs | in <code>0..1</code>, AABB overlap ≤ 1e-5 | in range, overlap 0 | | Outer AABB | (1.013, 0.986, 0.827) m ± 0.01 | (1.0128, 0.9865, 0.8271), zmin 0.002 | | Pot–leg clearance | ≥ 0.04 m (recomputed vs pole axes) | 0.0513 / 0.0513 / 0.0513 | | Collider tris | ≤ 200 | 98 | | Export | written, size &gt; 0 | 245060 / 245060 / 245044 bytes |</p>
-<p>DECIMATE COLLAPSE triangle counts are <strong>not</strong> identical across series — 5.2.1 is 4 tris leaner on LOD2. The gate is a ratio band, not an exact count. Bake pixels are stochastic; the gate is <code>has_data</code> plus operator <code>FINISHED</code>, not byte-identity. Construction uses no RNG. Export byte counts differ by 12 B on 5.2.1 (glTF serializer), not a gated axis.</p>
+<p>DECIMATE COLLAPSE triangle counts are <strong>not</strong> identical across series — 5.2.1 is 8 tris leaner on LOD2. The gate is a ratio band, not an exact count. Bake pixels are stochastic; the gate is <code>has_data</code> plus operator <code>FINISHED</code>, not byte-identity. Construction uses no RNG. Export byte counts differ by 16 B on 5.2.1 (glTF serializer), not a gated axis. The pot–leg clearance is recomputed from shell verts vs the three pole axes; clipping exits 3.</p>
 <p><code>--skip-decimate</code> skips the LOD DECIMATE stage so LOD1 ratio is 1.0 and exit 9 fires. That is the named budget the falsifier violates.</p>
 <h2>Run</h2>
 <pre><code>blender --background --python iron_cauldron.py --

docs/gallery/cart/index.html

@@ -43,6 +43,13 @@ entry in `showcase/gallery.json`, and a rendered still.
   characteristic 2 — that is a single-shell contract. Pairs of parts
   meant to touch assert a BVH surface gap below a named epsilon
   (vert-vert is the wrong metric for thin straps and collars).
+- **Material face floors.** Every declared material asserts a named
+  minimum face count on the finished mesh, recomputed from
+  `polygon.material_index`. This catches the slot-assignment wipe class:
+  `obj.data.materials.clear()` resets every polygon's `material_index`
+  to 0 on some versions, which renders the piece single-material while
+  the slot count still passes. Assign slots by index-preserving
+  append/replace, never clear-and-rebuild.
 - **Exit codes** are file-local: `0` success, argparse `2`, `3` and above
   in check order. `9` is legal. FATAL `sys.exit(1)` is a crash, never a
   named check.

docs/gallery/index.html

@@ -21,14 +21,17 @@ materials, UVs, evaluated LOD, collider, or export file.
 
 | Axis | Declared | Measured (4.5.11 / 5.1.2 / 5.2.1) |
 | --- | --- | --- |
-| Base triangles | 2470–2680 | 2572 / 2572 / 2572 |
+| Base triangles | 2470–2900 | 2600 / 2600 / 2600 |
 | LOD1 ratio | 0.32–0.62 of base | 0.5000 / 0.5000 / 0.5000 |
-| LOD2 ratio | 0.10–0.35 of base | 0.2193 / 0.2193 / 0.2146 |
-| Materials | exactly 2 distinct, ≥24 metal faces | 2 slots, 100 metal |
+| LOD2 ratio | 0.10–0.35 of base | 0.2200 / 0.2200 / 0.2154 |
+| Materials | exactly 2 distinct, metal ≥ 24, wood ≥ 800 faces | 2 slots, floors met |
 | UVs | in `0..1`, AABB overlap ≤ 1e-5 | in range, overlap 0 |
-| Outer AABB | (1.547, 0.749, 0.656) m ± 0.01 | (1.5473, 0.7486, 0.6560), zmin 0 |
-| Collider tris | ≤ 360 | 306 |
-| Export | written, size > 0 | 202500 / 202500 / 202492 bytes |
+| Outer AABB | (1.539, 0.749, 0.640) m ± 0.01 | (1.5393, 0.7486, 0.6400) |
+| Grounded | bbox min Z within 1e-4 of 0 | 0.0000 / 0.0000 / 0.0000 |
+| Hygiene | loose V/E, non-manifold, zero-area, doubles @1e-5, n-gons: all 0 | 0 / 0 / 0 on every axis |
+| Material-island gap | metal↔wood min distance ≤ 0.008 m | 0.00000 / 0.00000 / 0.00000 |
+| Collider tris | ≤ 360 | 122 |
+| Export | written, size > 0 | 201048 / 201048 / 201032 bytes |
 
 DECIMATE COLLAPSE triangle counts are **not** identical across series —
 5.2.1 is more aggressive on LOD2. The gate is a ratio band, not an
@@ -38,17 +41,20 @@ Export byte counts differ by 8 B on 5.2.1 (glTF serializer), not a
 gated axis.
 
 `--skip-decimate` skips the LOD DECIMATE stage so LOD1 ratio is 1.0 and
-exit 9 fires. That is the named budget the falsifier violates.
+exit 9 fires. `--lift-z` raises the finished mesh 0.05 m so the grounded
+budget fails and exit 16 fires. Those are the named budgets the two
+falsifiers violate.
 
 ## Run
 
 ```bash
 blender --background --python cart.py --
 blender --background --python cart.py -- --skip-decimate
+blender --background --python cart.py -- --lift-z
 blender --background --python cart.py -- --output cart.png
 ```
 
-Smoke does not pass `--output` or `--skip-decimate`.
+Smoke does not pass `--output`, `--skip-decimate`, or `--lift-z`.
 
 ## Exit codes
 
@@ -72,3 +78,6 @@ File-local. `9` is a valid check code. `10` is reserved for
 | 12 | Bake did not finish or image has no data |
 | 13 | Export file missing or empty |
 | 14 | `--output` produced no file |
+| 15 | Hygiene: loose geometry, non-manifold, zero-area, doubles, or n-gons |
+| 16 | Bbox min Z not grounded (`--lift-z` lands here) |
+| 17 | Material-island gap above tolerance (parts meant to touch) |