fix(showcase): rebuild cart and stone-well joints, with eight new hygiene budgets (#206)

* fix(showcase): hoop the cart's tyre onto the felloe and round the rim

The tyre's inner radius was set equal to the felloe's outer radius
(`r_mid = RIM_OUTER + TYRE_T/2, radial_t = TYRE_T/2`), which put both
surfaces on one plane for every segment: 32 coplanar cross-shell face
pairs, 16 per wheel. It was visible as speckle on the committed hero
and in a clay pass, and no budget could see it.

Derive the tyre's inner radius from the felloe's outer radius minus a
named interference (TYRE_SEAT) and its tread from the felloe plus its
own thickness, so the band bites into the rim and still owns the ground
contact. Wheel segments 16 -> 24: at 16 the rim read as a polygon and
the facet facing the key light rendered as a hard white plate. Iron
raised from (0.13, rough 0.32) to (0.20, rough 0.50), inside the range
its sibling pieces use, because the tyre was reading as black plastic.

Four new budgets, each recomputed from the generated mesh:

- coplanar cross-shell face pairs = 0 (hay-bale's combinatorics, copied)
- each tyre's own zmin on the floor, not just the AABB's
- tyre seat depth banded per angular station, 48 stations
- the two wheels mirrored in Y within 5e-5 m

Four new falsifiers, each landing on its own code and sized to stay
inside BBOX_TOL so the AABB gate cannot steal the failure: --flush-tyre
(15), --sink-tyre (18), --float-wheel (16), --skew-wheel (19).

Also drops the temp .glb once measured — the leak PR #205 found in
hay-bale is in this piece too.

Base triangles re-fitted to 2760-2960: narrower than the 2470-2900 it
replaces and centred on the measured 2856.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

* fix(showcase): put the well's posts under the roof corners and tenon them in

Three structural defects, all found by looking at an inspection sheet:

1. The four roof posts stood at 0/90/180/270 degrees while the roof's
   4-gon cone is rotated pi/4, so its corners sit on the diagonals. The
   posts were under the midpoint of each eave: the roof's corners
   cantilevered 0.80 m unsupported, and one post stood dead centre in
   the well mouth in every orthographic view. Posts moved to the
   diagonals, and the windlass, crank and grip turn with them.

2. Each post's bottom face landed exactly on the coping's top face —
   4 coplanar cross-shell face pairs, one per post. Posts are now
   tenoned POST_SEAT into the coping, with POST_TOP held fixed so
   nothing above them moves.

3. EAVE_HALF was derived from the post ring plus an overhang, giving a
   1.64 m roof over a 1.08 m drum: an umbrella, not a well house. It is
   now derived from what the roof must cover — the curb's own radius
   plus a named clearance — which brings the AABB to 1.312 m.

The bucket hung at z=0.68 with only its rim level with the coping:
invisible in the hero and in all six orthographic views. It now hangs
BUCKET_CLEAR above the measured coping top and reads in the still.

Five new budgets, each recomputed from the generated mesh — the tenon
and the bucket clearance measure against the coping top read off the
stone material, not against the constant the builder used:

- coplanar cross-shell face pairs = 0
- all 12 bottom-course stones on the floor, not just the lowest
- post tenon depth banded, per post
- each post within 0.02 rad in plan of a roof hip corner
- bucket clearance banded above the coping

Five new falsifiers. Two needed re-aiming to hit their own budget:
--stand-posts also returns the posts to the axis, because flush alone
at 45 degrees leaves no coping face within COPLANAR_CENTRE_MAX of a
foot; --turn-posts rotates by exactly one curb facet, because any other
angle sets the feet on different coping geometry and the gap gate (17)
steals the failure, and a full 45 degrees swings the crank past the
eave and fails the AABB gate (8).

Collider ceiling 320 -> 380: the convex hull of the resized roof
measures 346. Also drops the temp .glb once measured.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

* fix(examples): make ngon-triangulate's falsifier actually falsify

`--skip-triangulate` printed an error and returned 4 from its own
branch. The flag announced a failure rather than causing one, and the
handling assertions it exists to falsify never ran. It now skips the
repair and lets those assertions catch the unrepaired mesh, which
reports the real measurement (`ngons=1 tris=0 quads=4`).

The contract, the assertions and the exit codes are unchanged. Proven
identical before and after on 4.5.11 LTS, 5.1.2 and 5.2.1 LTS: default
0, --no-dissolve 3, --skip-triangulate 4.

README: adds the verified `calc_tangents` abort text, which is
byte-identical on all three binaries, a falsifier table naming what
each flag breaks, and 4.5/5.2 API links for calc_tangents,
dissolve_edges and triangulate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

* docs(showcase): fold this pass's defects into the shared conventions

Seven conventions every future piece inherits, each from a defect in
this pass that no existing budget could see: a band is hooped onto its
host and never set flush against it; a member is tenoned into its seat
and never stood on it, measured against the host read off the mesh;
posts go under a roof's corners, with the corners taken from the pooled
eave vertices rather than one fascia board; a roof is sized from what
it covers, not from what carries it; the subject hangs where it can be
seen; mirrored assemblies pair and compare, with the falsifier sized
inside BBOX_TOL; and segment counts are a silhouette budget.

Also registers this pass's falsifier flags in the shared list and
regenerates the gallery for the two rebuilt pieces.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

---------

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.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: 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>
+          <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.312×1.312×1.761 m, LOD ratios in band, convex collider 346 tris, hygiene zero (loose, non-manifold, doubles, n-gons), zero coplanar cross-shell face pairs, all 12 bottom-course stones on the floor, each post tenoned 18 mm into the measured coping and standing under a roof hip corner, the bucket hanging 0.10 m clear of the coping, grounded zmin, non-empty glTF. --stand-posts exits 15 on the z-fight budget; --float-stone exits 16 on the named-support budget; --shallow-tenon and --drop-bucket exit 18; --turn-posts exits 19 on post placement; --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 showcase piece <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: 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>
+          <p class="witnesses"><span class="tag">witnesses</span> Recomputed: 2856 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 154 tris, hygiene zero (loose, non-manifold, doubles, n-gons), zero coplanar cross-shell face pairs, both tyres grounded, tyre seat depth in band over 48 angular stations, the two wheels mirrored within 5e-5 m, grounded zmin, non-empty glTF. --flush-tyre exits 15 on the z-fight budget; --sink-tyre exits 18 on the tyre seat band; --float-wheel exits 16 on the named-support budget; --skew-wheel exits 19 on the wheel mirror; --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 showcase piece <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>

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

@@ -22,6 +22,38 @@ glTF tris = 12 for a cube *or* this mesh. `--skip-triangulate` exits 4.
 No gallery still. A hexagon on a cube does not read at thumbnail
 without fake annotation.
 
+## Verified behaviour
+
+`Mesh.calc_tangents` raises `RuntimeError` on any face with more than
+four loops. The message is byte-identical on 4.5.11 LTS, 5.1.2, and
+5.2.1 LTS:
+
+```
+Error: Tangent space can only be computed for tris/quads, aborting
+```
+
+`TANGENT_ABORT` matches on the `tris/quads` substring, so the check
+survives a reword of the surrounding sentence but still fails if the
+abort stops happening at all.
+
+## Falsifiers
+
+Each flag breaks one stage and lands on the assertion that stage feeds.
+Neither announces a failure; both let a real check catch the mesh.
+
+| Flag | What it breaks | Exit |
+| --- | --- | --- |
+| `--no-dissolve` | never makes the n-gon, so the pre-assertion finds no pathology (`ngon count 0 != 1`) | 3 |
+| `--skip-triangulate` | skips `bmesh.ops.triangulate`, so the handling assertion sees the n-gon survive (`ngons=1 tris=0 quads=4`) | 4 |
+
+## API reference
+
+| Name | 4.5 LTS | 5.2 LTS |
+| --- | --- | --- |
+| `Mesh.calc_tangents` | [4.5](https://docs.blender.org/api/4.5/bpy.types.Mesh.html#bpy.types.Mesh.calc_tangents) | [5.2](https://docs.blender.org/api/current/bpy.types.Mesh.html#bpy.types.Mesh.calc_tangents) |
+| `bmesh.ops.dissolve_edges` | [4.5](https://docs.blender.org/api/4.5/bmesh.ops.html#bmesh.ops.dissolve_edges) | [5.2](https://docs.blender.org/api/current/bmesh.ops.html#bmesh.ops.dissolve_edges) |
+| `bmesh.ops.triangulate` | [4.5](https://docs.blender.org/api/4.5/bmesh.ops.html#bmesh.ops.triangulate) | [5.2](https://docs.blender.org/api/current/bmesh.ops.html#bmesh.ops.triangulate) |
+
 ## Run
 
 ```bash
@@ -41,7 +73,7 @@ against it.
 | 1 | Uncaught exception (FATAL wrapper) |
 | 2 | argparse / usage |
 | 3 | Pathology missing: n-gon count, loops, or face count (`--no-dissolve` lands here) |
-| 4 | `calc_tangents` / triangulate handling (`--skip-triangulate` lands here) |
+| 4 | `calc_tangents` / triangulate handling (`--skip-triangulate` lands here, via the real handling assertion) |
 
 The `blender-smoke` workflow runs the check on Blender 5.2 LTS and 4.5 LTS
 (5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch).

docs/gallery/cart/index.html

@@ -9,7 +9,9 @@
 
 * 5 faces, 1 n-gon, that face has 6 loops
 * ``Mesh.calc_tangents`` aborts until triangulated
-  (same abort ``triangulate-tangents`` documents)
+  (same abort ``triangulate-tangents`` documents). The message is
+  byte-identical on 4.5.11 LTS, 5.1.2 and 5.2.1 LTS:
+  "Error: Tangent space can only be computed for tris/quads, aborting"
 * triangulate the n-gon → 4 tris + 4 quads, 28 loops, tangents succeed
 
 glTF tri count is 12 either way (hexagon+quads or a cube) — not a
@@ -117,13 +119,12 @@ def check(ob, skip_triangulate):
             file=sys.stderr,
         )
         return 4
-    if skip_triangulate:
-        print(
-            "ERROR: skip-triangulate left the n-gon; handling unrepaired",
-            file=sys.stderr,
-        )
-        return 4
-    triangulate_ngons(me)
+    # --skip-triangulate skips the repair and lets the handling assertions
+    # below catch the unrepaired mesh. Returning 4 from here instead would
+    # make the flag announce a failure rather than cause one, and the
+    # assertions it is supposed to falsify would never run.
+    if not skip_triangulate:
+        triangulate_ngons(me)
     leftover = ngons(me)
     tris = sum(1 for p in me.polygons if len(p.vertices) == 3)
     quads = sum(1 for p in me.polygons if len(p.vertices) == 4)

docs/gallery/contact-sheets/cart-contact-sheet.webp

@@ -42,6 +42,13 @@ entry in `showcase/gallery.json`, and a rendered still.
   coplanar-face budget fails (exit 15). `--short-stile` /
   `--short-post` lift a member out of its cup (exit 18 or 19).
   `--clip-ring` pulls a hung ring off the eye centerline (exit 18).
+  `--flush-tyre` / `--stand-posts` restore a flush surface so the
+  coplanar budget fails (exit 15). `--float-wheel` / `--float-stone`
+  lift one named support while the rest still ground the AABB (exit 16).
+  `--sink-tyre` / `--shallow-tenon` put a seat outside its band (exit
+  18). `--drop-bucket` hides the hung subject (exit 18).
+  `--skew-wheel` / `--turn-posts` break a mirror or placement budget
+  (exit 19).
   A budget with no falsifier witnesses nothing:
   prove each one fails once, and check the exit code, not just
   non-zero.
@@ -187,6 +194,63 @@ entry in `showcase/gallery.json`, and a rendered still.
   The outer AABB does not cover this: on a prop with an appendage the
   AABB is the appendage, and the body can drift to any size underneath
   it.
+- **A band is hooped onto its host, never set flush against it (exit
+  15/18).** A tyre, ferrule, hoop or collar derives its **inner** radius
+  from the host's **outer** radius minus a named interference, and its
+  outer radius from the host plus its own thickness. Writing
+  `r_mid = host_out + t/2, radial_t = t/2` — the obvious spelling —
+  makes the band's inner cylinder and the host's tread the *same
+  surface*, so every segment is a coplanar cross-shell pair around the
+  whole circumference. `cart` shipped that way and measured 32 pairs
+  (16 per wheel); the speckle was visible on the committed hero and in
+  a clay pass, and no budget could see it. `--flush-tyre` restores the
+  equality and is the falsifier.
+- **A member is tenoned into its seat, never stood on it (exit
+  15/18).** A post, leg or stile whose bottom face lands exactly on its
+  host's top face puts both on one plane. Derive the member's bottom
+  from the host's top minus a named seat depth, and hold the member's
+  *top* fixed so nothing above it moves. `stone-well` stood its four
+  roof posts on the coping and measured 4 pairs, one per post.
+  Assert the seat as a **band** recomputed against the host surface read
+  off the generated mesh — `max z` over the host's material — not
+  against the constant the builder used, which witnesses nothing.
+- **Posts go under the roof's corners, not the middle of its eaves
+  (exit 19).** Where a hip or pyramid roof is carried on four posts,
+  assert each post's plan bearing against a hip corner **recomputed from
+  the generated mesh**, as a wrapped angular difference. Take the
+  corners from the *pooled* vertices at the eave line: pulling them from
+  a single shell picks one fascia board, whose own extremes sit 90° off
+  the corners it is nailed to, and the budget then fails on a correct
+  model. `stone-well` placed its posts on the axes, which cantilevered
+  the roof's corners 0.80 m and stood one post dead centre in the well
+  mouth in every orthographic view.
+- **A roof is sized from what it must cover, not from what carries it.**
+  Deriving the eave reach from the post ring plus an overhang gave
+  `stone-well` a 1.64 m roof over a 1.08 m drum — an umbrella. Derive it
+  from the covered body's own radius plus a named clearance
+  (`EAVE_HALF = R_OUTER + CURB_OUT + EAVE_CLEAR`), and let the overhang
+  fall out of that. Expect the convex-hull collider budget to move when
+  the roof does; re-fit it and say so.
+- **The subject hangs where it can be seen (exit 18).** A prop whose
+  story is one small part — a bucket on a rope, a lantern on a hook —
+  asserts that part's clearance above the body it hangs over, as a band,
+  measured against the body read off the mesh. `stone-well`'s bucket sat
+  down the shaft with only its rim level with the coping: invisible in
+  the hero and in all six orthographic views, and no budget noticed.
+  `--drop-bucket` is the falsifier.
+- **Mirrored assemblies (exit 19).** Where a prop has a left and a
+  right of the same part — two wheels, two brackets — pair the shells
+  and assert they match in the two axes they share and in their extents,
+  within a named epsilon, and are opposite in the mirrored axis. Size
+  the falsifier's displacement to stay **inside** `BBOX_TOL` so the AABB
+  gate cannot steal the failure: `cart`'s `--skew-wheel` moves one wheel
+  6 mm along a track whose tolerance is 10 mm.
+- **Segment counts are a silhouette budget, not a triangle budget.** A
+  16-gon felloe reads as a polygon at hero size, and the flat facet
+  facing the key light renders as a hard white plate. `cart` went to 24
+  and the chords disappeared. Re-fit the triangle band around the new
+  measured count rather than leaving the old one — and prefer a band
+  *narrower* than the one it replaces, centred on the measurement.
 - **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: