docs: codify operational lessons from recent runs into agent guidance (#71)

Fifteen shipped PRs accumulated hard-won operational rules in prompt text
and PR bodies where new agents never see them. Move the durable ones into
AGENTS.md (governance: squash-merge standard, smoke-jobs-don't-rerun-on-
merge-SHA evidence rule, post-merge job set, Socket pending policy, DCO)
and CLAUDE.md (runtime: .scratch/ binary discovery, 4.4-is-not-4.5,
explicit-path staging vs the Cursor CLAUDE.md injection, contact-sheet and
falsification gates, generated-HTML review precedent), state the division
of labor at the top of each, and update docs/new-example-prompt.md so the
canonical prompt agrees with the guidance files.

Signed-off-by: fOuttaMyPaint <TMhospitalitystrategies@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: TMHSDigital

AGENTS.md

@@ -4,35 +4,28 @@
 
 Guidance for AI coding agents working on the Blender Developer Tools repository.
 
+**Division of labor:** this file carries fleet-standard governance and workflow
+rules — branching, commits, merge and CI-evidence policy, release automation,
+authoring standards. `CLAUDE.md` carries repo-specific operational facts an
+agent needs at runtime — content inventory, Blender runtime discovery, git
+staging hazards, and the example-shipping quality gates. Read both; neither
+repeats the other.
+
 ## Repository overview
 
 Skills, rules, snippets, starter templates, and runnable smoke-gated examples
-for Blender Python development.
-The repo targets **Blender 5.1** (current stable) with a **Blender 4.5 LTS**
-fallback. There is no MCP server. It ships 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 (counts are CI-enforced against README.md and the manifest):
-
-- 12 skills covering scaffolding, operators, panels, properties, mesh and
-  bmesh, headless batch scripts, slotted-actions animation (5.x), programmatic
-  geometry nodes, procedural materials and shaders, depsgraph and evaluated
-  data, drivers and application handlers, and `bl_info` to Extensions
-  Platform migration.
-- 6 rules encoding the most common AI anti-patterns when writing Blender
-  Python (ops-in-loops, bmesh leaks, legacy `bl_info`-only, prop assignment,
-  deprecated context-copy override, per-element loops over bulk mesh data).
-- 2 templates: `extension-addon-template` for Extensions Platform add-ons,
-  and `headless-batch-script-template` for unattended batch jobs.
-- 17 snippets covering canonical patterns.
-- 22 examples under `examples/<name>/`: runnable scripts that assert a real
-  API contract with deterministic checks, exit non-zero on failure, and
-  optionally render a still via `--output`. Each is executed headless on
-  Blender 4.5 LTS and 5.1 by `blender-smoke.yml`; its render ships in the
-  site gallery. Anatomy and authoring rules: copy `examples/bmesh-gear/`;
-  the render look is specified in `docs/VISUAL-STYLE.md`.
+for Blender Python development. The repo targets **Blender 5.1** (current
+stable) with a **Blender 4.5 LTS** fallback. There is no MCP server. It ships
+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 12 skills, 6 rules, 2 templates, 17 snippets, and 22
+examples (counts are CI-enforced against README.md and the manifest). The full
+inventory tables and per-item purposes live in `CLAUDE.md`. Example anatomy
+and authoring rules: copy `examples/bmesh-gear/`; the render look is specified
+in `docs/VISUAL-STYLE.md`; the canonical run prompt is
+`docs/new-example-prompt.md`.
 
 ## Repository structure
 
@@ -46,7 +39,8 @@ Blender-Developer-Tools/
   scripts/build_gallery.py       # generates docs/gallery/ (stdlib only)
   scripts/site/                  # vendored landing-page build (build_site.py + template)
   docs/gallery/                  # committed generated gallery pages + hero assets
-  .github/workflows/             # validate, blender-smoke, drift-check, release, pages, label-sync
+  docs/new-example-prompt.md     # canonical example-creation prompt
+  .github/workflows/             # validate, blender-smoke, drift-check, release, pages, label-sync, stale
   .github/dependabot.yml
   AGENTS.md, CLAUDE.md, README.md, ROADMAP.md, CHANGELOG.md
   CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md
@@ -56,7 +50,8 @@ Blender-Developer-Tools/
 
 ## Branching and commit model
 
-- Single `main` branch. No develop or release branches.
+- Single `main` branch. No develop or release branches. Work on a focused
+  feature branch off an up-to-date `main`. Never force-push or bypass hooks.
 - Conventional commits drive the auto-release workflow. It scans the commit subjects since
   the last tag and releases only when at least one is release-worthy:
   - `feat:` triggers a minor bump
@@ -67,7 +62,37 @@ Blender-Developer-Tools/
     bump. A mixed push still releases if any commit in range is a `feat:`/`fix:`.
   - `[skip ci]` in the head commit still bypasses the workflow entirely. With the commit-type
     gate above it is now an optional override, not a requirement for non-release commits.
-- Commit messages should describe the why, not the what.
+- Commit messages should describe the why, not the what, and carry a DCO
+  `Signed-off-by:` trailer matching the commit author (see CONTRIBUTING.md).
+- Stage with explicit paths only — never `git add -A` or `git add .`. The
+  reason is a repo-specific hazard documented in `CLAUDE.md` § Git staging.
+
+## Merge policy and CI evidence
+
+- **Squash-merge with branch deletion is the standard.** The PR becomes one
+  commit on `main`; delete the remote feature branch after merge, then
+  fast-forward local `main`.
+- **Smoke jobs do not re-run on the merge SHA.** `blender-smoke.yml` triggers
+  on `pull_request` (plus a weekly schedule and manual dispatch) — there is no
+  `push` trigger. The correct post-merge evidence for example changes is:
+  both Blender smoke jobs (4.5 LTS and 5.1) passed on the PR head SHA that
+  became the sole squash-merged commit, with the actual binary versions
+  confirmed in the job logs.
+- **Post-merge, verify green on `main`:** Release (`release.yml`), Validate
+  (`validate.yml`), Ecosystem drift check (`drift-check.yml`), and Deploy
+  GitHub Pages (`pages.yml`; paths-filtered, so it does not trigger for every
+  change).
+- **Socket Security checks** ("Socket Security: Project Report" and "Socket
+  Security: Pull Request Alerts") run on PRs via the Socket GitHub App. No
+  override policy has been decided: a pending or failing Socket check is
+  unresolved — wait before merging.
+- **Release-owned fields are never hand-edited:** `VERSION`, `CHANGELOG.md`,
+  the CLAUDE.md `**Version:**` line, the ROADMAP.md `**Current:**` line, and
+  the manifest `"version"` in `.cursor-plugin/plugin.json`. Generated gallery
+  pages under `docs/gallery/` are regenerated via `scripts/build_gallery.py`,
+  never hand-edited.
+- **Evidence over assertion:** PR bodies must label what was proven by live
+  run versus established by inspection only.
 
 ## Blender version targeting
 
@@ -80,7 +105,8 @@ Blender-Developer-Tools/
 
 When a 4.x and 5.x API genuinely diverge, skills must show both code paths,
 not just the 5.x one. The `slotted-actions-animation` skill is the load-bearing
-example.
+example. Local binary discovery and version-reporting rules are in
+`CLAUDE.md` § Blender runtime discovery.
 
 ## Skills
 

CLAUDE.md

@@ -4,6 +4,8 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+**Division of labor:** this file carries repo-specific operational facts an agent needs at runtime — content inventory, Blender runtime discovery, git staging hazards, and the example-shipping quality gates. `AGENTS.md` carries fleet-standard governance and workflow rules — branching, commits, merge and CI-evidence policy, release automation, authoring standards. Read both; neither repeats the other.
+
 ## Project Overview
 
 The **Blender Developer Tools** repository is at **v0.19.1**. It packages skills, rules, snippets, starter templates, and runnable smoke-gated examples for Blender Python development with Cursor and Claude Code. Coverage targets **Blender 5.1** (current stable) with **Blender 4.5 LTS** fallback. There is no MCP server; content is consumed directly by the AI when working in Blender add-on or scripting projects.
@@ -93,6 +95,30 @@ a `blender-smoke.yml` step, a README gallery row, hero webp (1280×720) in
 `docs/gallery/assets/` + preview webp (1200×675), then run `python scripts/build_gallery.py`.
 Renders must conform to the gallery look spec at `docs/VISUAL-STYLE.md`.
 
+## Blender Runtime Discovery
+
+- Local Blender binaries: check `.scratch/` at the repo root **first** — some machines have no system Blender install, and a prior agent run downloads official releases there (e.g. `.scratch/5.1/blender-5.1.x-.../blender[.exe]`). Then check system installs. Do not probe blindly; locate the binary, run it, and state the **exact binary path and the version the binary itself reports** in every report.
+- **5.1 is the local check version. 4.5 LTS is exercised by CI when unavailable locally.** 4.4 is not a substitute for 4.5 and must never be reported as 4.5.
+- If `.scratch/` lacks a needed version, download an official release from download.blender.org into it. `.scratch` is gitignored.
+- In scripts, version-branch on the `bpy.app.version` tuple, never on `bpy.app.version_string` — it reads e.g. `"4.5.11 LTS"`, not bare semver.
+
+## Git Staging
+
+Stage with **explicit paths only** — never `git add -A` or `git add .`. Cursor agent sessions inject a local guidance block into the working-copy `CLAUDE.md`; a bulk add sweeps it into the commit. It manifests as a `CLAUDE.md` hunk in `git diff` that you did not author (the file can be dirty before you touch anything). Leave it unstaged, and never stage `CLAUDE.md` unless you deliberately edited it.
+
+## Quality Gates for Example Runs
+
+- `docs/VISUAL-STYLE.md` is the **binding** render standard; deviations are defects.
+- **Contact-sheet gate:** composite the candidate hero beside the pinned calibration set — currently `armature-bend`, `damped-track-aim`, `bmesh-gear` — commit the composite under `docs/gallery/contact-sheets/`, link it in the PR body, and report per-criterion verdicts (stage darkness, wedge warmth, subject fill, saturation, thumbnail legibility) including mean luminance versus the calibration images. A claim without the committed composite is not acceptable evidence. The pinned set is updated (here and in `docs/new-example-prompt.md`) when a new example outclasses a member; the longer "calibration references" list in `docs/VISUAL-STYLE.md` is a style reference, not this contact-sheet set.
+- **Falsification:** every check must be proven to fail once — break the contract, observe the non-zero exit, restore — with the probe and the measured error reported in the PR body. An assertion that cannot fail witnesses nothing.
+- **After gallery regeneration** (`python scripts/build_gallery.py`), read the **generated HTML** character by character — the `<img alt>` text and witnesses callouts in `docs/gallery/index.html` and `docs/gallery/<name>/index.html` — not just `examples/gallery.json`. Precedent: the `teaches.split(".")[0]` bug truncated 14/21 card alts at dotted API paths like `bmesh.ops` while the source JSON looked fine (fixed in PR #68).
+
+## Example-Run Process
+
+- The canonical example-creation prompt lives at `docs/new-example-prompt.md`; keep it in agreement with this file and `AGENTS.md`.
+- The `ROADMAP.md` "Candidate pool" section is the subject source for example runs: remove a subject when it ships, and restock with subjects identified but not built.
+- PR bodies label what was proven by live run versus established by inspection only (see `AGENTS.md` § Merge policy and CI evidence for the merge and post-merge verification rules).
+
 ## Development Workflow
 
 This is a content repository, no build step for skills/rules/snippets/templates — edit

docs/new-example-prompt.md

@@ -74,8 +74,13 @@ candidate pool in sync: remove the shipped subject, and add any promising subjec
 you identified but did not build. Do not hand-edit release-owned version fields or
 generated pages; use the repository's generator.
 
-Run the new example's check-only path on both supported Blender versions, render and
-visually inspect its final image, regenerate the gallery, and run all relevant repository
+Run the new example's check-only path on both supported Blender versions. Locate local
+Blender binaries by checking `.scratch/` at the repo root first — prior runs download
+official releases there and some machines have no system install; download an official
+release into it if a needed version is missing (it is gitignored) — then system installs.
+Do not probe blindly; state the exact binary path and the version the binary itself
+reports for every run. Render and visually inspect the final image, regenerate the
+gallery, and run all relevant repository
 validation. If Blender 4.5 is unavailable locally, say so precisely and use the repository's
 4.5 CI job—do not substitute another version and report it as 4.5. If the render path
 requires an engine or device unavailable locally (Cycles on a GPU-less host), say so and
@@ -96,10 +101,12 @@ Contact-sheet gate (required before shipping the still): place the new hero besi
 the pinned calibration set — currently `armature-bend`, `damped-track-aim`,
 `bmesh-gear` — and compare stage darkness, wedge warmth, subject fill, saturation,
 and thumbnail legibility side by side. Do not ship until the new image holds up in
-that lineup—not merely "looks fine alone." Update this named set in this prompt
-whenever a new example outclasses one of them. One successful render command is not
-proof that the image is good, and neither is the second. Report that the
-contact-sheet comparison was done against those three references.
+that lineup—not merely "looks fine alone." Update this named set (here and in
+`CLAUDE.md`) whenever a new example outclasses one of them. One successful render
+command is not proof that the image is good, and neither is the second. Commit the
+composite under `docs/gallery/contact-sheets/`, link it in the PR body, and report
+per-criterion verdicts including mean luminance versus the calibration images — a
+claim without the committed composite is not acceptable evidence.
 
 After implementation and local verification:
 
@@ -111,16 +118,19 @@ After implementation and local verification:
    it once), visual notes, and an exact test plan. Label explicitly what was proven by
    live run versus established by inspection only.
 4. Watch every attached PR check, including validation, manifest/count checks, ecosystem
-   drift, security checks, and Blender 4.5/5.1 smoke jobs. Investigate and fix failures
-   within this change's scope, push fixes, and repeat until all checks pass.
+   drift, Socket Security checks, and Blender 4.5/5.1 smoke jobs. Investigate and fix
+   failures within this change's scope, push fixes, and repeat until all checks pass. A
+   pending or failing Socket check is unresolved — wait before merging.
 5. Review PR comments and requested changes. Apply valid feedback and re-run affected
    checks. Do not merge with unresolved failures or requested changes.
-6. Once the PR is mergeable and green, merge it using the repository's normal merge
-   strategy and delete the remote feature branch.
+6. Once the PR is mergeable and green, squash-merge it and delete the remote feature
+   branch.
 7. Wait for any automated release/version-sync commit triggered by the merge, then
    fast-forward local `main` to `origin/main`, and verify main HEAD is green including
-   all post-merge jobs (release, validate, drift, pages deploy). Do not hand-edit
-   release-owned version fields.
+   all post-merge jobs (Release, Validate, Ecosystem drift check, Deploy GitHub Pages).
+   The smoke jobs are pull_request-triggered and do not re-run on the merge SHA: the
+   post-merge evidence is that both smoke jobs passed on the PR head SHA that became
+   the sole squash-merged commit. Do not hand-edit release-owned version fields.
 8. Confirm the final working tree is clean and report the PR URL, merge commit, resulting
    version (if released), measured check values, and checks completed.