Use when implementing end-to-end BIM workflows that combine IfcOpenShell, Bonsai, and Blender -- such as IFC creation from scratch, model enrichment, validation pipelines, geometry extraction, or batch processing of building models. Prevents the common mistake of skipping unit and context setup before creating geometry, or directly modifying IFC attributes instead of using ifcopenshell.api.run(). Covers property set management across tools, spatial hierarchy patterns, and version compatibility for IFC2X3/IFC4/IFC4X3. Keywords: BIM workflow, IFC creation, model validation, property extraction, batch processing, spatial hierarchy, cross-technology, IfcOpenShell Bonsai Blender, pset management.

Use when reviewing, validating, or auditing Blender Python code for correctness. Runs systematic checks for deprecated API usage, context errors, version compatibility issues, threading violations, data reference invalidation, incorrect operator calls, and addon structure compliance. Prevents shipping code with silent version-dependent failures. Keywords: code review, validation, audit, deprecated API, context error, version compatibility, threading, addon structure, code quality, Blender Python.

Use when migrating, porting, or upgrading Blender Python scripts and addons across major versions (3.x to 4.x to 5.x). Provides a systematic migration process covering API renames, removed functions, changed parameters, extension system migration, BGL to GPU module conversion, and bone collection migration. Prevents incomplete migrations that compile but fail at runtime. Keywords: migration, porting, upgrade, version, 3.x to 4.x, 4.x to 5.x, API rename, bgl to gpu, extension migration, bl_info to manifest, bone collection.

Use when writing Blender Python scripts that access bpy module structure, RNA data, the context system, dependency graph, or operator invocation. Prevents the common mistake of accessing context attributes outside their valid scope or calling operators without checking poll(). Covers bpy.data, bpy.context, bpy.ops, depsgraph evaluation, and RNA property access patterns across Blender 3.x/4.x/5.x. Keywords: bpy, Blender Python, RNA, context, depsgraph, operator, bpy.data, bpy.ops.

Use when drawing custom overlays, viewport visualizations, or offscreen renders in Blender Python. Prevents the critical mistake of using the deprecated bgl module (removed in Blender 5.0) instead of the gpu module. Covers gpu.shader, gpu.batch, gpu.state, SpaceView3D draw handlers, built-in shaders, and BGL-to-gpu migration. Keywords: gpu module, bgl, draw handler, viewport overlay, offscreen rendering, SpaceView3D, shader, UNIFORM_COLOR, Blender Python drawing.

Use when dealing with Blender Python runtime behavior -- mathutils, threading, handlers, timers, or crashes after undo/redo. Prevents the #1 runtime crash: using threading for bpy operations instead of bpy.app.timers, or caching bpy.data references across undo boundaries. Covers Vector/Matrix/Quaternion, KDTree, BVHTree, @persistent handlers, bpy.msgbus subscriptions, and background mode limitations. Keywords: mathutils, threading, undo, ReferenceError, bpy.app.timers, @persistent, bpy.msgbus, KDTree, BVHTree, background mode, Blender crash.

Use when writing Blender Python code that must work across multiple versions (3.x/4.x/5.x), or when migrating scripts between Blender versions. Prevents breakage from renamed APIs, removed modules (bgl in 5.0), and changed function signatures. Provides the complete breaking changes matrix, deprecation timeline, and version-safe coding patterns. Keywords: Blender version, migration, deprecated, breaking change, bgl removal, bpy.app.version, version compatibility, 3.x, 4.x, 5.x, API changes.

Use when debugging Blender RuntimeError from restricted context, operator poll() failures, or wrong context for bpy.ops calls. Prevents the #1 Blender Python error: calling operators or accessing context attributes from wrong areas (e.g., timer callbacks, draw handlers). Covers context override removal in 4.0+, temp_override migration, and context-dependent attribute access patterns. Keywords: RuntimeError, restricted context, poll failure, context override, temp_override, bpy.ops error, wrong context, modal context, Blender context error.

Use when debugging Blender ReferenceError from removed objects, undo-invalidated bpy.data references, or stale ID pointers. Prevents the common crash of caching bpy.data references across undo/redo operations (references become invalid). Covers safe data access patterns, ID reference caching pitfalls, data lifecycle management, and bpy.data collections. Keywords: ReferenceError, undo, stale reference, bpy.data, ID pointer, data invalidation, removed object, data lifecycle, StructRNA, Blender crash.

Use when debugging Blender AttributeError from removed APIs, ImportError from deprecated modules (bgl in 5.0), or breaking changes in operator signatures between versions. Prevents silent failures from using APIs that were renamed or removed in newer Blender versions. Provides migration patterns from 3.x to 4.x to 5.x with complete replacement mappings. Keywords: AttributeError, ImportError, deprecated, version error, bgl, migration, breaking change, removed API, 3.x to 4.x, 4.x to 5.x, Blender upgrade.

Use when building a production Blender addon -- project structure, testing, CI/CD, or packaging for extensions.blender.org. Prevents the common mistake of hardcoding paths or skipping the extension manifest for Blender 4.2+. Covers multi-file addon structure, testing strategies, dependency management, and distribution workflows. Keywords: addon development, extension packaging, CI/CD, testing, multi-file addon, blender_manifest.toml, distribution, extensions.blender.org.

Use when implementing AEC-specific animations -- construction sequences, camera walkthroughs, solar studies, or phasing visualizations in Blender. Prevents the common mistake of keyframing visibility instead of using proper collection visibility for construction phases. Covers NLA workflow orchestration, batch keyframe operations, and time-based visualizations. Keywords: construction animation, camera walkthrough, solar study, phasing, NLA, keyframe, construction sequence, visibility animation, AEC visualization.

Use when automating Blender workflows -- batch rendering, headless processing via blender --background, file format conversion, or pipeline integration. Prevents the common mistake of using viewport operators in background mode (no UI context available). Covers command-line rendering, file I/O automation (OBJ/FBX/STL/USD/glTF), scene assembly, and CI/CD pipeline integration. Keywords: batch rendering, headless, blender --background, automation, file conversion, OBJ, FBX, STL, USD, glTF, pipeline, command-line.

Use when generating mesh geometry for AEC applications -- buildings from vertices, IFC geometry visualization, parametric elements, or custom mesh tools. Prevents the performance mistake of creating vertices one-by-one instead of using from_pydata or BMesh batch operations. Covers mesh creation, BMesh algorithms, foreach_get/set optimization, and mesh analysis tools. Keywords: mesh generation, from_pydata, BMesh, parametric, building geometry, mesh analysis, foreach_get, foreach_set, vertices, AEC mesh, custom mesh tool.

Use when implementing complex Blender operators -- modal operators with timer callbacks, file browsers, batch processing, or multi-step workflows. Prevents the common mistake of blocking the UI thread in long operations instead of using modal + timer pattern. Covers modal operators, file browser integration, undo/redo support, progress reporting, and batch processing operators. Keywords: modal operator, timer callback, file browser, batch processing, progress reporting, undo support, multi-step workflow, INVOKE_DEFAULT.

Use when creating a Blender addon or extension, or migrating from legacy bl_info to blender_manifest.toml (required in 5.0). Prevents the common mistake of using bl_info in Blender 5.0+ where only the manifest format is supported. Covers register/unregister lifecycle, multi-file addon structure, AddonPreferences, class naming, and extension packaging for extensions.blender.org. Keywords: addon, extension, bl_info, blender_manifest.toml, register, unregister, AddonPreferences, packaging, extensions.blender.org.

Use when creating animations programmatically in Blender -- keyframes, FCurves, Actions, NLA strips, drivers, or armature operations. Prevents the breaking change pitfall of using bone.layers (removed in 4.0) instead of BoneCollection. Covers keyframe_insert, FCurve access, Action data blocks, NLA system, driver expressions, and timeline control. Keywords: keyframe, FCurve, Action, NLA, BoneCollection, armature, driver, animation, bone layers, timeline, bpy.ops.anim.

Use when managing Blender data blocks -- collections, linked libraries, library overrides, or the asset system. Prevents the common mistake of not handling fake users when removing data blocks, or using append when link+override is needed. Covers bpy.data collections, BlendDataLibraries, library overrides, asset system, and data transfer between files. Keywords: bpy.data, collections, library overrides, linked library, asset system, append, link, fake user, data block, BlendDataLibraries.

Use when creating or modifying Blender materials and shader nodes via Python. Prevents the breaking change of using old Principled BSDF input names (e.g., "Subsurface" renamed to "Subsurface Weight" in 4.0). Covers material creation, node tree setup, Principled BSDF input mapping, UV assignment, texture loading, and material slot management. Keywords: material, shader, Principled BSDF, node tree, texture, UV map, material_slot, ShaderNodeBsdfPrincipled, node links, Blender materials.

Use when working with Blender modifiers via Python -- adding, configuring, or applying modifiers, or accessing Geometry Nodes inputs. Prevents the common mistake of reading mesh data before applying modifiers (getting unmodified geometry) instead of using depsgraph.evaluated_get(). Covers modifier stack, Geometry Nodes input identifiers, common AEC modifiers (Array, Boolean, Solidify), and evaluated mesh access. Keywords: modifier, Array, Boolean, Solidify, Geometry Nodes, depsgraph, evaluated_get, modifier.apply, modifier stack, input identifier.