fnf-blender-mcp 0.2.0 → 0.2.1

package/README.md

@@ -10,12 +10,12 @@ Each MCP connection owns one process. Its scene persists between commands; it ca
 
 ## Setup
 
-Requires Node.js 24+ with npm and Blender 4.2+. Version 0.2.0 introduces the background runtime; version 0.1.0 uses the previous add-on. Verify that 0.2.0 is published before installing it; this source change alone does not publish a release.
+Requires Node.js 24+ with npm and Blender 4.2+. Version 0.2.0 introduces the background runtime; version 0.1.0 uses the previous add-on. Install the latest published version (0.2.0 or newer); rerun the install command to update an existing installation.
 
 ```sh
-npm view fnf-blender-mcp@0.2.0 version --registry=https://registry.npmjs.org/
+npm view fnf-blender-mcp@latest version --registry=https://registry.npmjs.org/
 blenderDir="$HOME/.higgsfield/blender-mcp"
-npm install --prefix "$blenderDir" --registry=https://registry.npmjs.org/ fnf-blender-mcp@0.2.0
+npm install --prefix "$blenderDir" --registry=https://registry.npmjs.org/ fnf-blender-mcp@latest
 blenderCli="$blenderDir/node_modules/fnf-blender-mcp/dist/cli.js"
 node "$blenderCli" doctor --blender "/absolute/path/to/blender"
 node "$blenderCli" config --blender "/absolute/path/to/blender" --format json
@@ -36,10 +36,12 @@ The server starts Blender on its first execution call. `doctor` checks a separat
 | Files | `bl_save_project`, `bl_open_project` |
 | Evidence | `bl_render` |
 | Python/status | `bl_execute`, `bl_job_status` |
-| Offline guidance | `bl_get_skill` |
+| Offline guidance | `bl_list_skills`, `bl_get_skill`, `bl_get_skill_asset` |
 
 Start with `bl_get_skill(name: "blender-scene")`. Python runs sequentially on the process's main thread. Scene datablocks persist, while script-local variables do not. Assign a JSON-compatible `result` to return data. Python stdout/stderr are capped at 64 Ki characters each; JSON results are limited to 4 MiB. Native Blender diagnostics do not enter the MCP stdout protocol.
 
+The npm archive contains the Blender craft modules. `bl_list_skills` lists the modules in the installed package and their references/assets; `bl_get_skill` reads an entry or reference, and `bl_get_skill_asset` returns the local path of a bundled file. The original five `bl_get_skill` names remain valid. An MCP client can read this guidance directly without installing the modules as client-side skills; client-side installation is optional for hosts that support automatic skill activation. Existing installations do not gain new modules or tools until the npm package is updated and the MCP connection refreshed. Skill guidance does not execute Blender operations or prove a live connection.
+
 Render a camera frame to PNG; files up to 4 MiB receive an inline preview. Cycles supports sample overrides. Save/render require `overwrite: true` for existing output files; opening a different project refuses unsaved changes unless explicitly discarded. Arbitrary Python is not sandboxed and can bypass these typed-tool guards. Automatic execution of Python embedded in opened `.blend` files is disabled.
 
 ## Session lifecycle
@@ -61,8 +63,10 @@ npm run test:package
 BLENDER_EXECUTABLE=/absolute/path/to/blender npm run test:live
 ```
 
-Offline tests exercise actual MCP and child-process pipes using a Python CLI fixture, persistent session state, isolation, timeout recovery, process death, bounded results/history, output formatting, CLI configuration and typed-script guards. They do not replace live Blender validation. `test:package` installs the archive independently and verifies 19 tools, offline guidance and the absence of add-on files. `test:live` uses real Blender for geometry, materials, keyframes, file guards and a small Cycles render in disposable files.
+Offline tests exercise actual MCP and child-process pipes using a Python CLI fixture, persistent session state, isolation, timeout recovery, process death, bounded results/history, output formatting, CLI configuration and typed-script guards. They do not replace live Blender validation. `test:package` installs the archive independently and verifies 21 tools, offline guidance, asset lookup and the absence of runtime add-on files. `test:live` uses real Blender for geometry, materials, keyframes, file guards and a small Cycles render in disposable files.
 
 Verified on macOS arm64 with Blender 4.2.23 LTS: persistent scene, mesh/material/camera/light edits, keyframes, save/reopen guards and a Cycles PNG preview. Windows/Linux native Blender execution has not been verified locally.
 
 See [RELEASING.md](RELEASING.md) for release steps. The setup skill is mirrored in fnf-mcp-server's `/use-blender` command; keep its body and references synchronized. See [UPSTREAM.md](UPSTREAM.md) for provenance and [LICENSE](LICENSE) for the MIT license.
+
+Background Blender does not reliably mark direct Python edits as dirty. The MCP also tracks attempted mutations, including failed commands and arbitrary `bl_execute` calls, conservatively as unsaved until `bl_save_project` or an explicitly permitted `bl_open_project` succeeds. Read tools preserve this state.

package/RELEASING.md

@@ -3,9 +3,9 @@
 Run commands from this `blender/` directory. Its package and lockfile are independent of After Effects.
 
 1. Run `npm ci`, `npm test`, `npm run typecheck`, `npm run test:package`, and `test:live` with a real `BLENDER_EXECUTABLE` when available.
-2. Version 0.2.0 is prepared for the transition to a background process. Verify that it is unpublished with `npm view fnf-blender-mcp versions --json`. Never overwrite an existing npm version; bump both manifests for subsequent releases.
-3. Keep the version in README.md and skills/use-blender aligned with the fnf-mcp-server command bundle. Review migration instructions for removed commands and tools.
-4. Run `npm pack --json`, review the contents, then publish the reviewed archive with `npm publish ./fnf-blender-mcp-0.2.0.tgz --access public --registry=https://registry.npmjs.org/` when publication is authorized.
+2. Version 0.2.1 bundles the Blender craft skills, including the additions from PR #25. Verify that it is unpublished with `npm view fnf-blender-mcp versions --json`. Never overwrite an existing npm version; bump both manifests for subsequent releases.
+3. Keep README.md, skills/use-blender and the fnf-mcp-server command bundle on `fnf-blender-mcp@latest`; preserve historical migration versions. Review migration instructions for removed commands and tools.
+4. Merge the source changes and version metadata into `main`, check out its exact commit in a clean worktree, rerun the checks, then run `npm pack --json`, review the contents, then publish the reviewed archive with `npm publish ./fnf-blender-mcp-0.2.1.tgz --access public --registry=https://registry.npmjs.org/` when publication is authorized.
 5. Verify the public version and checksum and test a fresh registry installation. Publish the package before deploying the fnf-mcp-server instructions that require it.
 
 Merging the source MR does not publish npm. Version 0.1.0 still requires the old add-on; it is not a fallback for 0.2.0 setup. New clients need a refreshed configuration containing BLENDER_EXECUTABLE. Existing desktop files and add-ons are not removed by this release.

package/dist/server.js

@@ -3,7 +3,7 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { BL_TOOLS } from "./tools.js";
 import { BlenderTransport } from "./transport.js";
-import { getSkill, SKILL_NAMES } from "./skills.js";
+import { getSkill, getSkillAsset, listSkills } from "./skills.js";
 const packageInfo = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
 const errorResult = (error) => ({ isError: true, content: [{ type: "text", text: String(error) }] });
 export async function formatResult(job) {
@@ -32,7 +32,7 @@ export async function formatResult(job) {
 }
 export function createServer(transport = new BlenderTransport()) {
     const server = new McpServer({ name: "higgsfield-use-blender", title: "Higgsfield use Blender", version: packageInfo.version }, {
-        instructions: "Control a dedicated background Blender process; it cannot access an open desktop window. Save .blend files before disconnecting; unsaved state is lost on reconnect. Read bl_get_skill(blender-scene), then bl_health and bl_get_scene_summary before edits. Prefer typed tools; use bl_execute for other bpy operations. Commands can partially mutate before errors. On timeout, query bl_job_status; never blindly retry. Render and view results. Cloud generation is provided by a separate Higgsfield MCP, not this server.",
+        instructions: "Control a dedicated background Blender process; it cannot access an open desktop window. Save .blend files before disconnecting; unsaved state is lost on reconnect. Read bl_get_skill(blender-scene), then bl_health and bl_get_scene_summary before edits. For specialized work, call bl_list_skills, load the relevant skill with bl_get_skill and only needed references; bl_get_skill_asset locates bundled assets. Prefer typed tools; use bl_execute for other bpy operations. Commands can partially mutate before errors. On timeout, query bl_job_status; never blindly retry. Render and view results. Cloud generation is provided by a separate Higgsfield MCP, not this server.",
     });
     for (const tool of BL_TOOLS) {
         server.registerTool(tool.name, {
@@ -40,7 +40,8 @@ export function createServer(transport = new BlenderTransport()) {
             annotations: { readOnlyHint: tool.readOnly, destructiveHint: !tool.readOnly, idempotentHint: tool.readOnly, openWorldHint: tool.name === "bl_execute" },
         }, async (args) => {
             try {
-                return await formatResult(await transport.execute(tool.code(args), tool.name === "bl_render" ? 300 : 120));
+                const mutates = !tool.readOnly && !["bl_save_project", "bl_open_project"].includes(tool.name);
+                return await formatResult(await transport.execute(tool.code(args), tool.name === "bl_render" ? 300 : 120, mutates));
             }
             catch (error) {
                 return errorResult(error);
@@ -59,10 +60,43 @@ export function createServer(transport = new BlenderTransport()) {
             return errorResult(error);
         }
     });
+    server.registerTool("bl_list_skills", {
+        title: "List Blender Skills", description: "List bundled Blender skill names, descriptions, references and assets. Does not require Blender to be running.",
+        inputSchema: z.object({}).strict(),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            const index = await listSkills();
+            return { content: [{ type: "text", text: JSON.stringify(index) }], structuredContent: index };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
     server.registerTool("bl_get_skill", {
-        title: "Read Blender Skill", description: "Load offline Blender craft guidance. Start with blender-scene, then read the relevant topic. Does not require Blender to be running.",
-        inputSchema: z.object({ name: z.enum(SKILL_NAMES).default("blender-scene") }).strict(),
+        title: "Read Blender Skill", description: "Load a bundled Blender skill or one of its listed references. Start with blender-scene. Legacy topic names remain supported. Does not require Blender to be running.",
+        inputSchema: z.object({ name: z.string().default("blender-scene"), document: z.string().default("SKILL.md") }).strict(),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ name, document }) => {
+        try {
+            return { content: [{ type: "text", text: await getSkill(name, document) }] };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    server.registerTool("bl_get_skill_asset", {
+        title: "Locate Blender Skill Asset", description: "Return the absolute path and size of an asset bundled with a listed Blender skill. The path is local to the MCP host.",
+        inputSchema: z.object({ name: z.string(), path: z.string() }).strict(),
         annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    }, async ({ name }) => ({ content: [{ type: "text", text: await getSkill(name) }] }));
+    }, async ({ name, path }) => {
+        try {
+            const asset = await getSkillAsset(name, path);
+            return { content: [{ type: "text", text: JSON.stringify(asset) }], structuredContent: asset };
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
     return server;
 }

package/dist/skills.d.ts

@@ -1,2 +1,15 @@
-export declare const SKILL_NAMES: readonly ["blender-scene", "modeling", "materials", "lighting-camera", "animation"];
-export declare function getSkill(name: typeof SKILL_NAMES[number]): Promise<string>;
+export declare function listSkills(): Promise<{
+    skills: {
+        name: string;
+        description: string;
+        references: string[];
+        assets: string[];
+    }[];
+}>;
+export declare function getSkill(name: string, document?: string): Promise<string>;
+export declare function getSkillAsset(name: string, path: string): Promise<{
+    name: string;
+    path: string;
+    absolute_path: string;
+    bytes: number;
+}>;

package/dist/skills.js

@@ -1,6 +1,90 @@
-import { readFile } from "node:fs/promises";
-export const SKILL_NAMES = ["blender-scene", "modeling", "materials", "lighting-camera", "animation"];
-export async function getSkill(name) {
-    const relative = name === "blender-scene" ? "SKILL.md" : `references/${name}.md`;
-    return readFile(new URL(`../skills/blender-scene/${relative}`, import.meta.url), "utf8");
+import { readFile, readdir, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const root = fileURLToPath(new URL("../skills/", import.meta.url));
+const legacyReferences = new Set(["modeling", "materials", "lighting-camera", "animation"]);
+const skillName = /^blender-[a-z0-9-]+$/;
+const documentPath = /^references\/[a-zA-Z0-9/_-]+\.md$/;
+const assetPath = /^assets\/[a-zA-Z0-9][a-zA-Z0-9/._-]*$/;
+function validParts(path) {
+    return !path.split("/").some(part => part === "" || part === "." || part === "..");
+}
+async function bundledFile(name, path) {
+    const corpus = await realpath(root);
+    const base = await realpath(resolve(root, name));
+    const skillLocal = relative(corpus, base);
+    if (skillLocal === ".." || skillLocal.startsWith("../") || skillLocal.startsWith("..\\") || isAbsolute(skillLocal)) {
+        throw new Error("Skill path escapes the bundled corpus");
+    }
+    const file = await realpath(resolve(base, path));
+    const local = relative(base, file);
+    if (local === ".." || local.startsWith("../") || local.startsWith("..\\") || isAbsolute(local)) {
+        throw new Error("Skill path escapes the bundled corpus");
+    }
+    if (!(await stat(file)).isFile())
+        throw new Error("Skill path is not a file");
+    return file;
+}
+async function files(name, folder) {
+    try {
+        const candidates = (await readdir(resolve(root, name, folder), { recursive: true }))
+            .map(path => `${folder}/${path}`)
+            .filter(path => validParts(path) && (folder === "assets" ? assetPath.test(path) : documentPath.test(path)))
+            .sort();
+        const checked = await Promise.all(candidates.map(async (path) => {
+            if (!(await stat(resolve(root, name, path))).isFile())
+                return null;
+            await bundledFile(name, path);
+            return path;
+        }));
+        return checked.filter((path) => path !== null);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+async function requireSkill(name) {
+    if (!skillName.test(name))
+        throw new RangeError(`Unknown Blender skill '${name}'`);
+    try {
+        await bundledFile(name, "SKILL.md");
+    }
+    catch {
+        throw new RangeError(`Unknown Blender skill '${name}'. Call bl_list_skills for available names.`);
+    }
+}
+export async function listSkills() {
+    const entries = await readdir(root, { withFileTypes: true });
+    const names = entries.filter(entry => entry.isDirectory() && skillName.test(entry.name)).map(entry => entry.name).sort();
+    return { skills: await Promise.all(names.map(async (name) => {
+            const entry = await readFile(await bundledFile(name, "SKILL.md"), "utf8");
+            return {
+                name,
+                description: /^description:\s*(.+)$/m.exec(entry)?.[1] ?? "",
+                references: await files(name, "references"),
+                assets: await files(name, "assets"),
+            };
+        })) };
+}
+export async function getSkill(name, document = "SKILL.md") {
+    if (legacyReferences.has(name)) {
+        if (document !== "SKILL.md")
+            throw new RangeError("Legacy topic aliases do not have references");
+        return readFile(await bundledFile("blender-scene", `references/${name}.md`), "utf8");
+    }
+    await requireSkill(name);
+    if (document !== "SKILL.md" && (!validParts(document) || !documentPath.test(document) || !(await files(name, "references")).includes(document))) {
+        throw new RangeError(`Unknown reference '${document}' for '${name}'`);
+    }
+    return readFile(await bundledFile(name, document), "utf8");
+}
+export async function getSkillAsset(name, path) {
+    await requireSkill(name);
+    if (!validParts(path) || !assetPath.test(path) || !(await files(name, "assets")).includes(path)) {
+        throw new RangeError(`Unknown asset '${path}' for '${name}'`);
+    }
+    const absolute_path = await bundledFile(name, path);
+    return { name, path, absolute_path, bytes: (await stat(absolute_path)).size };
 }

package/dist/tools.js

@@ -189,7 +189,7 @@ result = _info`),
 ];
 BL_TOOLS.push(scriptTool("bl_health", "Inspect Blender", "Start or inspect this MCP session’s background Blender. Returns its version, PID, active file and scene; does not inspect an open desktop window.", {}, `import os
 result = {"version": bpy.app.version_string, "pid": os.getpid(), "background": bpy.app.background,
-          "file": bpy.data.filepath, "dirty": bpy.data.is_dirty, "scene": bpy.context.scene.name}`), scriptTool("bl_save_project", "Save Blender Project", "Save the current scene to an absolute .blend path. Existing files require overwrite=true.", {
+          "file": bpy.data.filepath, "dirty": _mcp_session["dirty"] or bpy.data.is_dirty, "scene": bpy.context.scene.name}`), scriptTool("bl_save_project", "Save Blender Project", "Save the current scene to an absolute .blend path. Existing files require overwrite=true.", {
     path: z.string().min(1), overwrite: z.boolean().default(false),
 }, `import os
 _path = _args["path"]
@@ -197,16 +197,20 @@ if not os.path.isabs(_path) or not _path.lower().endswith(".blend"):
     raise ValueError("Provide an absolute .blend path")
 if os.path.exists(_path) and not _args["overwrite"]:
     raise ValueError("File exists; use a new path or explicitly set overwrite=true")
-bpy.ops.wm.save_as_mainfile(filepath=_path, check_existing=False)
+if "FINISHED" not in bpy.ops.wm.save_as_mainfile(filepath=_path, check_existing=False):
+    raise RuntimeError("Project save did not finish")
+_mcp_session["dirty"] = False
 result = {"path": bpy.data.filepath, "saved": not bpy.data.is_dirty}`), scriptTool("bl_open_project", "Open Blender Project", "Replace the active project with an existing .blend file. Refuses unsaved changes unless discard_unsaved=true.", {
     path: z.string().min(1), discard_unsaved: z.boolean().default(false),
 }, `import os
 _path = _args["path"]
 if not os.path.isabs(_path) or not os.path.isfile(_path) or not _path.lower().endswith(".blend"):
     raise ValueError("Provide an existing absolute .blend path")
-if bpy.data.is_dirty and not _args["discard_unsaved"]:
+if (_mcp_session["dirty"] or bpy.data.is_dirty) and not _args["discard_unsaved"]:
     raise ValueError("The current project has unsaved changes; save first or explicitly set discard_unsaved=true")
-bpy.ops.wm.open_mainfile(filepath=_path, use_scripts=False)
+if "FINISHED" not in bpy.ops.wm.open_mainfile(filepath=_path, use_scripts=False):
+    raise RuntimeError("Project open did not finish")
+_mcp_session["dirty"] = False
 result = {"path": bpy.data.filepath, "scene": bpy.context.scene.name}`), scriptTool("bl_insert_keyframe", "Insert Object Keyframe", "Key the current location, Euler rotation or scale of a named object at a frame.", {
     name: z.string().min(1), property: z.enum(["location", "rotation_euler", "scale"]), frame: z.number().int(),
 }, `_obj = bpy.data.objects.get(_args["name"])

package/dist/transport.d.ts

@@ -25,6 +25,6 @@ export declare class BlenderTransport {
     private start;
     private launch;
     status(jobId: string): Promise<JobResult>;
-    execute(code: string, timeoutSeconds?: number): Promise<JobResult>;
+    execute(code: string, timeoutSeconds?: number, mutates?: boolean): Promise<JobResult>;
     close(): Promise<void>;
 }

package/dist/transport.js

@@ -152,7 +152,7 @@ export class BlenderTransport {
             throw new Error("Unknown job_id for this MCP session; history is limited to 128 jobs and disappears on reconnect.");
         return job;
     }
-    async execute(code, timeoutSeconds = 120) {
+    async execute(code, timeoutSeconds = 120, mutates = true) {
         if (!code || code.length > 1_000_000)
             throw new Error("Python source must contain 1–1000000 characters.");
         await this.start();
@@ -166,7 +166,7 @@ export class BlenderTransport {
         return new Promise((resolve, reject) => {
             const timer = setTimeout(() => reject(new Error(`Blender is still running; job_id=${id}. Use bl_job_status on this MCP session before retrying. No automatic retry or cancellation was sent.`)), timeoutSeconds * 1000);
             this.active = { id, finish: result => { clearTimeout(timer); resolve(result); } };
-            this.child.stdin.write(JSON.stringify({ job_id: id, code }) + "\n", error => { if (error)
+            this.child.stdin.write(JSON.stringify({ job_id: id, code, mutates }) + "\n", error => { if (error)
                 this.fail(error); });
         });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fnf-blender-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Higgsfield use Blender: local stdio MCP controlling a background Blender process without add-ons.",
   "type": "module",
   "license": "MIT",

package/scripts/background_runner.py

@@ -9,6 +9,7 @@ import traceback
 PREFIX = "HF_BLENDER_JSON:"
 MAX_RESULT = 4 * 1024 * 1024
 MAX_REQUEST = 8 * 1024 * 1024
+SESSION = {"dirty": False}
 
 
 class BoundedText(io.TextIOBase):
@@ -30,10 +31,16 @@ def execute(request):
     code = request["code"]
     if not isinstance(code, str) or not 0 < len(code) <= 1_000_000:
         raise ValueError("Invalid Python source length")
+    mutates = request.get("mutates", True)
+    if not isinstance(mutates, bool):
+        raise ValueError("Invalid mutation flag")
     stdout, stderr = BoundedText(), BoundedText()
     response = {"job_id": job_id, "state": "completed"}
     try:
-        namespace = {"__name__": "__blender_mcp__"}
+        namespace = {"__name__": "__blender_mcp__", "_mcp_session": SESSION}
+        # Background RNA writes may leave bpy.data.is_dirty false, even after partial failure.
+        if mutates:
+            SESSION["dirty"] = True
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
             exec(compile(code, "<blender-mcp>", "exec"), namespace)
         result = namespace.get("result")

package/skills/blender-animation/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: blender-animation
+description: Dynamic-by-default motion — the motion plan, semantic rigs, deliberate interpolation, constraints and drivers, surface contact, rotational aliasing, visibility keying, dynamic defaults per subject type, and the motion audit. For motion produced by a rigid-body solver rather than keyframes, use blender-destruction.
+---
+
+# Animation
+
+Read [blender-scene](../blender-scene/SKILL.md) for the local session contract.
+Tool names below use its capability mapping when the named interface is absent;
+read only the relevant rows in [blender-volatile](../blender-volatile/SKILL.md).
+
+Motion is part of the default deliverable: unless the user explicitly asked
+for a static scene, the Scene Passport defines at least one purposeful beat.
+"Dynamic" means the viewer can watch something change and read it — not that
+everything moves at once.
+
+## Motion plan
+
+Pin down before keying anything:
+
+- fps, frame range, playback duration;
+- rest pose and beat structure: anticipation → action → settle;
+- the carrier of each beat — object, camera, light, material, or environment;
+- the loop boundary, if the motion loops;
+- constraints, parenting, and control objects involved.
+
+One clear primary action, restrained secondaries, and at least one stable
+frame suitable for inspection and thumbnails.
+
+## Build animation
+
+- Bulk transform/lens keys → `bl_keyframe_properties`; turntable, camera
+  orbit/dolly, idle → `bl_create_motion_preset`; frame inspection →
+  `bl_set_frame`.
+- Drop to `bl_execute` only for what typed tools cannot express: F-curve
+  edits, constraints, drivers, armatures, shape keys, simulations, NLA.
+- Key rigs and semantic controls, not a pile of unrelated child transforms.
+  Key only properties that need to change.
+- Choose interpolation on purpose: Bezier for organic motion, linear for
+  constant rates, constant for stepped switches.
+- Pick quaternion or Euler deliberately so rotations do not flip mid-move;
+  connector boundaries speak radians.
+- Object animation and data animation are separate sets. Lens, `clip_start`,
+  and `dof.focus_distance` keys belong to `camera.data`. Follow Path
+  `offset_factor` belongs to the constraint and is animated on its owning
+  object, through `constraints[...].offset_factor`. Retime both object and
+  data actions, filtering their correct action slots (`blender-volatile`),
+  then check each shot's transform, path, lens, and focus key ranges.
+- Simulations must be deterministic enough that the audited frames reproduce.
+
+## Constraints and drivers
+
+- **`Copy Location` on a spinning child is forbidden.** Any residual offset
+  between target and owner orbits with the spin, and the part reads as about
+  to detach. Only rotation can be compensated.
+- Copy the steering component alone, in the control object's space
+  (CUSTOM to CUSTOM, single axis, mix AFTER). Copying full world rotation
+  drags support noise into the tilt.
+- The local space of a bone-parented child is useless: its own rotation is
+  static and the motion lives in the bone. Name the control object explicitly.
+- **Rolling contact is verified arithmetically.** Rotation per frame equals
+  distance per frame divided by radius, and the residual stays sub-millimetre.
+  The driver's sign follows the direction of the part's local axis; the
+  contact point holding still is the proof.
+- Ray-based ground tracking over a faceted support mesh returns noise, not
+  travel. Disable it and solve the surface response deliberately.
+
+## Surface contact solve
+
+For anything that must stay planted on uneven ground while it moves:
+
+1. One ray per support point gives the gaps.
+2. The mean gap is the height correction.
+3. Compute the slope angle with `atan2(height_difference, support_distance)`.
+   Use the full horizontal distance between the two compared support points,
+   not the half-span. For points at `-a` and `+a`, the denominator is `2*a`.
+   Resolve the sign and roll/pitch axis in the rig's local frame and check
+   the resulting contact gaps; banked or uneven supports may need a fitted
+   support plane rather than two independent slopes.
+4. Two passes per frame for convergence.
+5. Ease in and out over roughly 20 frames with a quintic so no correction
+   pops on entry.
+
+A baked contact holds height but does not pick up lateral slope: it passes on
+straights and drifts on arcs. Level ground under a tilted body means the body
+is wrong, not the ground.
+
+## Rotational aliasing
+
+An N-fold symmetric spinner strobes when its step per frame lands near a
+multiple of its symmetry sector — the blades nearly fill the previous
+positions and the eye reads a jerk or a reversal. Hold a constant step half a
+sector away from any multiple of the sector, then re-phase after the shot so
+the rotation stays continuous.
+
+Blur decides that read more than the keys do. A shutter near 0.2 at one step
+is no smear at all; 0.75 over 12 steps is the working baseline, raised toward
+0.95 by key for the fastest passage. The viewport never renders blur — spin
+and smear are judged from a render only.
+
+## Visibility keying
+
+- Visibility switches are keyed with constant interpolation.
+- **Constraint targets hide in render only.** `hide_viewport` drops an object
+  from the depsgraph, and every constraint reading it gets a stale matrix.
+- Everything else hides in render and viewport together. A render-only hide
+  leaves the viewport lying about framing: geometry sitting millimetres in
+  front of a lens still blocks the preview.
+- Props belong to the shots that need them, not to every range sharing a
+  state.
+- `animation_data_clear()` removes visibility keys along with everything else.
+
+## Dynamic defaults
+
+When the brief names no motion:
+
+- product/prop — slow turntable or camera orbit, settling on the hero angle;
+- environment — subtle camera drift plus a restrained practical-light change;
+- character/creature — idle breathing or weight shift, only if the rig
+  supports it;
+- abstract — one focal transformation with a small secondary response.
+
+Never invent character acting, destructive simulation, or a camera that never
+stops when subtle motion already satisfies the dynamic requirement.
+
+## Motion audit
+
+Sample at minimum: first/rest frame, departure, peak of the fastest change,
+settle, final frame plus the loop seam where one exists. Inspect animated
+properties through `bl_get_object` and `bl_execute`, and view camera renders
+at selected frames using `bl_set_frame` and `bl_render`. This replaces the
+unavailable `bl_audit_motion` and `bl_render_contact_sheet` tools. At each
+sample check framing, collisions
+and intersections, visibility, constraint behavior, shading continuity, and
+motion direction. Open F-curves only when the typed audit cannot explain a
+failure — a still render proves nothing about animation.
+
+The pass fails if expected properties carry no keys, motion is imperceptible,
+objects teleport, rotations flip, the camera loses the subject, or the loop
+jumps. Fix and sample again.

package/skills/blender-audit-finalize/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: blender-audit-finalize
+description: Audit a local Blender scene against its specification, measure structural, motion and visual failures, repair them, and save requested deliverables under the local recovery policy.
+---
+
+# Audit and finalize
+
+Read [blender-scene](../blender-scene/SKILL.md) for the local session contract.
+Tool names below use its capability mapping when the named interface is absent;
+read only the relevant rows in [blender-volatile](../blender-volatile/SKILL.md).
+
+The audit compares the scene to the Scene Passport — not to memory, and not to
+the arguments of the calls that built it. A build passes only when structural,
+motion, and visual evidence all agree.
+
+## Structural audit
+
+Run `bl_validate_scene`, diff against the pre-build snapshot with
+`bl_scene_diff`, and inspect the important objects with `bl_get_object`
+(`bl_execute` only for facts the typed reads do not expose). Confirm:
+
+- every expected object exists exactly once, under its semantic name;
+- dimensions, transforms, origins, parents, collections, visibility match;
+- active camera, frame range, fps, render engine, resolution match, and
+  `frame_end` reaches the last marker and the last key;
+- material slots and texture links resolve;
+- generated replacements sit inside their proxy footprints;
+- no stray defaults, `.001` duplicates, orphan stand-ins, or hidden failures;
+- related objects found under every prefix they use — one prefix search is
+  not a sweep;
+- hero/export meshes have sane normals, manifold state, and density.
+
+## Motion audit
+
+Mandatory for dynamic-default scenes; skipped only on an explicit static
+request.
+
+- Audit motion from fresh scene reads and `bl_execute`; when diagnosing a
+  failure, enumerate animated objects/properties, key times, and interpolation.
+  This package does not provide `bl_audit_motion`.
+- Sample first/rest, departure, peak, settle, and final/loop frames.
+- Check collisions, clipping, constraint jumps, rotation flips, camera
+  framing, visibility, loop continuity.
+- The promised motion must be perceptible and purposeful.
+
+A still image cannot pass this audit.
+
+## Visual audit
+
+1. Viewed camera render for composition; inspect datablocks, modifiers and
+   rigs for editability. A desktop viewport check is unavailable locally.
+2. Inspect active-camera material, light, shadow, transparency, and engine
+   settings through fresh reads, then view a `bl_render` output. The package
+   does not provide `bl_audit_render`.
+3. For dynamic scenes, call `bl_set_frame` and `bl_render` at representative
+   frames; view each result. There is no `bl_render_contact_sheet` tool.
+4. View the returned evidence — success JSON says nothing about appearance.
+   And view it at scale: image previews downsample, so few-pixel features
+   average away to nothing. Crop 1:1 and count bright pixels numerically
+   before concluding something did not render.
+5. **Unreachable evidence fallback** — when a render/screenshot URL cannot
+   be opened (network policy, expired link), report that retrieval failure
+   and obtain equivalent evidence at an accessible local path. Write camera
+   renders via `scene.render.filepath` +
+   `bpy.ops.render.render(write_still=True)`; obtain a local viewport capture
+   if the claim specifically concerns viewport state. Actually view the
+   replacement evidence. If it cannot be viewed either, mark the relevant
+   visual check `blocked`, give the user the available paths/URL, and never
+   substitute numeric proxies for appearance. Numeric proxies cover
+   structure and motion only.
+   One useful framing proxy:
+   `bpy_extras.object_utils.world_to_camera_view(scene, cam, world_co)`
+   returns NDC — x/y in `[0,1]` **with z > 0** means in-frame (z ≤ 0 is
+   behind the camera) — but NDC cannot tell a cylinder from a cactus.
+
+Check silhouette hierarchy, scale cues, contact, depth separation, texture
+scale, highlight/shadow detail, generated/local style coherence, and delivery
+framing. One extra rule: **no asset may read as an unresolved primitive from
+the active camera** unless its passport fidelity is `blockout`. A bare
+cylinder standing in for a cactus, or a uniform sphere for a rock, fails this
+check even when every structural metric passes.
+
+## Specialist audits
+
+Owned by their modules, executed here at finalize time when the Scene
+Passport declares the matching work:
+
+- **Cinematic lighting** (cinematic, commercial, product, night, atmosphere,
+  reference-matched): the full "Lighting audit" in
+  `blender-lighting-camera`. If isolated or grayscale evidence cannot
+  be produced, the lighting audit is `blocked`, not `passed`.
+- **Generated environment**: the "Audit gate" in `blender-hdri`. Record
+  the SDR limitation; a GPT Image PNG is never reported as true HDR/EXR.
+- **Generated PBR material**: the "Audit gate" in `blender-pbr`.
+  Luminance-derived maps are inferred, not measured.
+
+## Measuring a complaint
+
+- Measure the quantity that was complained about, in world space over time —
+  never the nearest available proxy. A perfect reading on the wrong quantity
+  closes the wrong case, and the complaint returns.
+- A clean zero can be the failure. A component that never varies proves rigid
+  parenting as readily as correctness; pick the reference frame the physical
+  claim is about — for a wheel that is the ground, not the body.
+- A hidden object returns a stale matrix. Measure on a frame where it is
+  visible.
+- `scene.ray_cast` follows viewport visibility, not render visibility. When
+  the ray and the render disagree, the render is the evidence.
+
+## Repair loop
+
+Fix the largest concrete failure first, then rerun the affected audit. No
+polishing of secondary detail while scale, framing, contact, or motion is
+wrong. A blocked check is reported as blocked — never dressed up as a pass.
+
+## Finalize
+
+- Modifiers, rigs, materials, and generated assets stay editable unless the
+  deliverable explicitly demands destructive application.
+- Proxies are removed only after their replacements pass; otherwise they are
+  parked predictably and reported.
+- Restore a useful frame and the intended active camera.
+- Record generated job ids, models, estimates, imported object names.
+- Report created/modified/deleted objects with the audit evidence.
+
+When `bl_finalize_build` is exposed, run it once after repairs and inspect
+its documented result; a `valid` field must be true when that is the contract.
+Otherwise use the core manual-finalize fallback and report each audit result
+with its actual evidence. Do not invent a tool response or silently convert a
+blocked generation, export, or visual check into a pass.
+
+## Save policy
+
+Follow blender-scene's local save and recovery contract. Recovery copies
+precede broad/destructive edits; save requested .blend outputs before
+reconnecting or replacing the active project. Preserve useful partial work
+even when an audit is blocked, clearly reporting its status. Confirm an
+ambiguous overwrite target; do not overwrite or pack resources merely as a
+side effect of audit/finalize. Report the verified saved path.