design-os-3d-blender

Spec → build → verify → gate. An agent operating system for Blender that ships parts you can print, not pictures you can post.

Contents: What is inside · Proof · Quick start · The loop · Robot-arm demo · Notes · License

An AI-agent operating system for Blender 5.2 LTS: skills, a verified knowledge base, an execution contract, and a production gate — built so an agent (Claude Code, Codex, Google Antigravity, or any MCP client) can model, rig, animate, render, and ship 3D-printable, dimension-correct parts rather than pretty demos.

Everything here is Blender-native: no vendor mesh generation, no downloaded assets, no paid model calls.

🧭 What is inside

🔬 Proof: the robot arm is real geometry, not a picture

The model open in Blender 5.2.0 — scene A5-Original-refined, 671 objects, frame 3031/3031, outliner and properties visible (full-window screenshot, not a viewport crop)	Six-angle Cycles orbit of the assembled parts at the final frame, rendered headless from the shipped .blend
Render tessellation of the 402 arm part meshes (114,723 polygons), Cycles Wireframe node — every edge you see is in the file	38 fit-prototype parts arranged on five 220×220 mm plates (PETG + TPU), exported as STL/3MF

Cycles render of the assembled model at the final frame (1600×1200, 96 samples, Metal). The full-speed MP4 of the assembly film is in builds/robot-arm-original-refined/video/.

Production gate run on the real print kit (2026-09-06). The 38 exported STLs were re-imported into a metre-scaled scene and gated against a spec generated from parts-list.csv (target dimensions ± 0.1 mm, one shell per part, PETG/TPU):

GATE PASS | 38 part(s), 0 failing check(s) | scene=72ab501e47bf spec=d88bc836fb3a | Blender 5.2.0 LTS
836 checks pass · 0 fail · 38 skip (no min_wall_mm declared) · 38 info (overhang reported, not gated)

Per part: non_manifold_edges, non_contiguous_edges, wire_edges, loose_verts, zero_area_faces, self_intersection_pairs, shells, signed_volume_positive, bbox_dims_mm, scale_applied, scene_unit_system, scene_scale_length, then STL round-trip repeats of the topology and dimension checks. Report, spec and the reproduction script: builds/robot-arm-print-assembly/reports/gate-report-260906.json, gate-spec-260906.json, scripts/gate-import-parts.py. The report's exclusions say what this does not prove: load capacity, print success, assembly fit, thermal/creep — those remain physical evidence, and the arm stays unreleased for manufacture.

🚀 Quick start

Requirements: macOS/Linux, Blender 5.2.x, Python 3.10+ on the host (stdlib only). Optional interactive path: blender-mcp addon connected in the Blender GUI.

export BLENDER_BIN=/Applications/Blender.app/Contents/MacOS/Blender   # adjust
python3 -m unittest discover -s tests/execution                      # execution contract
python3 -m unittest discover -s tests/production-gate                # gate on generated fixtures
python3 scripts/blender-knowledge.py check && python3 scripts/blender-knowledge.py list

Run any bpy payload headless and get a machine-readable verdict:

bash scripts/headless-run.sh my-pass.py          # last line: AGENT_OK {...} or AGENT_FAIL {...}; exit 0/1/2/3

Over MCP (Claude/Codex with the blender-mcp addon), execute the same payload with the same contract:

import sys; sys.path.insert(0, "<ROOT>/scripts")
import agent_runtime as rt; rt.run_file("<ROOT>/builds/<slug>/pass-01.py")

Gate a part for printing (write the spec before detailing):

cp specs/examples/bracket-m3.spec.json builds/my-part/spec.json   # dims ± tol, holes, fasteners, material, min wall
python3 scripts/production-gate.py --scene builds/my-part/part.blend --spec builds/my-part/spec.json \
        --report builds/my-part/reports/gate-report.json --export-dir builds/my-part/parts

Exit 0 = every declared check passed (digital evidence only); 1 = a requirement failed; 2 = spec/scene incomplete; 3 = execution error. specs/README.md lists exactly what each check proves and does not prove (load, fit after shrinkage, thermal duty stay physical evidence).

🔁 The loop agents follow

Contract → Plan (scene graph) → Code (pass files ≤ ~80 lines) → Critic → Execute → Verify → Verdict

• Contract first. A printable part needs spec.json; a reference image needs a fidelity contract. Missing numbers → request-input, not a guess. (Every full rebuild in our record traced to a spec that arrived after detailing.)
• Numbers before pixels. Assert postconditions, then framing() + a 0.2 s preview, then a screenshot with the expectation written down first.
• Verdict is one of continue · refine-spec · refine-code · request-input · stop. Two failures on the same step change the class of approach; three escalate.
• Success is the sentinel, never "Code executed successfully".

🤖 Robot-arm demo (builds/)

• robot-arm-original-refined/ — the accepted step-by-step assembly film (3,020 frames, Cycles), source .blend, clearance/overlap checks, decoded-frame review reports.
• robot-arm-print-assembly/ — 38 fit-prototype parts on 5 plates (PETG + TPU) as STL/3MF, parts list, assembly-step CSV, mesh audit and export checks.
• robot-arm-v2-engineered/ — the task-demo scripts the knowledge catalog cites as execution examples (motion plan, path check, STL export with manifest, delivery audit).

Status is deliberately separated per domain: media accepted · motion checked at sampled poses · fit prototypes exported · manufacture BLOCKED (wrist torque margin, retention hardware, thermal duty and loaded trials remain open — see the build READMEs). The frame sequences and draft renders (several GB) are not shipped.

📝 Notes

• <ROOT> in docs and snippets = absolute path of this repo on your machine.
• .agents/skills/img2threejs is a vendored copy of img2threejs (Apache-2.0, license included).
• tests/blender/ target drone builds that are not shipped here.

📄 License

MIT — see LICENSE.