fix: close the mechanical audit issues (#196)

* fix: state the current security support policy

The supported-versions table named 0.2.x while the repository is at 0.78.18,
so it claimed support for releases eleven minors behind and none of the ones
that exist.

Replace it with the policy the project can actually keep: latest release
only, no backports, no maintenance branches. The row points at VERSION rather
than naming a number, so it cannot drift again on the next release. Adds the
one-line reason there are no backports — this is content, not a runtime.

Closes #186

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

* fix: stop the gallery calling showcase pieces examples

The gallery grid concatenates 51 examples and 26 showcase pieces, then
labelled all 77 with the example noun: the count chip read "77 examples",
every showcase card carried aria-label "<name> example detail page" and a
"View example" link, each showcase detail page titled itself "<name> —
Examples" and claimed "Rendered headless by the example itself", and the
landing page offered to "Browse all 51 examples in the gallery" for a page
holding 77 cards. The two categories are distinct everywhere else in the
repository; the site was the last place conflating them.

Derive the noun per entry from the `showcase` tag instead of hardcoding it
(`kind_noun`), and split the counts:

- count chip and its live-updating JS: "51 examples, 26 showcase pieces"
- card aria-label and card link: "example" or "showcase piece" per card
- showcase detail pages title as "— Showcase —" and credit "the showcase
  piece itself"
- gallery title "Examples Gallery" -> "Examples and Showcase"; description
  now says showcase pieces share the grid and carry the tag
- landing CTA names both counts
- search placeholder, chip toolbar, and empty-state text no longer say
  "examples" for a grid holding both
- the generator's summary line prints the breakdown

Verified against the generated HTML, not the source JSON: 51 "example" and
26 "showcase piece" nouns on the index, correct titles on a showcase detail
page and an example detail page, no residual "Examples Gallery" string, and
dotted-path alt text still intact.

Closes #187

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

* fix: label PRs that touch examples and showcase

label-sync.yml covered skills, rules, snippets, templates, docs, and .github
but not examples/ or showcase/ — the two directories that carry the bulk of
content work. A PR adding an example got no path label at all unless it also
touched a README, and showcase PRs were labelled `documentation` for their
README alone.

Add both branches in the same shape as the existing ones. The `examples` and
`showcase` labels have been created on the repository (green and purple);
every label this workflow can now apply — skills, rules, snippets, templates,
examples, showcase, documentation, ci — exists, so the `gh label create
--force` fallback in the apply step stays a fallback rather than the thing
that silently invents grey labels.

Closes #188

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

* fix: carve out check-only examples from the render requirement

docs/new-example-prompt.md required every example to produce a deliberate
render and wire gallery metadata and assets, with no exception. Eight of the
59 examples ship no render, no gallery.json entry, and no hero asset — an
established, deliberate category the authoring prompt did not acknowledge, so
the prompt described a rule the repository does not follow. CLAUDE.md stated
it more strongly still: "their renders ship in the site gallery", of all 59.

State the exception in both, keyed to a criterion rather than a list of the
eight so it stays true as the set changes: an example is check-only when its
witness is a data or state fact that no scene redesign can make visible — a
datablock name, an RNA attribute's presence, a post-exit sidecar, a topology
count, export metadata — so the render would be identical whether the API
held or broke. The existing "redesign the scene until failure would be
visible" instruction is the test to attempt first; the exception is for
contracts that are invisible, not renders that are hard.

CLAUDE.md now says 51 of 59 ship a render, and records that a check-only
example wires only the plugin manifest entry, the smoke catalog row, and its
README.

Verified on disk: exactly eight examples have no gallery.json entry
(coincident-vert-weld, eval-mesh-datablock-name, exit-pre-sidecar,
gn-bundle-roundtrip, mesh-automasking-settings, ngon-triangulate,
unapplied-scale-gltf, vse-linear-modifiers); all eight have a
tests/smoke/catalog.json row, none takes --output, and each carries at least
one falsifier flag. Smoke coverage is unaffected.

Closes #146

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

* fix: describe how the content is actually consumed

The overview claimed the content is consumed by "any MCP-capable client".
There is no MCP server in this repository and never has been: Cursor and
Claude Code read the files directly from a checkout. The line promised a
capability that does not exist, which is a defect rather than a wording
preference — a reader evaluating the project would go looking for a server
to register.

Describe the real mechanism instead: Cursor applies rules/*.mdc by scope
glob and takes skills by name; Claude Code reads skills/ and rules/ from the
workspace or a referenced checkout; any agent that can read workspace files
works the same way.

`pages.yml` also path-filters on a `mcp-tools.json` that has never existed in
this repository's history — it comes from the shared fleet site builder,
which supports tool repos that do ship an MCP server. Filed separately rather
than edited here.

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

* docs: say where to get Blender in the quick start

The quick start hands the reader a `blender --background --python ...`
command without ever saying where `blender` comes from or which versions the
repository supports. The supported-versions table is further down the page
and links nowhere.

Add one bullet above the run command: the LTS download link, which of 5.2
and 4.5 is primary, and the macOS app-bundle path that trips people up when
`blender` is not on PATH.

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

* docs: introduce falsifiers in the README

The falsifier is this repository's central convention — it is what makes a
green example run evidence rather than decoration — and it appeared only in
CLAUDE.md, CONTRIBUTING.md, and the PR template. A reader evaluating the
project from the README never met the word, so the examples read as scripts
that happen to print OK.

Add a short section above Showcase: what a falsifier is, that it changes
input so a real assertion fails rather than skipping the check, that all 59
examples carry one, and the concrete bmesh-gear case (`--no-extrude` breaks
the closed-form topology match and exits 3). Names the three flags that are
commonly mistaken for falsifiers and links to CONTRIBUTING.md for the
exit-code model.

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

---------

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

Author: TMHSDigital

.github/workflows/label-sync.yml

@@ -48,6 +48,14 @@ jobs:
             LABELS="$LABELS templates"
           fi
 
+          if echo "$FILES" | grep -q "^examples/"; then
+            LABELS="$LABELS examples"
+          fi
+
+          if echo "$FILES" | grep -q "^showcase/"; then
+            LABELS="$LABELS showcase"
+          fi
+
           if echo "$FILES" | grep -qE "(README\.md|AGENTS\.md|CLAUDE\.md|ROADMAP\.md|CHANGELOG\.md|^docs/)"; then
             LABELS="$LABELS documentation"
           fi

CLAUDE.md

@@ -105,12 +105,25 @@ AI asset pipeline track: `decimate_to_budget.py`, `convex_hull_collider.py`, `lo
 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 of them run headless on Blender 5.2 LTS and 4.5 LTS in `blender-smoke.yml` (5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch);
-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
+**51 of the 59 ship a render in the site gallery** at `docs/gallery/`. The other
+eight are **check-only**: they carry no `--output` path, no gallery entry, and no
+hero asset. The criterion is whether the contract is expressible in pixels. An
+example is check-only when its witness is a data or state fact that no scene
+redesign can make visible — a datablock name, an RNA attribute's presence, a
+post-exit sidecar, a topology count, export metadata — so a render would look
+identical whether the API held or broke. That is a category, not a shortcut: a
+subject whose render *could* be made legible must be rendered, per
+`docs/new-example-prompt.md`. Smoke coverage is unaffected; every check-only
+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),
 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
+`tests/smoke/catalog.json` row, and its README — it is deliberately absent from
+`examples/gallery.json` and `docs/gallery/`.
 Renders must conform to the gallery look spec at `docs/VISUAL-STYLE.md`.
 Render paths gate framing through the shared helper `examples/gallery_framing.py` —
 imported via a `__file__`-relative `sys.path` shim, the repo's only

README.md

@@ -39,7 +39,7 @@
 
 This repository ships **16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 26 showcase pieces** for Blender Python development targeting Blender 5.2 LTS (current stable) with Blender 4.5 LTS fallback support. Blender 5.1 is prior stable.
 
-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.
+The content is consumed by AI coding agents reading these files directly from a checkout — **there is no MCP server in this repository, and none is required**. Cursor applies `rules/*.mdc` automatically wherever their scope globs match and takes skills by name in chat; Claude Code reads `skills/` and `rules/` from the project workspace, or from this repo kept as a referenced checkout. Any agent that can read files in a workspace can use it the same way. There is no build step for the content — edit the Markdown and Python files directly.
 
 | Layer | Role |
 | --- | --- |
@@ -58,6 +58,7 @@ git clone https://github.com/TMHSDigital/Blender-Developer-Tools.git
 
 - **Cursor** — point Cursor at the checkout (or symlink `rules/` into your project). The `.mdc` rules apply automatically by glob scope; skills are referenced by name in chat.
 - **Claude Code** — copy `skills/` and `rules/` into your project workspace, or keep this repo as a checkout that Claude Code references directly.
+- **Get Blender** — download **5.2 LTS** (primary target) or **4.5 LTS** (supported fallback) from [blender.org/download/lts](https://www.blender.org/download/lts/); current stable lives at [blender.org/download](https://www.blender.org/download/). The `blender` command below is that binary — on macOS it is inside the app bundle at `/Applications/Blender.app/Contents/MacOS/Blender`.
 - **Run an example** — every example is a self-checking headless script (exit non-zero on failure, no GPU needed for the check):
 
 ```bash
@@ -72,6 +73,34 @@ blender --background --python examples/bmesh-gear/bmesh_gear.py --
 | Blender 5.1 | Prior stable (weekly cron; PR via `needs-5.1` or manual dispatch) |
 | Blender 4.5 LTS | Fallback supported (skills show both code paths where 4.x and 5.x APIs diverge) |
 
+## Falsifiers
+
+Every one of the 59 examples carries a **falsifier**: a flag that changes the
+input so a real assertion fails. It never disables the assertion, skips the
+check, or short-circuits to an error — it feeds the script something the
+contract says must not pass, and the same check that guards the happy path
+catches it.
+
+```bash
+# The contract holds: exit 0
+blender --background --python examples/bmesh-gear/bmesh_gear.py --
+
+# The falsifier: skip the extrude, so the topology no longer matches the
+# closed form. The topology check fires and the script exits 3.
+blender --background --python examples/bmesh-gear/bmesh_gear.py -- --no-extrude
+```
+
+This is what makes a green run mean something. An assertion that has only
+ever passed witnesses nothing — it could be comparing a constant to itself.
+Proving each one fails once, on demand, is the difference between a test
+suite and a set of scripts that print "OK". Shipping an example requires
+demonstrating the falsifier's non-zero exit and reporting the measured error.
+
+`--api`, `--check-pixels`, and `--output` are not falsifiers; they select a
+code path rather than break a contract. Full conventions, including the
+per-script exit-code model, are in
+[`CONTRIBUTING.md`](CONTRIBUTING.md#exit-codes).
+
 ## Showcase
 
 Budget-conformance props. Not examples. Conventions: [`showcase/README.md`](showcase/README.md).

SECURITY.md

@@ -26,10 +26,19 @@ Issues with the Blender Python API itself (`bpy`, `bmesh`, `bpy_extras`) belong
 
 ## Supported Versions
 
+This is a content repository — Markdown, MDC, Python, and TOML files consumed
+directly by an AI agent. There is no installed runtime, no server, and no
+long-lived deployment to patch, so there are no maintenance branches and no
+backports.
+
 | Version | Supported |
 |---------|-----------|
-| 0.2.x   | Yes       |
-| < 0.2.0 | No        |
+| Latest release (see [`VERSION`](VERSION)) | Yes |
+| Any earlier release | No |
+
+A confirmed fix lands on `main` and ships in the next release cut by
+`release.yml`. Consumers pin by tag or track `main`; the remedy in both cases
+is to move to the current release. Nothing older is patched in place.
 
 ## Response Timeline
 

docs/gallery/anvil/index.html

@@ -3,18 +3,18 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>anvil — Examples — Blender Developer Tools</title>
+  <title>anvil — Showcase — Blender Developer Tools</title>
   <meta name="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." />
   <link rel="canonical" href="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/anvil/" />
   <link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
   <meta name="theme-color" content="#1a1b1e" />
   <meta property="og:type" content="website" />
-  <meta property="og:title" content="anvil — Examples — Blender Developer Tools" />
+  <meta property="og:title" content="anvil — Showcase — Blender Developer Tools" />
   <meta property="og: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 property="og:url" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/anvil/" />
   <meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/anvil-hero.webp" />
   <meta name="twitter:card" content="summary_large_image" />
-  <meta name="twitter:title" content="anvil — Examples — Blender Developer Tools" />
+  <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" />
   <style>
@@ -239,7 +239,7 @@
 <body>
   <a class="skip" href="#main">Skip to content</a>
   <div class="topbar">
-    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples Gallery</a>
+    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples and Showcase</a>
     <div class="topbar-right">
       <a class="ghlink" href="https://github.com/TMHSDigital/Blender-Developer-Tools">GitHub</a>
     </div>
@@ -252,7 +252,7 @@ <h1>anvil</h1>
     <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>
-    <p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
+    <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>
     <div class="runline">
       <pre id="runCmd">blender --background --python showcase/anvil/anvil.py --</pre>

docs/gallery/armature-bend/index.html

@@ -239,7 +239,7 @@
 <body>
   <a class="skip" href="#main">Skip to content</a>
   <div class="topbar">
-    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples Gallery</a>
+    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples and Showcase</a>
     <div class="topbar-right">
       <a class="ghlink" href="https://github.com/TMHSDigital/Blender-Developer-Tools">GitHub</a>
     </div>

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

@@ -239,7 +239,7 @@
 <body>
   <a class="skip" href="#main">Skip to content</a>
   <div class="topbar">
-    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples Gallery</a>
+    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples and Showcase</a>
     <div class="topbar-right">
       <a class="ghlink" href="https://github.com/TMHSDigital/Blender-Developer-Tools">GitHub</a>
     </div>

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

@@ -239,7 +239,7 @@
 <body>
   <a class="skip" href="#main">Skip to content</a>
   <div class="topbar">
-    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples Gallery</a>
+    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples and Showcase</a>
     <div class="topbar-right">
       <a class="ghlink" href="https://github.com/TMHSDigital/Blender-Developer-Tools">GitHub</a>
     </div>

docs/gallery/bmesh-gear/index.html

@@ -239,7 +239,7 @@
 <body>
   <a class="skip" href="#main">Skip to content</a>
   <div class="topbar">
-    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples Gallery</a>
+    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples and Showcase</a>
     <div class="topbar-right">
       <a class="ghlink" href="https://github.com/TMHSDigital/Blender-Developer-Tools">GitHub</a>
     </div>

docs/gallery/campfire/index.html

@@ -3,18 +3,18 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>campfire — Examples — Blender Developer Tools</title>
+  <title>campfire — Showcase — Blender Developer Tools</title>
   <meta name="description" content="A procedural campfire through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract." />
   <link rel="canonical" href="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/campfire/" />
   <link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
   <meta name="theme-color" content="#1a1b1e" />
   <meta property="og:type" content="website" />
-  <meta property="og:title" content="campfire — Examples — Blender Developer Tools" />
+  <meta property="og:title" content="campfire — Showcase — Blender Developer Tools" />
   <meta property="og:description" content="A procedural campfire through UVs, bake, LOD, collider, and Unity glTF, asserting recomputed budgets rather than an API contract." />
   <meta property="og:url" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/campfire/" />
   <meta property="og:image" content="https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/assets/campfire-hero.webp" />
   <meta name="twitter:card" content="summary_large_image" />
-  <meta name="twitter:title" content="campfire — Examples — Blender Developer Tools" />
+  <meta name="twitter:title" content="campfire — Showcase — Blender Developer Tools" />
   <meta name="twitter:description" content="A procedural campfire 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/campfire-hero.webp" />
   <style>
@@ -239,7 +239,7 @@
 <body>
   <a class="skip" href="#main">Skip to content</a>
   <div class="topbar">
-    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples Gallery</a>
+    <a class="back" href="../"><span aria-hidden="true">&larr;</span> Examples and Showcase</a>
     <div class="topbar-right">
       <a class="ghlink" href="https://github.com/TMHSDigital/Blender-Developer-Tools">GitHub</a>
     </div>
@@ -252,7 +252,7 @@ <h1>campfire</h1>
     <button class="detail-hero" id="heroZoom" type="button" aria-label="Zoom campfire render">
       <img src="../assets/campfire-hero.webp" alt="campfire render" width="1280" height="720" />
     </button>
-    <p class="zoom-hint">Rendered headless by the example itself — click to zoom.</p>
+    <p class="zoom-hint">Rendered headless by the showcase piece itself — click to zoom.</p>
     <div class="callout"><span class="tag">witnesses</span> Recomputed: 2200 tris, three materials with 216 wood, 48 ash and 1304 stone faces, UVs in 0..1 with zero AABB overlap, outer AABB 0.807×0.808×0.404 m, LOD ratios in band, convex collider 198 tris, hygiene 0, 14 grounded bottom stones, teepee kiss 0.00001 m, course seat 0, non-empty glTF. --skip-decimate exits 9; --stray-vert 15; --lift-z/--short-stones 16; --float-logs 17; --gap-courses 18.</div>
     <div class="runline">
       <pre id="runCmd">blender --background --python showcase/campfire/campfire.py --</pre>