Official Codebase of 3DCodeVerse
Python
Plugin text lane 3/3: delete the prompt corpus (system/contract/asset text, the track templates, _claims), RUNBOOK and SKILLS; rewrite README, CLAUDE.md, INSTALL and ARCHITECTURE for the plugin
gaoypeng3fe540e14932
diff --git a/harness/CLAUDE.md b/harness/CLAUDE.mdindex 7c298570..a7e0dc2a 100644--- a/harness/CLAUDE.md+++ b/harness/CLAUDE.md@@ -1,121 +1,76 @@# 3dcodeverse — standing context-Backend harness (python package `codeverse3d`, CLI `3dcodeverse`,-repo path `harness/` under the 3dcodeverse checkout) for LLM-written **raw** 3D code:-Blender bpy · CadQuery · Three.js · URDF · GLSL / OpenGL, across four tracks-(`static_object`, `articulated_object`, `scene`, `graphics`), with pluggable-backends. **The coding agent is always a VENDOR's** — antigravity (`agy`, Google's-models) / claude-code / codex — and the harness supplies the workspace, the prompt and the-3D tools its track can use (over MCP; 16 in the registry, filtered per track — D48-review), then reads the result. The harness's OWN api use is planning,-judging, and single-shot file generation (Gemini/Anthropic/OpenAI).-It does not implement an agent loop: the in-process `api-agent` was deleted-2026-08-28 (owner's call — reimplementing what the vendors already ship was never-this project's job). Plus a data-flywheel record per run.+`harness/` IS the plugin (python package `codeverse3d`, console script `3dcode`, skills under+`skills/`, the judge under `agents/`, manifests `.claude-plugin/plugin.json`,+`.codex-plugin/plugin.json`, `plugin.json`; the repo root's `.claude-plugin/marketplace.json`+lists it). It installs into Claude Code, Codex and Antigravity and boosts the HOST agent's 3D+ability: the host writes raw Blender bpy / CadQuery / Three.js / URDF / GLSL / moderngl code+in a workspace, the `3dcode` instruments build, measure, render and gate it, a fresh-context+judge subagent scores the renders. No pipeline, no stage graph, no round loop, no vendor-CLI+backends, no model API clients, no API keys, no cost ledger, no run records: flow and wording+live in the skills, each rule in ONE place; code keeps only what a model cannot do or cannot do+reliably — real execution, measurement, deterministic checks, score arithmetic. Old behaviour+is in releases v0.0.0 / v0.0.1; the flywheel is the separate `flywheel/` package.-Read `docs/ARCHITECTURE.md` (design, package map, what a run-really does, known limits), `docs/RUNBOOK.md` (how to run / resume / extend), `eval/docs/EVAL.md`-(evaluation protocol + judge calibration) and `eval/docs/COMPLEXITY.md` (the objective-complexity vector + the score-vs-complexity corpus study) before changing anything.--Historical cost experiments, decision logs, skill measurements, the cross-package signature-notes and the pre-trim docs are local-only notes (COST.md, DECISIONS.md, SKILLS_LEDGER.md,-INTERFACES.md and HISTORY.md under harness/docs, ignored by Git; the tracked docs carry only-what running the harness needs).-Historical citations in comments refer to these optional notes; they are not required-to install, run or test the harness. Current rules and interfaces live in the tracked docs.+Read `docs/ARCHITECTURE.md` (design laws, package map, the workspace, every instrument, the+gates, judging) and `docs/INSTALL.md` before changing anything.## Laws (do not break)-1. Generated code is raw language — never an SDK/helper import; the harness owns+1. Generated code is raw language — never an SDK/helper import; the plugin ownswrappers/exporters (`codeverse3d/languages/wrappers/`, `languages/opengl_python/wrappers/`,- `runtime_js/`).-2. `codeverse3d/contracts/` is data-only and shared; `conventions.py` is the only- place that states frames/units/naming. Import, never restate.-3. Deterministic gates/measurements run by the harness; VLM only for perception.- Score is computed in code from rubric weights; caps/floors are explicit.-4. Typed everything; no regex-on-id control flow; a file may be long but not a god file —- cap **2 000 lines** per file, **3 000** absolute (owner, 2026-08-28; was 1 500, and the old- ~400-line guideline is long gone). Merging is NOT a goal in itself — a merge must DELETE- code, not just move it between files.-5. Cheap first: lint → build → gates → montaged views → VLM. Budgets are hard.-6. Every round = a git commit of `src/`; every call = a `Usage`; every run = `record.json`.-7. No wrapper re-centres or grounds the object: export **as authored**, warn in the- build, let `check_contract`/`check_connectivity` gate it.+ `runtime_js/`). The one exception the skills name: `scene_threejs`'s harness-owned+ `src/lib/*.js`, copied into the workspace.+2. `codeverse3d/contracts/` is data-only and shared; `conventions.py` is the only place that+ states frames/units/naming in code. Import, never restate. A skill may state a frame to+ the agent, who cannot import it — the number must agree with `conventions.py`.+3. Deterministic gates/measurements run in code; a model only perceives and judges. The score+ is computed in code from rubric weights; caps/floors are explicit.+4. Typed everything; no regex-on-id control flow; cap **2 000 lines** per file, **3 000**+ absolute. A merge must DELETE code, not move it.+5. Cheap first: lint → build → gates → montaged views → the judge.+6. Requirements, never templates: a skill keeps interface, sandbox rules and measured+ thresholds, ONE executable interface example per language under `references/`, no code+ fence over ~12 lines, no budget or cost wording, no recipes the brief did not ask for.+7. No wrapper re-centres or grounds the object: export **as authored**, warn in the build, let+ `check-contract` / `check-connectivity` gate it.+8. The judge is a FRESH context that sees `judge/rNN/brief.md` and the images, never the+ builder's code or reasoning; `3dcode score` is the only thing that turns a judgment into a+ number.-## Supported versions (what other people can run this on)-python **3.13** (one fixed version — owner's decision 2026-08-26; no floor, no matrix) ·-node **20.6+** · Blender **5.2 LTS** only (D104, 2026-10-14; 4.2 / 5.0 compatibility dropped) · Linux x86_64. **There is no CI** (removed 2026-08-26 by the-owner): run `ruff check codeverse3d tests` and the offline suite locally BEFORE every-push, with `set -o pipefail` so a `| tail` cannot swallow a red exit. The version lives in-`pyproject` `requires-python` + ruff `target-version` + `setup.sh`, and-`spatial/node.py:NODE_MIN` + `runtime_js/package.json` `engines` for node, pinned together by-`tests/core/test_portability.py`. Details: `docs/INSTALL.md` §2.1.+## Supported versions+python **3.13** (one fixed version) · node **20.6+** · Blender **5.2 LTS** only · Linux x86_64.+There is no CI: run `ruff check codeverse3d` and the smoke scripts under+`/home/yipeng/3dcodeverse_tests/plugin_smoke/` (outside the repo) before every push, with+`set -o pipefail`.## Environment (this machine)-- Gemini keys: `~/.config/astra3d/gemini_keys.env` (30 keys, the owner's list of 2026-10-14: Scene1-10, Argon1-10, argon-test-1..10) → `get_settings().gemini_api_keys`- (or `GEMINI_API_KEYS` / `GEMINI_API_KEY` env). Settings: `~/.config/3dcodeverse/config.yaml`- or `./3dcodeverse.yaml`, env prefix `C3D_` (the- grammar and examples: docs/INSTALL.md §8.3). Every `C3D_*` switch is a `Settings` field read through `get_settings()`- where it is used — never read the environment by hand.-- Blender 5.2.2 LTS headless: `~/.local/bin/blender-5.2` (always `--factory-startup`; clear scene). The judged-frame- fast path is Cycles CUDA + GPU OIDN + persistent data (D104; measured 0.21 s/frame at 1024x576 after the first);- OptiX is unavailable under WSL2 and probing it crashes Blender — never enumerate it.-- Node 24 (floor 20.6) + `runtime_js/node_modules` ([email protected], puppeteer; chrome cached). Headless- Chrome WebGL uses the GPU on WSL2 with `--use-angle=gl-egl` + Mesa d3d12 env (see- `runtime_js/gpu_launch.cjs`; `C3D_RENDER_GPU=on|off|auto`); SwiftShader fallback.- Bare ESM `import 'three'` needs `--import runtime_js/lib/resolve_three.mjs`- (`spatial.node.run_node(three_hook=True)`) — `NODE_PATH` alone does not work;- that hook is `module.registerHooks` on node ≥ 22.15, `module.register` below.- The `graphics` track renders with moderngl (d3d12 GPU context, llvmpipe fallback).-- CLIs: `agy` (Antigravity; gemini-cli was deleted in D103, 2026-10-13) — runs ONLY in- Gemini-API mode (Gemini models only, keys required; no subscription sign-in): one key from the- shared pool, a per-session HOME carrying `modelProvider: gemini` + the 3dcode MCP server, priced. `codex` (MCP needs- `default_tools_approval_mode="approve"`) and `claude` run on local subscriptions: test- lightly. No Anthropic/OpenAI API keys here. `setup.sh` keeps all three at their latest release- (`--no-clis` skips); no version is pinned or required — `doctor` prints what it found (owner, 2026-11-03; D115).-- DEFAULT generator: `agy:gemini-4-argon` (D103, 2026-10-13); planner and- captioner default to `gemini:gemini-4-argon` too.- `gemini-3.8-flash` is the cheap API model (single-shot, flash judge — lenient; needs- the defect checklist for range). Judge default `gemini:gemini-4-argon` (`Settings.default_judge`)- with `judge.thinking=medium`; tracks use n_samples=1. The argon loop uses the same model and- thinking on rubric `scene`. Historical pro/flash calibration results remain in `eval/docs/EVAL.md`.-- Live runs under `runs/` (`e2e_*`): read-only reference material; never modify.-- Every model call and vendor session is priced into the run's `telemetry/cost.jsonl` — the ONLY record of- money: `record.total_usage` is its sum at list price (D84). A run's minutes are its steps' time minus- the time lost to provider errors (`RunRecord.minutes`). Use `3dcodeverse cost <slug>` for actual costs.+- Blender 5.2.2 LTS headless: `~/.local/bin/blender-5.2` (always `--factory-startup`). The+ judged-frame fast path is Cycles CUDA + GPU OIDN + persistent data; OptiX is unavailable under+ WSL2 and probing it crashes Blender — never enumerate it.+- Node 24 (floor 20.6) + `runtime_js/node_modules` ([email protected], puppeteer; chrome cached).+ Headless Chrome WebGL uses the GPU on WSL2 with `--use-angle=gl-egl` + Mesa d3d12 env+ (`runtime_js/gpu_launch.cjs`; `C3D_RENDER_GPU=on|off|auto`); SwiftShader fallback. Bare ESM+ `import 'three'` needs `--import runtime_js/lib/resolve_three.mjs`+ (`spatial.node.run_node(three_hook=True)`). The `graphics` track renders with moderngl+ (d3d12 GPU context, llvmpipe fallback).+- Settings: `~/.config/3dcodeverse/config.yaml` or `./3dcodeverse.yaml`, env prefix `C3D_`;+ every switch is a `Settings` field read through `get_settings()` — never read the+ environment by hand.+- Hosts: `agy`, `claude`, `codex` are installed; test plugin loading only in a TEMP home+ (`HOME=/tmp/x`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR`) — never touch the real `~/.claude`,+ `~/.codex`, `~/.gemini`.## Commands```-pip install -e harness # once, from the 3dcodeverse checkout (entry point: 3dcodeverse)-cd harness-3dcodeverse doctor [--live] [--no-gpu] [--json]-3dcodeverse make "a mid-century wooden dining chair" --track static_object --language blender-3dcodeverse make "..." --track static_object --language threejs --generator agy:gemini-4-argon-3dcodeverse make "..." --track articulated_object --language urdf_blender-3dcodeverse make "..." --track scene --language scene_threejs --rounds 2 --max-minutes 60-3dcodeverse make "..." --track scene --language scene_blender --rounds 2 --max-minutes 90 # bpy scene on Blender 5.2.2 (D105): every module the agent's, Cycles judged frames-# Every track states REQUIREMENTS, never templates (D106 scene, D107 the rest, 2026-10-15): no language ships a cookbook, no inlined-# recipes, placeholder skeletons; a prompt / skill keeps only interface, sandbox rules and measured thresholds, each contract.md ONE-# executable interface example (tests/prompts/test_snippets_run.py), the craft as short optional practices in the skills (fences ≤ ~12 lines).-3dcodeverse make "neon rain on a window" --track graphics --language glsl_shader-3dcodeverse make "..." --image ref.png --rounds 2 --dim height=0.45 --must "three legs" --no-run-3dcodeverse make "..." --no-pick # a run = baseline + --rounds refine rounds (fixed); make then picks a round → deliverable/ unless --no-pick-3dcodeverse pick <slug> [--round N] # hand over a round (codeverse3d/addons/select.py)-3dcodeverse resume <slug> · 3dcodeverse show <slug> [--section status] (`status` = its STATUS section) · 3dcodeverse judge <slug> [--model ... --n 3 --thinking medium]-3dcodeverse tools list · 3dcodeverse tools measure --workspace runs/<slug> · 3dcodeverse mcp --workspace runs/<slug>-3dcodeverse cost <slug> · 3dcodeverse cost --runs-dir ../eval/bench/out/<battery>-3dcodeverse cost prices [--stale]-3dcodeverse flywheel export runs/ dataset/ [--pack --drop-duplicates --captions-dir d/] · 3dcodeverse flywheel pairs runs/ pairs.jsonl-3dcodeverse flywheel caption <slug> [--out dir] # the gallery is `3dcodeverse gallery build --embed`-3dcodeverse gallery serve [ROOTS...] [--port 8765] [--reload] · 3dcodeverse gallery build --out gallery.html [--embed]-(cd ../eval && python -m bench.run_bench bench/prompts/static_objects_v1.yaml --generator ... --judge gemini:gemini-4-argon) # report: python -m bench.report bench/out/<battery>-python -m codeverse3d.addons.calibration runs/<slug>... --model gemini:gemini-4-argon --n 3 --out out/-python ../eval/bench/complexity_report.py ../eval/bench/out --recursive # score-vs-complexity + $/complexity point (eval/docs/COMPLEXITY.md)-python ../eval/bench/compare_backends.py --prompts ../eval/bench/prompts/compare_v1.yaml --arms harness:agy:gemini-4-argon,oneshot:claude-code --judge gemini:gemini-4-argon --out ../eval/bench/out/compare_v1-python -m tests.prompts.manifest [--bless | --dump DIR] # what every model is shown, pinned (RUNBOOK §7): bless only a change a model is MEANT to see-python -m pytest tests -q -m "not live" # the offline suite (real Blender + headless Chrome + CadQuery)-python -m pytest tests -q -m "not live and not blender and not node" # pure python (the bench tests: `cd ../eval && python -m pytest`)-# (how many: `--collect-only`; a count written here drifts every commit)-# both run PARALLEL by default (pytest-xdist, -n auto --dist worksteal, in pyproject addopts).-# A nested pytest inside a test MUST pass -n0 or it forks another full set of workers.+bash setup.sh # python package + runtime_js + chrome + doctor+python -m codeverse3d.doctor [--json]+3dcode init --workspace W --track static_object --language blender --prompt "a dining chair" [--must ...] [--dim height=0.45] [--reference img.png]+3dcode validate-plan --workspace W+3dcode build | check | judge-pack --round N | score --round N (always --workspace W; --json for JSON)+3dcode measure | check-contract | check-connectivity | cross-section | render-views | render-sheet | isolate | compare-reference | joint-sweep+3dcode scene-probe | check-placement | scene-views | shader-probe | gl-probe | gl-frames+agy plugin validate . --strict --json # the plugin layout (skills, agents, manifest)+claude plugin marketplace add <repo>; claude plugin install 3dcodeverse@3dcodeverse # in a temp CLAUDE_CONFIG_DIR+codex plugin marketplace add <repo>; codex plugin add 3dcodeverse@3dcodeverse # in a temp CODEX_HOME+ruff check codeverse3d```diff --git a/harness/README.md b/harness/README.mdindex 548307db..89eaa886 100644--- a/harness/README.md+++ b/harness/README.md@@ -1,61 +1,61 @@-# 3dcodeverse harness+# 3dcodeverse-A backend harness in which LLMs write **raw, executable 3D code** — Blender `bpy`,-CadQuery, Three.js, URDF, GLSL / OpenGL — and the harness plans, builds, measures,-renders, judges, refines and records every run as data-flywheel material.+A plugin for **Claude Code, Codex and Antigravity (`agy`)** that makes the host coding agent+good at real 3D: it writes **raw, executable 3D code** — Blender `bpy`, CadQuery, Three.js,+URDF, GLSL, moderngl — and the plugin builds, measures, renders and gates what it wrote, then+has a fresh-context judge score it.* **Tracks:** `static_object` · `articulated_object` · `scene` · `graphics`-* **Languages:** `blender` · `cadquery` · `threejs` · `urdf_blender` ·- `scene_threejs` · `scene_blender` · `glsl_shader` · `opengl_python`-* **Backends:** Gemini / Anthropic / OpenAI chat models; coding agents `claude-code`,- `codex`, `agy` (Antigravity) — always a vendor's CLI — and- `single-shot` generation on any chat model.-* **Spatial tools** (direct, or over the MCP server `3dcode` for the agentic CLIs): build,- measure, render, section, connectivity/contract checks, joint sweeps, scene and GL probes —- the list is `docs/ARCHITECTURE.md` §5.-* **Judging:** rubric VLM judge (default `gemini:gemini-4-argon`, thinking `medium`) on labelled 2×2- montages with binary defect checklists; code-computed scores, floors and caps from- deterministic gates; reference and likeness judges;- a calibration harness (`addons/calibration.py`).-* **Flywheel:** git-versioned `src/` per round, `record.json`, sample export with- quality tiers + dedupe (+ parquet, tar locators), preference/repair/cross-backend- pairs, captions, HTML gallery.-* **Looking at results:** `3dcodeverse gallery serve` — a local page over `runs/` +- `eval/bench/out/*/runs` with filters, a per-filter summary strip and a detail page per run;- it serves the run directories too, so every link (sheet, renders, `src/`, `object.glb`- in an orbit viewer, `record.json`) actually opens. `3dcodeverse gallery build --embed` writes- the same page as one shareable file.--## Architecture--Every run is **spec → plan → skeleton → [scene stages] → baseline round → refine rounds → finalise → record**. The package tree is `docs/ARCHITECTURE.md` §2.--Design laws and what each stage does: `docs/ARCHITECTURE.md`.--**Supported versions:** python **3.13** and node **20.6+** (Linux x86_64; Blender-5.2 LTS optional). Developed and measured on python 3.13 / node 24; there is no CI — the offline suite and-`ruff` run locally before every push. See `docs/INSTALL.md` §2.1.+* **Languages:** `blender` · `cadquery` · `threejs` · `urdf_blender` · `scene_threejs` ·+ `scene_blender` · `glsl_shader` · `opengl_python`+* **Skills** (`skills/`): `3d-director` (the workflow: init → plan → code → check → judge →+ refine, stop rules), `3d-lang-<language>` × 8 (each language's files, frame, sandbox and+ every threshold the instruments measure) and the `c3d-*` craft bundles (parts that touch,+ bbox contract, repeats, scene lighting / placement / materials / motion, shader traps …).+* **Instruments** (`3dcode`, a command-line tool): `init`, `validate-plan`, `build`, `check`+ (every gate of the track), `judge-pack`, `score`, and the per-track probes — `measure`,+ `check-contract`, `check-connectivity`, `cross-section`, `render-views`, `render-sheet`,+ `isolate`, `compare-reference`, `joint-sweep`, `scene-probe`, `check-placement`,+ `scene-views`, `shader-probe`, `gl-probe`, `gl-frames`. Each prints a verdict, numbers,+ fix hints and the paths of the PNGs it wrote.+* **Judge** (`agents/3d-judge.md`): a subagent that reads only `judge/rNN/brief.md` + the+ images and writes `judgment.json`; `3dcode score` does the arithmetic from the rubric's+ weights, penalties, floors and gate caps.++Everything model-side — writing code, looking at renders, judging — is the host agent's own+model and billing. There is no pipeline, no vendor backend, no API key and no cost ledger in+this package.++## Install```bash-bash setup.sh # python package + runtime_js + headless Chrome + the agy / claude / codex CLIs at their latest + doctor-# ...or by hand:-pip install -e '.[all,dev]' # entry point: 3dcodeverse-(cd runtime_js && npm ci) # [email protected] + puppeteer 24 (chrome → ~/.cache/puppeteer)-curl -fsSL https://antigravity.google/cli/install.sh | bash # agy, the default generator's CLI (`agy update` later)-npm i -g @anthropic-ai/claude-code@latest @openai/codex@latest # optional generators claude-code / codex (local subscriptions)-export GEMINI_API_KEYS="key1,key2" # agy runs in Gemini-API mode on this key pool (docs/INSTALL.md §8)-3dcodeverse doctor-3dcodeverse make "a mid-century wooden dining chair" --track static_object --language blender-3dcodeverse make "a kitchen cabinet with one door and a drawer" --track articulated_object --language urdf_blender-3dcodeverse make "a small japanese garden at dusk with a koi pond" --track scene --language scene_threejs-3dcodeverse make "neon cyberpunk rain on a window" --track graphics --language glsl_shader-3dcodeverse gallery serve # browse every run at http://127.0.0.1:8765/ (docs/RUNBOOK.md §4)-python -m pytest tests -q -m "not live"+git clone <this repo> 3dcodeverse && cd 3dcodeverse+bash harness/setup.sh # python package (console script `3dcode`) + runtime_js + headless Chrome + doctor+python -m codeverse3d.doctor # deps, Blender, node, GPU++claude plugin marketplace add . # Claude Code: the repo is a marketplace+claude plugin install 3dcodeverse@3dcodeverse+codex plugin marketplace add . # Codex+codex plugin add 3dcodeverse@3dcodeverse+agy plugin install harness # Antigravity```-Expected cost and time per track: `docs/RUNBOOK.md` §2. Inspect actual run costs with-`3dcodeverse cost <slug>`.+Prerequisites and troubleshooting: `docs/INSTALL.md`. Python 3.13, node ≥ 20.6; Blender+5.2 LTS for the `blender` languages; CadQuery and moderngl as extras.-Docs: `docs/INSTALL.md` (install / prerequisites / doctor troubleshooting) ·-`docs/ARCHITECTURE.md` (design + what a run does) · `docs/RUNBOOK.md` (operate / extend) ·-`eval/docs/EVAL.md` (evaluation protocol + judge calibration) · `CLAUDE.md` (working rules).+## Use++Ask the host agent for a 3D thing and name the language if you care:++> Make a mid-century wooden dining chair in Blender bpy.+> Make a kitchen cabinet with one door and a drawer as a URDF mechanism.+> Make a small Japanese garden at dusk with a koi pond as a three.js scene.+> Make neon rain on a window as a GLSL shader.++The `3d-director` skill drives the rest: a workspace directory with `spec.json`, `plan.json`,+`src/` (the code), `artifacts/` (object.glb, renders, gates) and `judge/rNN/` (brief, montages,+judgment, score). The deliverable is the best-scoring round's `src/` and its artifacts.++Docs: `docs/INSTALL.md` (install / prerequisites / doctor) · `docs/ARCHITECTURE.md` (design,+the workspace, every instrument and gate, judging) · `CLAUDE.md` (working rules for changing+the plugin).diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 4b8e139e..8e151a6b 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -1,406 +1,150 @@-# 3dcodeverse harness — architecture+# 3dcodeverse — architecture-Package `codeverse3d`, CLI `3dcodeverse`, repo location `harness/` in the-3dcodeverse checkout. Backend only. Python 3.13 (one fixed version), a small Node runtime-(`runtime_js/`) for everything Three.js / headless Chrome, and moderngl for the graphics track.-How-to is in `docs/RUNBOOK.md`, the skill library in-`docs/SKILLS.md`, the evaluation protocol in `eval/docs/EVAL.md`.+`harness/` is a plugin for Claude Code, Codex and Antigravity. The HOST agent drives+everything — plan, write raw code, build, look, judge, refine — and the plugin gives it three+things: **skills** (the workflow, a measured contract per language, craft bundles), a **judge+subagent**, and the **`3dcode` instruments** (build/export, measurement, renders,+deterministic gates, judge material, score arithmetic). Python 3.13 (`codeverse3d`), a small+node runtime (`runtime_js/`) for everything Three.js / headless Chrome, moderngl for the+graphics track.## 0. What it is-A data-flywheel harness in which LLMs write **raw executable 3D code** — no SDK layered on top-of the language — for four **tracks**:+LLM-written **raw executable 3D code** — no SDK layered on the language — for four tracks:| track | languages | deliverable ||---|---|---|-| `static_object` | `blender` (bpy), `cadquery`, `threejs` | code + canonical `object.glb` (+stl/step) |-| `articulated_object` | `urdf_blender` (bpy link meshes + hand-written URDF) | code + `robot.urdf` + `meshes/*.glb` (raw link frames) + `object.glb` (node hierarchy with joint extras) |-| `scene` | `scene_threejs` (multi-file three.js + GLSL; optional bpy-built GLB assets), `scene_blender` (multi-file bpy, every module the agent's) | `src/**` + `public/assets/*.glb` + renders + probes |-| `graphics` | `glsl_shader` (Shadertoy-style fragment shader), `opengl_python` (raw moderngl + GLSL, multi-pass) | shader/program source + judged animation frames + sheet + GIF + frame metrics |--…driven by any of these backends behind two protocols:--* `ChatModel` (API): `gemini:*`, `anthropic:*`, `openai:*` — planner, judge, captioner,- single-shot generation.-* `CodingAgent` (agentic session on a workspace): always a vendor CLI — `agy:*` (Antigravity,- Google's models, Gemini-API mode with pool keys + MCP), `claude-code:*`, `codex:*`. Plus- `single-shot:<chat-model>` (one envelope of files, no tools) handled inside- `tracks/generation.py`. The harness implements no agent loop of its own.--Every run is: **spec → plan → skeleton → [scene stages] → baseline round → `max_rounds` refine rounds → finalise → record**. Which round to hand over is-decided AFTER the run by the `addons/select` reader (`3dcodeverse pick`; `3dcodeverse make` calls it by-score): it writes `deliverable/` for that round. The record, the git history of `src/` and every-round's kept build are the flywheel unit.+| `static_object` | `blender` (bpy), `cadquery`, `threejs` | code + `artifacts/object.glb` (+ stl / step) |+| `articulated_object` | `urdf_blender` (bpy link meshes + hand-written URDF) | code + `robot.urdf` + `meshes/*.glb` + `object.glb` |+| `scene` | `scene_threejs` (multi-file three.js + GLSL), `scene_blender` (multi-file bpy) | `src/**` + `public/assets/*.glb` + renders + probes |+| `graphics` | `glsl_shader`, `opengl_python` | source + judged frames + sheet + GIF + frame metrics |## 1. Design laws-1. **Code is truth; artifacts are derived.** Raw code in `src/` is the deliverable; GLB/renders- are regenerated from it. Every round is a commit and keeps its own build under- `artifacts/rNN/`, so any round can be handed over without a rebuild.-2. **Requirements, never templates.** The harness states what must be true, where, and how it is- measured — interface (files, functions, frames / units / naming), sandbox rules, measured- thresholds — never a mandated shape, count, layout or code structure the brief did not ask- for. No language ships a cookbook; each `contract.md` keeps ONE executable interface example- (`tests/prompts/test_snippets_run.py` runs it), the craft is a few short optional practices in- the skills, and no code block in a prompt or skill is over ~12 lines.-3. **Code answers when code can answer.** Deterministic gates / measurements run by the harness;- the VLM is used only for perception and judgement, and its score is computed in code from- rubric weights.-4. **Move responsibility out of agent code**: export wrappers, camera rigs, placement validation,- URDF composition math, scene assembly, GLSL headers.-5. **Evidence-based acceptance.** Every plan carries an acceptance checklist; items are proved by- measurements / probes / judge votes, not prose.-6. **Typed everything.** One contracts package; no regex-on-id control flow, no stringly-typed- dicts, no god files (cap 2 000 lines per file, 3 000 absolute). A merge must delete code, not- merely move it.-7. **Cheap first.** Lint → build → deterministic gates → montaged views → VLM.-8. **Separate generator from judge.** The judge sees spec + renders + measurements + acceptance- list; never the generator's reasoning.-9. **Money is measured, time is bounded.** The wall clock is the hard per-run ceiling- (`BudgetGuard`), key pools have per-key limiters, and every call is one row of the run's- ledger, `telemetry/cost.jsonl` — the only record of money.-10. **Reproducible.** Prompt / rubric / skill hashes and tool versions are recorded on every run- (`record.prompt_hashes`, `record.environment`).-11. **Export as authored.** No wrapper re-centres, rescales or grounds the object; builds warn,- `check_contract` / `check_connectivity` gate, the agent fixes the source.--## 2. Package map (as built)+1. **Code is truth; artifacts are derived.** `src/` is the deliverable; every GLB, PNG and+ URDF is regenerated from it. Every round is a git commit of `src/`.+2. **Requirements, never templates.** A skill states what must be true, where, and how it is+ measured — interface, sandbox, thresholds — never a mandated shape or structure the brief+ did not ask for; ONE executable interface example per language; no fence over ~12 lines.+3. **Code answers when code can answer.** Deterministic gates and measurements run in code;+ the model perceives and judges; the score is computed from rubric weights, penalties, floors+ and caps.+4. **Responsibility out of agent code**: export wrappers, camera rigs, placement validation,+ URDF composition math, scene assembly, GLSL headers are the plugin's.+5. **Evidence-based acceptance.** Every plan carries an acceptance checklist; the judge+ answers each item from renders or measurements.+6. **Typed everything.** One contracts package; no regex-on-id control flow; no god files+ (2 000 lines, 3 000 absolute); a merge must delete code.+7. **Cheap first.** Lint → build → gates → montaged views → the judge.+8. **Generator and judge are separate contexts.** The judge sees `brief.md` and images only.+9. **Export as authored.** No wrapper re-centres or grounds; the gates measure where the+ agent put things and print the translation that fixes it.+10. **Each rule in ONE place.** Flow and wording live in the skills; a number the code+ measures is stated where the agent reads it, in the words of the gate that measures it.++## 2. Package map```-codeverse3d/- conventions.py frames (LANGUAGE_FRAME, GLB_FRAME), units, OBJECT_VIEWS/_QUICK/_CLAY_VIEWS, SCENE_VIEWS,- to_snake/to_pascal/slugify, MAX_TRIS_*, BBOX_TOLERANCE_M, CONTACT_GAP_M (THE source)- config.py Settings (C3D_* env, ~/.config/3dcodeverse/config.yaml; Settings.backends(**overrides)- builds a Spec's Backends). ONE switch grammar: every C3D_* knob is a field, read through- get_settings() where it is used; an on/off switch is a Flag, Settings.FLAT holds the flat- spellings of nested knobs (docs/INSTALL.md §8.3)- contracts/ pydantic: common (Track, Language, Usage, Budget, Backends, TRACK_INFO registry,- ENTRY_FILE/code_file/LANGUAGE_LABEL tables), spec, plan, artifacts- (GateFinding, GateReport, BuildResult.gates, RenderView, RenderSet, Judgment), run- (+ SkillsUsage/SkillRead), chat, agent (typed AgentJob)- workspace.py run-dir layout + git snapshots- doctor.py the environment checks behind `3dcodeverse doctor` (deps, Blender, node, GPU probe, keys,- pool admission, vendor CLIs, MCP, skills)- proc.py stdlib-only subprocess + atomic-JSON primitives (ManagedProcess owns every child's- lifecycle: group kill on ANY exception, bounded pumps, stdin writer; run_subprocess,- write_json_atomic, scrub_secrets), the tolerant readers/writer (read_json_or_none,- iter_jsonl_lines, read_jsonl_lenient, append_jsonl_line), the JSONL event log (EventLog),- the run lock (ONE writer per run dir: fcntl.flock at <runs>/.locks/<slug>.lock naming the- holder, printed by `3dcodeverse status`), fan_out, sha256_file, version_line. RULE: any- stdlib-only file / JSON / JSONL helper lives HERE. A leaf: imports nothing from codeverse3d- models/ ChatModel (base.py), parts.py; gemini.py (request/response shapes, dead-key + 429 rotation);- anthropic.py openai.py; retry.py (KeyPool with outcomes ok | 429 | 5xx | error | dead | skip,- the max_in_flight cap as machine-wide flock'd slots, rotate_with_retries — the one retry- loop); pricing.py, health.py (preflight probe: no retries), schema_utils.py (strict schema),- registry.py- agents/ registry.py (the CodingAgent protocol + dispatch — every backend is a vendor CLI),- backends.py (claude-code / codex / antigravity: argv, env, each CLI's own record read back;- agy's API-mode HOME + pool key), cli_common.py (sessions, the watchdog clocks, the prompt on- stdin, the transcript, files_changed attribution, THE failure vocabulary, provider_wait),- materialize.py (workspace context files + hard rules)- languages/ LanguageRuntime + RuntimeLayout (base.py: every runtime states its file layout —- expected_files / files_for — and the tracks ask it); one module per language:- blender/ cadquery/ threejs/ urdf/ scene_threejs/ scene_blender/ glsl_shader/ opengl_python/- are each a single __init__.py (lint → skeleton → runtime) beside their data (starter/ for scene_threejs,- opengl_python/wrappers/run_gl.py; the contract text is prompts/<lang>/contract.md); wrappers/- holds the python build wrappers (run_bpy, run_bpy_links, run_cq, run_bpy_scene), the- scene_blender render driver (render_bpy_scene) and what they share (_wrapper_common,- _census, _census_glb, _finite — the NaN / inf check on everything a Blender wrapper writes).- spatial/ node.py, render.py, observe.py, tool_common.py (shared tool plumbing),- render_scene.py (judge view subset, content-fitted orbit), render_blender.py (scene_blender:- Blender pixels under a GPU slot + CPU fallback, the same metrics.json),- frame_metrics.py (scene_frames gate), frame_motion.py (measured inter-frame motion),- scene_placement.py (scene_placement gate = the check_placement tool's verdict: floating /- sunken / unsupported / interpenetration / cantilevered per placed asset; thresholds =- Settings.placement), gl_render.py (GlHost), frame_stats.py (gl_frames),- sheet.py (montage_2x2, crop_region), measure.py, connectivity.py, contract.py- (authoring-frame hints), sections.py (the cross_section tool + the judge slices), silhouette.py,- probes.py, complexity.py (objective complexity vector → Measurement.extra),- joints_model.py joints_poses.py joints_export.py joints_sweep.py joints_collide.py- (deterministic penetration; joints_sweep.sweep_gate is THE joint_sweep verdict — the round's- gate and the tool's), registry.py, tools.py (every @tool registration), mcp_server.py- (MCP name: 3dcode). Render modes are contracts.artifacts.RENDER_MODES (shaded wire normals- silhouette clay); build error_type spellings are languages/_common.MISSING_ENTRY and- BUILD_TIMEOUT for every runtime- skills/ registry.py (typed ROUTES + the router),- model.py (Skill/Selection + the SKILL.md loader), prompting.py (per-backend- discovery root + the mandate text), materialize.py, telemetry.py (the read probe: the CLIs'- own tool calls first, atime as fallback); switches are Settings fields (C3D_SKILLS*, on by- default)- cost/ types.py (CallCost/Stage/Role) ledger.py (append-only telemetry/cost.jsonl + price- provenance) context.py (per-call > ambient attribution) instrument.py (MeteredChatModel /- MeteredAgent — one row per ChatModel.generate; one session row for a backend that does NOT- meter itself; run_ledger is context-local so parallel batteries work) tally.py (a block's- money = its ledger rows, its lost seconds → StepTime) guard.py (text_tokens: the- ~4 chars/token estimate)- judges/ base.py (JudgeInput; round_input + plan_summary, the ONE payload builder the in-run judge,- `3dcodeverse judge`, calibration and eval all use), rubrics.py + rubrics/*.yaml (defect- checklists, the wire schema, caps and scoring), prompt_builder.py (image prep, montages, the- judge messages), vlm_judge.py (+ the reference/likeness judges). No Judge- Protocol: a judge is duck-typed `.judge(JudgeInput) -> Judgment`- reference.py a user `--image` against the render: the proportion check- orchestrator.py the round loop's LIBRARY, not the loop: RoundPolicy, refine-task compilation + grouping,- StageRunner + RunState (resume), BudgetGuard (the clock). The loop itself is- tracks/lifecycle.py:_round_loop → tracks/steps.py:run_round- tracks/ __init__.py (get_track(track, **options) → a lifecycle.BaseTrack), lifecycle.py, steps.py,- generation.py (agent +- single-shot strategies + the file envelope), repair.py, planner.py (the ONE planner loop + the- cached EngineeringBrief, plan budgets, and the ONE owner of what differs per track when- planning: template, example, temperature, output floor, acceptance), prompting.py (prompt- helpers), common.py (RunContext, Services), static_object.py (+ the reference-image gates),- articulated_object.py (+ the planned-motion gate), scene.py, scene_assets.py (+ cheap- single-shot asset generation), zone_layout.py (per-zone structured layout calls +- deterministic validator), graphics.py (the whole graphics track), plan_features.py- (eval-only: which C3D_* names are live, and pin_plan_blockers() deciding when two arms may- share one plan), depth.py, project_checks.py (Spec.checks: the project's deterministic checks, run on- every built round and joined to its gates as project:<name>), skills_hook.py (the round's view of codeverse3d/skills: attach- before generating, probe reads after — a no-op under C3D_SKILLS=0)- record/ what every run WRITES: record.py (finalize_record, load_record, iter_runs,- effective_judgment), deliverable.py (every round's kept build under artifacts/rNN/, and- deliverable/ for ONE round — built by addons/select), telemetry.py, git_history.py (files at- a round's commit)- addons/ optional tools that READ finished runs; outside cli/ nothing imports them- (tests/core/test_addons_boundary.py). dataset/ = export.py, pack.py, pairs.py, refine.py,- captions.py, index.py, sample.py, quality.py (tiers + code fingerprints + duplicate groups)- — `3dcodeverse flywheel …`; costreport/ = audit.py, report.py — `3dcodeverse cost`;- calibration.py (judge repeatability over recorded runs); skill_targets.py (measured targets- + claims per skill bundle); select.py (round_rows / pick / summarise / package: which round- of a finished run to hand over — `3dcodeverse pick`, and `3dcodeverse make` after the run)- addons/gallery/ THE local run gallery (`3dcodeverse gallery serve|build`): cards.py, compare.py (side-by-side- arms), index.py (run roots → typed RunEntry, tolerant of half-written records), model.py,- page.py (cards + table + filters + per-filter summary), detail.py (/run/<battery>/<slug>),- code.py (src browser), viewer.py (GLB orbit viewer on the vendored three.js), urls.py- (server vs file:// targets + content types + the traversal guard), server.py (stdlib- http.server, loopback-only), theme.py (CSS + the index-page JS)- prompts/ EVERY piece of prompt material the harness writes, and the only place it lives:- <lang>/{system,contract}.md (+ effects_catalog.md, asset.md where a language has them),- system/* (harness contract, single-shot envelope, role_{scope,asset,repair}.j2),- tracks/*.j2. catalog.py answers "what exists and how does each piece reach the model",- including the ONE per-language lookup language_prompt(language, name) / language_text.- codeverse3d/skills/ is what an AGENT chooses to read; a file that tries to be both is the- bug this split prevents- cli/ main.py (app wiring, make/resume/mcp + the doctor/tools/gallery commands), inspect_cmd.py- (judge on one existing run), layout_cmd.py (THE single-run view: `show` = STATUS /- DELIVERABLE / QUALITY EVIDENCE / COST & SETTINGS; `status` = `show --section status`),- flywheel_cmd.py, cost_cmd.py (`3dcodeverse cost`), skills_cmd.py (`3dcodeverse skills- list|show|validate|report`)-eval/bench/ the battery launcher and reports (`python -m bench.run_bench` / `bench.report`,- compare_backends.py, ab_plan.py, complexity_report.py, prompts/*.yaml); never imported by- the harness — eval/docs/EVAL.md-runtime_js/ export_glb.mjs (placement policy, instance baking, selfcheck) render_glb.mjs render_scene.mjs- probe_scene.mjs check_shaders.mjs gpu_launch.cjs serve.cjs lib/{resolve_three, scene_host,- host_coverage, host_census, host_placement, orbit, instances, census, glsl_audit, browser/…}- browser/post.js — scene post chain: GTAO + selective (emissive-mask) bloom + an optional- colour grade; ON for scene renders, `C3D_POST=0` / `--no-post` to disable-tests/ one directory per package area (the count is `pytest --collect-only`'s; the bench tests are- ../eval/tests)-```--## 3. Workspace layout--One run is one directory, `runs/<slug>/`: `src/` is the code (git, one commit per round),-`artifacts/` the last round's build plus every round's own `artifacts/rNN/`, and a pick writes-`deliverable/` + `selection.json`; `telemetry/` holds the cost ledger-(`workspace.py` names the buckets; `3dcodeverse show <slug>` walks a run).--## 4. Per-language authoring contracts (raw code; the harness owns export)--The authoritative text is `codeverse3d/prompts/<lang>/contract.md` (+ `system.md`) for each language. The harness-owned-`src/lib/` (scene_threejs effect library, `HARNESS_OWNED_SRC`) is committed with `src/`, so the deliverable and the-dataset sample carry it.--## 5. Spatial tool registry--`@tool(name, ArgsModel, description, *, tracks=(), languages=(), cost_hint)` registers-`fn(ctx, args) -> Observation` → (a) direct call from tracks, (b) the stdio MCP server (name-`3dcode`) for the vendor CLIs, (c) a native tool schema for any embedder (`ToolDef.schema()`),-(d) a prompt card. The 16 tools: `build` (every track), `measure`, `render_views`,-`render_sheet`, `isolate`, `cross_section`, `check_connectivity`, `check_contract`,-`compare_reference` (object tracks), `joint_sweep` (articulated), `shader_probe`, `scene_probe`,-`scene_views`, `check_placement` (scene), `gl_probe`, `gl_frames` (graphics).--An `Observation` carries two different answers: `ok` is the **verdict** and `failed` says the-tool **could not run** (exception, missing artefact, unusable arguments). MCP `is_error` is-`failed` alone: a negative verdict is a result whose text leads with FAIL, because a vendor CLI-retries an errored call. The MCP server bounds every payload it hands over (`MAX_TEXT_CHARS`,-`max_images_for`): no image at all on a `failed` result, one on a FAIL verdict.--## 6. Judging--`VlmJudge(rubric, model_id, n_samples)` sends **montages, not loose views**: ≤ 5 labelled 2×2-montages (shaded / geometry-only clay-or-normals / poses) + ≤ 2 detail crops at ≤ 1024 px,-shuffled per sample. The wire schema is **observe-then-score** (summary, strengths, issues,-**defect checklist**, acceptance *before* criteria). Every rubric carries binary `defects`-(id/text/penalty/cap); defect and acceptance votes are majority and-`overall = caps(weighted_mean − Σ penalties)`. Floors, deterministic caps from gate findings-(`data["kind"]`), console errors, missing must-acceptance and `missing_views` rules apply on-top; degraded verdicts are glitches, not scores.--The judge's structure facts come from the gates, rendered from the stored `GateReport` so-`3dcodeverse judge <slug>` and calibration see exactly what the in-run judge saw: on the static track-the connectivity gate's **contact ledger** (parts / contacts / floating / deepest overlap, the-plan's PLANNED JOINS as contact or OPEN with the gap, the lowest point above the floor); on an-object-track round whose connectivity gate carries an ERROR, the payload grows **cross-section-slices** (`Settings.judge.slices = "on-error"`): `spatial.sections.judge_slices` cuts the round's-GLB on the two vertical centre planes, red hatch only on the gate's ERROR penetration pairs,-appended after the montages with a factual rig-text block. A clean round's payload is-byte-identical to the unconditional one (test-pinned).--`ReferenceJudge` for image-conditioned specs. Rubrics (pass threshold 0.70 unless named):-`static_object` (0.72), `articulated` (requires pose views: the `missing_pose_sheet` cap), `scene`-(placement caps floating 0.60 / sunken 0.65 / interpenetration 0.70 / scale 0.75 / free_exempt-0.75 measured by `scene_placement`, frame-gate caps dark/blown/flat/content_small, graded-must-acceptance), `asset`, `reference`, `shader` (graphics, `gl_frames` caps; also the-`LikenessJudge` default).--The default judge is `gemini:gemini-4-argon` (`Settings.default_judge`) with-`judge.thinking=medium`. **Calibration** (`addons/calibration.py`) re-judges recorded rounds-with repeated samples. The pro/flash measurements in `eval/docs/EVAL.md` §6 describe those-models; they do not establish Argon's variance or accuracy.--## 7. Run pipeline (all tracks)--A run is three parts, and only the first is a graph.--**7.1 The pre-round stages — declared, one tuple per track.** `BaseTrack.stages` is a tuple of-`StageNode`s, walked by `lifecycle.run_stages` over `StageRunner`. The block below is drawn from-those declarations (`tests/install/test_docs.py` fails when it drifts, printing the block to-paste):--```stage-graph-static_object plan → skeleton → materialize* → round 0-articulated_object plan → skeleton → materialize* → round 0-scene plan → skeleton → materialize* → (assets ∥ env ∥ layouts?) → clock* → asset_api* → zones → clock* → assemble → round 0-graphics plan → skeleton → materialize* → round 0+harness/+ .claude-plugin/plugin.json .codex-plugin/plugin.json plugin.json the three manifests (name 3dcodeverse)+ bin/3dcode launcher: $C3D_PYTHON | .venv/bin/python | python3, PYTHONPATH=<plugin>, python -m codeverse3d.cli+ skills/3d-director/ the workflow + references/plan-<track>.md (what plan.json holds per track)+ skills/3d-lang-<lang>/ one per language: files, frame, sandbox, thresholds + references/interface.md+ skills/c3d-*/ craft bundles (optional practices for one defect class each)+ agents/3d-judge.md the judge subagent+ codeverse3d/+ cli.py `3dcode`: argparse generated from the tool registry's pydantic arg models+ config.py Settings (binaries, limits, render) via C3D_*; resolve_blender()+ conventions.py THE frames / units / naming / view presets / thresholds shared by code+ doctor.py python -m codeverse3d.doctor+ contracts/ data-only models: Spec, Plan (Static / Articulated / Scene / Graphics), artifacts (BuildResult, GateReport, Measurement)+ languages/<lang>/ runtime per language: lint, build, wrappers (the exporters), starter files+ spatial/ measure, connectivity, contract, sections, sheet, render (three.js / Blender / moderngl), joints_*, scene_placement, probes, registry + tools+ gates.py the per-track gate assembly and judged-view rig (`check`, `judge-pack`)+ judges/rubrics/*.yaml the rubrics (criteria, anchors, defects, caps); rubrics.py parses a judgment and scores it+ judges/prompt_builder.py montage / crop planning and the brief+ runtime_js/ [email protected] + puppeteer: render_glb.mjs, the scene runner, the post chain, resolve_three.mjs+ setup.sh pyproject.toml README.md CLAUDE.md docs/```-`→` in order; `(a ∥ b)` siblings side by side, each its own cached stage, timed as ONE step of-the run's minutes, a failing sibling raised after every sibling has finished and cached; `?` runs-under a `Settings` switch (`layouts`: `zone_layouts`, on); `*` is not cached — it runs every-session. Every other stage is cached under its key (`stages/<name>.json`): what its result-depends on, named in the declaration. **Once rounds exist** a recorded stage is served whatever-its key (`stage.frozen`), and the skeleton never runs at all; `3dcodeverse resume --force` is the one-way to regenerate a stage under them: it archives the round journal + `record.json` to-`rounds/pre_force/` and the run starts again at round 0. The plan itself is `run()`'s, before-the graph (`plan_stage_key`).--What the scene stages do: `assets` — both kinds climb one ladder (single-shot → check → one-repair → agent; blender_glb heroes get a sub-workspace with the static planner's parts + asset-judge + one re-judged fix pass, undone when worse); `env` — `env_file` (`src/env.js` /-`src/env.py`): a `shared_tree` session credited with its own file only; when that file was not-written, ONE single-shot recovery runs before the zones, checked by `SceneRuntime.check_env` (the-env module alone lints, builds and lights what it builds), one repair on failure, the placeholder-restored if it still fails. An env that lights nothing is a `scene_probe` ERROR, so the ROUND's-build fails and its repair is handed the env. `layouts` — per-zone layouts (planner calls, never-fatal); `asset_api` — what the zones are told about the assets; `zones` — ONE session owns every-zone file; `clock` — the run stops here when the hard budget is spent, after the zones are-recorded; `assemble` — `scene.js`, deterministic.+## 3. The workspace-**7.2 The round — `steps.run_round`, a fixed chain in code.** Nothing in a round can be cached-(every step reads the git tree the step before it wrote). **7.3 The round loop —-`BaseTrack._round_loop`, a state machine in code**: each round's tasks come from the previous-round's verdict.+A 3D project is a directory. Every instrument takes `--workspace DIR` (absolute; default+`$C3D_WORKSPACE`, else the cwd), handled once in the CLI; `spec.json` is re-read on every call.```-round 0 "baseline": generate → build_with_repair → measure → gates → render → post-render gates → judge- object tracks: ONE session drafts the WHOLE object — every part file + the entry — each file written once and- then edited; a part still the skeleton's box is a `placeholder_part` contract ERROR-then max_rounds refine rounds, EACH built on the round before it — a FIXED count: no pass, plateau or regression stop- refine tasks = the previous round's gate ERRORS (fix hints, authoring-frame numbers) ∪ failed must-acceptance- ∪ its judge improvement plan (≤ 6 tasks, ≤ 6 compacted instruction lines each; a placeholder part's ERROR first)- fan out when the track allows it (scene: zones/assets/env) AND ≥ 2 file-disjoint groups AND every task maps to- files; the object tracks never fan out: ONE session edits the whole object in place, told to make targeted edits,- never whole-file rewrites; its window ends RoundPolicy.judge_reserve_s before the run's hard ceiling so the- round is still built and judged; a single-shot refine is fenced to the files its tasks name- generate → build+repair (error-focused, escalates on identical signatures) → gates → render → judge- → commit src/ (the round's commit) and copy its build to artifacts/rNN/- a round left without a verdict (judge outage / degraded) is re-judged once before the next is planned, and so- is the LAST round before the run ends (still none → judge_unavailable)- a round that raises mid-way still reports what it burned (record.extra['aborted_rounds'])- a round whose every task failed raises RoundFailed, TYPED: .quota → agent_quota; .transient (a provider- failure) or .stalled (the watchdog found a session hung) → the SAME round re-runs once, baseline included;- neither → no_change (a refine round) / the run fails (the baseline)- a refine round launches only while RoundPolicy.can_open — judge_reserve_s plus min_session_s left on the hard- clock (else round.skipped_budget → budget); a budget stop after refine sessions changed src/ gets ONE bounded- grace and a no-generation round that builds, renders and judges those edits (BaseTrack._salvage)-stop reasons: max_rounds | budget (the wall clock — BudgetGuard / max_minutes) | agent_quota | no_change |- no_refine_tasks | judge_unavailable | failed-finalise: the workspace ENDS AT THE LAST ROUND; finalize_record → record.json. No best round, no deliverable/-after the run (`3dcodeverse make`, unless --no-pick): addons/select.pick(by="score") — rounds without a project:* /- contract_fixed ERROR first, then highest effective score, ties → fewer gate errors → the earlier round — then package(): deliverable/ + selection.json+spec.json track, language, prompt, constraints {must_have, must_not, dimensions_m, style}, references, fixed_parts, checks+plan.json the agent's plan, validated and normalised by `validate-plan`+src/ the agent's raw code (scene: public/ for compiled assets)+artifacts/ object.glb / meshes/, renders/, measurement.json, build.json, gates.json — instrument output, read-only+judge/rNN/ brief.md + montages (judge-pack) · judgment.json (the judge) · score.json (score)```-Track-specific gates: static `connectivity` + `contract` (+ `reference_silhouette`); articulated-+ `joint_sweep` + `motion_direction`; scene `scene_placement` (per placed asset — a direct child-of a zone root — foot-column gap to the surface beneath, burial depth, water, contacts and 3-D-interpenetration pairs from `runtime_js/lib/host_placement.mjs`; every other root is scenery,-never a row, but still supports, buries, holds and clips the zone assets) + `scene_frames` (`spatial/frame_metrics.py`: dark/blown/flat frames, camera in geometry, content-too small, `no_motion` — the first and last animation frame of one camera diffed, the per-camera-"% of pixels changed" handed to the judge as a fact — and `unused_glb_asset`, from the geometry-UUIDs the scene host records per loaded GLB); graphics `gl_frames`-(NaN/black/blown/static/flicker). A build's OWN gate reports ride `BuildResult.gates` — scene-`scene_probe` + `shader_preflight`, graphics `gl_frames` — and `steps.run_round` appends them to-the round's gates after the track's (a failed build's too: a shader compile error is what routes-the shader-traps skill). `scene_probe` also holds the scene draw budget: the census's-`totals.draws` WARNs past `conventions.DRAWS_WARN_SCENE` and fails the build past-`MAX_DRAWS_SCENE`; no gate or judge reads fps.--## 8. Cost and time--`docs/RUNBOOK.md` §2 gives expected cost and time per track. `3dcodeverse cost <slug>` prints a-run's recorded spend.+## 4. The instruments (`3dcode <subcommand> --workspace DIR [--flag value]`)-## 9. Known limits+Every call prints the verdict first (`PASS` / `FAIL` / `ERROR`), then numbers and fix hints,+then the absolute paths of the PNGs it wrote; `--json` prints the result as JSON. Exit 0 =+the tool ran (a FAIL is exit 0); non-zero = it could not run. Tool names and their arguments+come from the `@tool` registry (`spatial/registry.py`, `spatial/tools.py`): one definition →+python function + argparse subcommand (kebab-case; a list argument is a repeated flag).-* Judge: recorded flash measurements are lenient/noisy on fine distinctions (overall std- ≈ 0.08–0.12 at n=3); its dynamic range comes from the defect checklist. Calibrate the- selected model with repeated samples before using small score differences for decisions.- Detail crops are position-heuristic (no 2D part boxes).-* Scene judging is deliberately narrow: the judge sees the scene's OWN cameras plus at most four- overview-rig tiles; the harness's eye-level rig is a diagnostic only. A `must` acceptance item- the harness cannot verify caps a round at 0.60 AND fails its verdict, so on the scene track- only the spec's `must_have` list keeps that priority (the plan's own checklist is `should`).-* Articulated: candidate selection uses the quick 4-view rig plus the sweep's pose views; mimic- joints are honoured; the sweep is O(links² × poses).-* Scenes: fps is a record only (the draw count is what is gated); camera-in-geometry can miss- open-back enclosures.-* threejs: textures are stripped on GLB export; `userData.tick` cannot survive export.-* agy has no per-workspace MCP: each session gets a HOME of its own with the 3dcode server in it.- A killed agy session books no usage; a killed codex session books an ESTIMATE (ledger- `source="estimate"`); a killed claude-code session books its per-message usage, whose output- side is a floor.-* Vendor sessions see only the routed skill bundles, except agy (5 built-ins; no per-session- switch) and any user-level skill root codex might grow.-* Anthropic / OpenAI backends are mock-tested only.-* Budget checks run between steps: a round the clock cuts mid-way is rolled back (its spend- stays in `aborted_rounds`) — give scenes `--max-minutes 60`.-* A sustained Gemini outage can still fail a round (`3dcodeverse resume` re-uses cached stages). A- storm-dead agent session gets the round loop's ONE transport retry (fresh key), no single-shot- fallback.--## 10. Flywheel+| subcommand | tracks | does |+|---|---|---|+| `init --track --language --prompt [--must]* [--must-not]* [--dim k=v]* [--reference path]*` | all | writes `spec.json`, the layout and the language's starter files; prints the entry files and the skill to read |+| `validate-plan` | all | validates `plan.json` against the track's plan model + the deterministic plan checks (placeholder echo, hard quality complaints, acceptance present, fixed-part clash); writes the normalised plan back; FAIL lists each error with its JSON path |+| `build` | all | lint + build with the language runtime, export, measure; `artifacts/build.json` |+| `check` | all | build + measure + every gate of the track → `artifacts/gates.json`; the round's verdict |+| `judge-pack --round N` | all | renders the judged views, post-render gates, composes the montages/crops, writes `judge/rNN/brief.md` + images; needs a prior `check` in the same state |+| `score --round N` | all | parses `judge/rNN/judgment.json` strictly, applies weights, penalties, floors and the gate caps from `gates.json` → `score.json`; prints overall, passed, caps, the improvement list |+| `measure [--parts]*` | object | bbox / extents, ground gap, per-part size / tris / islands |+| `check-contract` | object | built GLB vs `plan.json`: missing parts, bbox deltas, overall size, ground contact |+| `check-connectivity` | object | contact graph: floating parts (with the gap vector), interpenetration, stray islands |+| `cross-section [--axis x|y|z] [--at 0..1] [--parts]*` | object | a labelled section image + loops / area / hollow ratio |+| `render-views [--views]* [--mode shaded|wire|…] [--isolate]* [--explode f] [--size px]` | object | named camera views + a contact sheet |+| `render-sheet [--mode]` | object | the 14-view labelled contact sheet |+| `isolate --part NAME [--views]*` | object | one part alone + its measurement row |+| `compare-reference [--view] [--reference-index i] [--size px]` | object | a render beside a reference image |+| `joint-sweep [--joints]*` | articulated | every joint through its range + random combinations; overlap depths; limit poses rendered |+| `shader-probe` | scene_threejs | compiles every ShaderMaterial headlessly |+| `scene-probe` | scene | census, draw / triangle counts, console errors |+| `scene-views [--cameras authored|orbit|all] [--times]*` | scene | authored cameras and/or the overview rig; the frame table and measured motion |+| `check-placement [--rebuild]` | scene | every placed root: floating / sunken / unsupported / interpenetration with the metres to move it |+| `gl-probe [--t s]` | graphics | compile / import + one frame with stats |+| `gl-frames [--times]* [--width] [--height]` | graphics | the judged frames, per-frame metrics and the gl_frames gate |++## 5. Gates (what `check` runs per track; thresholds are stated verbatim in the `3d-lang-*` skills)++* **object tracks**: lint; `check_contract` (per-part and overall bbox within+ max(10 mm, 10 %) per axis, WARN / 3 × ERROR; ground within 10 mm WARN / 30 mm ERROR;+ footprint centring; `placeholder_part`); `check_connectivity` (contact ≤ 2 mm; penetration+ > 2 mm WARN, > 10 mm ERROR; floating ERROR; islands < 5 % WARN); `detail_budget` (triangle+ floor / ceiling and build time from parts × instances); fixed parts; project checks.+ Articulated adds the FK check, `RestPenetration`, `joint_sweep` and `motion_direction`.+* **scene**: `scene_placement`, `scene_probe` (census, budgets, world / atmosphere, drivers),+ shader preflight (three.js), then after rendering `scene_frames` (exposure, camera, content)+ and `frame_motion`, `hero_unseen`.+* **graphics**: lint; `gl_frames` (NaN, black / blown, static, flicker, low detail).-`record.json` per run + git history; `3dcodeverse flywheel export` writes sample folders-(`<out>/<track>/<language>/<slug>/{code.<ext>, src/**, robot.urdf, meta.json, captions.json,-renders/}`) of the PICKED round (the last built round when none was judged) with **quality-tiers** from that round's verdict (A passed & 0 gate errors, B passed, C score ≥ 0.6, D else),-acceptance checklists, gate summaries and `(code fingerprint, prompt)` dedupe-(`--drop-duplicates`; side-car captions via `--captions-dir`); `metadata.parquet`/`.jsonl` carry-tier, gate errors, cost, fingerprints, `duplicate_of`; `--pack` tars with byte-range locators.-`flywheel pairs` emits preference pairs (round i < j by judge Δ ≥ τ) and round-level repair-pairs; `flywheel refine` emits the loop's OWN transitions — one row per (round i → round i+1)-where the harness asked for a change, carrying what condemned the round, the instructions-written in response, both code snapshots and whether the score moved-(`addons/dataset/refine.RefineTransition`). That is the supervision the harness produces that a-one-shot corpus cannot. `finetune/llamafactory/` turns those rows into training files; the-harness writes the measurement, not the trainer's format. `flywheel caption` adds {detailed,-instruction, factory} captions (`--out` for side-car mode); the gallery is `3dcodeverse gallery build---embed`.+## 6. Judging-`codeverse3d/addons/gallery/` is the **local** answer to the same question: `3dcodeverse gallery-serve` indexes `runs/` + every `eval/bench/out/*/runs`, serves the page **and the run-directories** on 127.0.0.1 (sheet, renders, `src/`, `object.glb` in an orbit viewer built on the-vendored three.js, `record.json`), and re-reads a run's record per request so a battery that is-still writing shows up live (RUNBOOK §4). A URL can only name a `(battery, slug)` the scanner-found under a declared root, and `urls.safe_join` refuses anything that escapes that run-directory. `3dcodeverse gallery build [--embed]` writes the same page as one file.+`judge-pack` renders the track's judged views (objects: the 14-view rig + detail and contact+crops; articulated: plus the pose sheet; scenes: every authored camera at t = 0 and 1.5 s plus+the overview rig; graphics: the frame sheet), composes labelled 2 × 2 montages, and writes+`brief.md`: the request, the plan digest, the acceptance items, the measured numbers and gate+facts, the rubric's criteria with anchors, the binary defect checklist with penalties and caps,+and the EXACT JSON the judge returns (`criteria`, `summary`, `strengths`, `issues`,+`improvement_plan`, `acceptance`, `defects`). The `3d-judge` agent reads only that folder and+writes `judgment.json`. `score` parses it strictly (`judges/rubrics.py`), fills measured+criteria from code, applies weights, subtracts defect penalties, applies floors, then the caps+from `gates.json` (build error 0; floating 0.60; penetration 0.70; contract violation 0.75;+an unmet `must` acceptance item 0.60 / 0.70 on graphics; the per-track measured caps), and+prints the improvement list with gate ERRORs first. Rubrics: `static_object`, `articulated`,+`scene`, `shader`, `asset`, `reference` under `judges/rubrics/`.++## 7. Known limits++* The judge is the host's model; its calibration is the host's. The rubrics were calibrated+ on Gemini-class judges (the historical numbers live in the flywheel's docs).+* `scene_threejs` heroes (`blender_glb` assets) are built in a separate `static_object`+ workspace and copied into `public/assets/`; nothing automates that.+* No run record, cost or telemetry is kept here; `flywheel/` reads old records.diff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.mdindex aa8d78b2..2a931bf7 100644--- a/harness/docs/INSTALL.md+++ b/harness/docs/INSTALL.md@@ -1,497 +1,100 @@-# Installing the 3dcodeverse harness--Paths are relative to the harness root (`harness/` in the 3dcodeverse checkout) unless absolute.-Once installed, read `docs/RUNBOOK.md` (how to run) and `docs/ARCHITECTURE.md` (what a run-does).--1. [TL;DR](#1-tldr) · 2. [Prerequisites](#2-prerequisites)-(incl. [supported versions](#21-supported-versions)) ·-3. [Get the code](#3-get-the-code) · 4. [Python package + extras](#4-python-package--extras) ·-5. [runtime_js — the node side](#5-runtime_js--the-node-side) · 6. [Blender](#6-blender) ·-7. [GPU / headless rendering](#7-gpu--headless-rendering) ·-8. [Keys, CLIs and settings](#8-keys-clis-and-settings) ·-9. [Verify — `3dcodeverse doctor`](#9-verify--3dcodeverse-doctor) ·-10. [5-minute smoke](#10-5-minute-smoke) · 11. [Uninstall / cleanup](#11-uninstall--cleanup)-----+# Installing 3dcodeverse## 1. TL;DR```bashgit clone <repo> 3dcodeverse && cd 3dcodeverse-python3 -m venv .venv && source .venv/bin/activate # see §3 — a distro python3 is- # PEP 668 and pip will refuse it-bash harness/setup.sh # python + node deps + chrome + the agy / claude / codex CLIs + doctor+bash harness/setup.sh # python package (`3dcode`) + runtime_js + headless Chrome + doctor+python -m codeverse3d.doctor # what was found: python, node, Chrome/WebGL, Blender, cadquery, moderngl, GPU```--`setup.sh` is idempotent — it checks the interpreter versions, runs-`pip install -e 'harness[all,dev]'`, runs `npm ci` in `runtime_js/` **only when the lockfile-actually moved**, makes sure puppeteer's Chrome is downloaded, brings the three coding-agent-CLIs to their latest release (§8.2), and finishes by printing `3dcodeverse doctor`. Flags:-`--extras cad,urdf`, `--python /path/to/python`, `--no-python`, `--no-node`, `--no-chrome`,-`--no-clis`, `--no-doctor`, `--no-gpu`, `--force-npm`, `--help`.--The manual equivalent:-+`setup.sh` is idempotent: `pip install -e 'harness[all]'`, `npm ci` in `harness/runtime_js`+only when the lockfile moved, puppeteer's Chrome when its cache is missing, then doctor.+Options: `--extras LIST`, `--python PATH`, `--no-python`, `--no-node`, `--no-chrome`,+`--no-doctor`, `--no-gpu`, `--force-npm` (`npm ci` deletes `node_modules/` first — never while+a build is running). By hand:```bash-pip install -e 'harness[all,dev]'-cd harness/runtime_js && npm ci && npx puppeteer browsers install chrome && cd ..-curl -fsSL https://antigravity.google/cli/install.sh | bash # agy (later: `agy update`)-npm i -g @anthropic-ai/claude-code@latest @openai/codex@latest # the optional generators-3dcodeverse doctor+python -m venv .venv && source .venv/bin/activate # python 3.13+pip install -e 'harness[all]'+(cd harness/runtime_js && npm ci && npx puppeteer browsers install chrome)```-> **Running installs on a busy box.** `npm ci` deletes `node_modules/` before re-creating it,-> and `pip install -e` rewrites the entry points. If benches or renders are running against-> this checkout, use `setup.sh --no-clis` (it skips `npm ci` when the lockfile is unchanged) or-> wait for them to finish.-----+Then install the plugin into each host you use (§4).## 2. Prerequisites-### 2.1 Supported versions--One fixed Python version — **3.13** — no floor, no matrix, no compatibility shims, and no CI: the-offline suite and `ruff` are run locally before every push (see `CLAUDE.md`).--| component | version | how it is enforced | notes |-|---|---|---|---|-| **python** | **3.13** | `requires-python = ">=3.13"`; ruff `target-version = "py313"`; `PY_FLOOR` in `tests/core/test_portability.py`; `MIN_PY_MINOR` in `setup.sh` | the four places are pinned together by the portability test |-| **node** | **20.6.0+** (developed on 24 LTS) | `runtime_js/package.json` `engines.node`; `codeverse3d.spatial.node.NODE_MIN` fails every node workload with an actionable message | 20.6 is the `--import` module-hook floor |-| **Blender** | **5.2 LTS** only | `BLENDER_MIN = (5, 2)` in `codeverse3d/config.py`; `3dcodeverse doctor` fails anything older; `Settings.resolve_blender()` | `blender`, `urdf_blender` and `scene_blender` are the users; the prompts and lints state 5.2 API facts |-| **OS** | Linux x86_64 (WSL2 works) | — | macOS should work (nothing is Linux-specific except `resource.setrlimit` guards) but is not tested |--Moving to another Python later is the same four-line change (`requires-python`, ruff-`target-version`, `PY_FLOOR`, `MIN_PY_MINOR`).--### 2.2 What you need installed--| what | required? | how it degrades without it |+| need | required? | without it ||---|---|---|-| **Python 3.13** | yes | nothing runs; `requires-python = ">=3.13"` (§2.1) |-| **pip + venv** | yes | `setup.sh` cannot install the package. A stock Debian/Ubuntu `/usr/bin/python3` ships **without** pip and is PEP 668 `EXTERNALLY-MANAGED`, so `pip install -e harness` refuses even once pip is present: `sudo apt install python3-venv python3-pip`, then use a virtualenv |-| **git** | yes | run workspaces are git repos (one commit per round); `Workspace.create()` and the flywheel pair miners fail |-| **node ≥ 20.6** | yes, except for the `graphics` track | the `threejs` / `scene_threejs` languages disappear **and no object renders happen at all**: `spatial/render.py` renders *every* GLB (Blender-built and CadQuery-built included) with three.js in headless Chrome. Only `graphics` (moderngl) is node-free |-| **Blender 5.2 LTS** | optional | `blender`, `urdf_blender` and `scene_blender` languages unavailable → the `static_object` default language and the whole `articulated_object` track cannot build (`BlenderNotFoundError`); scenes lose planner-chosen bpy GLB assets |-| **EGL-capable GPU stack** | optional | headless Chrome falls back to **SwiftShader** and moderngl to **llvmpipe** — everything still renders, just several times slower; no correctness change |-| C toolchain | usually no | only if pip has to build a wheel from source (`python-fcl` ships wheels for cp310–cp313 x86_64) |--Disk: ~100 MB for `runtime_js/node_modules`, ~640 MB for puppeteer's Chrome, ~1 GB for a-Blender tarball, plus whatever `runs/` and `~/.cache/codeverse3d` grow to.-------## 3. Get the code--```bash-git clone <repo> 3dcodeverse-cd 3dcodeverse-```--Layout: the harness is the `harness/` subdirectory (python dist `3dcodeverse`, import package-`codeverse3d`, CLI `3dcodeverse`). See the repo `README.md` for the other-top-level components.--Use a virtualenv or a conda env. It is only optional when your interpreter already owns its-site-packages: a distro `/usr/bin/python3` is PEP 668 `EXTERNALLY-MANAGED` and pip will refuse-to install into it. `setup.sh` checks for pip and for that marker up front and tells you which-of the two you hit.--```bash-python -m venv .venv && source .venv/bin/activate # or: conda create -n c3d python=3.13-```-------## 4. Python package + extras--```bash-pip install -e harness # core only-pip install -e 'harness[all,dev]' # everything (what setup.sh does)-```--`-e` (editable) is the intended mode: the harness is developed in place and the console script-`3dcodeverse` points back at the checkout.--Core dependencies (always installed): pydantic + pydantic-settings (contracts, settings), typer +-rich (CLI), jinja2 (prompt templates), pyyaml, numpy, trimesh (mesh measurement), python-fcl-(collision), pillow, google-genai, anthropic, openai.--| extra | pulls | unlocks |-|---|---|---|-| `cad` | cadquery | the `cadquery` language (`--language cadquery`) |-| `urdf` | yourdfpy, scipy | the `articulated_object` track: URDF parse/validate + joint math |-| `graphics` | moderngl | the `graphics` track (`glsl_shader`, `opengl_python`) — headless GL rendering in `spatial/gl_render.py` |-| `mesh` | shapely, networkx, matplotlib | `cross_section` (filled area / hollow ratio from shapely, the image drawn in matplotlib), mesh split / connectivity (networkx), judge cross-section slices on gate-ERROR rounds (without the extra the judge logs a warning and sends the payload without slices) |-| `mcp` | mcp | `3dcodeverse mcp` / `codeverse3d.spatial.mcp_server`, i.e. spatial tools for the `agy`, `claude-code` and `codex` backends |-| `flywheel` | pyarrow | `3dcodeverse flywheel export --pack` (parquet shards). A plain `flywheel export` needs nothing: without pyarrow it writes `metadata.jsonl` and skips `metadata.parquet` with a warning |-| `all` | all of the above | — |-| `dev` | pytest, pytest-timeout, ruff | the test suite and the linter |--`graphics`, `mesh`, `mcp` and `flywheel` are lazily imported: without them the harness installs-and starts fine and only the named feature raises `ImportError` at the moment you use it.-`3dcodeverse doctor` lists every one of these modules under `python deps` and only tolerates the-optional-extra modules — `shapely` (mesh), `yourdfpy` (urdf), `mcp`, `moderngl` (graphics),-`cadquery` (cad) — as WARN, naming the extra to install; everything else missing is a FAIL.--Run the offline test suite to confirm the install:-+| **Python 3.13** + pip + venv | yes | nothing runs (`requires-python = ">=3.13"`). Debian/Ubuntu: `sudo apt install python3-venv python3-pip`, then a virtualenv (PEP 668) |+| **node ≥ 20.6** | yes, except for the `graphics` track | the `threejs` / `scene_threejs` languages disappear and NO object renders happen: every GLB (Blender- and CadQuery-built too) is rendered with three.js in headless Chrome |+| **Blender 5.2 LTS** | for `blender`, `urdf_blender`, `scene_blender` | those languages raise `BlenderNotFoundError`; `articulated_object` cannot build |+| **cadquery** (extra `cad`) | for `cadquery` | that language is unavailable |+| **moderngl** (extra `graphics`) | for `glsl_shader`, `opengl_python` | the `graphics` track is unavailable |+| **EGL-capable GPU stack** | optional | headless Chrome falls back to SwiftShader and moderngl to llvmpipe — same results, several times slower |++Disk: ~100 MB `runtime_js/node_modules`, ~640 MB puppeteer Chrome, ~1 GB a Blender tarball.+Extras: `cad` (cadquery), `urdf` (yourdfpy, scipy), `graphics` (moderngl), `mesh` (shapely,+networkx, matplotlib — cross-section area, mesh split, judge slices); `all` is every one.+`doctor` reports a missing extra's module as WARN naming the extra; everything else missing is+FAIL.++### Blender+Blender 5.2 LTS is the one supported version (`BLENDER_MIN = (5, 2)` in `codeverse3d/config.py`).```bash-cd harness-python -m pytest tests -q # needs node + Blender for the full set-python -m pytest tests -q -m "not live and not blender and not node" # pure-python subset-# Parallel by default (pytest-xdist, -n auto --dist worksteal). Serial: add -n0.-python -m pytest tests -q -m live # OPT-IN: real API calls, needs keys-```--Live tests are deselected by default (`addopts = ["-m", "not live"]` in `pyproject.toml`), so a-bare `pytest` never spends money and never hangs waiting on a provider outage. A command-line-`-m` **replaces** that default rather than adding to it, so any subset you select must spell-`not live` itself — as the line above does.-------## 5. runtime_js — the node side--Node.js itself is a *system prerequisite* you install once (§2). `runtime_js/` is a small **npm-package owned by the harness**, and `node_modules/` is that package's dependency tree, downloaded-by npm into the checkout. Apart from the `graphics` track, every render in the harness goes-through it (`spatial/render.py` → `render_glb.mjs` → three.js in headless Chrome), whichever-language produced the GLB.--```-harness/runtime_js/- package.json committed — 2 direct deps- package-lock.json committed — exact tree, the reproducibility unit- node_modules/ NOT committed — .gitignore'd, ~100 MB, created by `npm ci`- *.mjs *.cjs lib/ the harness's own node code (see runtime_js/README.md)-```--Direct dependencies: `three` (GLB export, the render rig, the scene host, GLSL preflight) and-`puppeteer` (headless Chrome for WebGL rendering).--### Install / refresh--```bash-cd harness/runtime_js-npm ci # exact lockfile install-npx puppeteer browsers install chrome # only if the Chrome cache is missing (see below)-```--Use **`npm ci`**, not `npm install`: `ci` installs exactly what `package-lock.json` pins and-never rewrites it, which is what keeps renders reproducible. `npm ci` **deletes-`node_modules/` first**, so do not run it while a bench or render is using this checkout. Re-run-it when `node_modules/` does not exist (fresh clone), when you pulled a change to-`runtime_js/package.json` / `package-lock.json`, or when `3dcodeverse doctor` reports `three` or-`puppeteer` FAIL. `setup.sh` automates exactly that test (`--force-npm` overrides).--### Chrome--puppeteer downloads its own Chrome build (it does **not** use a system Chrome) into-`~/.cache/puppeteer` (~640 MB). npm's `postinstall` normally does this for you; run the explicit-command when the cache was cleared or when `PUPPETEER_SKIP_DOWNLOAD` was set:--```bash-cd harness/runtime_js && npx puppeteer browsers install chrome-```--Re-running it is a no-op that just prints the cached path. `PUPPETEER_CACHE_DIR` moves the-cache elsewhere (keep it consistent between install and run).--### Why generated code never sees this directory--Agent-written Three.js code is **raw** — it does `import * as THREE from 'three'` and nothing-else; it never imports a harness module and never gets a `node_modules/` of its own inside the-run workspace. The harness resolves that bare specifier for it in two places:--* **node**: `node --import runtime_js/lib/resolve_three.mjs …` installs a `registerHooks`- resolver that redirects `three` and `three/addons/*` into `runtime_js/node_modules`, for a- module living anywhere on disk (`NODE_PATH` cannot do this — it is CommonJS-only). Python- side: `spatial.node.run_node(..., three_hook=True)`.-* **browser**: `serve.cjs` mounts `runtime_js/` at `/__runtime/` on the loopback server and- `importMapHtml()` emits an import map pointing `three` at- `/__runtime/node_modules/three/build/three.module.js`. Nothing is ever fetched from a CDN.-------## 6. Blender--Optional, but the `static_object` default language, the entire `articulated_object` track and-the `scene_blender` scene language need it. **Blender 5.2 LTS is the one supported version**-(`doctor` fails anything older).--Option A — distro package (only if it ships 5.2 LTS):--```bash-sudo apt-get install blender # or: brew install --cask blender-```--Option B — official tarball (no sudo needed); verify the checksum against-<https://download.blender.org/release/Blender5.2/blender-5.2.2.sha256>:--```bash-mkdir -p ~/tools && cd ~/toolscurl -LO https://download.blender.org/release/Blender5.2/blender-5.2.2-linux-x64.tar.xz-tar xf blender-5.2.2-linux-x64.tar.xz-~/tools/blender-5.2.2-linux-x64/blender --version # Blender 5.2.2 LTS-```--### Missing X11 libraries (no sudo)--The stock Linux build links `libSM.so.6` / `libICE.so.6` even in `--background` mode. If they-are not installed system-wide, extract them from the distro packages into a directory of your-own and put a one-line wrapper on `PATH` named `blender-5.2` (the first name the harness looks-for):--```bash-#!/bin/bash-BLENDER_HOME="${BLENDER_HOME:-$HOME/tools/blender-5.2.2-linux-x64}"-export LD_LIBRARY_PATH="$HOME/.local/xlibs/usr/lib/x86_64-linux-gnu:${LD_LIBRARY_PATH}"-exec "$BLENDER_HOME/blender" "$@"-```--### Rendering--`languages/wrappers/render_bpy_scene.py` owns every render setting for `scene_blender`'s judged-frames: Cycles on CUDA with GPU denoising and persistent data when a CUDA device exists, CPU-otherwise; `Settings.render.blender_frame_time_limit_s` (default 20 s) caps a heavy scene's-sampling per frame. **OptiX is never enumerated** (it is unavailable under WSL2 and probing it-crashes Blender). `3dcodeverse doctor` times one small frame on exactly this path.--### How the harness finds it--`Settings.resolve_blender()` (`codeverse3d/config.py`) returns the first hit of:--1. `settings.binaries.blender` when it is set — in the settings YAML or with- `C3D_BINARIES__BLENDER=/path/to/blender`. A configured binary is never replaced by one from- `PATH`: if it is missing or not executable, builds raise `BlenderNotFoundError` and `doctor`- reports `blender FAIL`;-2. only when nothing is configured: `blender-5.2`, then `blender` on `PATH`.--Nothing found → `3dcodeverse doctor` reports `blender FAIL` and builds raise-`BlenderNotFoundError`. Blender is always invoked `-b --factory-startup` with-`PYTHONPATH`/`PYTHONHOME` stripped from the child env, so your conda env cannot leak into bpy.-------## 7. GPU / headless rendering--Nothing to install beyond the `graphics` extra (§4) and `runtime_js` (§5) — the harness picks-the backend itself and both paths have a software fallback.--* **Three.js / scenes** → headless Chrome via `runtime_js/gpu_launch.cjs`, which tries- `--use-angle=gl-egl` plus the Mesa d3d12 env and probes `UNMASKED_RENDERER`; a negative- verdict is cached 20 minutes in `~/.cache/codeverse3d/gpu_probe.json`, and it falls back to- SwiftShader. Force with `C3D_RENDER_GPU=on|off|auto` (node side) or `render.gpu` in the- settings YAML / `C3D_RENDER__GPU`.-* **graphics track** → moderngl in a fresh subprocess per render (`spatial/gl_render.py`), which- sets `GALLIUM_DRIVER=d3d12` + `MESA_LOADER_DRIVER_OVERRIDE=d3d12` first and retries with- `LIBGL_ALWAYS_SOFTWARE=1` + llvmpipe if the context cannot be created. You do not set these- yourself.--On a headless Linux server without a GPU, both fallbacks work out of the box; expect renders to-take a few times longer. On WSL2 you need the vendor's WSL driver installed on the Windows side-for the d3d12 path — check with `3dcodeverse doctor`'s `chrome webgl` row.-------## 8. Keys, CLIs and settings--### 8.1 Model API keys--| variable | needed for | notes |-|---|---|---|-| `GEMINI_API_KEYS` | all `gemini:*` models (planner, judge, captioner, generators) and `agy` | comma-separated list; the whole list becomes one `KeyPool` (a 429 rotates to another key, dead keys are benched 1 h) |-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | same | single-key fallback when `GEMINI_API_KEYS` is unset |-| `ANTHROPIC_API_KEY` | `anthropic:*` chat models | optional; unset → those backends are unavailable (doctor WARN) |-| `OPENAI_API_KEY` | `openai:*` chat models | optional; `C3D_OPENAI_BASE_URL` points at a compatible gateway |--Resolution order for the Gemini keys (`codeverse3d/config.py`), first non-empty wins: settings-YAML `gemini_api_keys:` → `GEMINI_API_KEYS` (csv) → `GEMINI_API_KEY` / `GOOGLE_API_KEY` → a-line `GEMINI_API_KEYS="key1,key2,…"` in `~/.config/astra3d/gemini_keys.env`. Duplicates are-removed, order preserved. Keys are never written into run records.--```bash-export GEMINI_API_KEYS="key1,key2,key3" # e.g. in ~/.bashrc-3dcodeverse doctor --live # one ~$0.00001 "pong" call-```--### 8.2 The coding-agent CLIs (`agy` required, the rest optional)--The generator is always a vendor CLI: `--generator agy:… | claude-code:… | codex:…`. The-default is `agy:gemini-4-argon`, so **`agy` is the one CLI a default run needs**. The harness-runs agy **only in Gemini-API mode**, so it needs Gemini keys (§8.1): one key from the harness's-own pool per session, the 3dcode MCP tools, priced at Gemini list price — no sign-in, no-non-Gemini model. Without keys an agy session fails at once (doctor row `gemini keys`).-The other two are needed only when you name them.--`setup.sh` brings all three to their latest release on every run (`--no-clis` skips it): agy-through its own `agy update` — or, when there is no agy at all, Google's checksum-verified-installer into `~/.local/bin` — and the two npm globals whenever the installed version differs-from the registry's `latest`. A claude or codex installed another way (a native installer,-Homebrew) is left to its own updater. Nothing pins a version; the closing `doctor` prints the-three it found. By hand:--```bash-curl -fsSL https://antigravity.google/cli/install.sh | bash # agy; later: `agy update`-npm i -g @anthropic-ai/claude-code@latest @openai/codex@latest # claude, codex-agy --version && claude --version && codex --version-```--`claude` and `codex` authenticate against your local subscription (their own `login` flows).-The harness handles the per-CLI quirks for you (agy's per-session API-mode HOME, codex's MCP-approval mode): `docs/RUNBOOK.md` §3. The spatial MCP server itself is the `mcp` extra (§4);-check it with `python -m codeverse3d.spatial.mcp_server --workspace <ws> --list`.--### 8.3 Settings file and `C3D_` overrides--Loaded in this order, later wins: built-in defaults → `~/.config/3dcodeverse/config.yaml` →-`./3dcodeverse.yaml` (current working directory) → `C3D_*` environment variables. Neither YAML-file is required.--```yaml-# ~/.config/3dcodeverse/config.yaml-runs_dir: /data/runs-cache_dir: /data/cache/codeverse3d-binaries:- blender: ~/.local/bin/blender-5.2-render:- gpu: auto # auto | on | off- width: 768-limits:- agent_timeout_s: 1800- max_parallel_agents: 6-default_judge: gemini:gemini-4-argon-judge:- thinking: medium-```--Env equivalents use the `C3D_` prefix and `__` for nesting:--```bash-export C3D_RUNS_DIR=/data/runs-export C3D_BINARIES__BLENDER=/opt/blender/blender-export C3D_RENDER__GPU=off-export C3D_LIMITS__AGENT_TIMEOUT_S=900-export C3D_DEFAULT_JUDGE=gemini:gemini-4-argon-export C3D_JUDGE__THINKING=medium-```--Every knob the harness reads is a `Settings` field (`codeverse3d/config.py`, one description-each): `C3D_<FIELD>` at the top level, `C3D_<SECTION>__<FIELD>` nested, plus two flat-spellings of nested knobs — `C3D_MAX_IN_FLIGHT`, `C3D_RENDER_GPU`. An-on/off switch (`C3D_SKILLS`, `C3D_POST`, `C3D_PLAN_BRIEF`, … — every `Flag` field) takes-on/off, 1/0, true/false or yes/no in any case; a typo warns and keeps the default, and an empty-value is unset. The node side also reads `C3D_RENDER_GPU` and `C3D_CACHE_DIR` itself, and one-variable only it reads: `C3D_BROWSER_REUSE=off` disables the shared headless-Chrome daemon.-------## 9. Verify — `3dcodeverse doctor`--```bash-cd harness && 3dcodeverse doctor # add --live for one tiny Gemini call, --no-gpu to skip the Chrome probe, --json for machine output-```--One row per check (`python`, `python deps`, `blender`, `blender cycles`,-`blender gpu slots`, `node`, `three`, `puppeteer`, `chrome webgl`, `gemini keys`, `in-flight-slots`, `anthropic key`, `openai key`, `agy`, `claude`, `codex`, `git`,-`mcp`; `--live` adds `gemini live call`); any FAIL row makes it exit 1, WARN-rows name what is optional or busy.--### Troubleshooting table--| row | status | meaning | fix |-|---|---|---|---|-| `python` | — | interpreter running the CLI | if it is not the interpreter you installed into, your shell is picking up another `3dcodeverse` — `which -a 3dcodeverse`, reinstall with `python -m pip install -e harness` |-| `python deps` | FAIL | a core import is missing/broken | `pip install -e 'harness[all]'`; a broken native lib (`fcl`) shows up here too — reinstall that wheel (`pip install --force-reinstall python-fcl`) |-| `python deps` | WARN | only optional-extra modules missing (`shapely` / `yourdfpy` / `mcp` / `moderngl` / `cadquery`) | install the extra the row names, e.g. `pip install -e 'harness[mesh,urdf,mcp,graphics,cad]'` (§4) |-| `blender` | FAIL | no binary found, or `--version` failed | §6 — install Blender, or `export C3D_BINARIES__BLENDER=/path/to/blender`. If it is found but fails, run it by hand: a `libSM.so.6`/`libICE.so.6` error means you need the `LD_LIBRARY_PATH` wrapper |-| `blender cycles` | WARN | Cycles sees no CUDA device | scene_blender's judged frames render on the CPU (a few times slower) — fine without an NVIDIA GPU; on WSL2 install the vendor WSL GPU driver. The row also names the judged-frame samples / device (`C3D_RENDER__BLENDER_*`) |-| `blender render` | FAIL / SKIP | the render probe could not run Blender (or there is none) | see the `blender` row |-| `blender gpu slots` | WARN | every machine-wide GPU Blender render slot is held right now | other renders are on the GPU; a render waits `C3D_RENDER__BLENDER_GPU_WAIT_S` for a slot and then renders on the CPU — nothing to fix unless it stays full. `C3D_RENDER__BLENDER_GPU_SLOTS` sizes it |-| `node` | FAIL | node missing or older than 20.6.0 (§2.1) | install a newer node (`nvm install --lts`) or point `binaries.node` / `C3D_BINARIES__NODE` at one. The same check fires from every node workload (`codeverse3d.spatial.node.run_node`), so a too-old node cannot fail obscurely mid-render |-| `runtime_js` | FAIL | the node runtime directory cannot be resolved | use a full checkout, or set `C3D_RUNTIME_JS=/path/to/harness/runtime_js`; then run `npm ci` there (§5) |-| `three` | FAIL | `runtime_js/node_modules/three` missing | `cd harness/runtime_js && npm ci` (§5) |-| `puppeteer` | FAIL | not installed in `runtime_js` | `cd harness/runtime_js && npm ci` |-| `puppeteer` | WARN | installed, but no Chrome in `~/.cache/puppeteer` | `cd harness/runtime_js && npx puppeteer browsers install chrome` (or unset `PUPPETEER_SKIP_DOWNLOAD` / fix `PUPPETEER_CACHE_DIR`) |-| `chrome webgl` | WARN | Chrome launched but on SwiftShader | fine, just slower; on WSL2 install the vendor WSL GPU driver, on a server install Mesa EGL. `C3D_RENDER_GPU=off` to stop probing |-| `chrome webgl` | FAIL | the browser could not launch at all | usually missing shared libs for Chrome (`ldd ~/.cache/puppeteer/chrome/*/chrome-linux64/chrome \| grep -i "not found"`) or a stale endpoint file — `rm -f ~/.cache/codeverse3d/browser_*.lock` and retry; `--no-gpu` skips this probe |-| `chrome webgl` | SKIP | `runtime_js/gpu_launch.cjs` not present | you are not in a full checkout |-| `gemini keys` | FAIL | no keys resolved | `export GEMINI_API_KEYS="k1,k2"` (§8.1) — everything model-driven needs this |-| `anthropic key` / `openai key` | WARN | not set | expected unless you use `anthropic:*` / `openai:*`; export the key to clear it |-| `agy` / `claude` / `codex` | WARN | CLI not on `PATH` | only that `--generator` is unavailable — but `agy` serves the default generator (§8.2) |-| `git` | FAIL | git missing | install git — run workspaces are git repos |-| `mcp` | WARN | `mcp` package or the server module missing | `pip install -e 'harness[mcp]'`; only affects the agentic CLI backends |-| `gemini live call` (`--live`) | FAIL | key rejected / no network | check the key value and outbound access; a `503 … high demand` is transient, not an install problem |-| `in-flight slots` | WARN | every machine-wide slot is held right now (`busy n/n`), or `max_in_flight=0` switched the cap off | busy: other harness processes are mid-call and new calls wait for a slot — nothing to fix unless it stays full; a slot is held only while a call is out and a killed process frees its slots at once. Off: unset `C3D_MAX_IN_FLIGHT` |-------## 10. 5-minute smoke--The cheapest end-to-end run is a single-shot shader on the `graphics` track (~$0.05, ~2-minutes, no Blender, no node). Point it at a throwaway runs directory so you do not mix it into-real data:--```bash-cd harness-3dcodeverse make "a slow rotating neon hex grid" \- --track graphics --language glsl_shader \- --generator single-shot:gemini:gemini-3.8-flash \- --rounds 0 --max-minutes 20 \- --runs-dir /tmp/c3d_smoke-3dcodeverse status <slug> --runs-dir /tmp/c3d_smoke-```--If node and Blender are installed, the equivalent object-track smoke is-`3dcodeverse make "a simple wooden stool" --track static_object --language blender---generator single-shot:gemini:gemini-3.8-flash --rounds 0` (~$0.1, a few minutes).--Artifacts land in `<runs-dir>/<slug>/`:--```-spec.json plan.json record.json run_state.json events.jsonl-src/ the generated code (a git repo — one commit per round)-artifacts/ build.json, census.json, measurement.json,- object.glb (object tracks) / frames/ + frames_sheet.png +- preview.gif + metrics.json (graphics)-artifacts/renders/rNN/ per-round view PNGs + sheet.png-artifacts/gates/rNN/ deterministic gate output-artifacts/judge/rNN.json the VLM verdict and the computed score-trajectories/ per-call transcripts-```--`3dcodeverse status <slug>` prints the rounds table, cost and last events; the full operating guide is-`docs/RUNBOOK.md`.--> **`capacity storm N/10 … waiting Ns`** means the Gemini endpoint is busy, not that your-> install is broken: the harness backs off (up to 10 waits, ~10 min in total) and rotates keys,-> which is why the smoke above gets `--max-minutes 20`. `3dcodeverse resume <slug> --runs-dir …`-> continues from the last completed stage. To prove the key path alone, `3dcodeverse doctor-> --live` is the one-call version.-------## 11. Uninstall / cleanup--```bash-pip uninstall 3dcodeverse # removes the editable install + the 3dcodeverse command-rm -rf harness/runtime_js/node_modules # re-creatable with `npm ci`-rm -rf ~/.cache/puppeteer # downloaded Chrome builds-rm -rf ~/.cache/codeverse3d # harness cache — see below-rm -rf harness/3dcodeverse.egg-info harness/.pytest_cache harness/.ruff_cache-```--`~/.cache/codeverse3d` (or `cache_dir` / `C3D_CACHE_DIR`) holds only regenerable things:-`renders/` and `judge_images/` (render + montage cache), `gpu_probe.json`, `browser_*.lock` (the-shared headless-Chrome endpoint file — do not delete it while renders are running).--**Your data is not in either cache.** `runs/`, `eval/bench/out/` and any exported dataset are-the flywheel output — delete them deliberately, never as part of a cleanup.--Uninstalling does not touch `~/.config/3dcodeverse/config.yaml`,-`~/.config/astra3d/gemini_keys.env` or the globally installed CLIs — remove those by hand-(`npm rm -g @anthropic-ai/claude-code @openai/codex`; agy: `rm ~/.local/bin/agy` and the-`# Added by Antigravity CLI installer` PATH lines in `~/.bashrc` / `~/.profile`).+tar xf blender-5.2.2-linux-x64.tar.xz && ~/tools/blender-5.2.2-linux-x64/blender --version+```+`Settings.resolve_blender()` takes `binaries.blender` from the settings file or+`C3D_BINARIES__BLENDER=/path/to/blender` first (a configured binary that is missing is a+FAIL, never replaced by PATH), else `blender-5.2`, then `blender` on PATH. Headless Blender+without X11 libraries (no sudo): download the X11 `.so`s the tarball needs and put a one-line+wrapper named `blender-5.2` on PATH that sets `LD_LIBRARY_PATH` and execs the binary. Every+Blender build runs `--factory-startup` in an emptied scene; `scene_blender`'s judged frames are+Cycles (32 samples + OpenImageDenoise, AgX, exposure 0), GPU when the doctor finds one.++### runtime_js+`harness/runtime_js/` is a small npm package the plugin owns ([email protected], puppeteer); its+`node_modules/` is not committed. Generated code never sees it: node builds get+`--import runtime_js/lib/resolve_three.mjs` (a `registerHooks` resolver for `three` and+`three/addons/*`), and the browser gets `/__runtime/node_modules/three/...` over the local+server. Nothing is fetched from a CDN. Use `npm ci`, not `npm install`.++### Headless Chrome and the GPU+On WSL2 WebGL uses the GPU with `--use-angle=gl-egl` plus the Mesa d3d12 environment+(`runtime_js/gpu_launch.cjs`); `C3D_RENDER_GPU=on|off|auto` forces it. moderngl uses a d3d12+or EGL context, llvmpipe otherwise. `doctor --no-gpu` skips the probe.++## 3. Settings+`~/.config/3dcodeverse/config.yaml` or `./3dcodeverse.yaml`; every field is also an+environment variable with the `C3D_` prefix and `__` for nesting (`C3D_BINARIES__BLENDER`,+`C3D_LIMITS__BUILD_TIMEOUT_S=300`). `python -m codeverse3d.doctor --json` prints what is in+effect. Nothing in the plugin needs an API key.++## 4. Installing the plugin into a host+The repository root is a marketplace (`.claude-plugin/marketplace.json`) whose one plugin is+`harness/`.+```bash+# Claude Code+claude plugin marketplace add /path/to/3dcodeverse # or the GitHub owner/repo+claude plugin install 3dcodeverse@3dcodeverse+claude plugin details 3dcodeverse # skills, the judge agent, token cost+# Codex+codex plugin marketplace add /path/to/3dcodeverse+codex plugin add 3dcodeverse@3dcodeverse+# Antigravity+agy plugin install /path/to/3dcodeverse/harness+agy plugin validate /path/to/3dcodeverse/harness --strict+```+The host then sees the skills (`3d-director`, `3d-lang-*`, `c3d-*`) and the `3d-judge`+subagent. The skills run `3dcode …` in the host's terminal: the console script from+`pip install -e harness`, or `harness/bin/3dcode` (`$C3D_PYTHON`, else `harness/.venv/bin/python`,+else `python3`, with `PYTHONPATH=harness`). To try a host without touching your real config,+point it at a temporary home (`HOME=/tmp/x`, `CODEX_HOME=/tmp/x/.codex`,+`CLAUDE_CONFIG_DIR=/tmp/x/.claude`).++## 5. Doctor troubleshooting+* `python FAIL` — not 3.13: make a venv from a 3.13 interpreter and rerun `setup.sh --python`.+* `node FAIL` — below 20.6, or `runtime_js/node_modules` missing: `npm ci` in `runtime_js/`.+* `chrome FAIL` — `npx puppeteer browsers install chrome` in `runtime_js/`.+* `blender FAIL` — nothing on PATH named `blender-5.2` / `blender`, or an older version, or a+ configured binary that is not executable (§2).+* `gpu WARN` — SwiftShader / llvmpipe in use: slower, not wrong.