From b9952e7c54d9a3c8c1d9453b9645832141bd06b5 Mon Sep 17 00:00:00 2001 From: fOuttaMyPaint Date: Sun, 19 Jul 2026 14:16:58 -0400 Subject: [PATCH] docs: add live MCP vs headless harness guidance Documents the two execution paths for Blender work: the official Blender Lab MCP server (machine-local, optional, exploration only) versus the headless harness, which remains the only source of truth for witnesses, checks, and CI evidence. Adds a one-line pointer in AGENTS.md canonical references. Signed-off-by: fOuttaMyPaint --- AGENTS.md | 1 + CLAUDE.md | 9 +++++++++ 2 files changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8c53974..6a952d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -179,6 +179,7 @@ way, and a one-paragraph rationale. 30 to 80 lines is the right size. - Blender 4.5 LTS Python API: https://docs.blender.org/api/4.5/ - Extensions Platform reference: https://docs.blender.org/manual/en/latest/advanced/extensions/index.html - Release notes (`developer.blender.org`): https://developer.blender.org/ +- Live MCP session vs headless harness policy: `CLAUDE.md` § "Live MCP vs Headless Harness" — headless is the only source of truth for evidence. When information conflicts, prefer the docs over Stack Overflow or older add-on source. The 2.x to 4.x to 5.x churn around Actions, Extensions, and diff --git a/CLAUDE.md b/CLAUDE.md index 38c1921..5ab6829 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -102,6 +102,15 @@ Renders must conform to the gallery look spec at `docs/VISUAL-STYLE.md`. - 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. +## Live MCP vs Headless Harness + +Two execution paths exist for Blender work. The headless harness (`.scratch/` or system binaries, check-only scripts, CI smoke) is the **only source of truth for correctness** — every witness, check, and CI gate runs headless. The official Blender Lab MCP server ([lab/blender_mcp](https://projects.blender.org/lab/blender_mcp)), when registered on the local machine, provides a live interactive session for exploration. + +- **Use the live MCP for:** interactively inspecting a scene while designing a render, querying data relations, diagnosing why staged geometry or lighting looks wrong, and prototyping API calls before committing them to a script. +- **Never use the live MCP for:** anything a check depends on, anything reported as verification evidence, or anything CI must reproduce. A behavior observed in the live session must be re-proven in the headless script before it counts. Examples must never import from, depend on, or assume the MCP server. +- **Safety:** the server executes generated code in the running Blender instance without guards. Only attach it to scratch scenes, never to files you cannot afford to mutate. +- **Availability is machine-local and optional:** if the server is not registered, proceed headless without comment. + ## 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.