diff --git a/.github/workflows/label-sync.yml b/.github/workflows/label-sync.yml index 7a89802a..4a9f9a6c 100644 --- a/.github/workflows/label-sync.yml +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index d9a9c46d..720477d1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -105,12 +105,25 @@ AI asset pipeline track: `decimate_to_budget.py`, `convex_hull_collider.py`, `lo Runnable scripts at `examples//`, 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 diff --git a/README.md b/README.md index 384cafd1..df575e95 100644 --- a/README.md +++ b/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). diff --git a/SECURITY.md b/SECURITY.md index 88b7295f..9c4bcbd8 100644 --- a/SECURITY.md +++ b/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 diff --git a/docs/gallery/anvil/index.html b/docs/gallery/anvil/index.html index c5f1bed5..203dd7f5 100644 --- a/docs/gallery/anvil/index.html +++ b/docs/gallery/anvil/index.html @@ -3,18 +3,18 @@ - anvil — Examples — Blender Developer Tools + anvil — Showcase — Blender Developer Tools - + - +