feat: add mesh-hygiene-audit example (#101)

* feat: add mesh-hygiene-audit example

Ship the engine-ingest topology checklist as a runnable dual-panel gallery
example so prop pipelines can prove tris/quads, manifold edges, winding,
and Euler 2 before hull/LOD/export.

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

* fix: bump README badge example count to 35

Validate-counts greps for the contiguous '35 examples' substring in the
header badge; the prose '35 runnable examples' alone does not match.

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -78,6 +78,7 @@
     "examples/image-pixels-testcard",
     "examples/light-link-studio",
     "examples/lod-decimate-chain",
+    "examples/mesh-hygiene-audit",
     "examples/parent-inverse-orrery",
     "examples/png-exr-alpha",
     "examples/shader-node-group",

.github/workflows/blender-smoke.yml

@@ -496,3 +496,12 @@ jobs:
           # 8→55 deg brightens zenith (rise gate ≥ 1.25). Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/sky-texture-sun-elevation/sky_texture_sun_elevation.py --
+
+      - name: Shipped example - mesh hygiene audit (topology ingest checklist)
+        run: |
+          set -euo pipefail
+          # Check only (no render): stepped utility pedestal; asserts no ngons,
+          # no loose verts, manifold edges (exactly 2 faces), no zero-area faces,
+          # positive signed volume, Euler V-E+F == 2. Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/mesh-hygiene-audit/mesh_hygiene_audit.py --

README.md

@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  <strong>12 skills</strong> &nbsp;&bull;&nbsp; <strong>6 rules</strong> &nbsp;&bull;&nbsp; <strong>2 templates</strong> &nbsp;&bull;&nbsp; <strong>17 snippets</strong> &nbsp;&bull;&nbsp; <strong>34 examples</strong>
+  <strong>12 skills</strong> &nbsp;&bull;&nbsp; <strong>6 rules</strong> &nbsp;&bull;&nbsp; <strong>2 templates</strong> &nbsp;&bull;&nbsp; <strong>17 snippets</strong> &nbsp;&bull;&nbsp; <strong>35 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 34 runnable examples** for Blender Python development targeting Blender 5.1 (current stable) with Blender 4.5 LTS fallback support.
+This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 35 runnable examples** for Blender Python development targeting Blender 5.1 (current stable) with Blender 4.5 LTS fallback support.
 
 The content is consumed by AI coding agents (Cursor, Claude Code, any MCP-capable client) when working on Blender add-ons, geometry nodes scripts, batch pipelines, or animation tooling. There is no build step. Edit the markdown and Python files directly.
 
@@ -537,7 +537,7 @@ portable path is `radius`.
 </details>
 
 <details>
-<summary><strong>Game asset pipeline</strong> — 7 examples</summary>
+<summary><strong>Game asset pipeline</strong> — 8 examples</summary>
 
 <table>
 <tr>
@@ -664,6 +664,24 @@ quantization (1.407e-04, not float-exact). Documents the legacy
 `shade_auto_smooth` operator trap: CANCELLED headless on 4.5, FINISHED
 with the Smooth-by-Angle modifier on 5.1.
 
+</td>
+</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 street electrical pedestal — left orange emissive wireframe with loose-vert bead and DIRTY placard, right teal CLEAN manifold — 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 24/44/22, volume 0.989248). Companion to
+[`collision-hull-proxy`](examples/collision-hull-proxy/) (hull watertightness)
+and [`bmesh-gear`](examples/bmesh-gear/) (parametric closed solids). Dual-panel
+still: DIRTY (injected boundary + loose vert) vs CLEAN.
+
 </td>
 </tr>
 </table>

ROADMAP.md

@@ -120,7 +120,8 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - Volumetric scatter optical-depth witness: Volume Scatter density → Beer–Lambert transmittance along a known path (Cycles; Stage deviation)
 - Freestyle SVG / line-set witness: Freestyle line set on a silhouette (full render pass; prefer Line Art first)
 - prop-origin-transform witness — origin to base center, `transform_apply` through the data API, delta transforms, `matrix_parent_inverse` so parented children do not teleport; closed forms: post-apply scale exactly (1,1,1), local bbox min Z == 0, world bbox unchanged (builds on `parent-inverse-orrery`, does not duplicate it)
-- mesh-hygiene-audit witness — the engine-ingest checklist as executable contract: no ngons, no loose vertices, no non-manifold edges, no zero-area faces, consistent outward winding; closed forms via Euler characteristic and exact edge-face incidence counts
+- ~~mesh-hygiene-audit witness~~ **SHIPPED** as `examples/mesh-hygiene-audit/` — engine-ingest topology checklist on a stepped street electrical pedestal: no ngons, no loose verts, manifold edges (exactly 2 faces), no zero-area faces (`min_area` printed), positive signed volume, Euler `V−E+F==2` (24/44/22, volume 0.989248); byte-identical on 4.5.11 and 5.1.2; dual-panel dirty vs clean still
+- UV atlas pack witness — lightmap/unique UV island packing with non-overlap + utilization closed forms (deferred behind hygiene/origin; overlaps `uv-layer-grid` / `triangulate-tangents` / `gltf-export-roundtrip` UV arc)
 
 ## Future (uncommitted)
 

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

@@ -187,6 +187,7 @@ <h1>Examples Gallery</h1>
     <button class="chip" data-tag="depsgraph" type="button">depsgraph</button>
     <button class="chip" data-tag="drivers" type="button">drivers</button>
     <button class="chip" data-tag="export" type="button">export</button>
+    <button class="chip" data-tag="game-pipeline" type="button">game-pipeline</button>
     <button class="chip" data-tag="geometry-nodes" type="button">geometry-nodes</button>
     <button class="chip" data-tag="grease-pencil" type="button">grease-pencil</button>
     <button class="chip" data-tag="images" type="button">images</button>
@@ -584,6 +585,17 @@ <h2><a href="gp-lineart-contour/">gp-lineart-contour</a></h2>
           <a class="card-link" href="gp-lineart-contour/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
+      <article class="card" data-tags="bmesh mesh game-pipeline">
+        <a class="card-media" href="mesh-hygiene-audit/" aria-label="mesh-hygiene-audit example detail page">
+          <img src="assets/mesh-hygiene-audit-hero.webp" alt="mesh-hygiene-audit — Engine-ingest mesh hygiene as executable topology checks on a stepped street electrical pedestal (plinth, cabinet, drip cap)." 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 as executable topology checks on a stepped street electrical pedestal (plinth, cabinet, drip cap). Gates: no ngons, no loose verts, every edge borders exactly 2 faces, no zero-area faces (min_area printed), positive signed volume, Euler V-E+F==2 (24/44/22, volume 0.989248). Dual-panel dirty vs clean still marks defects.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> AI pipelines that skip topology gates ship ngons, loose verts, open boundaries, inverted winding, or non-sphere Euler into engine ingest. Injecting one defect class at a time exits non-zero (ngon=3, loose=4, boundary=5, zero-area=6, flip=7); the clean solid recovers hygiene_ok on both 4.5.11 and 5.1.2.</p>
+          <a class="card-link" href="mesh-hygiene-audit/">View example <span aria-hidden="true">&rarr;</span></a>
+        </div>
+      </article>
     </div>
   </main>
   <footer>