fix(examples): redesign mesh-hygiene-audit as a flanged street valve with marked defects (#269)

The gallery review judged the hero weak: a crude octagonal brass spool shown
twice, the defects a thin orange wire that read as a render glitch, and floor
labels unreadable at card size.

The subject is now a designed upright street valve in eight named parts
(body casting, side outlet, 22 flange bolts, gland nut, threaded stem,
brass handwheel hub, rim and spokes; four materials, chamfered steps). The
still shows a dirty copy beside the clean valve with no labels. The dirty
body carries a hole, a flipped patch, an ngon and three loose verts. Markers
are read back from audit incidence: red boundary tubes, red loose-vert beads
and an amber ngon slot. Flipped faces and the inside of the hole glow red
through the paint's Backfacing mix, so the renderer itself shows the winding.
On the clean valve the same material shows no red.

The check is stronger, not weaker. Gates 3-7 now run on every part, not
just one mesh. A new winding-consistency gate (BMEdge.is_contiguous, exit 7)
catches flipped patches that signed volume misses. --inject KIND covers
every gate, including a buried second shell that only Euler (exit 8) can
see. The render path adds the asset-quality floor (exit 11) and refuses to
write a still if staging loses a defect class.

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

Author: TMHSDigital

README.md

@@ -992,19 +992,21 @@ with the Smooth-by-Angle modifier on 5.1.
 </tr>
 <tr>
 <td width="46%" valign="middle">
-<a href="examples/mesh-hygiene-audit/"><img src="examples/mesh-hygiene-audit/preview.webp" alt="Mesh hygiene audit: dual-panel dirty vs clean brass street valves filling the frame — left with backlit through-hole, emissive boundary tubes and loose-vert bead over a DIRTY placard, right intact CLEAN manifold — proving the engine-ingest topology checklist" /></a>
+<a href="examples/mesh-hygiene-audit/"><img src="examples/mesh-hygiene-audit/preview.webp" alt="Mesh hygiene audit: two blue flanged street valves with brass handwheels — the left dirty copy with a red-outlined hole, a red flipped patch on the bonnet, an amber ngon on the base flange and three red loose-vert beads, the right one intact — proving the engine-ingest topology checklist" /></a>
 </td>
 <td valign="middle">
 
 ### [mesh-hygiene-audit](examples/mesh-hygiene-audit/)
 
 The mesh-cleanliness contract a prop pipeline relies on before engine ingest:
 no ngons, no loose vertices, every edge bordering exactly two faces, no
-zero-area faces, positive signed volume, and Euler `V − E + F == 2` for a
-closed solid (measured 66/136/72, volume 0.652001). Companion to
+zero-area faces, contiguous and outward winding on all eight parts of a
+flanged street valve, and Euler `V − E + F == 2` on its body casting
+(measured 802/1632/832, volume 0.453344). Companion to
 [`collision-hull-proxy`](examples/collision-hull-proxy/) (hull watertightness)
-and [`bmesh-gear`](examples/bmesh-gear/) (parametric closed solids). Dual-panel
-still: DIRTY through-hole + loose-vert bead vs CLEAN manifold (same brass).
+and [`bmesh-gear`](examples/bmesh-gear/) (parametric closed solids). Still: a
+dirty copy with a hole, flipped patch, ngon and loose verts marked from live
+audit data beside the intact valve; the paint glows red on any back face.
 
 </td>
 </tr>

docs/gallery/asset-sheets/mesh-hygiene-audit.webp

@@ -739,12 +739,12 @@ <h2><a href="gp-lineart-contour/">gp-lineart-contour</a></h2>
       </article>
       <article class="card" data-tags="bmesh mesh game-pipeline">
         <a class="card-media" href="mesh-hygiene-audit/" tabindex="-1" aria-hidden="true">
-          <img src="assets/mesh-hygiene-audit-hero.webp" alt="Two brass spool-shaped props labelled DIRTY and CLEAN; the dirty one has glowing orange stray edges inside it." loading="lazy" decoding="async" />
+          <img src="assets/mesh-hygiene-audit-hero.webp" alt="Two blue street valves with brass handwheels: the left has a red-outlined hole, a red bonnet patch, an amber flange patch and three red beads beside it; the right is intact." loading="lazy" decoding="async" />
         </a>
         <div class="card-body">
           <h2><a href="mesh-hygiene-audit/">mesh-hygiene-audit</a></h2>
-          <p class="teaches">Engine-ingest mesh hygiene on an octagonal street valve: no ngons, no loose verts, manifold edges, no zero-area faces, positive signed volume, Euler V-E+F==2. Dual-panel still shows a through-hole and loose-vert bead derived from live mesh incidence — same brass on both so color alone cannot carry the proof.</p>
-          <p class="witnesses"><span class="tag">witnesses</span> Pipelines that skip topology gates ship open boundaries, loose verts, or non-sphere Euler into engine ingest. The still makes the boundary hole and loose vert readable; ngon / zero-area / full winding invert remain check-only.</p>
+          <p class="teaches">Engine-ingest mesh hygiene on every part of a flanged street valve: no ngons, no loose verts, manifold edges, no zero-area faces, contiguous and outward winding, Euler V-E+F==2 on the body casting. A dirty copy carries a hole, a flipped patch, an ngon and loose verts, each marked from live audit incidence; the paint glows red wherever the renderer sees a back face.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> Pipelines that skip topology gates ship open boundaries, flipped patches, ngons, loose verts or stray shells into engine ingest. The still shows the first four on a dirty copy; zero-area faces and a buried second shell remain check-only.</p>
           <a class="card-link" href="mesh-hygiene-audit/">View example<span class="sr-only"> mesh-hygiene-audit</span> <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>

docs/gallery/assets/mesh-hygiene-audit-hero.webp

@@ -487,9 +487,9 @@
     {
       "name": "mesh-hygiene-audit",
       "dir": "examples/mesh-hygiene-audit",
-      "teaches": "Engine-ingest mesh hygiene on an octagonal street valve: no ngons, no loose verts, manifold edges, no zero-area faces, positive signed volume, Euler V-E+F==2. Dual-panel still shows a through-hole and loose-vert bead derived from live mesh incidence — same brass on both so color alone cannot carry the proof.",
-      "alt": "Two brass spool-shaped props labelled DIRTY and CLEAN; the dirty one has glowing orange stray edges inside it.",
-      "witnessesFix": "Pipelines that skip topology gates ship open boundaries, loose verts, or non-sphere Euler into engine ingest. The still makes the boundary hole and loose vert readable; ngon / zero-area / full winding invert remain check-only.",
+      "teaches": "Engine-ingest mesh hygiene on every part of a flanged street valve: no ngons, no loose verts, manifold edges, no zero-area faces, contiguous and outward winding, Euler V-E+F==2 on the body casting. A dirty copy carries a hole, a flipped patch, an ngon and loose verts, each marked from live audit incidence; the paint glows red wherever the renderer sees a back face.",
+      "alt": "Two blue street valves with brass handwheels: the left has a red-outlined hole, a red bonnet patch, an amber flange patch and three red beads beside it; the right is intact.",
+      "witnessesFix": "Pipelines that skip topology gates ship open boundaries, flipped patches, ngons, loose verts or stray shells into engine ingest. The still shows the first four on a dirty copy; zero-area faces and a buried second shell remain check-only.",
       "hero": "docs/gallery/assets/mesh-hygiene-audit-hero.webp",
       "preview": "examples/mesh-hygiene-audit/preview.webp",
       "tags": [

docs/gallery/contact-sheets/mesh-hygiene-audit-contact-sheet.webp

@@ -1,8 +1,10 @@
 # Mesh Hygiene Audit
 
-A runnable example that builds an octagonal street valve body and runs the
-**engine-ingest mesh hygiene checklist** as executable topology checks,
-following [`mesh-editing-and-bmesh`](../../skills/mesh-editing-and-bmesh/SKILL.md).
+A runnable example that builds an upright flanged street valve — body
+casting, side outlet, 22 flange bolts, gland nut, threaded stem, brass
+handwheel hub, rim and spokes — and runs the **engine-ingest mesh hygiene
+checklist** on every part as executable topology checks, following
+[`mesh-editing-and-bmesh`](../../skills/mesh-editing-and-bmesh/SKILL.md).
 
 **Pipeline arc neighbors:** watertight / Euler on collision *hulls* in
 [`collision-hull-proxy`](../collision-hull-proxy/), parametric closed solids
@@ -12,67 +14,87 @@ in [`bmesh-gear`](../bmesh-gear/), LOD face budgets in
 pipeline runs on the *render* mesh before hull / LOD / export.
 
 **Scope:** this witnesses the bpy-level contract a prop pipeline relies on
-(tris+quads, no loose verts, manifold edges, no zero-area faces, outward
-winding, Euler 2 for a closed solid). It is not an engine exporter.
+(tris+quads, no loose verts, manifold edges, no zero-area faces, consistent
+and outward winding, Euler 2 for the genus-0 body casting). It is not an
+engine exporter.
 
 **What it witnesses:** every gate is derived from mesh combinatorics or the
-divergence-theorem volume — never from a prior-run capture:
+divergence-theorem volume — never from a prior-run capture. Gates 3–7 run on
+all eight parts; the Euler gate runs on the body casting, the one closed
+genus-0 shell the other parts mount on (the handwheel rim is a torus, the
+bolt and spoke meshes are many shells, so a single-sphere Euler test does
+not describe them):
 
 - **No ngons.** `len(poly.vertices) <= 4` for every face.
 - **No loose vertices.** Every vert has degree ≥ 1.
 - **Manifold edges.** Every edge borders exactly 2 faces (closed solid).
 - **No zero-area faces.** Face area > 1e-10; prints measured `min_area`.
+- **Consistent winding.** Every manifold edge is `BMEdge.is_contiguous` —
+  a flipped patch leaves seam edges whose two faces traverse it the same way.
 - **Outward winding.** Positive signed volume (divergence theorem).
-- **Euler sphere.** `V − E + F == 2` for the clean closed manifold
-  (measured: verts=66 edges=136 faces=72, volume≈0.652001, min_area≈1.146e-02).
+- **Euler sphere.** `V − E + F == 2` on the body casting
+  (measured: verts=802 edges=1632 faces=832, volume≈0.453344,
+  min_area≈1.223e-03).
 
-**What each check catches on failure:** loose vert injected (exit 4);
-face deleted → boundary edges (exit 5); edge dissolved → ngon (exit 3);
-all faces flipped → signed volume negated (exit 7); face collapsed →
-zero-area (exit 6).
+**What each check catches on failure** (`--inject KIND`, default target the
+body casting, `--inject-part NAME` for any other part): `ngon` → exit 3;
+`loose` → exit 4; `boundary` (one face deleted) → exit 5; `zero_area` (face
+collapsed) → exit 6; `flip_patch` (one face flipped) → exit 7 on winding
+seams; `flip` (all faces) → exit 7 on negative volume; `shell` (a leftover
+second closed shell buried inside) → exit 8, the one defect every per-edge
+gate misses. `--inject-ngon` is kept as an alias for `--inject ngon`.
 
-**Version witness:** output is byte-identical on Blender 4.5.11 LTS and
-5.1.2 — same counts, same volume, same `min_area`.
+**Version witness:** the check output is identical on Blender 5.2.1 LTS,
+5.1.2 and 4.5.11 LTS — same counts, same volume, same `min_area`.
 
-**Render as proof:** dual panel, same brass on both. DIRTY stages a
-camera-facing through-hole (boundary edges) plus a loose vert; emissive
-beads/edge tubes are built from the live mesh incidence the check uses —
-not decorative paint. CLEAN is the intact manifold. An out-of-frame AREA
-light rakes through the hole from behind so the aperture reads warm without
-a visible light panel in frame.
+**Render as proof:** a dirty copy of the same valve (left) beside the clean
+valve (right), same paint on both. The dirty body casting carries four real
+gate failures, each placed on the camera-facing side: a hole through the
+globe (open boundary), a flipped patch on the bonnet dome, an ngon merged
+into the base-flange annulus, and three stray loose vertices. The markers are
+read back from the dirty mesh's audit incidence, not from the staging code:
+boundary edges become glowing red tubes, loose verts red beads, ngon faces an
+amber material slot. The flipped patch and the inside of the hole need no
+marker — the paint mixes to red on the shader's own `Backfacing` output, so
+the renderer shows every face it sees from behind. On the clean valve that
+same material shows no red anywhere, because no back side is visible on a
+closed, outward-wound shell. The render path refuses to write a still
+(exit 9) if staging loses any of the four defect classes.
 
-**Not depicted in the still (check-proven only):** ngon dissolve, zero-area
-collapse, and full-mesh winding invert — they do not read as geometry at
-thumbnail scale without faking annotation.
+**Not depicted in the still (check-proven only):** zero-area collapse and
+the buried second shell — neither changes a single pixel.
 
 ## Run
 
 ```bash
 blender --background --python mesh_hygiene_audit.py --
-blender --background --python mesh_hygiene_audit.py -- --inject-ngon
+blender --background --python mesh_hygiene_audit.py -- --inject ngon
+blender --background --python mesh_hygiene_audit.py -- --inject flip_patch --inject-part Valve.HandwheelRim
 blender --background --python mesh_hygiene_audit.py -- --output hygiene.png
 blender --background --python mesh_hygiene_audit.py -- --output hygiene.png --engine cycles
 ```
 
 ## Exit codes
 
 Per-script sequential checks. `9` is a valid check code; there is no rule
-against it. `10` is the shared framing helper.
+against it. `10` is the shared framing helper, `11` the shared asset-quality
+helper.
 
 | Code | Meaning |
 | --- | --- |
 | 0 | Success |
 | 1 | Uncaught exception (FATAL wrapper) |
 | 2 | argparse / usage |
-| 3 | Ngon present (`--inject-ngon` lands here) |
+| 3 | Ngon present (`--inject ngon` lands here) |
 | 4 | Loose vertices |
 | 5 | Non-manifold or boundary edges |
 | 6 | Zero-area faces |
-| 7 | Signed volume ≤ 0 |
-| 8 | Euler characteristic ≠ 2 |
-| 9 | `--output` produced no file |
+| 7 | Winding seam edges, or signed volume ≤ 0 |
+| 8 | Body casting Euler characteristic ≠ 2 |
+| 9 | `--output` produced no file, or dirty staging lost a defect class |
 | 10 | Gallery framing violation |
+| 11 | Gallery asset-quality floor violation |
 
 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).
-Smoke does not pass `--output` or `--inject-ngon`.
+Smoke does not pass `--output` or `--inject`.