From b53dac241014ea25081dc91be62bdf0ded743d63 Mon Sep 17 00:00:00 2001 From: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Date: Mon, 21 Sep 2026 18:51:12 -0400 Subject: [PATCH 1/3] fix: correct inventory counts that no longer match the tree The game-asset category header, the contributing guide's inventory, and the security scope still described an older tree. Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Co-authored-by: Cursor --- CONTRIBUTING.md | 10 +++++++--- README.md | 3 ++- SECURITY.md | 2 +- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2cdd3330..404c77cd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 + / + README.md showcase/ README.md gallery.json @@ -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 diff --git a/README.md b/README.md index 392862c5..384cafd1 100644 --- a/README.md +++ b/README.md @@ -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`.
-Game asset pipeline — 21 examples +Game asset pipeline — 22 examples diff --git a/SECURITY.md b/SECURITY.md index 47b0e453..88b7295f 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -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. From b9719ae513a7b58057a9ee96554ed3232d7889aa Mon Sep 17 00:00:00 2001 From: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Date: Mon, 21 Sep 2026 18:51:56 -0400 Subject: [PATCH 2/3] fix: point contributor docs at the smoke catalog and real paths Authoring docs still said to add a blender-smoke.yml step and cited skill and rule paths that are not in the tree. Smoke rows live in the catalog, and the manifest check includes showcase. Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Co-authored-by: Cursor --- .github/PULL_REQUEST_TEMPLATE.md | 4 ++-- AGENTS.md | 4 ++-- CLAUDE.md | 2 +- CONTRIBUTING.md | 6 +++--- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index aeeab416..5dc3c7a2 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -27,8 +27,8 @@ 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)). - [ ] No credentials, business emails, or local filesystem paths. diff --git a/AGENTS.md b/AGENTS.md index 4dec7982..ca076250 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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) diff --git a/CLAUDE.md b/CLAUDE.md index 8e078ba6..e36817cb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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` — diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 404c77cd..cdda9902 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -55,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: --- @@ -71,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 From 324342af5667d95ebc7cbfbf97c863991800b58c Mon Sep 17 00:00:00 2001 From: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Date: Mon, 21 Sep 2026 18:52:10 -0400 Subject: [PATCH 3/3] fix: resolve the pull request template link to CONTRIBUTING The template lives in .github, so a same-directory CONTRIBUTING.md link does not resolve. Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com> Co-authored-by: Cursor --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5dc3c7a2..684b6ab6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -30,7 +30,7 @@ Label every claim. - [ ] 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