docs: document the 5.1 smoke lever for contributors

Place the how-to in CONTRIBUTING.md, where version targeting already lives,
and point at it from the workflow header, README, AGENTS.md, and the PR template.

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: TMHSDigital

.github/PULL_REQUEST_TEMPLATE.md

@@ -17,7 +17,7 @@ Label every claim.
 - **live-run-proven:** exact binary path + the version that binary printed (`blender --version`). Headless harness only. Live MCP does not count.
 - **inspection-only:** read the skill / diff / RNA docs; no process ran.
 
-`blender-smoke.yml` has no `push` trigger. Post-merge smoke evidence is the PR-head 5.2 + 4.5 jobs (state the versions from those logs).
+`blender-smoke.yml` has no `push` trigger. Post-merge smoke evidence is the PR-head 5.2 + 4.5 jobs (state the versions from those logs). Apply `needs-5.1` when 5.1 must be CI-proven on the PR; default matrix does not include it.
 
 ## Release-owned fields — do not hand-edit
 

AGENTS.md

@@ -157,7 +157,10 @@ way, and a one-paragraph rationale. 30 to 80 lines is the right size.
   the manifest `version` line (see `release.yml` below) — never hand-edit it.
 - `blender-smoke.yml` executes every shipped example (check-only, no render)
   plus snippet/template smoke tests inside REAL headless Blender, on
-  5.2 LTS and 4.5 LTS for every PR (5.1 on the weekly cron). Examples run
+  5.2 LTS and 4.5 LTS for every PR. 5.1 is weekly cron, the opt-in
+  `needs-5.1` PR label (`pull_request` types include `labeled`), or
+  `workflow_dispatch` with a `series` input. Auto-label does not apply
+  `needs-5.1`. Contributor-facing notes live in CONTRIBUTING.md. Examples run
   through `tests/smoke/run_example.py` (catalog: `tests/smoke/catalog.json`).
   SKIP is exit 77 plus a `SMOKE_SKIP:` reason, and only when `--min-version`
   is above this Blender; exit 0 with that marker is a vacuous pass and fails.

CLAUDE.md

@@ -102,7 +102,7 @@ AI asset pipeline track: `decimate_to_budget.py`, `convex_hull_collider.py`, `lo
 
 Runnable scripts at `examples/<name>/`, each asserting a real API contract with
 deterministic checks (exit non-zero on failure) and optionally rendering a still via
-`--output`. All of them run headless on Blender 5.2 LTS and 4.5 LTS in `blender-smoke.yml` (5.1 on the weekly cron);
+`--output`. All of them run headless on Blender 5.2 LTS and 4.5 LTS in `blender-smoke.yml` (5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch);
 their renders ship in the site gallery at `docs/gallery/`. `examples/gallery.json` is the
 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

CONTRIBUTING.md

@@ -99,6 +99,19 @@ else:
     ...
 ```
 
+## Blender smoke on pull requests
+
+Default PR smoke is Blender 5.2 and 4.5 (`.github/workflows/blender-smoke.yml`).
+5.1 is not in that matrix.
+
+- Apply the `needs-5.1` label when the change can diverge on 5.1 (bake, UV
+  RNA, version-branched API). That starts a 5.1 smoke job. Auto-label will
+  not apply this; it is opt-in.
+- Run any series on demand: Actions > Blender Smoke Test > Run workflow,
+  pick the branch and the `series` input.
+- Monday 07:00 UTC cron still runs 5.2, 5.1, and 4.5. Do not treat cron as
+  PR evidence.
+
 ## Standards-version Markers
 
 Files that participate in ecosystem drift checking must carry a `standards-version` marker matching the current meta-repo `STANDARDS_VERSION` (which is decoupled from this repo's `VERSION`):

README.md

@@ -66,13 +66,13 @@ blender --background --python examples/bmesh-gear/bmesh_gear.py --
 | Version | Status |
 | --- | --- |
 | Blender 5.2 LTS | Primary target (current stable; all examples assume 5.2 unless a 4.5 path is shown) |
-| Blender 5.1 | Prior stable (weekly smoke only) |
+| Blender 5.1 | Prior stable (weekly cron; PR via `needs-5.1` or manual dispatch) |
 | Blender 4.5 LTS | Fallback supported (skills show both code paths where 4.x and 5.x APIs diverge) |
 
 ## Examples
 
 Runnable, smoke-gated demos live in [`examples/`](examples/) — each is executed headless on
-Blender 5.2 LTS and 4.5 LTS by the `blender-smoke` workflow (5.1 on the weekly cron), so the screenshots reflect code
+Blender 5.2 LTS and 4.5 LTS by the `blender-smoke` workflow (5.1 on the weekly cron, the `needs-5.1` PR label, or manual dispatch), so the screenshots reflect code
 that actually runs. Browse them all with filters and full-size renders in the
 **[examples gallery](https://tmhsdigital.github.io/Blender-Developer-Tools/gallery/)**,
 or expand a category below.