@@ -27,10 +27,10 @@ Label every claim.
 
 - [ ] Explicit paths only (`git add` never `-A` / `.`). Leave unstaged Cursor-injected `CLAUDE.md` hunks.
 - [ ] Counts in `README.md` match disk if content was added or removed (`validate-counts`).
-- [ ] Manifest arrays list every new skill / rule / snippet / template / example (`validate-manifest`). Do not touch the `"version"` line.
-- [ ] New example: `gallery.json`, smoke step, README row, hero/preview webp, `python scripts/build_gallery.py`, framing / contact-sheet gates as in `CLAUDE.md`.
+- [ ] Manifest arrays list every new skill / rule / snippet / template / example / showcase piece (`validate-manifest`). Do not touch the `"version"` line.
+- [ ] New example: `gallery.json`, `tests/smoke/catalog.json` row, README row, hero/preview webp, `python scripts/build_gallery.py`, framing / contact-sheet gates as in `CLAUDE.md`.
 - [ ] Every new check was falsified once (break it, non-zero exit, restore) — or this PR has no new check.
-- [ ] DCO `Signed-off-by:` on every commit ([CONTRIBUTING.md](CONTRIBUTING.md)).
+- [ ] DCO `Signed-off-by:` on every commit ([CONTRIBUTING.md](../CONTRIBUTING.md)).
 - [ ] No credentials, business emails, or local filesystem paths.
 
 ## Test plan
 
@@ -151,11 +151,11 @@ way, and a one-paragraph rationale. 30 to 80 lines is the right size.
 
 - `validate.yml` runs file structure checks plus a `validate-counts` job that
   asserts the README aggregate counts (skills, rules, templates, snippets,
-  and examples) match filesystem reality. The counts language in `README.md`
+  examples, and showcase pieces) match filesystem reality. The counts language in `README.md`
   is load-bearing: the job greps for it.
 - `validate.yml` also runs a `validate-manifest` job that checks
   `.cursor-plugin/plugin.json` against reality: every listed path must exist,
-  every skill, rule, snippet, template, and example on disk must be listed,
+  every skill, rule, snippet, template, example, and showcase piece on disk must be listed,
   and the manifest `version` must equal `VERSION`. The release pipeline owns
   the manifest `version` line (see `release.yml` below) — never hand-edit it.
 - `blender-smoke.yml` executes every shipped example (check-only, no render)
 
@@ -109,7 +109,7 @@ their renders ship in the site gallery at `docs/gallery/`. `examples/gallery.jso
 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
 wire all of: gallery.json entry, `.cursor-plugin/plugin.json` examples array (CI-gated),
-a `blender-smoke.yml` step, a README gallery row, hero webp (1280×720) in
+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`.
 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` —
 
@@ -1,6 +1,6 @@
 # Contributing to Blender Developer Tools
 
-Thanks for helping improve this repository. This document describes how to set up locally, extend skills, rules, snippets, and the template, and submit changes.
+Thanks for helping improve this repository. This document describes how to set up locally, extend skills, rules, snippets, templates, examples, and showcase pieces, and submit changes.
 
 ## Getting Started
 
@@ -20,7 +20,7 @@ Thanks for helping improve this repository. This document describes how to set u
 
 ## Repository Structure
 
-This repo is a content collection (skills, rules, snippets, and one template) for Blender Python development. There is no runtime, no MCP server, and no test runner; CI validates frontmatter, syntax, and aggregate counts.
+This repo is a content collection (skills, rules, snippets, templates, examples, and showcase pieces) for Blender Python development. There is no runtime and no MCP server. Headless checks run through `tests/smoke/run_example.py`; CI validates frontmatter, syntax, and aggregate counts.
 
 ```text
 skills/
@@ -35,6 +35,10 @@ templates/
     blender_manifest.toml
     __init__.py
     README.md
+examples/
+  gallery.json
+  <example-name>/
+    README.md
 showcase/
   README.md
   gallery.json
@@ -51,12 +55,12 @@ showcase/
 
 ## Adding a Skill
 
-1. Add a **kebab-case** directory under `skills/`, e.g. `skills/procedural-materials/`.
+1. Add a **kebab-case** directory under `skills/`, e.g. `skills/procedural-materials-and-shaders/`.
 2. Create **`SKILL.md`** with YAML frontmatter:
 
    ```yaml
    ---
-   name: procedural-materials
+   name: procedural-materials-and-shaders
    description: One-line description, under 200 chars.
    standards-version: <current meta-repo STANDARDS_VERSION>
    ---
@@ -67,7 +71,7 @@ showcase/
 
 ## Adding a Rule
 
-1. Add a **`.mdc`** file under `rules/`, e.g. `rules/avoid-python-loops-on-vertices.mdc`.
+1. Add a **`.mdc`** file under `rules/`, e.g. `rules/use-foreach-set-for-bulk-data.mdc`.
 2. Start with YAML **frontmatter**:
 
    ```yaml
@@ -191,7 +195,7 @@ The drift-check workflow enforces these on every push and PR.
 
 ## Aggregate Counts
 
-`README.md` declares aggregate counts (e.g. "16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 1 showcase piece"). The `validate-counts` job in `.github/workflows/validate.yml` enforces these substrings against the filesystem on every push and PR. Showcase pieces are counted separately from examples. When you add or remove content, update the README counts in the same commit.
+`README.md` declares aggregate counts (e.g. "16 skills, 9 rules, 3 templates, 27 snippets, 59 examples, and 26 showcase pieces"). The `validate-counts` job in `.github/workflows/validate.yml` enforces these substrings against the filesystem on every push and PR. Showcase pieces are counted separately from examples. When you add or remove content, update the README counts in the same commit.
 
 ## Pull Request Process
 
 
@@ -47,6 +47,7 @@ The content is consumed by AI coding agents (Cursor, Claude Code, any MCP-capabl
 | **Rules** | Guardrails for the most common AI mistakes: ops-in-loops, bmesh leaks, legacy `bl_info` only, prop assignments, deprecated context-copy override, per-element loops over bulk mesh data, import without scale check, export without evaluated geometry, mixed glTF/FBX axis RNA |
 | **Templates** | A working Extensions Platform add-on starter, a headless batch script starter, and a GLB-in engine-ready asset pipeline |
 | **Snippets** | 27 small standalone Python files demonstrating canonical patterns |
+| **Examples** | Runnable headless scripts under [`examples/`](examples/). Each asserts an API contract and exits non-zero on failure. |
 | **Showcase** | Budget-conformance props under [`showcase/`](showcase/). Not examples. Conventions: [`showcase/README.md`](showcase/README.md) |
 
 ## Quick start
@@ -777,7 +778,7 @@ portable path is `radius`.
 </details>
 
 <details>
-<summary><strong>Game asset pipeline</strong> — 21 examples</summary>
+<summary><strong>Game asset pipeline</strong> — 22 examples</summary>
 
 <table>
 <tr>
 
@@ -15,7 +15,7 @@ Please include:
 
 ## Scope
 
-This repository ships Markdown skill files, MDC rule files, Python snippets, and two starter templates (a Blender extension add-on and a headless batch script). The primary security concerns are:
+This repository ships Markdown skill files, MDC rule files, Python snippets, and three starter templates (a Blender extension add-on, a headless batch script, and a GLB-in engine-ready asset pipeline). The primary security concerns are:
 
 - **Snippets or templates demonstrating insecure patterns** (executing arbitrary code from `.blend` files, loading remote scripts without validation, leaking filesystem paths into logs).
 - **The extension-addon template declaring over-broad permissions** in `blender_manifest.toml` (e.g. `network`, `files`, `clipboard`, `camera`) without a documented justification.