docs: codify operational lessons from recent runs into agent guidance

[TMHSDigital]

Summary

Audit and upgrade of AGENTS.md and CLAUDE.md so any agent on any machine can run the standard example-creation and quality prompts without rediscovering environment facts or repeating documented mistakes. Every claim below was verified against the repository (workflow triggers, .gitignore, script behavior, PR bodies #57–#70) before being written down.

Division of labor (now stated at the top of both files): AGENTS.md 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, example-shipping quality gates).

Inventory

Already documented (left in place, location noted)

• Falsification requirement, gallery-HTML character-level review with the teaches.split(".")[0] precedent, "4.4 is not 4.5", contact-sheet gate with pinned set — all in docs/new-example-prompt.md (now also in CLAUDE.md so guidance-file readers get them).
• Release-owned fields (VERSION, CHANGELOG, **Version:**, **Current:**, manifest "version"), workflow descriptions, version targeting, conventional-commit release gating — AGENTS.md/CLAUDE.md, verified accurate.
• .scratch is already gitignored (.gitignore:26) — no change needed.

Newly added

• Blender runtime discovery (CLAUDE.md): check .scratch/ at repo root first, then system installs; never probe blindly; state exact binary path + binary-reported version in every report; may download official releases into .scratch/; branch on the bpy.app.version tuple, not version_string ("4.5.11 LTS" — recurring lesson in PRs feat: add grease-pencil-rosette example (GPv3 attribute API drift witness) #57, feat: add png-exr-alpha float PNG false-unpremul witness #69).
• Git staging (CLAUDE.md): explicit paths only, never git add -A — Cursor agent sessions inject a local block into the working-copy CLAUDE.md that a bulk add sweeps into commits; it manifests as an unauthored CLAUDE.md hunk in git diff. (No committed instance found in history — the rule has held; described as it manifests in the working tree.)
• Merge policy and CI evidence (AGENTS.md): squash-merge + branch deletion standard; blender-smoke.yml is pull_request-triggered (verified: no push trigger) so post-merge evidence = both smoke jobs green on the PR head SHA that became the sole squash commit, binary versions confirmed in job logs; post-merge job set verified from workflow triggers: Release, Validate, Ecosystem drift check, Deploy GitHub Pages (paths-filtered); DCO sign-off per CONTRIBUTING.md.
• Socket policy (AGENTS.md + prompt): checks are "Socket Security: Project Report" / "Pull Request Alerts" (GitHub App; verified on PR feat: add png-exr-alpha float PNG false-unpremul witness #69's check rollup). No override policy is decided, so the documented default is: pending/failing = unresolved — wait before merging.
• Contact-sheet gate hardened (CLAUDE.md + prompt): composite committed under docs/gallery/contact-sheets/ and linked in the PR body is required evidence; per-criterion verdicts including mean luminance vs the calibration images (per PR feat: add png-exr-alpha float PNG false-unpremul witness #69's format); pinned set armature-bend, damped-track-aim, bmesh-gear, updated when outclassed. Disambiguated from docs/VISUAL-STYLE.md's longer six-member "calibration references" list, which is a style reference, not the contact-sheet set.
• Process (CLAUDE.md): ROADMAP candidate pool drain-on-ship/restock; canonical prompt location docs/new-example-prompt.md; evidence-over-assertion labeling in PR bodies.

Corrected

• docs/new-example-prompt.md updated to agree with the guidance files: .scratch/ discovery + exact-path/version reporting; committed composite + mean luminance in the contact-sheet gate; "normal merge strategy" → explicit squash-merge + branch deletion; Socket pending rule; post-merge job names + smoke-evidence rule.
• AGENTS.md workflows listing now includes stale.yml (was missing).

Removed

• AGENTS.md content-base enumeration (per-skill/rule/template/snippet detail) reduced to counts + pointer to CLAUDE.md's tables — it duplicated CLAUDE.md verbatim in prose form, violating the no-duplication rule.

Test plan

• Established by inspection: no workflow greps AGENTS.md/CLAUDE.md content; the standards-version: 1.10.0 markers and the release-owned **Version:** line are preserved byte-identical, so drift-check and release-doc-sync are unaffected.
• Live: watch Validate, Ecosystem drift check, Socket, and smoke jobs on this PR.
• docs: subject → no release is cut on merge (verified against the release-worthiness gate in release.yml).

🤖 Generated with Claude Code