@@ -7,7 +7,7 @@ full version with Wrong/Right examples.
 
 ## always-free-bmesh
 
-Flag bmesh.new() calls without a paired bm.free() in a try/finally block. BMesh allocates C-side memory that Python's garbage collector cannot reclaim; missing free() leaks and eventually crashes Blender.
+Flag bmesh.new() calls without a paired bm.free() in a try/finally block. Blender frees an unreferenced BMesh only when its Python wrapper dies, which a traceback, global, closure or modal operator can delay for the whole session; an explicit free() in finally releases it deterministically.
 
 Applies to: `**/*.py`. Full rule: [`rules/always-free-bmesh.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/always-free-bmesh.mdc).
 
 
@@ -12,7 +12,7 @@ full version with Wrong/Right examples.
 
 ## always-free-bmesh
 
-Flag bmesh.new() calls without a paired bm.free() in a try/finally block. BMesh allocates C-side memory that Python's garbage collector cannot reclaim; missing free() leaks and eventually crashes Blender.
+Flag bmesh.new() calls without a paired bm.free() in a try/finally block. Blender frees an unreferenced BMesh only when its Python wrapper dies, which a traceback, global, closure or modal operator can delay for the whole session; an explicit free() in finally releases it deterministically.
 
 Applies to: `**/*.py`. Full rule: [`rules/always-free-bmesh.mdc`](https://github.com/TMHSDigital/Blender-Developer-Tools/blob/main/rules/always-free-bmesh.mdc).
 
 
@@ -1,5 +1,5 @@
 ---
-description: Flag bmesh.new() calls without a paired bm.free() in a try/finally block. BMesh allocates C-side memory that Python's garbage collector cannot reclaim; missing free() leaks and eventually crashes Blender.
+description: Flag bmesh.new() calls without a paired bm.free() in a try/finally block. Blender frees an unreferenced BMesh only when its Python wrapper dies, which a traceback, global, closure or modal operator can delay for the whole session; an explicit free() in finally releases it deterministically.
 alwaysApply: false
 globs:
   - "**/*.py"
@@ -10,13 +10,21 @@ standards-version: 1.10.0
 
 `bmesh.new()` returns a Python wrapper around a C-side BMesh structure.
 The structure holds the vertex, edge, face, loop, and attribute layer
-storage that the bmesh module operates on. Python's garbage collector
-sees the wrapper but **cannot free the underlying C memory**. That has
-to be done explicitly with `bm.free()`.
-
-Forgetting `bm.free()` leaks. Long-running scripts and modal operators
-that loop without freeing eventually exhaust memory and crash Blender,
-often after the user has done significant unsaved work.
+storage that the bmesh module operates on. Blender frees it when the
+wrapper is garbage-collected ("typically when the script finishes
+executing", per the `BMesh.free()` docs), so the problem is not that the
+memory can never be reclaimed. It is **when**:
+
+- An exception's traceback holds the frame, and with it `bm`, alive
+  (`sys.last_traceback` keeps the last one for the whole session).
+- A global, a closure, a class attribute or a modal operator's `self`
+  keeps the wrapper reachable for as long as the add-on runs.
+- A loop that builds a BMesh per iteration without freeing can hold many
+  full mesh copies at once before collection catches up.
+
+`bm.free()` in a `finally` releases the storage at a point you choose,
+on every path, and makes any later use of `bm` fail fast with
+`ReferenceError` instead of quietly reading stale data.
 
 ## What this rule flags
 
@@ -77,8 +85,8 @@ and `bm.free()` raises. Without it, a `KeyError` reading
 remaining session.
 
 For the edit-mode case where the bmesh comes from `bmesh.from_edit_mesh()`,
-**do not call `bm.free()`**. Edit-mode bmeshes are owned by Blender and
-freeing them double-frees and crashes:
+**do not call `bm.free()`**. Blender owns the edit-mode BMesh for as long
+as the mesh is in Edit Mode; your wrapper only borrows it:
 
 ```python
 # Edit-mode: Blender owns the bmesh, do not free it
@@ -124,9 +132,9 @@ RAM and survives until they restart Blender. For users on machines with
 16GB or less, even modest leaks (a few hundred MB per modal session)
 make Blender unusable after an hour.
 
-The crash itself is hard to diagnose: the OOM may not happen during
+The symptom is hard to diagnose: memory pressure may not surface during
 your code's execution at all, but during a later modifier evaluation
-that allocates the last piece of available RAM.
+that needs the RAM a lingering BMesh still holds.
 
 ## Related
 
 
@@ -199,7 +199,7 @@ def unregister():
 
 ## Compatibility paths
 
-For libraries you want to be installable on both 4.5 LTS and 5.2 LTS, also keep `bl_info` for 4.5 fallback even though new submissions to the extensions platform require the manifest. Blender prefers the manifest when both are present.
+`blender_manifest.toml` alone covers 4.2 and later, including 4.5 LTS and 5.2 LTS: with `blender_version_min = "4.5.0"`, a `bl_info` dict adds nothing. Keep `bl_info` alongside the manifest only if the add-on must also install on 4.1 or earlier, or through the legacy add-on folder / "Install legacy Add-on" path. Blender prefers the manifest when both are present.
 
 ```python
 bl_info = {
 
@@ -141,7 +141,7 @@ Origin at the lowest Z of the mesh (sit-on-ground) via `foreach_get` / `foreach_
 
 ### 6. Measure evaluated triangle count
 
-`obj.data` is the authored mesh. A DECIMATE modifier does not change `obj.data`. Count triangles on the evaluated mesh, and call `calc_loop_triangles()` first. Tessellation is not implicit on 4.5 or 5.x.
+`obj.data` is the authored mesh. A DECIMATE modifier does not change `obj.data`. Count triangles on the evaluated mesh. On 4.5 and 5.x `Mesh.loop_triangles` is computed lazily from the current topology, so `calc_loop_triangles()` is optional (harmless; it matters only on much older builds).
 
 ```python
 def evaluated_triangle_count(obj):
@@ -176,7 +176,7 @@ Draco, selected-only, explicit `export_yup`, and `export_apply=True` so the deci
 ## Common AI mistakes
 
 1. **Decimate ratio against `len(obj.data.polygons)`**. That ignores modifiers already on the stack and counts n-gons as one. Use evaluated `loop_triangles`.
-2. **Skipping `calc_loop_triangles()`**. `loop_triangles` can be empty or stale. Required on 4.5 LTS and 5.x.
+2. **Counting triangles on `obj.data`** instead of the evaluated mesh. A DECIMATE modifier does not change `obj.data`, so the count ignores the budget you just applied.
 3. **`export_apply=True` as "apply object transforms".** It applies modifiers excluding armatures. Apply object scale first.
 4. **Hulling the dense render mesh.** Over budget. Hull a coarse cage.
 5. **`bm.normal_update()` for flipped faces.** Use `recalc_face_normals`.
@@ -187,7 +187,7 @@ Draco, selected-only, explicit `export_yup`, and `export_apply=True` so the deci
 
 The cleanup sequence is the same on 4.5 LTS and 5.x:
 
-- `Mesh.calc_loop_triangles()` is still required before `mesh.loop_triangles` on 4.5 LTS, 5.1, and 5.2. Not implicit. Verified: https://docs.blender.org/api/5.1/bpy.types.Mesh.html#bpy.types.Mesh.calc_loop_triangles and https://docs.blender.org/api/4.5/bpy.types.Mesh.html#bpy.types.Mesh.calc_loop_triangles. The 5.1 bmesh module still says tessellation "needs to be called explicitly": https://docs.blender.org/api/5.1/bmesh.html
+- `Mesh.loop_triangles` is lazily computed on 4.5 LTS and 5.x: measured on 4.5.11 and 5.2.1, a fresh cube reads 12 without `calc_loop_triangles()`, as do a `to_mesh()` result and a mesh rewritten by bmesh. The "needs to be called explicitly" note in the bmesh docs is about `BMesh.calc_loop_triangles()`, the bmesh-side tessellation, not `Mesh.loop_triangles`.
 - `Mesh.calc_normals()` is gone since 4.0. `bmesh.ops.recalc_face_normals` on both LTS lines.
 - glTF import has no `global_scale` on either line. FBX does.
 - `DecimateModifier.decimate_type='COLLAPSE'` and `ratio` are stable across 4.5 LTS and 5.x.
 
@@ -228,7 +228,7 @@ This produces a `.zip` in `dist\` that the user installs via Edit > Preferences
 | `extension build` command | Available | Available |
 | Schema version | `1.0.0` | `1.0.0` |
 
-The Extensions Platform shipped in Blender 4.2. Migrations done now will work on 4.2+ and 5.x without further changes. Code targeting 4.0 or earlier still needs the `bl_info`-only path.
+The Extensions Platform shipped in Blender 4.2. Migrations done now will work on 4.2+ and 5.x without further changes. Code targeting 4.1 or earlier still needs the `bl_info` path.
 
 ## See also
 
 
@@ -62,11 +62,10 @@ Three steps:
 
 ## The lifetime rule (critical)
 
-Every `to_mesh()` must be paired with a `to_mesh_clear()`. If you skip the clear:
+Every `to_mesh()` must be paired with a `to_mesh_clear()`. The evaluated object owns **one** temporary mesh: a second `to_mesh()` on the same object returns that same mesh (measured on 4.5.11 and 5.2.1), so a missing clear does not multiply per call. If you skip the clear:
 
-- The temporary mesh leaks for the lifetime of the depsgraph (typically the session)
-- Repeated calls accumulate memory
-- In some 5.x builds the next depsgraph evaluation crashes if too many temp meshes are outstanding
+- That temporary mesh stays allocated until the object is re-evaluated or freed, once per evaluated object you touched (a whole-scene exporter holds a full copy of every mesh)
+- Code that keeps using the mesh after the next depsgraph update reads freed data; clearing at a known point makes the lifetime explicit
 
 ```python
 obj_eval, mesh_eval = get_evaluated_mesh(obj)
@@ -180,7 +179,7 @@ When you build your own exporter on top of `evaluated_depsgraph_get()`, the deps
 ## Common AI mistakes
 
 - **Reading `obj.data.vertices` and calling it "what the user sees"**. It is not. This is the single most common AI exporter bug.
-- **Forgetting `to_mesh_clear`**. The temporary mesh leaks. Cumulative leaks degrade Blender's memory headroom and can crash long-running batch jobs.
+- **Forgetting `to_mesh_clear`**. Each evaluated object keeps its temporary mesh until it is re-evaluated or freed. Across a whole-scene export that is a second copy of every mesh held at once.
 - **Storing `mesh_eval` past the cleanup point**. Once `to_mesh_clear` runs, the mesh datablock is freed. Any references become dangling.
 - **Calling `evaluated_get` without the depsgraph argument**. The signature is `obj.evaluated_get(depsgraph)`; passing nothing raises a `TypeError`.
 - **Treating `obj.data` as identical to `obj_eval.data`**. They are different mesh datablocks. The first is the source; the second is post-evaluation.
 
@@ -33,7 +33,12 @@ Or with arguments after `--`:
 blender --background scene.blend --python my_script.py -- --output out.png --frames 1,5,10
 ```
 
-`--background` (or `-b`) tells Blender not to launch a UI window. `--python` (or `-P`) runs a Python script. The script receives `sys.argv` containing everything after the `--` separator.
+`--background` (or `-b`) tells Blender not to launch a UI window. `--python` (or `-P`) runs a Python script. The script's `sys.argv` is Blender's **full** command line (`blender`, `--background`, `--python`, ...); slice off everything up to and including `--` to get your own arguments, as the parser below does.
+
+Two flags matter for unattended runs:
+
+- `--factory-startup` ignores the user's startup file and preferences (add-ons, themes, auto-run settings), so the job behaves the same on every machine.
+- `--python-exit-code N` makes an uncaught exception in the script exit Blender with code `N`. Without it, a traceback still exits **0**, and CI reports success.
 
 ## What changes without a UI
 
@@ -68,8 +73,8 @@ for obj in list(bpy.data.objects):
 ```
 
 ```python
-# WRONG: requires UI for the file dialog.
-bpy.ops.export_scene.obj(filepath="/tmp/out.obj")  # may also fail because the OBJ exporter is now under wm.obj_export
+# WRONG: export_scene.obj was the legacy Python OBJ add-on, removed in 4.0.
+bpy.ops.export_scene.obj(filepath="/tmp/out.obj")  # AttributeError on 4.x / 5.x
 
 # RIGHT in 5.x: the new exporter operates on bpy.data, not the active object selection.
 bpy.ops.wm.obj_export(filepath="/tmp/out.obj", export_selected_objects=False)
@@ -201,7 +206,7 @@ if __name__ == "__main__":
 
 Notes:
 
-- `bpy.ops.render.render(write_still=True)` is one of the few `bpy.ops` calls that work in `--background`.
+- `bpy.ops.render.render(write_still=True)` works in `--background`, like other operators that do not need a window or editor area.
 - EEVEE's engine identifier is `BLENDER_EEVEE` on Blender 5.0+ and `BLENDER_EEVEE_NEXT` on 4.2-4.5 LTS (the id was reclaimed in 5.0 after legacy EEVEE was removed in 4.2). Detect via `bpy.app.version`.
 
 ## Detecting Blender version in scripts
 
@@ -69,7 +69,7 @@ Use this layer when:
 - You're doing structural edits (split edges, merge verts, dissolve faces).
 - You need iteration order to be stable mid-edit.
 
-The `try`/`finally` with `bm.free()` is **mandatory**. `bmesh.new()` allocates memory in the C side that Python's garbage collector cannot reclaim. Forgetting `bm.free()` leaks BMesh structures and eventually crashes Blender. See the rule `always-free-bmesh`.
+The `try`/`finally` with `bm.free()` is **mandatory**. `bmesh.new()` allocates C-side storage that is released only when the wrapper is collected, and a traceback, global, closure or modal operator can keep it alive for the whole session. `free()` in `finally` releases it on every path and makes any later use of `bm` raise `ReferenceError`. See the rule `always-free-bmesh`.
 
 ### Layer 3: `bpy.ops.mesh.*` operators
 
@@ -127,7 +127,7 @@ obj = bpy.data.objects["Cube"]
 bpy.data.objects.remove(obj, do_unlink=True)
 ```
 
-`do_unlink=True` removes the object from any collections it was linked into before deleting it. Skip it and Blender will refuse to delete an object still referenced.
+`do_unlink=True` removes the object from any collections it was linked into before deleting it. It is already the default (`remove(object, *, do_unlink=True, ...)`); passing it explicitly documents intent. With `do_unlink=False`, Blender refuses to delete an object that is still referenced.
 
 ## `foreach_set` for bulk vertex injection
 
@@ -264,7 +264,7 @@ After mutating selection, call `bm.select_flush_mode()` if you've changed indivi
 
 6. **Skipping `mesh.update()`** after `foreach_set` or vertex coordinate edits. The mesh stays out of date until the next depsgraph cycle.
 
-7. **Wrong dtype in `foreach_set`** (`float64` instead of `float32`). Silently writes garbage on some platforms.
+7. **Mismatched dtype in `foreach_set`** (a `float64` buffer for a float32 attribute). The values are converted correctly (round-trip error about 1e-7, float32 precision, on 4.5.11 and 5.2.1), but slower: 38 ms vs 21 ms for 361k vertices on 5.2.1 (34 vs 24 ms on 4.5.11). Match the attribute's type (`float32` for `co`) for bulk speed.
 
 8. **Trusting glTF as an n-gon witness.** The exporter always triangulates. A cube and a hexagon-from-dissolved-edge both ship 12 tris. Hygiene (`len(poly.vertices) <= 4`) and `Mesh.calc_tangents` (aborts on n-gons) must run on the Blender mesh. Witness: [`examples/ngon-triangulate/`](https://github.com/TMHSDigital/Blender-Developer-Tools/tree/main/examples/ngon-triangulate).
 
 
@@ -87,10 +87,10 @@ class MESH_OT_offset_along_normals(bpy.types.Operator):
 
 ### `bl_options` you almost always want
 
-- `'REGISTER'`: makes the operator show up in the redo panel and undo history. Without this, the operator is invisible to the user after running and properties cannot be tweaked.
+- `'REGISTER'`: reports the operator in the Info editor and enables the Adjust Last Operation (redo) panel. Without it, properties cannot be tweaked after running. It does not add an undo step; that is `'UNDO'`.
 - `'UNDO'`: hooks into the undo stack. Without this, your operator's effect cannot be undone with Ctrl-Z.
-- `'INTERNAL'`: hides the operator from search and help. Use for operators called only by other operators or panels.
-- `'BLOCKING'`: pauses other UI updates while running. Reserve for modal operators that need exclusive input.
+- `'INTERNAL'`: hides the operator from operator search. Use for operators called only by other operators or panels. It still runs from Python and buttons.
+- `'BLOCKING'`: blocks anything else from using the cursor while the operator runs. Reserve for modal operators that need exclusive mouse input.
 - `'GRAB_CURSOR'` and `'GRAB_CURSOR_X'` / `'GRAB_CURSOR_Y'`: useful in modal operators to capture mouse motion.
 
 ## Defensive context handling