fix(gallery): describe each still in its alt text instead of the API it teaches (#221)

Every gallery image's alt was derived from `teaches`, which says what the
code proves, not what the picture shows, and 29 of 79 card alts were cut at
160 characters. Detail-page, zoom and landing images said only
"<name> render".

- Each examples/ and showcase/ gallery.json entry gains an `alt`: one
  sentence written from the committed still (all 79, longest 135 chars).
- build_gallery.py uses it for the card, the detail hero, the zoom image
  and the zoom button label, and fails the build on a missing or overlong
  alt. The teaches-derived card_alt/first_sentence helpers go.
- The landing template uses it for both card grids.
- CLAUDE.md, CONTRIBUTING.md and docs/new-example-prompt.md say new entries
  need one.

Closes #213

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

Author: TMHSDigital

CLAUDE.md

@@ -122,7 +122,7 @@ example still carries a `tests/smoke/catalog.json` row and a falsifier.
 `examples/gallery.json` is the
 gallery's source of truth. When authoring a new gallery example, copy the anatomy of
 `examples/bmesh-gear/` (script structure, README shape, dark-studio render recipe) and
-wire all of: gallery.json entry, `.cursor-plugin/plugin.json` examples array (CI-gated),
+wire all of: gallery.json entry (with an `alt` sentence describing the still; the build fails without one), `.cursor-plugin/plugin.json` examples array (CI-gated),
 a `tests/smoke/catalog.json` row, a README gallery row, hero webp (1280×720) in
 `docs/gallery/assets/` + preview webp (1200×675), then run `python scripts/build_gallery.py`.
 A check-only example wires only the `.cursor-plugin/plugin.json` entry, the

CONTRIBUTING.md

@@ -115,8 +115,9 @@ budget conformance, never an API contract.
    **named** budget fails.
 2. List the directory in `.cursor-plugin/plugin.json` `"showcase"` and add a
    `tests/smoke/catalog.json` row. The runner takes opaque script paths.
-3. Add a `showcase/gallery.json` `pieces[]` entry, render a still, and run
-   `python scripts/build_gallery.py`. Do not hand-edit `docs/gallery/` HTML.
+3. Add a `showcase/gallery.json` `pieces[]` entry, including an `alt`: one
+   sentence saying what the still shows (the generator fails without it).
+   Render a still, and run `python scripts/build_gallery.py`. Do not hand-edit `docs/gallery/` HTML.
 4. Update the README showcase-piece count. `validate-counts` checks it
    separately from the example total.
 

docs/gallery/anvil/index.html

@@ -16,13 +16,13 @@
   <meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/anvil-hero.webp" />
   <meta property="og:image:width" content="1280" />
   <meta property="og:image:height" content="720" />
-  <meta property="og:image:alt" content="anvil: the showcase piece&#x27;s own headless render" />
+  <meta property="og:image:alt" content="A black iron anvil mounted on a hooped timber stump." />
   <meta property="og:site_name" content="Blender Developer Tools" />
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="anvil — Showcase — Blender Developer Tools" />
   <meta name="twitter:description" content="A procedural blacksmith anvil on a timber stump through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract." />
   <meta name="twitter:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/anvil-hero.webp" />
-  <meta name="twitter:image:alt" content="anvil: the showcase piece&#x27;s own headless render" />
+  <meta name="twitter:image:alt" content="A black iron anvil mounted on a hooped timber stump." />
   <style>
     /* fonts are deployed by the landing build (docs/fonts/) */
     @font-face { font-family: 'Barlow Condensed'; font-weight: 600; font-display: swap;
@@ -268,8 +268,8 @@ <h1>anvil</h1>
     <p>A procedural blacksmith anvil on a timber stump through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract.</p>
   </header>
   <main id="main">
-    <button class="detail-hero" id="heroZoom" type="button" aria-label="Zoom anvil render">
-      <img src="../assets/anvil-hero.webp" alt="anvil render" width="1280" height="720" />
+    <button class="detail-hero" id="heroZoom" type="button" aria-label="View full size: A black iron anvil mounted on a hooped timber stump.">
+      <img src="../assets/anvil-hero.webp" alt="A black iron anvil mounted on a hooped timber stump." width="1280" height="720" />
     </button>
     <p class="zoom-hint">Rendered headless by the showcase piece itself — click to zoom.</p>
     <div class="callout"><span class="tag">witnesses</span> Recomputed: 2988 tris, two materials with 1040 wood and 822 metal faces, UVs in 0..1 with zero AABB overlap, outer AABB 0.621×0.414×0.489 m, LOD ratios in band, convex collider 134 tris, hygiene 0, 16 grounded staves, hoop bite 0.003 m, foot-on-head gap 0.003 m, non-empty glTF. --skip-decimate exits 9; --stray-vert 15; --lift-z/--short-staves 16; --float-anvil 17; --round-band 18.</div>
@@ -1677,7 +1677,7 @@ <h2>Source</h2>
   </main>
   <dialog class="lightbox" id="lightbox" aria-label="Full-size render">
     <button class="lightbox-close" type="button" autofocus>Close</button>
-    <img src="../assets/anvil-hero.webp" alt="anvil render, full size" />
+    <img src="../assets/anvil-hero.webp" alt="A black iron anvil mounted on a hooped timber stump." />
   </dialog>
   <footer>
     <div class="statusbar">

docs/gallery/armature-bend/index.html

@@ -16,13 +16,13 @@
   <meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/armature-bend-hero.webp" />
   <meta property="og:image:width" content="1280" />
   <meta property="og:image:height" content="720" />
-  <meta property="og:image:alt" content="armature-bend: the example&#x27;s own headless render" />
+  <meta property="og:image:alt" content="Three tapered tubes, coral to amber to teal, standing straight, half curled and fully curled by an armature." />
   <meta property="og:site_name" content="Blender Developer Tools" />
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="armature-bend — Examples — Blender Developer Tools" />
   <meta name="twitter:description" content="Rigging end to end in the data API — edit_bones chain construction, name-bound vertex groups with smoothstep blend zones, posing, and depsgraph evaluation — bending a tapered tube through rest, half, and full curl." />
   <meta name="twitter:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/armature-bend-hero.webp" />
-  <meta name="twitter:image:alt" content="armature-bend: the example&#x27;s own headless render" />
+  <meta name="twitter:image:alt" content="Three tapered tubes, coral to amber to teal, standing straight, half curled and fully curled by an armature." />
   <style>
     /* fonts are deployed by the landing build (docs/fonts/) */
     @font-face { font-family: 'Barlow Condensed'; font-weight: 600; font-display: swap;
@@ -268,8 +268,8 @@ <h1>armature-bend</h1>
     <p>Rigging end to end in the data API — edit_bones chain construction, name-bound vertex groups with smoothstep blend zones, posing, and depsgraph evaluation — bending a tapered tube through rest, half, and full curl.</p>
   </header>
   <main id="main">
-    <button class="detail-hero" id="heroZoom" type="button" aria-label="Zoom armature-bend render">
-      <img src="../assets/armature-bend-hero.webp" alt="armature-bend render" width="1280" height="720" />
+    <button class="detail-hero" id="heroZoom" type="button" aria-label="View full size: Three tapered tubes, coral to amber to teal, standing straight, half curled and fully curled by an armature.">
+      <img src="../assets/armature-bend-hero.webp" alt="Three tapered tubes, coral to amber to teal, standing straight, half curled and fully curled by an armature." width="1280" height="720" />
     </button>
     <p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
     <div class="callout"><span class="tag">witnesses</span> edit_bones exists only in edit mode (empty in object mode), vertex groups bind to bones strictly by name, and the armature modifier is exactly linear blend skinning: every evaluated vertex must equal Σ wᵢ·(pose_bone.matrix @ bone.matrix_local.inverted()) @ rest, root ring pinned, tip deflected — a straight tube fails.</div>
@@ -636,7 +636,7 @@ <h2>Source</h2>
   </main>
   <dialog class="lightbox" id="lightbox" aria-label="Full-size render">
     <button class="lightbox-close" type="button" autofocus>Close</button>
-    <img src="../assets/armature-bend-hero.webp" alt="armature-bend render, full size" />
+    <img src="../assets/armature-bend-hero.webp" alt="Three tapered tubes, coral to amber to teal, standing straight, half curled and fully curled by an armature." />
   </dialog>
   <footer>
     <div class="statusbar">

docs/gallery/attribute-domain-shear/index.html

@@ -16,13 +16,13 @@
   <meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/attribute-domain-shear-hero.webp" />
   <meta property="og:image:width" content="1280" />
   <meta property="og:image:height" content="720" />
-  <meta property="og:image:alt" content="attribute-domain-shear: the example&#x27;s own headless render" />
+  <meta property="og:image:alt" content="Two octagonal rainbow-coloured caps labelled CORNER and POINT, last write wins, showing different colour blending." />
   <meta property="og:site_name" content="Blender Developer Tools" />
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="attribute-domain-shear — Examples — Blender Developer Tools" />
   <meta name="twitter:description" content="POINT vs CORNER color-attribute domains on a shared-vertex pinwheel: CORNER stays exact per face while a naive per-wedge POINT loop shears to the last write at the hub. Crisp petals versus a smeared swirl in one frame; the measured shear equals the palette closed form." />
   <meta name="twitter:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/attribute-domain-shear-hero.webp" />
-  <meta name="twitter:image:alt" content="attribute-domain-shear: the example&#x27;s own headless render" />
+  <meta name="twitter:image:alt" content="Two octagonal rainbow-coloured caps labelled CORNER and POINT, last write wins, showing different colour blending." />
   <style>
     /* fonts are deployed by the landing build (docs/fonts/) */
     @font-face { font-family: 'Barlow Condensed'; font-weight: 600; font-display: swap;
@@ -268,8 +268,8 @@ <h1>attribute-domain-shear</h1>
     <p>POINT vs CORNER color-attribute domains on a shared-vertex pinwheel: CORNER stays exact per face while a naive per-wedge POINT loop shears to the last write at the hub. Crisp petals versus a smeared swirl in one frame; the measured shear equals the palette closed form.</p>
   </header>
   <main id="main">
-    <button class="detail-hero" id="heroZoom" type="button" aria-label="Zoom attribute-domain-shear render">
-      <img src="../assets/attribute-domain-shear-hero.webp" alt="attribute-domain-shear render" width="1280" height="720" />
+    <button class="detail-hero" id="heroZoom" type="button" aria-label="View full size: Two octagonal rainbow-coloured caps labelled CORNER and POINT, last write wins, showing different colour blending.">
+      <img src="../assets/attribute-domain-shear-hero.webp" alt="Two octagonal rainbow-coloured caps labelled CORNER and POINT, last write wins, showing different colour blending." width="1280" height="720" />
     </button>
     <p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
     <div class="callout"><span class="tag">witnesses</span> Authoring per-face colors into a POINT-domain attribute overwrites shared vertices once per neighbor; the last write wins and intended colors shear across every shared vertex.</div>
@@ -722,7 +722,7 @@ <h2>Source</h2>
   </main>
   <dialog class="lightbox" id="lightbox" aria-label="Full-size render">
     <button class="lightbox-close" type="button" autofocus>Close</button>
-    <img src="../assets/attribute-domain-shear-hero.webp" alt="attribute-domain-shear render, full size" />
+    <img src="../assets/attribute-domain-shear-hero.webp" alt="Two octagonal rainbow-coloured caps labelled CORNER and POINT, last write wins, showing different colour blending." />
   </dialog>
   <footer>
     <div class="statusbar">

docs/gallery/bake-normal-high-to-low/index.html

@@ -16,13 +16,13 @@
   <meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/bake-normal-high-to-low-hero.webp" />
   <meta property="og:image:width" content="1280" />
   <meta property="og:image:height" content="720" />
-  <meta property="og:image:alt" content="bake-normal-high-to-low: the example&#x27;s own headless render" />
+  <meta property="og:image:alt" content="A baked tangent-space normal map shown as a lilac card beside a bronze plate wearing it, with a radial embossed pattern." />
   <meta property="og:site_name" content="Blender Developer Tools" />
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="bake-normal-high-to-low — Examples — Blender Developer Tools" />
   <meta name="twitter:description" content="A collapse-decimated hatch plate receiving a Cycles cage-baked tangent normal map from a ribbed high-poly source" />
   <meta name="twitter:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/bake-normal-high-to-low-hero.webp" />
-  <meta name="twitter:image:alt" content="bake-normal-high-to-low: the example&#x27;s own headless render" />
+  <meta name="twitter:image:alt" content="A baked tangent-space normal map shown as a lilac card beside a bronze plate wearing it, with a radial embossed pattern." />
   <style>
     /* fonts are deployed by the landing build (docs/fonts/) */
     @font-face { font-family: 'Barlow Condensed'; font-weight: 600; font-display: swap;
@@ -268,8 +268,8 @@ <h1>bake-normal-high-to-low</h1>
     <p>A collapse-decimated hatch plate receiving a Cycles cage-baked tangent normal map from a ribbed high-poly source</p>
   </header>
   <main id="main">
-    <button class="detail-hero" id="heroZoom" type="button" aria-label="Zoom bake-normal-high-to-low render">
-      <img src="../assets/bake-normal-high-to-low-hero.webp" alt="bake-normal-high-to-low render" width="1280" height="720" />
+    <button class="detail-hero" id="heroZoom" type="button" aria-label="View full size: A baked tangent-space normal map shown as a lilac card beside a bronze plate wearing it, with a radial embossed pattern.">
+      <img src="../assets/bake-normal-high-to-low-hero.webp" alt="A baked tangent-space normal map shown as a lilac card beside a bronze plate wearing it, with a radial embossed pattern." width="1280" height="720" />
     </button>
     <p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
     <div class="callout"><span class="tag">witnesses</span> Statistical gates not byte-identity: detail frac 0.7211 / MAD 0.09356 vs flat 0.0000 / 0.00277; --flat-source exits 5; type=NORMAL not bake_type; RNA identical on 4.5.11, 5.1.2, 5.2.1</div>
@@ -840,7 +840,7 @@ <h2>Source</h2>
   </main>
   <dialog class="lightbox" id="lightbox" aria-label="Full-size render">
     <button class="lightbox-close" type="button" autofocus>Close</button>
-    <img src="../assets/bake-normal-high-to-low-hero.webp" alt="bake-normal-high-to-low render, full size" />
+    <img src="../assets/bake-normal-high-to-low-hero.webp" alt="A baked tangent-space normal map shown as a lilac card beside a bronze plate wearing it, with a radial embossed pattern." />
   </dialog>
   <footer>
     <div class="statusbar">

docs/gallery/bmesh-gear/index.html

@@ -16,13 +16,13 @@
   <meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/bmesh-gear-hero.webp" />
   <meta property="og:image:width" content="1280" />
   <meta property="og:image:height" content="720" />
-  <meta property="og:image:alt" content="bmesh-gear: the example&#x27;s own headless render" />
+  <meta property="og:image:alt" content="A gold fourteen-tooth gear lying at an angle, its face covered in concentric grooves." />
   <meta property="og:site_name" content="Blender Developer Tools" />
   <meta name="twitter:card" content="summary_large_image" />
   <meta name="twitter:title" content="bmesh-gear — Examples — Blender Developer Tools" />
   <meta name="twitter:description" content="A 14-tooth gear built entirely with bmesh — profile ring, face, extrude — with bm.free() in a try/finally, exactly as the ownership contract demands." />
   <meta name="twitter:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/bmesh-gear-hero.webp" />
-  <meta name="twitter:image:alt" content="bmesh-gear: the example&#x27;s own headless render" />
+  <meta name="twitter:image:alt" content="A gold fourteen-tooth gear lying at an angle, its face covered in concentric grooves." />
   <style>
     /* fonts are deployed by the landing build (docs/fonts/) */
     @font-face { font-family: 'Barlow Condensed'; font-weight: 600; font-display: swap;
@@ -268,8 +268,8 @@ <h1>bmesh-gear</h1>
     <p>A 14-tooth gear built entirely with bmesh — profile ring, face, extrude — with bm.free() in a try/finally, exactly as the ownership contract demands.</p>
   </header>
   <main id="main">
-    <button class="detail-hero" id="heroZoom" type="button" aria-label="Zoom bmesh-gear render">
-      <img src="../assets/bmesh-gear-hero.webp" alt="bmesh-gear render" width="1280" height="720" />
+    <button class="detail-hero" id="heroZoom" type="button" aria-label="View full size: A gold fourteen-tooth gear lying at an angle, its face covered in concentric grooves.">
+      <img src="../assets/bmesh-gear-hero.webp" alt="A gold fourteen-tooth gear lying at an angle, its face covered in concentric grooves." width="1280" height="720" />
     </button>
     <p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
     <div class="callout"><span class="tag">witnesses</span> Parametric bmesh topology is exactly predictable: verts, edges, and faces match their closed forms, and every edge borders exactly two faces (watertight).</div>
@@ -531,7 +531,7 @@ <h2>Source</h2>
   </main>
   <dialog class="lightbox" id="lightbox" aria-label="Full-size render">
     <button class="lightbox-close" type="button" autofocus>Close</button>
-    <img src="../assets/bmesh-gear-hero.webp" alt="bmesh-gear render, full size" />
+    <img src="../assets/bmesh-gear-hero.webp" alt="A gold fourteen-tooth gear lying at an angle, its face covered in concentric grooves." />
   </dialog>
   <footer>
     <div class="statusbar">