Skip to content

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.md
index 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 owns
wrappers/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.md
index 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.md
index 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.md
index 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
```bash
git 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 ~/tools
curl -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.