Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
Python 3dai-agentsclaude-codecomputer-graphicsgenerativeimage-to-3dprocedural-generationthreejstypescriptwebgl
README remake (3D showcase, live-demo links) + public ROADMAP + token-cost doc
hoainhodc7c1a2cbf18
diff --git a/README.md b/README.mdindex a20d7ff..5bc312d 100644--- a/README.md+++ b/README.md@@ -1,73 +1,55 @@-# img2threejs+```+ ___ ____ _ _ _+ (_)_ __ ___ __ |___ \| |_| |__ _ __ ___ ___ (_)___+ | | '_ ` _ \ / _` | __) | __| '_ \| '__/ _ \/ _ \| / __|+ | | | | | | | (_| |/ __/| |_| | | | | | __/ __/ | \__ \+ |_|_| |_| |_|\__, |_____|\__|_| |_|_| \___|\___|/ |___/+ |___/ |__/+```-Rebuild the object in a reference image as a **code-only, procedural Three.js model** — quality-gated, animation-ready, and deliberately token-efficient. This is reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.+**Rebuild the object in a reference image as a code-only, procedural Three.js model.** Quality-gated, animation-ready, and deliberately token-efficient. Reconstruction-by-code — not photogrammetry, mesh extraction, or downloaded art packs.-+[](LICENSE)+[](SKILL.md)+[](CONTRIBUTING.md)+[](https://threejs.org)+[](scripts)-*Above: a single reference image reconstructed in code — correct proportions, colours, bevels, gold trim, and an emissive emblem — running live in the browser.*-----+-## What it does+*A single reference image reconstructed in code — correct proportions, colours, bevels, gold trim, and an emissive emblem — running live in the browser.*-You give it one reference image of an object. It produces a `THREE.Group` factory written in TypeScript that recreates that object from primitives, procedural shaders, and generated geometry — with a runtime hierarchy (pivots, sockets, colliders) so the result is ready to animate, not an inert lump.+### [→ Open the Live Demo Gallery](https://hoainho.github.io/img2threejs-showcase/)-It works under Claude Code, Codex, or OpenCode. It is agent-agnostic: wherever the docs say "agent vision" or "agent browser tool", it uses whatever the host provides (native image reading, a browser MCP, the project preview, or a user-supplied screenshot).+Every model in the gallery is generated code, running in your browser. No mesh files, no downloads.----## Subjects and detail accuracy (v1.1)--- Objects and characters. Each subject is classified `object`, `character`, or `hybrid`. Objects follow the hard-surface pipeline; characters route through an anatomy-aware track (head-unit proportions, facial landmarks, pose) documented in `references/character-reconstruction.md`.-- Detail-first analysis. Before code generation the pipeline enumerates a `detailInventory` of identity-defining small details (gloss, bevel/rounding, screws/rivets, engraved or painted linework, contours, stains and wear). Every detail must map to a real component or material entry, and a strict-quality gate blocks generation until the inventory is complete. Taxonomy: `references/detail-inventory.md`.-- Maximum likeness for a specific person or character. An opt-in projection-first path fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. A single image cannot guarantee 100 percent likeness, so the pipeline reports per-region confidence and asks for more views when it matters. Details and sources: `references/likeness-maximization.md`.--## Why it is token-efficient--Most image-to-3D agent loops burn tokens by asking the model to do mechanical work — re-reading the whole model every pass, scoring pixels, validating JSON by hand, re-running steps it already did. img2threejs pushes all of that into deterministic scripts and spends model tokens only where judgment is actually required.--- **Scripts enforce, the model judges.** Ten Python scripts handle validation, gating, spec authoring, PBR extraction, comparison-sheet packaging, and pipeline state. They never score visuals. The model's tokens go to one thing: looking at a single side-by-side sheet and deciding pass or fail.-- **Zero dependencies, zero install churn.** Every script is pure Python 3.10+ standard library. No pip, no PIL, no numpy, no Playwright. PNG read/write is done with `struct` and `zlib`. Nothing to install means nothing to debug in-context.-- **Pass-gated generation.** The code generator emits only the currently unlocked build pass. The model does not regenerate or re-read the entire model on every iteration — each step is small and scoped.-- **Fail fast, before codegen.** A strict-quality gate blocks shallow specs before a single line of Three.js is generated, so you never spend tokens rendering and re-doing a model that was underspecified from the start.-- **One image per review.** Each pass is judged from exactly one packaged comparison sheet (reference beside render), not a scattering of screenshots.-- **Text output, not binaries.** The result is diffable TypeScript plus a JSON spec — small, reviewable, and version-controllable, instead of multi-megabyte mesh files.--The net effect: you still get a faithful 3D model from an image, but the expensive model context is reserved for visual judgment and code, not bookkeeping.+## Live demos-## Token cost analysis+Three reconstructions built entirely from primitives, procedural shaders, and generated geometry. Open each one, orbit it, and read the generated source.-The numbers below are engineering estimates, not a measured benchmark. They are order-of-magnitude figures anchored to one reference build (a rounded-bevel loot chest: gradient enamel, gold corner brackets, an emissive emblem, resolved in about six render-review cycles). Actual cost varies with the model tier, image resolution, object complexity, and — above all — how many review cycles a subject needs. Treat them as a cost model, not a guarantee.+| Demo | Subject | View | Source |+| --- | --- | --- | --- |+| Crowned Loot Chest | hard-surface object | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/crown-chest) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/crown-chest/createCrownChestModel.ts) |+| Beach Character | stylized character | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/character) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/character/createCharacterModel.ts) |+| Portrait Bust | stylized likeness | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/portrait) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/portrait/createPortraitModel.ts) |-Where the tokens go per full object reconstruction (image to a verified 3D model):+The gallery source lives in [hoainho/img2threejs-showcase](https://github.com/hoainho/img2threejs-showcase). If this project is useful, a star on this repo helps others find it.-| Stage | Est. model tokens | Notes |-| --- | --- | --- |-| Deterministic scripts (probe, assessment, spec, validate, generate, sync) | ~2k-5k total | Run as subprocesses. This is the work that is near-free. |-| Read the reference image | <1k | A small reference; higher-res costs more. |-| Author assessment + detail inventory + spec JSON | ~15k-25k | The spec is the largest text artifact. |-| Write and edit the Three.js factory | ~20k-45k | Scales with part count and edit iterations. |-| Render-review loop (5-8 cycles) | ~30k-70k | The dominant cost; scales linearly with cycles. |-| **Total, one object** | **~80k-180k** | Simple/few-cycles to complex/many-cycles. |+----One render-review cycle in isolation:+## What it does-| Step | Est. model tokens |-| --- | --- |-| Capture screenshot (browser tool) | ~0 (tool call) |-| Package comparison sheet (stdlib script) | ~0 (subprocess) |-| Inspect the comparison sheet with vision | ~2k-3k |-| Write the review and scores (script) | ~1k-2k |-| **Per cycle** | **~5k-12k** |+You give it one reference image of an object. It produces a `THREE.Group` factory written in TypeScript that recreates that object from primitives, procedural shaders, and generated geometry — with a runtime hierarchy (pivots, sockets, colliders) so the result is ready to animate, not an inert lump.-Characters cost more (more review cycles plus landmark and projection checks): roughly ~150k-350k for a full stylized/likeness reconstruction once the v1.2 character generator lands.+It runs under Claude Code, Codex, or OpenCode. It is agent-agnostic: wherever the docs say "agent vision" or "agent browser tool", it uses whatever the host provides — native image reading, a browser MCP, the project preview, or a user-supplied screenshot.-What this buys you:+### Subjects and detail accuracy-- Deterministic scripts contribute close to zero model tokens, so validation, gating, detail counting, sheet packaging, and pipeline state never eat context.-- Model tokens are spent only on vision (reading one sheet per pass), authoring the spec, and writing code.-- The gates are the savings mechanism: strict-quality blocks codegen on an underspecified spec, and the detail-inventory gate blocks it on missing detail — each avoided bad render saves roughly one full cycle (~10k-20k tokens).-- The single biggest lever on cost is the review-cycle count. A well-formed spec up front is worth more tokens than any micro-optimization downstream.+- **Objects and characters.** Each subject is classified `object`, `character`, or `hybrid`. Objects follow the hard-surface pipeline; characters route through an anatomy-aware track (head-unit proportions, facial landmarks, pose) documented in `references/character-reconstruction.md`.+- **Detail-first analysis.** Before code generation the pipeline enumerates a `detailInventory` of identity-defining small details (gloss, bevel/rounding, screws/rivets, engraved or painted linework, contours, stains and wear). Every detail must map to a real component or material entry, and a strict-quality gate blocks generation until the inventory is complete. Taxonomy: `references/detail-inventory.md`.+- **Maximum likeness for a specific person or character.** An opt-in projection-first path fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. A single image cannot guarantee 100 percent likeness, so the pipeline reports per-region confidence and asks for more views when it matters. Details: `references/likeness-maximization.md`.---@@ -78,37 +60,37 @@ The skill runs a staged sculpting pipeline. Scripts gate each stage; the agent's```mermaidflowchart TDA[Reference image] --> B[Probe and suitability gate]- B --> C[Pre-Spec Assessment<br/>class, complexity, quality contract]- C --> D[Author ObjectSculptSpec<br/>components, materials, sockets]+ B --> C[Pre-Spec Assessment: class, complexity, quality contract]+ C --> D[Author ObjectSculptSpec: components, materials, sockets]D --> E{Validate and strict-quality}E -- too shallow --> DE -- ok --> F[Locked build passes]- F --> G[Generate Three.js factory<br/>current pass only]+ F --> G[Generate Three.js factory: current pass only]G --> H[Render in browser and screenshot]H --> I[Package one side-by-side sheet]I --> J{Agent vision review}- J -- score below threshold --> K[Self-correct:<br/>refine-spec or refine-code]+ J -- score below threshold --> K[Self-correct: refine-spec or refine-code]K --> FJ -- pass --> L{More passes?}L -- yes --> FL -- no --> M[Animation-ready Three.js model]```-### The build passes+### Build passes-The model is sculpted in a fixed order, and a pass only unlocks after the previous one is reviewed and accepted:+The model is sculpted in a fixed order; a pass unlocks only after the previous one is reviewed and accepted:-`blockout` to `structural-pass` to `form-refinement` to `material-pass` to `surface-pass` to `lighting-pass` to `interaction-pass` to `optimization-pass`+`blockout → structural-pass → form-refinement → material-pass → surface-pass → lighting-pass → interaction-pass → optimization-pass`-Each pass has its own acceptance criteria. A pass can be marked `continue` only with a real render, a comparison sheet, an agent-vision score at or above threshold, and every identity-defining feature at or above its own threshold.+Each pass has its own acceptance criteria. A pass is marked `continue` only with a real render, a comparison sheet, an agent-vision score at or above threshold, and every identity-defining feature at or above its own threshold.### The gates- **Suitability** — is the image a viable 3D target at all.- **Pre-spec and strict-quality** — blocks code generation until the spec is deep enough for the object's complexity (no single-root spec for a compound object).- **Screenshot feedback** — `continue` requires a render plus a comparison sheet plus a passing vision score.-- **Action-ready** — the model must expose a runtime hierarchy (pivots, sockets, colliders, destruction groups) via `root.userData.sculptRuntime`.-- **Attachment correctness** — child parts (handles, limbs, tubes) must declare how they join their parent, so nothing floats in mid-air.+- **Action-ready** — the model exposes a runtime hierarchy (pivots, sockets, colliders, destruction groups) via `root.userData.sculptRuntime`.+- **Attachment correctness** — child parts (handles, limbs, tubes) declare how they join their parent, so nothing floats in mid-air.- **Material and lighting realism** — independent PBR channels and real lights, never albedo aliased into roughness.### Self-correction@@ -133,7 +115,7 @@ After every pass the agent chooses exactly one action: `continue`, `refine-spec`3. **Follow the pipeline** — the skill validates the image, writes an assessment and spec, generates the factory pass by pass, and shows you a side-by-side comparison at each step until the render matches.-The scripts run from the skill root. They need only Python 3.10+ — nothing to install.+The scripts run from the skill root and need only Python 3.10+ — nothing to install.```bashpython3 scripts/probe_reference_image.py <image>@@ -145,6 +127,21 @@ python3 scripts/generate_threejs_factory.py spec.json --out src/createObjectMode---+## Why it is token-efficient++Most image-to-3D agent loops burn tokens by asking the model to do mechanical work — re-reading the whole model every pass, scoring pixels, validating JSON by hand, re-running steps it already did. img2threejs pushes all of that into deterministic scripts and spends model tokens only where judgment is actually required.++- **Scripts enforce, the model judges.** The Python scripts handle validation, gating, spec authoring, PBR extraction, comparison-sheet packaging, and pipeline state. They never score visuals. The model's tokens go to one thing: looking at a single side-by-side sheet and deciding pass or fail.+- **Zero dependencies, zero install churn.** Every script is pure Python 3.10+ standard library. No pip, no PIL, no numpy, no Playwright. PNG read/write is done with `struct` and `zlib`. Nothing to install means nothing to debug in-context.+- **Pass-gated generation.** The code generator emits only the currently unlocked build pass. The model does not regenerate or re-read the entire model on every iteration — each step is small and scoped.+- **Fail fast, before codegen.** A strict-quality gate blocks shallow specs before a single line of Three.js is generated, so you never spend tokens rendering a model that was underspecified from the start.+- **One image per review.** Each pass is judged from exactly one packaged comparison sheet (reference beside render), not a scattering of screenshots.+- **Text output, not binaries.** The result is diffable TypeScript plus a JSON spec — small, reviewable, and version-controllable, instead of multi-megabyte mesh files.++The net effect: you still get a faithful 3D model from an image, but the expensive model context is reserved for visual judgment and code, not bookkeeping. For the full per-stage and per-cycle token breakdown, see [docs/TOKEN_COST.md](docs/TOKEN_COST.md).++---+## Scripts| Script | Role |@@ -159,11 +156,11 @@ python3 scripts/generate_threejs_factory.py spec.json --out src/createObjectMode| `make_visual_comparison_sheet.py` | Package one reference-vs-render sheet for review. || `append_sculpt_review.py` | Record a per-pass review: scores, decision, evidence. || `visual_feature_gate.py` | Internal helper enforcing per-feature score thresholds. |-| `build_detail_inventory.py` | Slice the reference into zones and scaffold a detail inventory (gloss, bevel, fasteners, linework, stains). |-| `extract_reference_landmarks.py` | Overlay a landmark grid and scaffold an anatomy block for character subjects. |-| `solve_reference_camera.py` | Emit a reference-camera block so the render can be camera-matched to the photo. |-| `delight_reference.py` | Approximate a neutral albedo from the photo before texture projection (documented approximation). |-| `bake_projected_texture.py` | Emit a projection/UV-bake descriptor for photo-texture projection in the Three.js runtime. |+| `build_detail_inventory.py` | Slice the reference into zones and scaffold a detail inventory. |+| `extract_reference_landmarks.py` | Overlay a landmark grid and scaffold an anatomy block for characters. |+| `solve_reference_camera.py` | Emit a reference-camera block so the render can be camera-matched. |+| `delight_reference.py` | Approximate a neutral albedo from the photo before texture projection. |+| `bake_projected_texture.py` | Emit a projection/UV-bake descriptor for photo-texture projection. |The `references/` folder holds the detailed rubrics each gate applies (validation, pre-spec assessment, procedural patterns, material and lighting realism, attachment correctness, action-ready models, self-correction).@@ -177,20 +174,28 @@ The `references/` folder holds the detailed rubrics each gate applies (validatio----## Requirements+## Roadmap++- **v1.0** — object pipeline: staged sculpt, render-vs-reference review loop, action-ready hierarchy. *Shipped.*+- **v1.1** — detail-first analysis: required detail inventory, strict-quality gate. *Shipped.*+- **v1.2** — humanoid character generator: anatomy track, proportion-lock and feature-placement passes. *Shipped.*+- **v1.3** — likeness maximization: projection-first character rendering, per-region confidence. *Planned.*+- **v1.4** — animation-ready rigs: SkinnedMesh, morph targets, glTF export. *Planned.*-- Python 3.10+ (standard library only).-- A Three.js project or preview to render into (any modern bundler).-- A host that can read images and capture a browser screenshot (Claude Code, Codex, or OpenCode with a browser tool or user-supplied screenshots).+Full detail and later milestones: [ROADMAP.md](ROADMAP.md). Technical specification: [docs/UPGRADE_PLAN.md](docs/UPGRADE_PLAN.md).---## Honesty about limits-A single image cannot reveal hidden sides or guarantee exact geometry. The skill states plainly when output is approximate, stylized, or low-poly, and infers unseen faces by mirroring visible ones rather than faking confidence. "This cannot reach the requested fidelity from this image" is a valid, expected result.+A single image cannot reveal hidden sides or guarantee exact geometry. The skill states plainly when output is approximate, stylized, or low-poly, and infers unseen faces by mirroring visible ones rather than faking confidence. It is strong for hard-surface objects; characters are stylized reconstructions, not photoreal likeness. "This cannot reach the requested fidelity from this image" is a valid, expected result.---+## Contributing++Contributions are welcome — procedural material recipes, new gates, host coverage, and demos especially. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [roadmap](ROADMAP.md) for where the project is headed.+## License-MIT.+MIT. See [LICENSE](LICENSE).diff --git a/ROADMAP.md b/ROADMAP.mdnew file mode 100644index 0000000..5c60933--- /dev/null+++ b/ROADMAP.md@@ -0,0 +1,38 @@+# img2threejs Roadmap++This roadmap outlines the planned evolution of img2threejs from its initial release through major feature additions. For the full technical specification, requirements, and acceptance criteria, see [docs/UPGRADE_PLAN.md](docs/UPGRADE_PLAN.md).++## Version status++| Version | Theme | Status | Highlights |+|---|---|---|---|+| v1.0 | Object pipeline | Shipped | Staged sculpt pipeline (blockout through optimization), render-vs-reference review loop, action-ready runtime hierarchy |+| v1.1 | Detail-first analysis | Shipped | Required detailInventory artifact (gloss, bevel, fasteners, linework, stains), strict-quality gate blocking shallow specs before codegen |+| v1.2 | Humanoid character generator | Shipped | Character/hybrid domain detection, anatomy and facial landmarks, proportion-lock and feature-placement build passes, per-part character materials |+| v1.3 | Likeness maximization | Planned | Projection-first path wired into character rendering (camera solve, de-lighting, texture projection), opt-in generativeAssist mode with confidence reporting, high-likeness character demo |+| v1.4 | Animation-ready rigs | Planned | True humanoid rig and pivot hierarchy (replacing current world-space flatten), SkinnedMesh with morph targets, glTF export |+| v1.5 | Ecosystem | Planned | Expanded live demo gallery accepting community demos via pull request, broader host and agent coverage, measured token-cost benchmark replacing current estimates |++## Version details++### v1.0 - Object pipeline+The foundational release introduces the staged reconstruction pipeline for hard-surface objects. Images are analyzed for suitability, authored into an ObjectSculptSpec describing components and materials, then generated pass by pass as Three.js code. Each pass gates on a visual review using side-by-side comparison sheets. The result exposes a runtime hierarchy (pivots, sockets, colliders) ready for animation.++### v1.1 - Detail-first analysis+Micro-detail capture becomes a required, evidence-linked artifact with its own validation gate. A detail inventory enumerates identity-defining small features (gloss zones, bevels, screws and rivets, engraved or painted lines, contours, stains and wear). Every detail must map to a real component or material entry, and the strict-quality gate blocks code generation until the inventory is complete and linked. This prevents shallow specs from reaching the renderer.++### v1.2 - Humanoid character generator+Characters and hybrid subjects are now first-class. The pipeline detects character-like form language and routes the reconstruction through an anatomy-aware track. A humanoid component template with measured head-unit proportions, facial landmark placement, and pose alignment emerges from the assessment. Build passes for proportion-locking and feature-placement gate on anatomical correctness. Per-part character materials (skin, hair, cloth, accessories) integrate with the Track A detail machinery, producing stylized human figures with correct proportions and recognizable likeness.++### v1.3 - Likeness maximization+The projection-first path maximizes likeness for specific people or characters. A parametric humanoid template is fitted to image landmarks, the reference photo is de-lit and camera-matched, then projected onto the fitted mesh as texture. This achieves significantly higher visual fidelity than hand-authored primitives. An optional, clearly flagged generativeAssist mode allows import of a base mesh from external image-to-3D generators, then applies the same projection and material pipeline. Per-region confidence reporting acknowledges unobservable areas (back, sides, occluded geometry) and requests additional views when fidelity matters. A high-likeness character demo showcases the technique.++### v1.4 - Animation-ready rigs+The character rig moves from a flattened world-space hierarchy to a proper animated skeleton with named joints (neck, shoulders, elbows, hips, knees, ankles). SkinnedMesh deformation and morph targets enable facial expression and body deformation. Clean, predictable mesh topology supports blendshape deformation without artifacts. The rig and morph channels export as glTF and integrate with industry-standard animation tools and game engines.++### v1.5 - Ecosystem+The project expands beyond a single skill into a broader ecosystem. A live demo gallery on the project site showcases community reconstructions accepted via pull request, lowering the barrier to sharing results. Coverage extends to more Claude hosts (Codex, OpenCode) and browser automation MCPs. Token costs are measured empirically across real reconstructions rather than estimated, replacing the current engineering-estimate model with a reproducible benchmark. This version solidifies the pipeline as a reference implementation for single-image 3D reconstruction by code.++## Contributing++img2threejs welcomes contributions. For planning or submitting work on v1.3 and later features, see [CONTRIBUTING.md](CONTRIBUTING.md). Feature requests and bug reports help prioritize future releases. The roadmap is responsive to real-world usage and feedback from the open-source community.diff --git a/docs/TOKEN_COST.md b/docs/TOKEN_COST.mdnew file mode 100644index 0000000..cadf2e1--- /dev/null+++ b/docs/TOKEN_COST.md@@ -0,0 +1,37 @@+# Token Cost Analysis++The numbers below are engineering estimates, not a measured benchmark. They are order-of-magnitude figures anchored to one reference build (a rounded-bevel loot chest: gradient enamel, gold corner brackets, an emissive emblem, resolved in about six render-review cycles). Actual cost varies with the model tier, image resolution, object complexity, and — above all — how many review cycles a subject needs. Treat them as a cost model, not a guarantee.++A measured benchmark, based on empirical data across real reconstructions, is planned for v1.5. See [ROADMAP.md](../ROADMAP.md) for details.++## Where the tokens go per full object reconstruction++| Stage | Est. model tokens | Notes |+|---|---|---|+| Deterministic scripts (probe, assessment, spec, validate, generate, sync) | ~2k-5k total | Run as subprocesses. This is the work that is near-free. |+| Read the reference image | <1k | A small reference; higher-res costs more. |+| Author assessment + detail inventory + spec JSON | ~15k-25k | The spec is the largest text artifact. |+| Write and edit the Three.js factory | ~20k-45k | Scales with part count and edit iterations. |+| Render-review loop (5-8 cycles) | ~30k-70k | The dominant cost; scales linearly with cycles. |+| **Total, one object** | **~80k-180k** | Simple/few-cycles to complex/many-cycles. |++## One render-review cycle in isolation++| Step | Est. model tokens |+|---|---|+| Capture screenshot (browser tool) | ~0 (tool call) |+| Package comparison sheet (stdlib script) | ~0 (subprocess) |+| Inspect the comparison sheet with vision | ~2k-3k |+| Write the review and scores (script) | ~1k-2k |+| **Per cycle** | **~5k-12k** |++## Character reconstruction cost++Characters cost more (more review cycles plus landmark and projection checks): roughly ~150k-350k for a full stylized or likeness-maximized reconstruction with the v1.2 character generator.++## What this buys you++- Deterministic scripts contribute close to zero model tokens, so validation, gating, detail counting, sheet packaging, and pipeline state never eat context.+- Model tokens are spent only on vision (reading one sheet per pass), authoring the spec, and writing code.+- The gates are the savings mechanism: strict-quality blocks codegen on an underspecified spec, and the detail-inventory gate blocks it on missing detail — each avoided bad render saves roughly one full cycle (~10k-20k tokens).+- The single biggest lever on cost is the review-cycle count. A well-formed spec up front is worth more tokens than any micro-optimization downstream.