feat: four rules for the headline Blender 5 breaks

The porting table lists about 20 breaks, but only bgl, the normals API,
.sequences, context.copy and bl_info had a rule, so the most common 5.x
breaks were caught only when an agent happened to load the right skill.
action.fcurves is one of the three bugs the README tagline names. New rules,
each stating only behavior this repo already measured on 4.5 and 5.x:

- no-legacy-action-fcurves: action.fcurves/groups/id_root (removed in 5.0)
- principled-v2-socket-names: 3.x Principled BSDF input names or indices
- no-nodes-modifier-idprop-inputs: mod[ident] = value without a 5.2 branch
- branch-eevee-engine-id: a literal EEVEE engine id without a 5.0 branch

Each is linked from its porting-table row; the Cursor manifest, CLAUDE.md
and README tables, counts (12 -> 16) and the generated Claude/AGENTS/Copilot
rule files are updated.

Closes #526

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LpkeXRvikhJZSVGBFM91Dv
Signed-off-by: TM Hospitality Strategies <TMHospitalityStrategies@gmail.com>

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -58,6 +58,10 @@
     "rules/use-correct-axis-rna-per-exporter.mdc",
     "rules/no-bgl.mdc",
     "rules/no-removed-normals-api.mdc",
-    "rules/no-legacy-vse-sequences.mdc"
+    "rules/no-legacy-vse-sequences.mdc",
+    "rules/no-legacy-action-fcurves.mdc",
+    "rules/principled-v2-socket-names.mdc",
+    "rules/no-nodes-modifier-idprop-inputs.mdc",
+    "rules/branch-eevee-engine-id.mdc"
   ]
 }

AGENTS.md

@@ -20,7 +20,7 @@ a `.cursor-plugin/plugin.json` manifest so the ecosystem drift checker
 classifies it as a `cursor-plugin`. This is content the AI loads when the user
 asks Blender questions or works on Blender add-ons in Cursor or Claude Code.
 
-The content base is 25 skills, 12 rules, 3 templates, 31 snippets, 66
+The content base is 25 skills, 16 rules, 3 templates, 31 snippets, 66
 examples, and 80 showcase pieces (counts are CI-enforced across README.md, the agent docs, ROADMAP.md,
 `site.json` and the site templates). The full inventory tables and per-item purposes live in
 `CLAUDE.md`. Example anatomy and authoring rules: copy `examples/bmesh-gear/`;
@@ -33,7 +33,7 @@ in `docs/VISUAL-STYLE.md`; the canonical run prompt is
 ```
 Blender-Developer-Tools/
   skills/<skill-name>/SKILL.md   # 25 skill files
-  rules/<rule-name>.mdc          # 12 rule files
+  rules/<rule-name>.mdc          # 16 rule files
   templates/<template-name>/     # 3 starter templates
   snippets/<snippet-name>.py     # 31 standalone Python snippets
   examples/<name>/               # 69 runnable smoke-gated examples (+ gallery.json)

CLAUDE.md

@@ -18,7 +18,7 @@ The **Blender Developer Tools** repository is at **v0.158.0**. It packages skill
 
 ```
 skills/<skill-name>/SKILL.md   - AI workflow definitions, 25 total
-rules/<rule-name>.mdc          - Anti-pattern rules, 12 total
+rules/<rule-name>.mdc          - Anti-pattern rules, 16 total
 templates/<template-name>/     - Starter projects, 3 total
 snippets/<snippet-name>.py     - Standalone code patterns, 31 total
 examples/<name>/               - Runnable smoke-gated examples, 69 total (+ gallery.json)
@@ -60,7 +60,7 @@ VERSION                        - Source of truth for the repo version
 | curves-and-text | Curve and TextCurve datablocks: splines, bevel/extrude closed forms, `body`, Bfont, evaluated mesh read-back |
 | compositor-nodes | 4.5 `scene.node_tree` vs 5.x `scene.compositing_node_group`, Glare node enum-to-menu-socket change, `use_compositing` |
 
-## Rules (12)
+## Rules (16)
 
 Every rule sets `alwaysApply: false`, so the Scope column below is the rule's
 actual load condition, not a description: a rule enters context only when a file
@@ -80,6 +80,10 @@ matching its `globs` does. Changing a glob changes when the rule fires.
 | no-bgl | `*.py` | `import bgl` or any `bgl.` call (removed in 5.x; the add-on fails to register) |
 | no-removed-normals-api | `*.py` | `use_auto_smooth`, `auto_smooth_angle`, `calc_normals_split()` and the other normals calls removed in 4.1 |
 | no-legacy-vse-sequences | `*.py` | `sequence_editor.sequences` / `.sequences_all` (removed in 5.x; `.strips` / `.strips_all` exist on 4.5 too) |
+| no-legacy-action-fcurves | `*.py` | `action.fcurves`, `action.groups`, `action.id_root` (removed in 5.0; F-curves live in the slot's channelbag) |
+| principled-v2-socket-names | `*.py` | Principled BSDF inputs by 3.x name (`Emission`, `Specular`, `Clearcoat`, ...) or by index (renamed in 4.0) |
+| no-nodes-modifier-idprop-inputs | `*.py` | `mod["Socket_N"] = value` on a NODES modifier without a 5.2 branch (TypeError on 5.2; `mod.properties.inputs` does not exist before it) |
+| branch-eevee-engine-id | `*.py` | literal `'BLENDER_EEVEE_NEXT'` / `'BLENDER_EEVEE'` engine id without a 5.0 version branch |
 
 ## Templates (3)
 

CONTRIBUTING.md

@@ -329,7 +329,7 @@ The drift-check workflow enforces these on every push and PR.
 
 ## Aggregate Counts
 
-`README.md` declares aggregate counts (e.g. "25 skills, 12 rules, 3 templates, 31 snippets, 69 examples, and 80 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.
+`README.md` declares aggregate counts (e.g. "25 skills, 16 rules, 3 templates, 31 snippets, 69 examples, and 80 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
 

README.md

@@ -25,7 +25,7 @@
 </p>
 
 <p align="center">
-  <strong>25 skills</strong> &nbsp;&bull;&nbsp; <strong>12 rules</strong> &nbsp;&bull;&nbsp; <strong>3 templates</strong> &nbsp;&bull;&nbsp; <strong>31 snippets</strong> &nbsp;&bull;&nbsp; <strong>69 examples</strong> &nbsp;&bull;&nbsp; <strong>80 showcase pieces</strong>
+  <strong>25 skills</strong> &nbsp;&bull;&nbsp; <strong>16 rules</strong> &nbsp;&bull;&nbsp; <strong>3 templates</strong> &nbsp;&bull;&nbsp; <strong>31 snippets</strong> &nbsp;&bull;&nbsp; <strong>69 examples</strong> &nbsp;&bull;&nbsp; <strong>80 showcase pieces</strong>
 </p>
 
 <p align="center">
@@ -44,14 +44,14 @@
 
 ## Overview
 
-This repository ships **25 skills, 12 rules, 3 templates, 31 snippets, 69 examples, and 80 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.
+This repository ships **25 skills, 16 rules, 3 templates, 31 snippets, 69 examples, and 80 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, installed as a plugin or read from a checkout. An optional second plugin registers the official [Blender Lab MCP server](https://www.blender.org/lab/mcp-server/) for live sessions (see [Live Blender session](#live-blender-session-mcp)); the server is referenced from upstream, not part of this repository, and nothing else depends on it. Cursor and Claude Code both install it as a plugin (see [Quick start](#quick-start)): Cursor loads the skills and applies `rules/*.mdc` wherever their scope globs match; Claude Code loads the skills and gets the rules through a generated `blender-rules` skill, since it does not read Cursor `.mdc` files. An agent picks a skill up when its description matches the task. 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 |
 | --- | --- |
 | **Skills** | Guided workflows: scaffolding, operators, panels, properties, mesh and bmesh, headless batch, slotted actions, geometry nodes, procedural materials, depsgraph queries, drivers and handlers, `bl_info` migration, video sequencer, imported-mesh cleanup, high-to-low baking, engine export presets, extension runtime and packaging, timers, modal operators and threading, GPU drawing and viewport overlays, porting add-ons to Blender 5, Grease Pencil v3, constraints and parenting, images and pixels, curves and text, compositor nodes |
-| **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, and the 5.x removals: `bgl`, the pre-4.1 normals API, `sequence_editor.sequences` |
+| **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, and the 5.x breaks: `bgl`, the pre-4.1 normals API, `sequence_editor.sequences`, `action.fcurves`, 3.x Principled socket names, NodesModifier ID-property inputs, the EEVEE engine id |
 | **Templates** | A working Extensions Platform add-on starter, a headless batch script starter, and a GLB-in engine-ready asset pipeline |
 | **Snippets** | 31 small standalone Python files demonstrating canonical patterns, 5 to 75 lines each |
 | **Examples** | Runnable headless scripts under [`examples/`](examples/). Each asserts an API contract and exits non-zero on failure. |
@@ -61,7 +61,7 @@ The content is consumed by AI coding agents, installed as a plugin or read from
 
 Neither agent needs a clone of `main`: both install the slim `plugin-dist` build. Clone the full repository only to [run the examples or contribute](#run-the-examples-or-contribute).
 
-- **Cursor** — install it as a local plugin from the slim `plugin-dist` branch, then run **Developer: Reload Window**. **Customize** lists the 25 skills and 12 rules; the rules apply by glob scope and the agent loads a skill when its description matches the task.
+- **Cursor** — install it as a local plugin from the slim `plugin-dist` branch, then run **Developer: Reload Window**. **Customize** lists the 25 skills and 16 rules; the rules apply by glob scope and the agent loads a skill when its description matches the task.
 
   ```bash
   git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git ~/.cursor/plugins/local/blender-developer-tools
@@ -198,7 +198,7 @@ Browse both, with filters, full-size renders and each script's README, in the **
 
 ```
 skills/<name>/SKILL.md   - 25 skill files, YAML frontmatter, one canonical pattern each
-rules/<name>.mdc         - 12 rule files, anti-pattern + correction
+rules/<name>.mdc         - 16 rule files, anti-pattern + correction
 templates/<name>/        - 3 template directories (extension-addon-template, headless-batch-script-template, ai-asset-pipeline-template)
 snippets/<name>.py       - 31 standalone Python snippets, 5 to 75 lines each
 examples/<name>/         - 69 example directories: script, README with exit codes and falsifier
@@ -208,7 +208,7 @@ claude/                  - generated Claude Code copies of the rules (blender-ru
 
 ## Using rules in Cursor
 
-With the Cursor plugin installed, the `.mdc` files in `rules/` apply automatically when Cursor opens a Blender Python project, scoped by the `globs` in each rule's frontmatter. The 12 rules are:
+With the Cursor plugin installed, the `.mdc` files in `rules/` apply automatically when Cursor opens a Blender Python project, scoped by the `globs` in each rule's frontmatter. The 16 rules are:
 
 - `prefer-data-over-ops-in-loops`: flags `bpy.ops.*` calls inside object iteration
 - `always-free-bmesh`: flags `bmesh.new()` without paired `bm.free()` in `try`/`finally`
@@ -222,6 +222,10 @@ With the Cursor plugin installed, the `.mdc` files in `rules/` apply automatical
 - `no-bgl`: flags `import bgl` or any `bgl.` call (removed in 5.x; the add-on fails to register)
 - `no-removed-normals-api`: flags `use_auto_smooth`, `auto_smooth_angle`, `calc_normals_split()` and the other normals calls removed in 4.1
 - `no-legacy-vse-sequences`: flags `sequence_editor.sequences` / `.sequences_all` (removed in 5.x; `.strips` / `.strips_all` exist on 4.5 too)
+- `no-legacy-action-fcurves`: flags `action.fcurves`, `action.groups` and `action.id_root` (removed in 5.0; reach F-curves through the slot's channelbag)
+- `principled-v2-socket-names`: flags Principled BSDF inputs by 3.x name (`Emission`, `Specular`, `Clearcoat`, ...) or by index (renamed in 4.0)
+- `no-nodes-modifier-idprop-inputs`: flags `mod["Socket_N"] = value` on a Geometry Nodes modifier without a 5.2 version branch (the dict write raises on 5.2)
+- `branch-eevee-engine-id`: flags a literal `'BLENDER_EEVEE_NEXT'` / `'BLENDER_EEVEE'` engine id without a 5.0 version branch
 
 Cursor: the plugin covers the rules (see [Quick start](#quick-start)); copying `rules/*.mdc` into a project's `.cursor/rules/` is only the per-project alternative without the plugin. Claude Code: the plugin ships the rules as the `blender-rules` skill.
 

ROADMAP.md

@@ -39,6 +39,7 @@ derives the actual version from conventional-commit types.
 | Porting snippets and the legacy VSE `.sequences` rule | 20 | 12 | 3 | 31 | Shipped |
 | Skills for stranded examples: Grease Pencil v3, constraints and parenting, images and pixels, curves and text, compositor nodes | 25 | 12 | 3 | 31 | Shipped |
 | Live-session bridge (opt-in `blender-live-session` plugin, upstream Blender Lab MCP) | - | - | - | - | Shipped |
+| Rules for the headline 5.x breaks: `action.fcurves`, Principled v2 socket names, NodesModifier ID-property inputs, the EEVEE engine id | 25 | 16 | 3 | 31 | Shipped |
 | Stable (1.0) | — | — | — | — | Upcoming; criteria below |
 
 ## What "Stable (1.0)" means

claude/blender-rules.md

@@ -11,18 +11,36 @@ Flag bmesh.new() calls without a paired bm.free() in a try/finally block. Blende
 
 Applies to: `**/*.py`. Full rule: [`rules/always-free-bmesh.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/always-free-bmesh.mdc).
 
+## branch-eevee-engine-id
+
+Flag `render.engine = 'BLENDER_EEVEE_NEXT'` or `= 'BLENDER_EEVEE'` written without a version branch. EEVEE Next used the id 'BLENDER_EEVEE_NEXT' on 4.2 through 4.5 LTS and took back 'BLENDER_EEVEE' in 5.0; each id raises TypeError (enum not found) on the other side. Branch on bpy.app.version >= (5, 0, 0). See the procedural-materials-and-shaders skill.
+
+Applies to: `**/*.py`. Full rule: [`rules/branch-eevee-engine-id.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/branch-eevee-engine-id.mdc).
+
 ## no-bgl
 
 Flag `import bgl` and any `bgl.` call. The `bgl` OpenGL wrapper was deprecated in 3.x and is gone in Blender 5.x (`importlib.util.find_spec('bgl')` is `None` on 5.0, 5.1 and 5.2), so an add-on that imports it fails to register. Draw with the `gpu` module, `gpu.state` and `gpu_extras.batch` instead; see the gpu-drawing-and-overlays skill.
 
 Applies to: `**/*.py`. Full rule: [`rules/no-bgl.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/no-bgl.mdc).
 
+## no-legacy-action-fcurves
+
+Flag `action.fcurves`, `action.groups` and `action.id_root` on an Action. Blender 5.0 removed the flat legacy Action API (AttributeError on 5.x); F-curves live in a channelbag per slot. On 4.4/4.5 LTS the legacy path still runs but is a trap on a fresh Action (it creates a slot without binding it). Reach F-curves through the slot's channelbag, or use obj.keyframe_insert. See the slotted-actions-animation skill.
+
+Applies to: `**/*.py`. Full rule: [`rules/no-legacy-action-fcurves.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/no-legacy-action-fcurves.mdc).
+
 ## no-legacy-vse-sequences
 
 Flag `sequence_editor.sequences` and `.sequences_all`. Both are gone in Blender 5.x (AttributeError on 5.0, 5.1 and 5.2), while `.strips` and `.strips_all` already exist on 4.5 LTS, so use those everywhere with no version branch. See the vse-python skill.
 
 Applies to: `**/*.py`. Full rule: [`rules/no-legacy-vse-sequences.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/no-legacy-vse-sequences.mdc).
 
+## no-nodes-modifier-idprop-inputs
+
+Flag writing a Geometry Nodes modifier input as an ID property (`mod["Socket_2"] = value`, `mod[identifier] = value`) without a version branch. Blender 5.2 removed that form (it raises TypeError, id properties not supported for this type); 5.2+ writes `getattr(mod.properties.inputs, identifier).value`, which does not exist on 4.5 LTS or 5.1. Branch on bpy.app.version >= (5, 2, 0). See the geometry-nodes-python skill.
+
+Applies to: `**/*.py`. Full rule: [`rules/no-nodes-modifier-idprop-inputs.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/no-nodes-modifier-idprop-inputs.mdc).
+
 ## no-removed-normals-api
 
 Flag the mesh normals API removed in Blender 4.1 — `use_auto_smooth`, `auto_smooth_angle`, `calc_normals_split()`, `free_normals_split()`, `create_normals_split()`. Each raises AttributeError on 4.5 LTS and 5.x. Use `Mesh.set_sharp_from_angle`, `object.shade_auto_smooth`, and `Mesh.corner_normals` (always current) instead.
@@ -47,6 +65,12 @@ Flag uses of `bpy.context.copy()` to override context for an operator call. Pass
 
 Applies to: `**/*.py`. Full rule: [`rules/prefer-temp-override-over-context-copy.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/prefer-temp-override-over-context-copy.mdc).
 
+## principled-v2-socket-names
+
+Flag Principled BSDF inputs looked up by their 3.x names (`inputs["Emission"]`, `["Specular"]`, `["Clearcoat"]`, `["Subsurface"]`, `["Transmission"]`, `["Sheen"]`) or by index. Principled v2 (Blender 4.0) renamed them, so they raise KeyError on 4.5 LTS and 5.x. Use the 4.0+ names (`Emission Color`, `Specular IOR Level`, `Coat Weight`, ...), which need no version branch. See the procedural-materials-and-shaders skill.
+
+Applies to: `**/*.py`. Full rule: [`rules/principled-v2-socket-names.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/principled-v2-socket-names.mdc).
+
 ## target-extensions-platform-format
 
 Flag new Blender add-ons that ship only a legacy bl_info dict without a blender_manifest.toml. New add-ons must use the Extensions Platform format. bl_info may appear alongside as a fallback for backward compatibility, but the manifest is the source of truth.