# AGENTS.md: Blender add-on (bpy)

## Commands
- Build an extension zip: `blender --command extension build` (reads `blender_manifest.toml`)
- Validate: `blender --command extension validate`
- Headless tests: `blender --background --factory-startup --python-exit-code 1 --python tests/run_tests.py`
- Check `blender_version_min` in the manifest and only use bpy APIs available in that version.

## Code map
`blender_manifest.toml` (id, version, `blender_version_min`, permissions) · `__init__.py` (register/unregister only) · `operators/`, `panels/`, `props.py`, `utils/`.

## Rules
- Every class (Operator, Panel, PropertyGroup, Menu) is listed in one `classes` tuple, registered in order in `register()` and unregistered in reverse in `unregister()`. Re-enabling the add-on must not error.
- Operators: `bl_idname = "myaddon.verb_noun"`, `bl_label`, `bl_options = {'REGISTER', 'UNDO'}` for anything that changes data, a `poll()` classmethod, and return `{'FINISHED'}` or `{'CANCELLED'}`. Report problems with `self.report({'ERROR'}, msg)`.
- Panels: `bl_space_type`, `bl_region_type`, `bl_category`; draw only, never modify data in `draw()`.
- Store settings in a `PropertyGroup` attached via `bpy.types.Scene.myaddon = PointerProperty(...)` (remove it in `unregister`). Preferences go in `AddonPreferences` keyed by `__package__`.
- Prefer data API (`bpy.data`, mesh/`bmesh`) over `bpy.ops` inside loops; `bpy.ops` depends on context and is slow. If you need an operator, pass a context with `context.temp_override(...)`.
- Don't store references to `bpy` data blocks across undo or file loads; look them up by name or use handlers with `@persistent`.
- Network access, file writes outside the user's chosen path, and subprocesses must be declared in manifest `permissions` and done only when the user triggers them.
- Third-party Python wheels are bundled via the manifest's `wheels` list, not installed with pip at runtime.

## Done
Validate and build succeed, headless tests pass, and the add-on enables, runs, and disables cleanly in a fresh profile.