feat: add parent-inverse-orrery example (matrix_parent_inverse contract)

Generated Blender code constantly writes `child.parent = pivot` and is
surprised the child teleports, then reads `matrix_world` before the
depsgraph has evaluated it. No existing example covers object parenting
or the transform-update contract, so this one witnesses both with a
brass orrery whose hierarchy is the subject: arms, planets, and a
two-level moon parented with the keep-world idiom
(matrix_parent_inverse = parent.matrix_world.inverted()), spun to
closed-form orbit positions the check verifies exactly. The trap itself
is asserted too - a bare-parented probe must jump, and the fix must
restore its world position to within 1e-5.

Runs check-only headless on Blender 4.5 LTS and 5.1 (both verified
locally on 4.5.11 and 5.1.2); --output renders the gallery still.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -68,6 +68,7 @@
     "examples/driver-wave",
     "examples/gn-instance-grid",
     "examples/gn-sdf-remesh",
+    "examples/parent-inverse-orrery",
     "examples/shader-node-group",
     "examples/shape-key-blend",
     "examples/swatch-grid",

.github/workflows/blender-smoke.yml

@@ -264,3 +264,14 @@ jobs:
           # failure.
           xvfb-run -a "$BLENDER" --background \
             --python examples/color-attribute-wheel/color_attribute_wheel.py --
+
+      - name: Shipped example - parent inverse orrery (matrix_parent_inverse)
+        run: |
+          set -euo pipefail
+          # Frame-independent check only (no render): a data-API orrery whose arms,
+          # planets, and moon are parented with the keep-world idiom; asserts bare
+          # `.parent =` teleports a probe, matrix_parent_inverse restores it exactly,
+          # matrix_world is stale until view_layer.update(), and every orbit lands
+          # on its closed form. Exits non-zero on failure.
+          xvfb-run -a "$BLENDER" --background \
+            --python examples/parent-inverse-orrery/parent_inverse_orrery.py --

AGENTS.md

@@ -27,7 +27,7 @@ The content base (counts are CI-enforced against README.md and the manifest):
 - 2 templates: `extension-addon-template` for Extensions Platform add-ons,
   and `headless-batch-script-template` for unattended batch jobs.
 - 17 snippets covering canonical patterns.
-- 15 examples under `examples/<name>/`: runnable scripts that assert a real
+- 16 examples under `examples/<name>/`: runnable scripts that assert a real
   API contract with deterministic checks, exit non-zero on failure, and
   optionally render a still via `--output`. Each is executed headless on
   Blender 4.5 LTS and 5.1 by `blender-smoke.yml`; its render ships in the
@@ -41,7 +41,7 @@ Blender-Developer-Tools/
   rules/<rule-name>.mdc          # 6 rule files
   templates/<template-name>/     # 2 starter templates
   snippets/<snippet-name>.py     # 17 standalone Python snippets
-  examples/<name>/               # 15 runnable smoke-gated examples (+ gallery.json)
+  examples/<name>/               # 16 runnable smoke-gated examples (+ gallery.json)
   scripts/build_gallery.py       # generates docs/gallery/ (stdlib only)
   scripts/site/                  # vendored landing-page build (build_site.py + template)
   docs/gallery/                  # committed generated gallery pages + hero assets

CLAUDE.md

@@ -19,7 +19,7 @@ skills/<skill-name>/SKILL.md   - AI workflow definitions, 12 total
 rules/<rule-name>.mdc          - Anti-pattern rules, 6 total
 templates/<template-name>/     - Starter projects, 2 total
 snippets/<snippet-name>.py     - Standalone code patterns, 17 total
-examples/<name>/               - Runnable smoke-gated examples, 15 total (+ gallery.json)
+examples/<name>/               - Runnable smoke-gated examples, 16 total (+ gallery.json)
 scripts/build_gallery.py       - Regenerates docs/gallery/ from gallery.json (stdlib only)
 scripts/site/                  - Vendored landing-page build (Jinja2)
 docs/gallery/                  - Committed generated gallery pages + hero renders
@@ -80,11 +80,11 @@ v0.1.0: canonical object creation and deletion, depsgraph evaluated mesh, bmesh
 
 v0.2.0: Principled BSDF material, driver-with-custom-function via `driver_namespace`, application handler registration, shader node group with cross-version `interface` API, `foreach_get` bulk vertex read, version-branch skeleton, and USD export with `evaluation_mode='RENDER'`.
 
-## Examples (15)
+## Examples (16)
 
 Runnable scripts at `examples/<name>/`, each asserting a real API contract with
 deterministic checks (exit non-zero on failure) and optionally rendering a still via
-`--output`. All fifteen run headless on Blender 4.5 LTS and 5.1 in `blender-smoke.yml`;
+`--output`. All sixteen run headless on Blender 4.5 LTS and 5.1 in `blender-smoke.yml`;
 their renders ship in the site gallery at `docs/gallery/`. `examples/gallery.json` is the
 gallery's source of truth. When authoring a new one, copy the anatomy of
 `examples/bmesh-gear/` (script structure, README shape, dark-studio render recipe) and

README.md

@@ -17,14 +17,14 @@
 </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>15 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>16 examples</strong>
 </p>
 
 ---
 
 ## Overview
 
-This repository ships **12 skills, 6 rules, 2 templates, 17 snippets, and 15 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 16 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.
 
@@ -264,6 +264,22 @@ HSV across face corners with `foreach_get`/`foreach_set`. Asserts the attribute
 is sized to loop count (not vertex count), is `active_color`, and that the
 shader `Attribute` node is actually linked to Base Color.
 
+</td>
+</tr>
+<tr>
+<td width="46%" valign="middle">
+<a href="examples/parent-inverse-orrery/"><img src="examples/parent-inverse-orrery/preview.webp" alt="Parent inverse orrery: a brass tabletop orrery with a glowing sun, three planets on pivot arms inside brass orbit rings, and a silver moon, on a dark studio floor" /></a>
+</td>
+<td valign="middle">
+
+### [parent-inverse-orrery](examples/parent-inverse-orrery/)
+
+A brass orrery parented entirely through the data API — the keep-world idiom
+`child.parent = pivot; child.matrix_parent_inverse = pivot.matrix_world.inverted()`
+carries arms, planets, and a two-level moon through spinning pivots. Asserts bare
+`.parent =` really teleports, `matrix_world` is stale until `view_layer.update()`,
+and every orbit lands on its closed form.
+
 </td>
 </tr>
 </table>

docs/gallery/assets/parent-inverse-orrery-hero.webp

@@ -190,10 +190,12 @@ <h1>Examples Gallery</h1>
     <button class="chip" data-tag="materials" type="button">materials</button>
     <button class="chip" data-tag="mesh" type="button">mesh</button>
     <button class="chip" data-tag="node-groups" type="button">node-groups</button>
+    <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="rendering" type="button">rendering</button>
     <button class="chip" data-tag="shape-keys" type="button">shape-keys</button>
+    <button class="chip" data-tag="transforms" type="button">transforms</button>
   </div>
   <main id="main">
     <div class="grid">
@@ -362,6 +364,17 @@ <h2><a href="color-attribute-wheel/">color-attribute-wheel</a></h2>
           <a class="card-link" href="color-attribute-wheel/">View example <span aria-hidden="true">&rarr;</span></a>
         </div>
       </article>
+      <article class="card" data-tags="objects transforms">
+        <a class="card-media" href="parent-inverse-orrery/" aria-label="parent-inverse-orrery example detail page">
+          <img src="assets/parent-inverse-orrery-hero.webp" alt="parent-inverse-orrery — Data-API parenting for a brass orrery — the keep-world idiom (child" loading="lazy" decoding="async" />
+        </a>
+        <div class="card-body">
+          <h2><a href="parent-inverse-orrery/">parent-inverse-orrery</a></h2>
+          <p class="teaches">Data-API parenting for a brass orrery — the keep-world idiom (child.parent = pivot; child.matrix_parent_inverse = pivot.matrix_world.inverted()) carrying arms, planets, and a two-level moon through spinning pivots.</p>
+          <p class="witnesses"><span class="tag">witnesses</span> Bare `.parent =` really does teleport the child; the idiom restores world position exactly; matrix_world stays stale until view_layer.update(); every orbit lands on its closed form.</p>
+          <a class="card-link" href="parent-inverse-orrery/">View example <span aria-hidden="true">&rarr;</span></a>
+        </div>
+      </article>
     </div>
   </main>
   <footer>