feat: add sky-texture-sun-elevation example (#99)

Witness World ShaderNodeTexSky across 4.5 NISHITA vs 5.1 MULTIPLE_SCATTERING,
the dust_density/aerosol_density trap, and sun_elevation zenith rise with a
dual-elevation gallery diptych.

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

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -81,6 +81,7 @@
     "examples/png-exr-alpha",
     "examples/shader-node-group",
     "examples/shape-key-blend",
+    "examples/sky-texture-sun-elevation",
     "examples/swatch-grid",
     "examples/temp-override-join",
     "examples/text-version-stamp",

.github/workflows/blender-smoke.yml

@@ -474,3 +474,14 @@ jobs:
           # Exits non-zero on failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/custom-normals-shade/custom_normals_shade.py --
+
+      - name: Shipped example - sky texture sun elevation (Nishita / MS + zenith rise)
+        run: |
+          set -euo pipefail
+          # Check only (no gallery still): World ShaderNodeTexSky drives
+          # Background Color; sky_type is NISHITA on 4.5 and MULTIPLE_SCATTERING
+          # on 5.1 (NISHITA gone); dust_density is 4.5-only (aerosol_density on
+          # 5.1). Two tiny Cycles OPEN_EXR zenith probes assert sun_elevation
+          # 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 --

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>32 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>33 examples</strong>
 </p>
 
 <p align="center">
@@ -36,7 +36,7 @@
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 32 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 33 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.
 
@@ -85,7 +85,7 @@ or expand a category below.
 </p>
 
 <details>
-<summary><strong>Materials, shading &amp; compositing</strong> — 6 examples</summary>
+<summary><strong>Materials, shading &amp; compositing</strong> — 7 examples</summary>
 
 <table>
 <tr>
@@ -179,6 +179,23 @@ as if associated-alpha — straight-authored dark values at low alpha clamp to w
 (closed-form error **0.98** at `(0.02, a=1/255)`). OpenEXR preserves float RGBA;
 byte images stay straight 8-bit. Also witnesses `EXR color_mode='RGB'` dropping alpha.
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/sky-texture-sun-elevation/"><img src="examples/sky-texture-sun-elevation/preview.webp" alt="Sky texture sun elevation: terracotta jar diptych on a dark floor — left panel low sun at 8 degrees with a deep blue zenith and warm horizon limb, right panel high sun at 55 degrees with a brighter cyan sky, proving ShaderNodeTexSky sun_elevation" /></a>
+</td>
+<td valign="middle">
+
+### [sky-texture-sun-elevation](examples/sky-texture-sun-elevation/)
+
+World `ShaderNodeTexSky` driving Background Color — the sky contract AI lighting
+code misses across 4.5 → 5.1. `sky_type` is `NISHITA` on 4.5 LTS and
+`MULTIPLE_SCATTERING` on 5.1 (`NISHITA` gone); `dust_density` exists only on 4.5
+(`aerosol_density` on 5.1). Two tiny Cycles EXR zenith probes assert
+`sun_elevation` 8° → 55° brightens zenith (rise **2.25x** / **1.50x**, gate ≥ 1.25).
+Gallery still is a dual-elevation diptych so the contract reads at thumbnail scale.
+
 </td>
 </tr>
 </table>

ROADMAP.md

@@ -114,6 +114,11 @@ Not committed; target list for the next content version. (v0.3.0 shipped the smo
 - Falsy `bpy_prop_collection` trap snippet: an empty collection is falsy, so `editor.strips or editor.sequences` silently falls through to the legacy accessor on an empty timeline — always branch on `hasattr`; likely generalizes across the API (found authoring `vse-cut-list`)
 - ~~Collision compound witness~~ **SHIPPED** as `examples/collision-hull-proxy/` — game-prop collision as a compound of convex pieces, each a `bmesh.ops.convex_hull` of a coarse `sec(π/n)`-inflated cage (containment 4.4e-08, watertight, positive signed volume, Euler 2, per-piece 255-face budget: body 70, caps 60×3, compound 250); a hull of the dense render mesh measures 380 faces — over budget — which is why pipelines hull cages; proud details cost cage rows, concave grooves are free; byte-identical on 4.5.11 and 5.1.2
 - ~~Custom-normals / shade-by-angle witness~~ **SHIPPED** as `examples/custom-normals-shade/` — the post-4.1 shading contract: `use_auto_smooth`/`use_custom_normals`/`calc_normals` are AttributeError on BOTH 4.5.11 and 5.1.2; `set_sharp_from_angle` sharp sets match an independent dihedral recompute exactly (188/388 edges, 3 meshes); evaluated normal welds/splits exact (0.0 dev); custom split normals survive depsgraph evaluation within int16 quantization (1.407e-04, not float-exact); **divergence**: the legacy `shade_auto_smooth` operator CANCELS headless on 4.5 ("Asset loading is unfinished", mesh untouched, no exception) while 5.1 FINISHES with the Smooth-by-Angle NODES modifier — the data API is the portable path
+- ~~Sky Texture / sun_elevation witness~~ **SHIPPED** as `examples/sky-texture-sun-elevation/` — World `ShaderNodeTexSky` → Background; `sky_type` is `NISHITA` on 4.5 and `MULTIPLE_SCATTERING` on 5.1 (`NISHITA` gone); `dust_density` is 4.5-only (`aerosol_density` on 5.1); zenith EXR rise 8°→55° measured **2.25x** (5.1.2) / **1.50x** (4.5.11), gate ≥ 1.25; dual-elevation gallery diptych
+- Grease Pencil Line Art contour witness: empty GPv3 object + `modifiers.new(..., "LINEART")`; `thickness` on 4.5 vs `radius` on 5.1; evaluated contour stroke counts for a known source mesh
+- Camera DOF + focus_distance witness: `cam.dof.use_dof`, focus plane vs defocus variance on high-freq cards (Stage deviation — depth needs background content)
+- 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
 

docs/gallery/assets/sky-texture-sun-elevation-hero.webp

@@ -197,11 +197,14 @@ <h1>Examples Gallery</h1>
     <button class="chip" data-tag="objects" type="button">objects</button>
     <button class="chip" data-tag="operators" type="button">operators</button>
     <button class="chip" data-tag="performance" type="button">performance</button>
+    <button class="chip" data-tag="render" type="button">render</button>
     <button class="chip" data-tag="rendering" type="button">rendering</button>
     <button class="chip" data-tag="sequencer" type="button">sequencer</button>
     <button class="chip" data-tag="shape-keys" type="button">shape-keys</button>
+    <button class="chip" data-tag="sky" type="button">sky</button>
     <button class="chip" data-tag="transforms" type="button">transforms</button>
     <button class="chip" data-tag="uv" type="button">uv</button>
+    <button class="chip" data-tag="world" type="button">world</button>
   </div>
   <main id="main">
     <div class="grid">
@@ -557,6 +560,17 @@ <h2><a href="custom-normals-shade/">custom-normals-shade</a></h2>
           <a class="card-link" href="custom-normals-shade/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
+      <article class="card" data-tags="world sky render">
+        <a class="card-media" href="sky-texture-sun-elevation/" aria-label="sky-texture-sun-elevation example detail page">
+          <img src="assets/sky-texture-sun-elevation-hero.webp" alt="sky-texture-sun-elevation — World ShaderNodeTexSky driving Background Color — the sky contract across 4.5 LTS and 5.1." loading="lazy" decoding="async" />
+        </a>
+        <div class="card-body">
+          <h2><a href="sky-texture-sun-elevation/">sky-texture-sun-elevation</a></h2>
+          <p class="teaches">World ShaderNodeTexSky driving Background Color — the sky contract across 4.5 LTS and 5.1. sky_type is NISHITA on 4.5 and MULTIPLE_SCATTERING on 5.1 (NISHITA gone); dust_density exists only on 4.5 (aerosol_density on 5.1). Two tiny Cycles OPEN_EXR zenith probes prove sun_elevation 8 deg to 55 deg brightens zenith (rise 2.25x on 5.1.2, 1.50x on 4.5.11, gate &gt;= 1.25).</p>
+          <p class="witnesses"><span class="tag">witnesses</span> AI code still assigns sky_type=&#x27;NISHITA&#x27; and dust_density on 5.1 — both are wrong (NISHITA removed; dust_density is AttributeError; use MULTIPLE_SCATTERING + aerosol_density). A near-black Background Strength alone is not a sky: Sky must link into Background Color. Elevation that does not brighten zenith fails the rise gate.</p>
+          <a class="card-link" href="sky-texture-sun-elevation/">View example <span aria-hidden="true">&rarr;</span></a>
+        </div>
+      </article>
     </div>
   </main>
   <footer>