Deploy verified img2threejs Docker Space

.dockerignore

@@ -0,0 +1,28 @@
+# VCS / local state
+.git/
+.gitignore
+.workflow/
+upstream-src/
+verification/
+rollout*.jsonl
+.env
+.env.*
+.venv/
+
+# Python
+**/__pycache__/
+**/*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Node (installed inside the image via npm ci)
+node_modules/
+
+# Test/build artifacts
+forge/tests/
+tests/fixtures/factory_fixture.ts
+*.log
+
+# OS cruft
+.DS_Store

.gitignore

@@ -0,0 +1,13 @@
+**/__pycache__/
+**/*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+node_modules/
+.env
+.env.*
+*.log
+rollout*.jsonl
+tests/fixtures/factory_fixture.ts
+verification/live-artifacts/

Dockerfile

@@ -0,0 +1,81 @@
+# syntax=docker/dockerfile:1
+# img2threejs — production Dockerfile for a Hugging Face Docker Space.
+#
+# Build stages:
+#   1. fixture      — regenerate the test fixture factory through the real
+#                     vendored pipeline (strict gate -> explicit unreviewed
+#                     hosted-preview manifest -> generation). A broken forge
+#                     copy fails here.
+#   2. nodesmoke    — npm ci (three + esbuild), bundle the fixture exactly as
+#                     the runtime does, and execute it headlessly in node
+#                     (scene-graph smoke: Group, meshes, finite bbox,
+#                     sculptRuntime). A non-executing factory fails the build.
+#   3. runtime      — python:3.12-slim, non-root UID 1000, tini init,
+#                     uvicorn on 0.0.0.0:7860, /health HEALTHCHECK.
+#                     (esbuild is a statically-linked native binary, so the
+#                     runtime needs no node; node exists only in stage 2.)
+
+# ---------------------------------------------------------------------------
+FROM python:3.12-slim-bookworm AS fixture
+WORKDIR /build
+COPY forge/ forge/
+COPY app/__init__.py app/__init__.py
+COPY app/forge_bridge.py app/forge_bridge.py
+COPY scripts/build_fixture_factory.py scripts/build_fixture_factory.py
+COPY tests/fixtures/canned_spec.json tests/fixtures/canned_spec.json
+RUN python3 scripts/build_fixture_factory.py /build/factory_fixture.ts
+
+# ---------------------------------------------------------------------------
+FROM node:22-bookworm-slim AS nodesmoke
+WORKDIR /build
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev --no-audit --no-fund && npm cache clean --force
+COPY --from=fixture /build/factory_fixture.ts /build/factory.ts
+COPY app/static/viewer-core.js app/static/viewer-core.js
+COPY scripts/node_smoke.mjs scripts/node_smoke.mjs
+RUN set -e; \
+    factory_export=$(grep -oE 'export function create[A-Za-z0-9]+Model' factory.ts | head -1 | awk '{print $3}'); \
+    pascal=$(echo "$factory_export" | sed -E 's/^create//; s/Model$//'); \
+    printf 'export { %s as makeModel, create%sLookDevLights as makeLights } from "./factory.ts";\nexport { mountViewer } from "%s";\n' \
+      "$factory_export" "$pascal" "/build/app/static/viewer-core.js" > entry.js; \
+    node_modules/.bin/esbuild entry.js \
+      --bundle --format=esm --target=es2022 --minify --outfile=model.bundle.js; \
+    node scripts/node_smoke.mjs /build/model.bundle.js
+
+# ---------------------------------------------------------------------------
+FROM python:3.12-slim-bookworm AS runtime
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    HOME=/home/user
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends tini curl ca-certificates \
+ && rm -rf /var/lib/apt/lists/* \
+ && useradd -m -u 1000 user
+
+USER user
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user package.json package-lock.json ./
+COPY --from=nodesmoke --chown=user /build/node_modules ./node_modules
+
+# Runtime source allowlist. Build/test/deploy helpers, fixtures, local
+# verification evidence and workspace state never enter the final image.
+COPY --chown=user:user app/ ./app/
+COPY --chown=user:user forge/ ./forge/
+COPY --chown=user:user LICENSE ./LICENSE
+
+EXPOSE 7860
+
+# Local-docker convenience only; the HF runner probes app_port over HTTP.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \
+  CMD curl -fsS http://localhost:7860/health || exit 1
+
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["python", "-m", "app.main"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hoainho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,10 +1,170 @@
 ---
-title: Img2threejs
-emoji: 📚
-colorFrom: yellow
-colorTo: yellow
+title: img2threejs
+emoji: 🧊
+colorFrom: indigo
+colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
+short_description: Strict-validated image to procedural Three.js code
+tags:
+  - threejs
+  - image-to-3d
+  - procedural-generation
+  - code-generation
+  - llm
+startup_duration_timeout: 30m
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# img2threejs — image to procedural Three.js
+
+Upload one object reference image. A vision-capable LLM authors an
+`ObjectSculptSpec`; deterministic validators enforce the upstream structural
+and strict-quality rules; and the vendored generator emits a TypeScript
+`THREE.Group` factory. The result renders in a sandboxed browser viewer and is
+downloadable as the original spec, TypeScript, an ESM bundle, and standalone
+HTML.
+
+This Docker Space adapts [hoainho/img2threejs](https://github.com/hoainho/img2threejs)
+(MIT). It is reconstruction-by-code, not photogrammetry, mesh extraction, or a
+downloaded asset pack.
+
+## What the hosted workflow guarantees
+
+```text
+image ──▶ byte/type/decompression guard + deterministic probe
+      ──▶ vision LLM authors ObjectSculptSpec
+      ──▶ strict validator (errors return to the LLM, up to 3 repair rounds)
+      ──▶ original spec saved locked and unreviewed
+      ──▶ separate hosted-preview compile manifest (all supported parts)
+      ──▶ vendored generator + esbuild ──▶ sandboxed viewer/downloads
+```
+
+The hosted preview does **not** fabricate upstream review evidence. The
+downloaded `spec.json` retains an empty `reviewHistory` and its original locked
+pass order. A separate compile copy marks itself
+`hosted-unreviewed-preview` and combines the declared components into one
+preview pass. It contains no screenshot comparison, AI-vision score, reviewer,
+or `continue` decision.
+
+The result is an approximate, stylized procedural reconstruction from a single
+image. Hidden sides are inferred rather than observed or measured. Structural
+strict validation is not visual approval; production approval requires running
+the upstream pass-by-pass render, comparison, and review loop outside this
+hosted preview. Unsupported geometry families and parent cycles are rejected
+instead of being replaced by placeholder boxes.
+
+## Required Space Secrets
+
+Conversion needs a vision-capable Anthropic Messages or OpenAI-compatible chat
+endpoint. Add these under **Settings → Secrets**:
+
+| Secret | Required | Example | Purpose |
+| --- | --- | --- | --- |
+| `LLM_API_KEY` | yes | provider API key | Credential; never logged or returned to the browser. |
+| `LLM_MODEL` | yes | `claude-sonnet-4-5`, `moonshotai/kimi-k3` | Provider model identifier; it must accept images. |
+| `LLM_BASE_URL` | no | `https://api.anthropic.com` | Provider base URL; defaults to Anthropic. |
+| `LLM_API_STYLE` | no | `auto`, `anthropic`, or `openai` | `auto` tries Messages then falls back on HTTP 404. |
+| `LLM_MAX_TOKENS` | no | `16384` | Response budget for the structured spec. |
+| `LLM_TIMEOUT_S` | no | `180` | Per-request timeout in seconds. |
+| `LLM_MAX_RETRIES` | no | `2` | Transient provider retries. |
+| `LLM_REFERER`, `LLM_TITLE` | no | provider-specific | Optional attribution headers. |
+
+`ANTHROPIC_API_KEY`/`ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, and
+`ANTHROPIC_MODEL` are accepted as server-side aliases. Without a key and model,
+the app still starts, `/health` reports `llm_configured: false`, and job creation
+returns `503 llm_not_configured`; no model or placeholder is emitted.
+
+## HTTP API
+
+```bash
+curl https://<space-host>/health
+curl -F "file=@object.png" https://<space-host>/api/jobs
+curl -N https://<space-host>/api/jobs/<job-id>/events
+curl https://<space-host>/api/jobs/<job-id>/artifacts/spec.json
+curl https://<space-host>/api/jobs/<job-id>/artifacts/factory.ts
+curl https://<space-host>/api/jobs/<job-id>/artifacts/model.bundle.js
+curl https://<space-host>/api/jobs/<job-id>/artifacts/standalone.html
+```
+
+Uploads are limited to PNG, JPEG, WebP, GIF, or BMP, 10 MiB, and 40 MP by
+default. SVG is rejected. Images are orientation-normalized, metadata-stripped,
+and downscaled to at most 1024 px before processing. Defaults permit 10 jobs per
+hour per client, 2 active conversions, and 8 queued/running jobs total.
+
+## Run and test locally
+
+Python 3.12 and Node 22 are the tested versions.
+
+```bash
+python3 -m pip install -r requirements.txt
+npm ci
+pytest -q
+python3 forge/tests/test_pipeline.py
+
+LLM_API_KEY=... LLM_MODEL=... LLM_BASE_URL=... python3 -m app.main
+# http://127.0.0.1:7860
+```
+
+Build and verify the same target architecture used by Hugging Face:
+
+```bash
+docker build --platform=linux/amd64 -t img2threejs .
+docker run --rm -p 7860:7860 \
+  -e LLM_API_KEY -e LLM_MODEL -e LLM_BASE_URL img2threejs
+
+scripts/verify_docker.sh
+```
+
+The Docker build regenerates a fixture factory through the real strict gate
+and hosted-preview compiler, bundles it with esbuild, and executes the bundle
+headlessly in Node. The final runtime image contains only runtime dependencies,
+`app/`, the required `forge/` source, and the license—not tests, scripts,
+rollouts, virtual environments, caches, or the upstream comparison clone.
+
+## Deploy and verify
+
+The helper uses the currently authenticated local `hf` CLI account; an
+`HF_TOKEN` environment variable is not required. `--dry-run` performs no Hub
+mutation and prints the exact deterministic upload allowlist.
+
+```bash
+hf auth whoami
+python3 scripts/deploy_space.py --dry-run
+python3 scripts/deploy_space.py                 # sets present LLM_* aliases as Secrets
+# or: python3 scripts/deploy_space.py --no-secrets
+
+hf spaces logs Mike0021/img2threejs --build --follow
+hf spaces logs Mike0021/img2threejs --follow
+
+python3 scripts/verify_space.py                 # wait/info/logs + GET-only probes
+python3 scripts/verify_space.py \
+  --e2e tests/fixtures/mug_photo.png            # real SSE job + artifact/node smoke
+```
+
+The deploy helper stages only its allowlist and issues one sanitized
+`hf upload`. Secret values are passed in a temporary mode-0600 secrets file;
+only secret names are printed. The live verifier never submits a job unless an
+explicit `--e2e IMAGE` is supplied.
+
+## Repository layout
+
+| Path | Purpose |
+| --- | --- |
+| `app/` | FastAPI service, LLM client, pipeline adapter, SPA, and sandboxed viewer |
+| `forge/` | Vendored upstream pipeline with targeted runtime generator/safety fixes |
+| `grimoire/`, `SKILL.md` | Upstream rubrics and complete agent workflow |
+| `tests/` | Unit, HTTP, pipeline, manifest, and render smoke tests |
+| `scripts/` | Fixture builder, Node smoke, Docker verifier, deployer, live verifier |
+| `docs/SECURITY.md` | Threat model, controls, and accepted limitations |
+
+The targeted `forge/` changes preserve declared component dimensions, avoid
+misinterpreting non-axis attachments, and reject unsupported hosted-preview
+geometry rather than emitting TODO placeholders. They are not represented as
+a byte-for-byte upstream tree.
+
+## License and attribution
+
+MIT — © 2026 hoainho (upstream) and this Space's contributors. See
+`LICENSE`. three.js is MIT © the three.js authors.

SKILL.md

@@ -0,0 +1,136 @@
+---
+name: img2threejs
+description: Turn an object or character reference image into a quality-gated, animation-ready procedural Three.js model built in code. Use for image-to-3D reconstruction, detail-accurate object rebuilds, stylized/likeness-maximized human characters, sculpt specs, and staged code generation.
+license: MIT
+version: 1.2.0
+---
+
+# img2threejs — Image to procedural Three.js
+
+Rebuild the object visible in a reference image as a **code-only** procedural Three.js model,
+gated by a staged sculpting pipeline and an AI-vision self-correction loop. This is
+reconstruction-by-code, **not** photogrammetry, mesh extraction, or downloaded art packs.
+
+Agent-agnostic: works under Claude Code, Codex, or OpenCode. Wherever this doc says "agent
+vision" or "agent browser tool", use whatever the host provides — native image reading, a
+browser MCP (playwright/chrome-devtools), the project preview, or a user-supplied screenshot.
+
+## When To Use
+
+The user attaches/points to an object image and wants a procedural Three.js model, a
+reconstruction/animation/destruction plan, a sculpt spec, or code. Also for material studies,
+action-ready props, game objects, botanical/mechanical parts, and stylized reconstructions.
+
+## Core Promise
+
+Sculpt from a photo, in order — never one-shot a mesh:
+1. **Validate** the image is a suitable 3D target (`grimoire/intake/validation_rubric.md`).
+2. **Assess** object class + complexity, then write a `qualityContract` before any code.
+3. **Spec** it: component hierarchy, materials, lighting, pivots, sockets, action anchors.
+4. **Build pass-by-pass** from blockout → structure → form → material → lighting → interaction → optimization.
+5. **Verify** each pass with a screenshot compared against the reference; fail a pass if an identity-defining feature is wrong even when the global score looks fine.
+
+State explicitly when output is approximate/stylized/low-poly. A single image cannot reveal
+hidden sides or guarantee exact geometry — say so instead of faking confidence.
+
+## Required Inputs
+
+- one image path / screenshot / URL / attached image (if missing or unreadable, ask)
+- intended use: prop, game object, hero render, playable/destructible object, animation rig
+  (default: real-time browser prop with interactive performance)
+
+## The Loop (scripts do enforcement; agent vision does judgment)
+
+Run scripts from the skill root (`forge/...`). Pure Python 3.10+ stdlib, no pip installs.
+Full flags: `grimoire/scripts.md`. Never let a script *score* visuals — that is the agent's job.
+
+1. Probe local images: `forge/stage1_intake/probe_image.py <image>` (metadata only, not a visual check).
+2. **Pre-Spec Assessment Gate** — classify + score complexity + write the quality contract:
+   `forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json`. Rules: `grimoire/intake/quality_contract.md`.
+   Set `objectClass.primaryDomain` (`object` | `character` | `hybrid`) and fill the seeded
+   `detailInventory` (its `targetMinDetails` scales with complexity).
+2b. **Detail inventory** (do not skip for detailed subjects) — scan zones and enumerate every
+   identity-defining small detail (gloss, bevel, fasteners, linework, contours, stains):
+   `forge/stage1_intake/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json`.
+   Each detail MUST map to a `component.localFeatures` or `material.localOverrides` entry — never
+   prose only. Taxonomy + 3D-term recipes: `grimoire/intake/detail_inventory.md`.
+2c. **Character/hybrid subjects** — capture head-unit proportions + facial/body landmarks:
+   `forge/stage1_intake/extract_landmarks.py <image> --out anatomy.json --overlay overlay.png`, then
+   fill `preSpecAssessment.anatomy`. Route: `grimoire/character/reconstruction.md`. For maximum
+   likeness use the projection-first path (`grimoire/character/likeness_maximization.md`): solve the camera
+   (`stage1_intake/solve_camera_pose.py`), de-light the photo (`stage1_intake/delight_albedo.py`), and project it onto
+   the fitted mesh (`stage3_build/bake_projected_texture.py`). A single image cannot guarantee 100% likeness —
+   report per-region confidence and request more views for a real person.
+3. Author the spec from the assessment:
+   `forge/stage2_spec/new_sculpt_spec.py "Name" --image <img> --assessment assessment.json --out object-sculpt-spec.json`.
+   Replace generic starter `featureReviewTargets` with the object's real identity-defining
+   systems (≤5 critical, ≤3 important per pass); for characters add `anatomy-proportion`,
+   `face-landmark-placement`, `pose-silhouette`, `outfit-and-palette`. Use 3D-graphics terms only
+   (`grimoire/glossary/3d_vocabulary.md`), never "nice/smooth/shiny".
+4. When material fidelity matters and a source image exists, extract reference PBR evidence per crop:
+   `forge/stage1_intake/extract_pbr_evidence.py <crop> --out-dir <dir> --material-id <id> --target-threshold 0.7`.
+   Confidence < 0.7 is a stop/refine-input signal, not a pass. It is inference, not inverse rendering.
+5. Validate, then strict-validate before generating code:
+   `forge/stage2_spec/validate_sculpt_spec.py object-sculpt-spec.json` then `--strict-quality`.
+   Strict blocks shallow specs (a complex object with one root, no repetition systems, no
+   local overrides, no micro groups is NOT implementation-ready even if JSON validates).
+6. **Locked build passes** — only touch the currently unlocked pass:
+   `forge/stage3_build/orchestrate_passes.py status object-sculpt-spec.json`
+   `forge/stage3_build/orchestrate_passes.py check object-sculpt-spec.json --pass-id <pass>`
+   `forge/stage3_build/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts`
+   (generator is pass-gated: a future `--pass-id` fails until prior passes are reviewed `continue`).
+7. Render the current pass in a browser/preview, capture a screenshot at a review viewpoint.
+8. Package one side-by-side sheet, then inspect it with agent vision:
+   `forge/stage4_review/make_comparison_sheet.py --reference <img> --render <shot> --out cmp.png --json`.
+9. Record the review (overall + per-layer + per-feature scores + decision):
+   `forge/stage4_review/append_review.py object-sculpt-spec.json --pass-id <pass> --fidelity <0-1> --action <continue|refine-spec|refine-code|request-input|stop> --summary "..." --render-screenshot <shot> --comparison-image cmp.png --ai-vision-score <0-1> --layer-scores-json '{...}' --feature-reviews-json <f.json> --in-place`.
+10. Sync pipeline state after manual review edits:
+    `forge/stage3_build/orchestrate_passes.py sync object-sculpt-spec.json --in-place`.
+
+## Gates (do not skip)
+
+- **Suitability**: pass / conditional / reject before any planning. `grimoire/intake/validation_rubric.md`.
+- **Pre-spec / strict-quality**: blocks code gen until the spec is deep enough for its contract.
+- **Screenshot feedback**: `continue` is allowed only with a render + comparison sheet + global
+  AI-vision score ≥ threshold (default 0.7) AND every critical feature ≥ its own threshold.
+  Details + per-layer scorecard: `grimoire/feedback/render_capture.md`.
+- **Action-ready**: build a runtime hierarchy (pivots, sockets, colliders, destruction groups),
+  never an inert lump; expose `root.userData.sculptRuntime`. `grimoire/readiness/action_rigging.md`.
+- **Attachment**: child appendages (branches/limbs/handles/tubes) need `attachment.parentSocket`,
+  `localStart`, `localEnd`, `contactType`, `embedDepth`/`overlap`, `gapTolerance` — no mid-air parts.
+  `grimoire/readiness/joint_attachment.md`.
+- **Material/lighting**: `grimoire/feedback/shading_realism.md` — independent PBR channels
+  (never alias albedo into roughness/normal/AO), macro/meso/micro frequency bands, real lights.
+- **Detail inventory**: for `moderate`+ subjects strict-quality blocks code gen until the
+  `detailInventory` reaches `targetMinDetails` and every detail maps to a real component/material
+  entry (gloss needs low-roughness/clearcoat; fasteners need instancing/micro parts).
+- **Character track**: when `primaryDomain` is `character`/`hybrid` (or `--character`), the spec
+  author auto-builds a stylized humanoid template (head/neck/torso/arms + hair, glasses,
+  headphones, face features), flattened to world space under a hidden root, with per-part
+  character materials and character build passes (`proportion-lock`, `feature-placement`).
+  strict-quality requires a filled `anatomy` block (head-units, proportions, face landmarks) and
+  character feature targets. Suitability routing for humans: `grimoire/intake/validation_rubric.md`
+  (stylized vs maximum-likeness). Stylized bust, not a face-copy; refine positions per reference.
+
+## Self-Correction
+
+After every pass, decide exactly one: `continue | refine-spec | refine-code | request-input | stop`.
+`refine-spec` fixes a wrong/missing/shallow spec (re-validate, don't patch code around it);
+`refine-code` fixes geometry/material/lighting that doesn't match a sound spec. Full root-cause
+guide + fidelity scale: `grimoire/review/self_correction.md`.
+
+## Implementation Rules (brief)
+
+TypeScript + plain Three.js unless the project uses a wrapper. `Group` factory
+`createObjectNameModel(spec, options)`, reconstruction data kept separate from renderer objects,
+deterministic seeds for all procedural noise. Prefer primitives / `Shape` extrude / curve+tube /
+instancing / displacement / generated canvas textures before any external art. Full geometry &
+material recipes + hard-won failure patterns: `grimoire/build/geometry_patterns.md`.
+
+## Output
+
+- **Analysis-only**: suitability verdict + scores, object extraction, macro→micro hierarchy,
+  geometry strategy, material/lighting recipe, animation/destruction feasibility, plan + risks.
+- **Implementation**: the above briefly, then edit code; verify with typecheck/build + a screenshot.
+- **Not feasible**: name the blocker, ask for more views / cleaner image / accepted stylization /
+  a narrower target. "This cannot reach the requested fidelity from this image" is a valid result.

app/__init__.py

@@ -0,0 +1 @@
+"""img2threejs Hugging Face Space application package."""

app/config.py

@@ -0,0 +1,202 @@
+"""Runtime configuration for the img2threejs Space.
+
+All values come from environment variables. On Hugging Face Spaces the
+``LLM_*`` variables are meant to be set as *Space Secrets* (Settings ->
+Secrets); they are injected into the process environment at runtime.
+
+The conventional ``ANTHROPIC_API_KEY`` / ``ANTHROPIC_BASE_URL`` /
+``ANTHROPIC_MODEL`` names are honoured as fallbacks so the Space also works
+when a deployer only sets those.
+
+Nothing in this module may ever log or return the API key value.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+from dataclasses import dataclass, field
+
+
+def _first(*names: str) -> str | None:
+    for name in names:
+        value = os.environ.get(name)
+        if value and value.strip():
+            return value.strip()
+    return None
+
+
+def _int(
+    name: str,
+    default: int,
+    *,
+    minimum: int | None = None,
+    maximum: int | None = None,
+) -> int:
+    """Read an integer setting without allowing malformed or extreme input.
+
+    Environment variables are an operational boundary, not trusted Python
+    values.  Falling back on parse failure keeps the app bootable; clamping
+    keeps an accidental value such as ``MAX_CONCURRENT_JOBS=-1`` from
+    disabling a guard or allocating an unreasonable amount of work.
+    """
+    raw = os.environ.get(name)
+    value = default
+    if raw is not None:
+        try:
+            value = int(raw.strip())
+        except (TypeError, ValueError):
+            value = default
+    if minimum is not None:
+        value = max(minimum, value)
+    if maximum is not None:
+        value = min(maximum, value)
+    return value
+
+
+def _float(
+    name: str,
+    default: float,
+    *,
+    minimum: float | None = None,
+    maximum: float | None = None,
+) -> float:
+    """Read a finite, optionally clamped floating-point setting."""
+    raw = os.environ.get(name)
+    value = default
+    if raw is not None:
+        try:
+            parsed = float(raw.strip())
+            value = parsed if math.isfinite(parsed) else default
+        except (TypeError, ValueError):
+            value = default
+    if minimum is not None:
+        value = max(minimum, value)
+    if maximum is not None:
+        value = min(maximum, value)
+    return value
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Immutable runtime settings snapshot."""
+
+    # --- LLM provider (Space Secrets) -------------------------------------
+    llm_api_key: str | None = field(
+        default_factory=lambda: _first("LLM_API_KEY", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN")
+    )
+    llm_base_url: str = field(
+        default_factory=lambda: _first("LLM_BASE_URL", "ANTHROPIC_BASE_URL")
+        or "https://api.anthropic.com"
+    )
+    llm_model: str | None = field(
+        default_factory=lambda: _first("LLM_MODEL", "ANTHROPIC_MODEL")
+    )
+    # "anthropic" = Messages API only, "openai" = chat/completions only,
+    # "auto" = anthropic first, fall back to openai on HTTP 404.
+    llm_api_style: str = field(
+        default_factory=lambda: (os.environ.get("LLM_API_STYLE") or "auto").strip().lower()
+    )
+    # Reasoning models (e.g. kimi-k3) spend thinking tokens inside this
+    # budget; 8192 truncates real specs. 16384 verified end-to-end.
+    llm_max_tokens: int = field(
+        default_factory=lambda: _int(
+            "LLM_MAX_TOKENS", 16384, minimum=256, maximum=131_072
+        )
+    )
+    llm_timeout_s: float = field(
+        default_factory=lambda: _float(
+            "LLM_TIMEOUT_S", 180.0, minimum=1.0, maximum=1800.0
+        )
+    )
+    llm_max_retries: int = field(
+        default_factory=lambda: _int("LLM_MAX_RETRIES", 2, minimum=0, maximum=10)
+    )
+    llm_referer: str | None = field(default_factory=lambda: _first("LLM_REFERER"))
+    llm_title: str | None = field(default_factory=lambda: _first("LLM_TITLE"))
+
+    # --- pipeline behaviour ------------------------------------------------
+    spec_repair_rounds: int = field(
+        default_factory=lambda: _int("SPEC_REPAIR_ROUNDS", 3, minimum=0, maximum=10)
+    )
+
+    # --- HTTP / server ------------------------------------------------------
+    port: int = field(
+        default_factory=lambda: _int("PORT", 7860, minimum=1, maximum=65_535)
+    )
+    runs_dir: str = field(default_factory=lambda: os.environ.get("RUNS_DIR", "/tmp/i2t-runs"))
+    max_upload_bytes: int = field(
+        default_factory=lambda: _int(
+            "MAX_UPLOAD_BYTES", 10 * 1024 * 1024,
+            minimum=64 * 1024, maximum=50 * 1024 * 1024,
+        )
+    )
+    max_image_pixels: int = field(
+        default_factory=lambda: _int(
+            "MAX_IMAGE_PIXELS", 40_000_000, minimum=4096, maximum=100_000_000
+        )
+    )
+    # Longest-side pixel cap for the normalised image handed to the forge
+    # scripts (pure-Python per-pixel readers) and to the LLM.
+    normalize_max_side: int = field(
+        default_factory=lambda: _int(
+            "NORMALIZE_MAX_SIDE", 1024, minimum=64, maximum=8192
+        )
+    )
+    job_ttl_s: int = field(
+        default_factory=lambda: _int(
+            "JOB_TTL_S", 2 * 60 * 60, minimum=60, maximum=7 * 24 * 60 * 60
+        )
+    )
+    # Wall-clock bound for a queued/running pipeline.  ``run_job`` owns the
+    # timeout transition so every timeout produces the same terminal event as
+    # other pipeline failures.
+    job_timeout_s: float = field(
+        default_factory=lambda: _float(
+            "JOB_TIMEOUT_S", 900.0, minimum=30.0, maximum=3600.0
+        )
+    )
+    max_concurrent_jobs: int = field(
+        default_factory=lambda: _int(
+            "MAX_CONCURRENT_JOBS", 2, minimum=1, maximum=16
+        )
+    )
+    # Hard cap on queued+running jobs (each pins its upload bytes in memory).
+    max_in_flight_jobs: int = field(
+        default_factory=lambda: _int(
+            "MAX_IN_FLIGHT_JOBS", 8, minimum=1, maximum=64
+        )
+    )
+    rate_limit_jobs_per_hour: int = field(
+        default_factory=lambda: _int(
+            "RATE_LIMIT_JOBS_PER_HOUR", 10, minimum=1, maximum=10_000
+        )
+    )
+
+    # --- tooling ------------------------------------------------------------
+    # esbuild 0.25+ ships a statically-linked native binary (no node needed
+    # at runtime); the .bin path is an npm-managed symlink to it.
+    esbuild_entry: str = field(
+        default_factory=lambda: os.environ.get("ESBUILD_ENTRY", "node_modules/.bin/esbuild")
+    )
+
+    # --- informational -------------------------------------------------------
+    space_id: str | None = field(default_factory=lambda: _first("SPACE_ID"))
+    space_host: str | None = field(default_factory=lambda: _first("SPACE_HOST"))
+
+    @property
+    def llm_configured(self) -> bool:
+        return bool(self.llm_api_key and self.llm_model)
+
+    @property
+    def missing_llm_vars(self) -> list[str]:
+        missing: list[str] = []
+        if not self.llm_api_key:
+            missing.append("LLM_API_KEY")
+        if not self.llm_model:
+            missing.append("LLM_MODEL")
+        return missing
+
+
+def load_settings() -> Settings:
+    return Settings()

app/exemplar_spec.json

@@ -0,0 +1,485 @@
+{
+  "targetName": "Mug",
+  "targetId": "mug",
+  "schemaVersion": "2.0",
+  "suitability": "pass",
+  "sourceImage": "ref.png",
+  "coordinateFrame": {
+    "up": "+Y",
+    "forward": "+Z",
+    "units": "meters",
+    "origin": "ground-center"
+  },
+  "silhouette": {
+    "primaryAxis": "y",
+    "dominantCurves": [
+      "cylindrical body"
+    ],
+    "negativeSpaces": [
+      "handle loop"
+    ]
+  },
+  "scores": {
+    "object_isolation": 3,
+    "silhouette_readability": 3
+  },
+  "terminologyProfile": {
+    "geometryTerms": [
+      "cylinder",
+      "torus",
+      "bevel"
+    ],
+    "materialTerms": [
+      "albedo",
+      "roughness",
+      "clearcoat"
+    ],
+    "lightingTerms": [
+      "key light",
+      "fill light",
+      "rim light"
+    ],
+    "descriptionRule": "measurable 3D terms only"
+  },
+  "preSpecAssessment": {
+    "objectClass": {
+      "primaryType": "vessel",
+      "primaryDomain": "object",
+      "formLanguage": [
+        "cylindrical",
+        "hard-surface"
+      ],
+      "structureKind": [
+        "single-body-with-appendage"
+      ],
+      "motionPotential": [
+        "static"
+      ],
+      "materialFamilies": [
+        "glazed-ceramic"
+      ]
+    },
+    "complexity": {
+      "tier": "simple",
+      "scores": {
+        "silhouetteComplexity": 1,
+        "componentCount": 1
+      },
+      "estimatedCounts": {
+        "macroComponents": 1,
+        "mesoComponents": 1,
+        "microFeatureGroups": 1,
+        "materialLayers": 1,
+        "repetitionSystems": 0
+      },
+      "reasoning": [
+        "single body plus handle"
+      ]
+    },
+    "specDepthDecision": {
+      "requiredDepth": "simple",
+      "minimumComponentLevels": [
+        "macro"
+      ],
+      "needsRepetitionSystems": false,
+      "needsMaterialLocalOverrides": true,
+      "needsMultipleReviewViews": true,
+      "needsActionReadyHierarchy": true
+    },
+    "unknownsToResolveBeforeImplementation": [],
+    "detailInventory": {
+      "scanMethod": "component-zones",
+      "targetMinDetails": 3,
+      "details": [
+        {
+          "id": "d1",
+          "kind": "gloss",
+          "zone": "body",
+          "mapsTo": {
+            "ref": "ceramic/glaze-gloss"
+          }
+        },
+        {
+          "id": "d2",
+          "kind": "bevel",
+          "zone": "rim",
+          "mapsTo": {
+            "ref": "body/rim-bevel"
+          }
+        },
+        {
+          "id": "d3",
+          "kind": "contour",
+          "zone": "handle",
+          "mapsTo": {
+            "ref": "handle"
+          }
+        }
+      ]
+    }
+  },
+  "qualityContract": {
+    "qualityBar": "simple",
+    "definitionOfDone": [
+      "render matches silhouette, glaze gloss, handle attachment"
+    ],
+    "minimumSpecDepth": {
+      "macroComponents": 1,
+      "mesoComponents": 0,
+      "microFeatureGroups": 0,
+      "materialLayers": 1,
+      "repetitionSystems": 0,
+      "reviewViewpoints": 2
+    },
+    "featureGroups": [
+      {
+        "id": "overall-silhouette",
+        "name": "Silhouette",
+        "required": true,
+        "qualityCriteria": [
+          "cylindrical body and handle loop read correctly"
+        ]
+      },
+      {
+        "id": "primary-structure",
+        "name": "Structure",
+        "required": true,
+        "qualityCriteria": [
+          "body/handle hierarchy named"
+        ]
+      },
+      {
+        "id": "surface-material-response",
+        "name": "Material",
+        "required": true,
+        "qualityCriteria": [
+          "glaze gloss and roughness variation specified"
+        ]
+      }
+    ],
+    "visualDeltaChecks": [
+      "silhouette delta"
+    ],
+    "antiShallowSpecRules": [
+      "no single-root compound objects"
+    ]
+  },
+  "qualityTargets": {
+    "targetFidelity": 0.7,
+    "mustMatch": [
+      "silhouette"
+    ],
+    "niceToHave": [],
+    "reviewViewpoints": [
+      "front",
+      "three-quarter"
+    ]
+  },
+  "actionReadiness": {
+    "contract": "runtime hierarchy with pivots and sockets",
+    "defaultRigType": "static-prop",
+    "rootMotionNode": "root",
+    "requiredComponentFields": [
+      "actionProfile"
+    ],
+    "transformChannels": [
+      "translate",
+      "rotate"
+    ],
+    "authoringRules": [
+      "no floating parts"
+    ]
+  },
+  "selfCorrectLoop": {
+    "enabled": true,
+    "reviewAfterPasses": [
+      "blockout"
+    ],
+    "allowedActions": [
+      "continue",
+      "refine-spec",
+      "refine-code",
+      "request-input",
+      "stop"
+    ],
+    "visualAcceptance": {
+      "reviewer": "ai-vision",
+      "threshold": 0.7,
+      "comparisonArtifactRequired": true,
+      "layerScoresRequired": true,
+      "requiredLayerScores": [
+        "silhouetteProportion"
+      ],
+      "featureReviewPolicy": {
+        "enabled": true,
+        "maxCriticalFeaturesPerPass": 5,
+        "maxImportantFeaturesPerPass": 3,
+        "criticalDefaultThreshold": 0.8,
+        "importantAverageThreshold": 0.65,
+        "adaptiveEscalation": true,
+        "singleImagePairOnly": true,
+        "reviewUnit": "semantic-subsystem",
+        "selectionRule": "most salient systems"
+      }
+    },
+    "screenshotPolicy": {
+      "requiredForPasses": [
+        "blockout"
+      ],
+      "preferredCapture": "in-app"
+    }
+  },
+  "featureReviewTargets": [
+    {
+      "id": "overall-silhouette",
+      "name": "Body silhouette",
+      "tier": "critical",
+      "passIds": [
+        "blockout"
+      ],
+      "minimumScore": 0.8,
+      "mustPass": true,
+      "componentRefs": [
+        "body"
+      ],
+      "evidenceRefs": [
+        "full-object"
+      ]
+    }
+  ],
+  "buildPasses": [
+    {
+      "id": "blockout",
+      "goal": "macro silhouette",
+      "componentRefs": [
+        "body"
+      ],
+      "acceptance": [
+        "silhouette reads"
+      ]
+    },
+    {
+      "id": "structural-pass",
+      "goal": "add handle",
+      "componentRefs": [
+        "handle"
+      ],
+      "acceptance": [
+        "handle attached"
+      ]
+    },
+    {
+      "id": "material-pass",
+      "goal": "glaze",
+      "componentRefs": [
+        "body"
+      ],
+      "acceptance": [
+        "glaze reads"
+      ]
+    }
+  ],
+  "sculptPipeline": {
+    "passGateMode": "locked-sequential",
+    "passOrder": [
+      "blockout",
+      "structural-pass",
+      "material-pass"
+    ],
+    "currentPass": "blockout",
+    "completedPasses": [],
+    "nextRequiredEvidence": [
+      "render screenshot"
+    ]
+  },
+  "lookDevTargets": {
+    "qualityPriority": "balanced"
+  },
+  "lightingFromPhoto": [
+    "key light upper left, soft directional",
+    "fill light from front, low intensity ambient",
+    "rim light from behind right for edge separation",
+    "exposure neutral with ACES tone mapping",
+    "contact shadow under base on ground plane"
+  ],
+  "componentTree": [
+    {
+      "id": "body",
+      "name": "Mug body",
+      "level": "macro",
+      "role": "shell",
+      "primitive": "cylinder",
+      "material": "ceramic",
+      "importance": 1.0,
+      "confidence": 0.9,
+      "dimensions": {
+        "width": 0.08,
+        "height": 0.1,
+        "depth": 0.08
+      },
+      "transform": {
+        "position": [
+          0,
+          0.05,
+          0
+        ],
+        "rotation": [
+          0,
+          0,
+          0
+        ],
+        "scale": [
+          1,
+          1,
+          1
+        ]
+      },
+      "actionProfile": {
+        "animationRole": "static",
+        "pivot": {
+          "mode": "center",
+          "localPosition": [
+            0,
+            0,
+            0
+          ],
+          "axis": [
+            0,
+            1,
+            0
+          ]
+        },
+        "sockets": [
+          {
+            "id": "handle-socket",
+            "localPosition": [
+              0.045,
+              0.0,
+              0.0
+            ]
+          }
+        ]
+      },
+      "localFeatures": [
+        {
+          "id": "rim-bevel",
+          "kind": "bevel",
+          "note": "rounded lip"
+        }
+      ],
+      "evidenceRefs": [
+        "full-object"
+      ]
+    },
+    {
+      "id": "handle",
+      "name": "Handle",
+      "level": "meso",
+      "role": "handle",
+      "primitive": "torus",
+      "material": "ceramic",
+      "parent": "body",
+      "importance": 0.8,
+      "confidence": 0.85,
+      "dimensions": {
+        "width": 0.04,
+        "height": 0.06,
+        "depth": 0.015
+      },
+      "transform": {
+      "position": [
+        0.055,
+        0.0,
+        0
+        ],
+        "rotation": [
+          0,
+          0,
+          0
+        ],
+        "scale": [
+          1,
+          1,
+          1
+        ]
+      },
+    "attachment": {
+      "parentId": "body",
+      "parentSocket": "handle-socket",
+        "localStart": [
+          0.04,
+          0.07,
+          0
+        ],
+        "localEnd": [
+          0.04,
+          0.03,
+          0
+        ],
+        "contactType": "embed",
+        "embedDepth": 0.004,
+        "gapTolerance": 0.001
+      },
+      "actionProfile": {
+        "animationRole": "static"
+      },
+      "evidenceRefs": [
+        "full-object"
+      ]
+    }
+  ],
+  "materials": [
+    {
+      "id": "ceramic",
+      "name": "Glazed ceramic",
+      "baseColor": "#3f6f9f",
+      "roughness": {
+        "base": 0.22,
+        "variation": 0.1
+      },
+      "metalness": {
+        "base": 0.0
+      },
+      "clearcoat": {
+        "base": 0.6
+      },
+      "colorVariation": {
+        "palette": [
+          "#3f6f9f",
+          "#35618c"
+        ],
+        "amplitude": 0.08
+      },
+      "localOverrides": [
+        {
+          "id": "glaze-gloss",
+          "region": "upper body",
+          "roughness": 0.12
+        }
+      ],
+      "ambientOcclusion": {
+        "cavityStrength": 0.3
+      }
+    }
+  ],
+  "repetitionSystems": [],
+  "proceduralStrategy": [
+    "blockout cylinder",
+    "attach handle torus",
+    "apply glaze"
+  ],
+  "reviewHistory": [],
+  "viewEvidence": [
+    {
+      "id": "full-object",
+      "imageRegion": {
+        "x": 0,
+        "y": 0,
+        "width": 1,
+        "height": 1
+      },
+      "confidence": 0.8
+    }
+  ],
+  "risks": []
+}

app/forge_bridge.py

@@ -0,0 +1,314 @@
+"""Subprocess bridge to the vendored upstream ``forge/`` pipeline scripts.
+
+This module is intentionally *standard-library only* so it can also run
+inside the minimal Docker build stage that regenerates the test fixture
+factory (``scripts/build_fixture_factory.py``).
+
+Safety contract:
+  * every invocation is a list-argv ``subprocess.run`` (never shell=True);
+  * child processes get a scrubbed environment (no ``LLM_*``/``ANTHROPIC_*``
+    variables can leak into them);
+  * every call has a hard timeout and bounded captured output;
+  * all file paths passed to the scripts live inside a per-job directory
+    owned by the caller -- the scripts resolve and write whatever path they
+    are given, so containment is enforced here by construction.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+FORGE = REPO_ROOT / "forge"
+
+PROBE = FORGE / "stage1_intake" / "probe_image.py"
+VALIDATE = FORGE / "stage2_spec" / "validate_sculpt_spec.py"
+ORCHESTRATE = FORGE / "stage3_build" / "orchestrate_passes.py"
+GENERATE = FORGE / "stage3_build" / "generate_threejs_factory.py"
+
+_MAX_CAPTURE = 1024 * 1024  # 1 MiB per stream
+
+
+class ForgeError(Exception):
+    """A forge script exited non-zero (or timed out). Carries diagnostics."""
+
+    def __init__(self, script: str, message: str, *, returncode: int | None = None,
+                 stdout: str = "", stderr: str = "") -> None:
+        super().__init__(message)
+        self.script = script
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+@dataclass(frozen=True)
+class ForgeResult:
+    returncode: int
+    stdout: str
+    stderr: str
+
+
+def _scrubbed_env() -> dict[str, str]:
+    env = {
+        "PATH": os.environ.get("PATH", "/usr/local/bin:/usr/bin:/bin"),
+        "HOME": os.environ.get("HOME", "/tmp"),
+        "PYTHONDONTWRITEBYTECODE": "1",
+        "PYTHONUNBUFFERED": "1",
+        "LANG": "C.UTF-8",
+    }
+    tmp = os.environ.get("TMPDIR")
+    if tmp:
+        env["TMPDIR"] = tmp
+    return env
+
+
+def run_forge(script: Path, *args: str, timeout: int = 120, cwd: Path | None = None) -> ForgeResult:
+    """Run a forge script; return captured output. Never raises on rc != 0."""
+    argv = [sys.executable, str(script), *args]
+    try:
+        proc = subprocess.run(
+            argv,
+            cwd=str(cwd) if cwd else None,
+            env=_scrubbed_env(),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            errors="replace",
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise ForgeError(
+            script.name, f"{script.name} timed out after {timeout}s",
+            returncode=None, stdout=exc.stdout or "", stderr=exc.stderr or "",
+        ) from exc
+    return ForgeResult(
+        returncode=proc.returncode,
+        stdout=proc.stdout[:_MAX_CAPTURE],
+        stderr=proc.stderr[:_MAX_CAPTURE],
+    )
+
+
+def probe_image(image_path: Path, *, timeout: int = 60) -> dict:
+    """Run stage1_intake/probe_image.py and parse its JSON stdout."""
+    result = run_forge(PROBE, str(image_path), timeout=timeout)
+    if result.returncode != 0:
+        raise ForgeError(
+            PROBE.name, f"probe_image failed (rc={result.returncode})",
+            returncode=result.returncode, stdout=result.stdout, stderr=result.stderr,
+        )
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise ForgeError(PROBE.name, "probe_image did not return JSON",
+                         returncode=result.returncode, stdout=result.stdout,
+                         stderr=result.stderr) from exc
+    if not isinstance(payload, dict):
+        raise ForgeError(PROBE.name, "probe_image returned non-object JSON",
+                         returncode=result.returncode, stdout=result.stdout)
+    return payload
+
+
+def validate_spec(spec_path: Path, *, strict: bool = True, timeout: int = 60) -> dict:
+    """Run the spec validator. Returns ``{ok, errors, warnings, ...}``.
+
+    The validator exits 0 on PASS and 1 on FAIL; both are normal outcomes.
+    rc > 1 (argparse/IO errors) raises ForgeError.
+    """
+    args = [str(spec_path), "--json"]
+    if strict:
+        args.append("--strict-quality")
+    result = run_forge(VALIDATE, *args, timeout=timeout)
+    if result.returncode not in (0, 1):
+        raise ForgeError(
+            VALIDATE.name, f"validate_sculpt_spec crashed (rc={result.returncode})",
+            returncode=result.returncode, stdout=result.stdout, stderr=result.stderr,
+        )
+    try:
+        payload = json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise ForgeError(VALIDATE.name, "validator did not return JSON",
+                         returncode=result.returncode, stdout=result.stdout,
+                         stderr=result.stderr) from exc
+    payload.setdefault("ok", result.returncode == 0)
+    return payload
+
+
+def orchestrate_sync(spec_path: Path, *, timeout: int = 60) -> None:
+    """Refresh sculptPipeline from reviewHistory (sync --in-place)."""
+    result = run_forge(ORCHESTRATE, "sync", str(spec_path), "--in-place", timeout=timeout)
+    if result.returncode != 0:
+        raise ForgeError(
+            ORCHESTRATE.name, f"orchestrate sync failed (rc={result.returncode})",
+            returncode=result.returncode, stdout=result.stdout, stderr=result.stderr,
+        )
+
+
+def generate_factory(spec_path: Path, out_path: Path, *, pass_id: str | None = None,
+                     timeout: int = 120) -> None:
+    """Emit the TypeScript factory. Raises ForgeError on gate/IO failure."""
+    args = [str(spec_path), "--out", str(out_path), "--force"]
+    if pass_id:
+        args.extend(["--pass-id", pass_id])
+    result = run_forge(GENERATE, *args, timeout=timeout)
+    if result.returncode != 0:
+        raise ForgeError(
+            GENERATE.name,
+            f"factory generation failed for pass {pass_id or '(current)'} "
+            f"(rc={result.returncode}): {result.stderr.strip()[:400]}",
+            returncode=result.returncode, stdout=result.stdout, stderr=result.stderr,
+        )
+    if not out_path.exists() or out_path.stat().st_size == 0:
+        raise ForgeError(GENERATE.name, "generator exited 0 but produced no output",
+                         returncode=result.returncode, stdout=result.stdout,
+                         stderr=result.stderr)
+
+
+HOSTED_PREVIEW_PASS = "hosted-preview"
+HOSTED_PRIMITIVES = {
+    "box", "sphere", "ellipsoid", "cylinder", "cone", "capsule", "torus",
+    "plane-card",
+}
+
+
+def _is_positive_number(value: object) -> bool:
+    return (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and float(value) > 0
+    )
+
+
+def _resolved_dimensions(component: dict) -> tuple[object, object, object]:
+    dimensions = component.get("dimensions")
+    if not isinstance(dimensions, dict):
+        return None, None, None
+    radius = dimensions.get("radius")
+    diameter = float(radius) * 2 if _is_positive_number(radius) else None
+    width = dimensions.get("width", diameter)
+    height = dimensions.get("height", dimensions.get("length"))
+    depth = dimensions.get("depth", diameter)
+    if component.get("primitive") == "plane-card" and depth is None:
+        depth = 1.0
+    return width, height, depth
+
+
+def hosted_spec_errors(spec: dict) -> list[str]:
+    """Return deterministic limitations of the hosted preview compiler.
+
+    The upstream schema accepts procedural primitive families that the
+    vendored generator still represents with placeholder boxes. The hosted
+    service rejects those before generation rather than returning a model
+    that silently disagrees with its spec. Parent cycles are also rejected
+    explicitly so generator recursion cannot hang.
+    """
+    components = [
+        item for item in spec.get("componentTree", []) if isinstance(item, dict)
+    ]
+    errors: list[str] = []
+    ids = {
+        str(item.get("id")) for item in components
+        if isinstance(item.get("id"), str) and item.get("id")
+    }
+    parents: dict[str, str | None] = {}
+    for index, component in enumerate(components):
+        component_id = component.get("id")
+        label = str(component_id or f"componentTree[{index}]")
+        primitive = str(component.get("primitive") or "")
+        if primitive not in HOSTED_PRIMITIVES:
+            errors.append(
+                f"hosted preview: component {label!r} uses unsupported primitive "
+                f"{primitive!r}; choose one of {', '.join(sorted(HOSTED_PRIMITIVES))}"
+            )
+        dimensions = _resolved_dimensions(component)
+        if not all(_is_positive_number(value) for value in dimensions):
+            errors.append(
+                f"hosted preview: component {label!r} needs positive width, height, "
+                "and depth dimensions (radius/length aliases are accepted)"
+            )
+        if isinstance(component_id, str) and component_id:
+            parent = component.get("parent")
+            parents[component_id] = str(parent) if parent is not None else None
+
+    for component_id, parent in parents.items():
+        if parent is not None and parent not in ids:
+            errors.append(
+                f"hosted preview: component {component_id!r} references missing parent {parent!r}"
+            )
+            continue
+        seen: set[str] = set()
+        cursor: str | None = component_id
+        while cursor is not None and cursor in parents:
+            if cursor in seen:
+                errors.append(
+                    f"hosted preview: component parent cycle contains {cursor!r}"
+                )
+                break
+            seen.add(cursor)
+            cursor = parents[cursor]
+    return list(dict.fromkeys(errors))
+
+
+def prepare_hosted_preview(spec: dict) -> dict:
+    """Create an app-only compile manifest without claiming visual approval.
+
+    ``spec`` remains the strict-gated upstream artifact with its locked pass
+    order and empty review history. The returned deep copy contains one
+    explicitly unreviewed preview pass referencing every declared component.
+    It is compiled solely to let users inspect the procedural draft; it is
+    not an upstream ``continue`` decision and carries no scores or evidence.
+    """
+    preview = copy.deepcopy(spec)
+    component_refs = [
+        item["id"] for item in preview.get("componentTree", [])
+        if isinstance(item, dict) and isinstance(item.get("id"), str) and item["id"]
+    ]
+    source_order = pass_order(spec)
+    preview["buildPasses"] = [{
+        "id": HOSTED_PREVIEW_PASS,
+        "label": "Hosted unreviewed preview",
+        "goal": "Compile all strict-validated components for inspection only",
+        "componentRefs": component_refs,
+        "acceptance": ["No visual acceptance is claimed by this preview"],
+        "acceptanceCriteria": ["No visual acceptance is claimed by this preview"],
+    }]
+    preview["sculptPipeline"] = {
+        "passGateMode": "hosted-unreviewed-preview",
+        "passOrder": [HOSTED_PREVIEW_PASS],
+        "currentPass": HOSTED_PREVIEW_PASS,
+        "completedPasses": [],
+        "sourcePassOrder": source_order,
+    }
+    preview["reviewHistory"] = []
+    preview["hostedPreview"] = {
+        "reviewStatus": "unreviewed",
+        "sourcePassOrder": source_order,
+        "notice": (
+            "Compile-only preview. No screenshot comparison, AI-vision score, "
+            "or upstream build-pass approval has occurred."
+        ),
+    }
+    return preview
+
+
+def pass_order(spec: dict) -> list[str]:
+    ids = [
+        item["id"]
+        for item in spec.get("buildPasses", [])
+        if isinstance(item, dict) and isinstance(item.get("id"), str) and item["id"].strip()
+    ]
+    return ids or ["blockout"]
+
+
+_FACTORY_EXPORT_RE = re.compile(r"export function (create\w+Model)\b")
+
+
+def factory_export_name(ts_source: str) -> str | None:
+    """Extract the ``create<Name>Model`` export from generated TypeScript."""
+    match = _FACTORY_EXPORT_RE.search(ts_source)
+    return match.group(1) if match else None

app/image_guard.py

@@ -0,0 +1,184 @@
+"""Untrusted image upload validation and normalisation.
+
+Security contract (see docs/SECURITY.md):
+  * hard byte cap enforced before decoding;
+  * content sniffing with Pillow -- the client-supplied filename, extension
+    and Content-Type are never trusted;
+  * decompression-bomb guards (Pillow ``MAX_IMAGE_PIXELS`` + explicit pixel
+    and dimension caps);
+  * SVG rejected outright (scriptable XML, not an image for our purposes);
+  * output is a freshly re-encoded RGB PNG (EXIF/ICC/XMP metadata stripped,
+    orientation applied), downscaled so the pure-Python per-pixel PNG readers
+    in ``forge/`` and the LLM image payload stay cheap.
+"""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass
+
+from PIL import Image, ImageOps
+
+# Pillow's own bomb guard; load_settings() re-applies the configured value
+# at import time of the pipeline (module-level default keeps tests simple).
+Image.MAX_IMAGE_PIXELS = 40_000_000
+
+ALLOWED_FORMATS = {"PNG", "JPEG", "WEBP", "GIF", "BMP"}
+
+
+class ImageRejected(Exception):
+    """Raised when an upload fails validation. Carries a user-safe reason."""
+
+    def __init__(self, reason: str, code: str = "image_rejected") -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.code = code
+
+
+@dataclass(frozen=True)
+class NormalizedImage:
+    png_bytes: bytes
+    width: int
+    height: int
+    original_format: str
+    original_width: int
+    original_height: int
+    downscaled: bool
+
+
+def _sniff(data: bytes) -> Image.Image:
+    """Open enough of the image to identify its format and dimensions.
+
+    Do not decode pixels here.  Callers must enforce declared dimension and
+    pixel caps before invoking ``load()``; that ordering is the protection
+    against small compressed files expanding into excessive work or memory.
+    """
+    if not data:
+        raise ImageRejected("The uploaded file is empty.", "empty_file")
+    # Cheap pre-check: SVG (and other XML) is rejected before Pillow ever
+    # sees it -- it is a document, not a raster image.
+    head = data[:512].lstrip().lower()
+    if head.startswith(b"<") and (b"<svg" in head or b"<?xml" in head):
+        raise ImageRejected(
+            "SVG and other vector/XML documents are not accepted. "
+            "Please upload a raster image (PNG, JPEG, WebP, GIF or BMP).",
+            "svg_rejected",
+        )
+    try:
+        img = Image.open(io.BytesIO(data))
+    except Image.DecompressionBombError as exc:
+        raise ImageRejected(
+            "The image is unreasonably large (decompression guard).",
+            "image_too_large",
+        ) from exc
+    except Exception as exc:  # UnidentifiedImageError and friends
+        raise ImageRejected(
+            "The uploaded file could not be decoded as an image. "
+            "Accepted formats: PNG, JPEG, WebP, GIF, BMP.",
+            "not_an_image",
+        ) from exc
+    fmt = (img.format or "").upper()
+    if fmt not in ALLOWED_FORMATS:
+        img.close()
+        raise ImageRejected(
+            f"Unsupported image format {fmt or 'unknown'!r}. "
+            "Accepted formats: PNG, JPEG, WebP, GIF, BMP.",
+            "unsupported_format",
+        )
+    return img
+
+
+def validate_and_normalize(
+    data: bytes,
+    *,
+    max_bytes: int = 10 * 1024 * 1024,
+    max_pixels: int = 40_000_000,
+    max_side: int = 8192,
+    normalize_max_side: int = 1024,
+) -> NormalizedImage:
+    """Validate raw upload bytes and return a normalised RGB PNG.
+
+    Raises ImageRejected with a user-safe reason on any violation.
+    """
+    if len(data) > max_bytes:
+        raise ImageRejected(
+            f"The file is {len(data) / (1024 * 1024):.1f} MiB; the limit is "
+            f"{max_bytes // (1024 * 1024)} MiB.",
+            "file_too_large",
+        )
+
+    Image.MAX_IMAGE_PIXELS = max_pixels
+    img = _sniff(data)
+    original_format = (img.format or "").upper()
+    original_width, original_height = img.size
+
+    if original_width <= 0 or original_height <= 0:
+        img.close()
+        raise ImageRejected(
+            "The image has invalid dimensions.",
+            "image_too_large",
+        )
+    if original_width * original_height > max_pixels:
+        img.close()
+        raise ImageRejected(
+            f"The image has {original_width * original_height:,} pixels; the limit is "
+            f"{max_pixels:,}.",
+            "image_too_large",
+        )
+    if max(original_width, original_height) > max_side:
+        img.close()
+        raise ImageRejected(
+            f"The image is {original_width}x{original_height}px; the longest side may "
+            f"be at most {max_side}px.",
+            "image_too_large",
+        )
+
+    source = img
+    try:
+        # Pixel decode happens only after the cheap header-based limits above.
+        try:
+            img.load()
+        except Image.DecompressionBombError as exc:
+            raise ImageRejected(
+                "The image is unreasonably large (decompression guard).",
+                "image_too_large",
+            ) from exc
+        except Exception as exc:
+            raise ImageRejected(
+                "The uploaded file could not be fully decoded as an image.",
+                "not_an_image",
+            ) from exc
+
+        # Apply EXIF orientation, then flatten to RGB (drops alpha compositing
+        # surprises and strips all metadata when re-encoded).
+        img = ImageOps.exif_transpose(img)
+        if img.mode == "P":
+            img = img.convert("RGBA")
+        if img.mode in ("RGBA", "LA"):
+            background = Image.new("RGB", img.size, (255, 255, 255))
+            alpha = img.getchannel("A") if "A" in img.getbands() else None
+            background.paste(img.convert("RGB"), mask=alpha)
+            img = background
+        elif img.mode != "RGB":
+            img = img.convert("RGB")
+
+        downscaled = False
+        if max(img.size) > normalize_max_side:
+            img = ImageOps.contain(img, (normalize_max_side, normalize_max_side))
+            downscaled = True
+
+        buf = io.BytesIO()
+        img.save(buf, format="PNG", optimize=True)
+        return NormalizedImage(
+            png_bytes=buf.getvalue(),
+            width=img.size[0],
+            height=img.size[1],
+            original_format=original_format,
+            original_width=original_width,
+            original_height=original_height,
+            downscaled=downscaled,
+        )
+    finally:
+        source.close()
+        if img is not source:
+            img.close()

app/llm.py

@@ -0,0 +1,322 @@
+"""Async client for Anthropic-compatible Messages APIs (with an
+OpenAI-compatible chat/completions fallback).
+
+Verified wire protocol (2026-07, against https://openrouter.ai/api and
+https://api.anthropic.com):
+
+  POST {base}/v1/messages          (or {base}/messages when base ends /v1)
+  headers: x-api-key, authorization: Bearer, anthropic-version: 2023-06-01
+  body:    {model, max_tokens, system, messages:[{role, content:[
+               {type:"image", source:{type:"base64", media_type, data}},
+               {type:"text", text}]}]}
+  reply:   {content:[{type:"text", text}], stop_reason, ...}
+
+OpenAI fallback (only on HTTP 404, or when LLM_API_STYLE=openai):
+  POST {base}/chat/completions (base normalised to include /v1)
+  headers: authorization: Bearer
+  body:    {model, max_tokens, messages:[{role:"user", content:[
+               {type:"text", text}, {type:"image_url",
+                image_url:{url:"data:image/png;base64,..."}}]}]}
+  reply:   {choices:[{message:{content}}]}
+
+Retry policy: retry at most ``max_retries`` times on 408/409/429/5xx and
+transport errors with exponential backoff + jitter, honouring Retry-After.
+Never retry 400/401/403/404-style client faults. The API key is never logged
+or included in error messages.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import re
+from dataclasses import dataclass
+
+import httpx
+
+from .config import Settings
+
+ANTHROPIC_VERSION = "2023-06-01"
+_RETRYABLE_STATUS = {408, 409, 429, 500, 502, 503, 504}
+
+
+class LLMError(Exception):
+    """User-safe LLM failure description (never contains credentials)."""
+
+    def __init__(self, message: str, *, code: str = "llm_error",
+                 status: int | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+@dataclass(frozen=True)
+class LLMResponse:
+    text: str
+    stop_reason: str | None
+    style: str  # "anthropic" | "openai"
+
+
+def user_turn(prompt: str, image_png: bytes | None = None) -> dict:
+    """Anthropic-format user message; optionally with a PNG image block."""
+    content: list[dict] = []
+    if image_png is not None:
+        import base64
+
+        content.append({
+            "type": "image",
+            "source": {"type": "base64", "media_type": "image/png",
+                       "data": base64.b64encode(image_png).decode("ascii")},
+        })
+    content.append({"type": "text", "text": prompt})
+    return {"role": "user", "content": content}
+
+
+def assistant_turn(text: str) -> dict:
+    return {"role": "assistant", "content": [{"type": "text", "text": text}]}
+
+
+def _messages_url(base: str) -> str:
+    base = base.rstrip("/")
+    return base + "/messages" if base.endswith("/v1") else base + "/v1/messages"
+
+
+def _chat_completions_url(base: str) -> str:
+    base = base.rstrip("/")
+    return base + "/chat/completions" if base.endswith("/v1") else base + "/v1/chat/completions"
+
+
+def _headers(settings: Settings, style: str) -> dict[str, str]:
+    headers = {"content-type": "application/json"}
+    key = settings.llm_api_key or ""
+    if style == "anthropic":
+        # Both header conventions are sent: Anthropic accepts x-api-key;
+        # OpenRouter's anthropic-compatible endpoint accepts either.
+        headers["x-api-key"] = key
+        headers["authorization"] = f"Bearer {key}"
+        headers["anthropic-version"] = ANTHROPIC_VERSION
+    else:
+        headers["authorization"] = f"Bearer {key}"
+    if settings.llm_referer:
+        headers["HTTP-Referer"] = settings.llm_referer
+    if settings.llm_title:
+        headers["X-Title"] = settings.llm_title
+    return headers
+
+
+def _anthropic_body(settings: Settings, system: str, messages: list[dict]) -> dict:
+    return {
+        "model": settings.llm_model,
+        "max_tokens": settings.llm_max_tokens,
+        "system": system,
+        "messages": messages,
+    }
+
+
+def _openai_body(settings: Settings, system: str, messages: list[dict]) -> dict:
+    converted: list[dict] = [{"role": "system", "content": system}]
+    for item in messages:
+        role = item.get("role", "user")
+        parts = item.get("content")
+        if isinstance(parts, str):
+            converted.append({"role": role, "content": parts})
+            continue
+        out_parts: list[dict] = []
+        for part in parts if isinstance(parts, list) else []:
+            if not isinstance(part, dict):
+                continue
+            if part.get("type") == "text":
+                out_parts.append({"type": "text", "text": part.get("text", "")})
+            elif part.get("type") == "image":
+                source = part.get("source") or {}
+                url = f"data:{source.get('media_type', 'image/png')};base64,{source.get('data', '')}"
+                out_parts.append({"type": "image_url", "image_url": {"url": url}})
+        # Collapse text-only content to a plain string (canonical OpenAI shape).
+        if out_parts and all(p["type"] == "text" for p in out_parts):
+            converted.append({"role": role,
+                              "content": "".join(p["text"] for p in out_parts)})
+        else:
+            converted.append({"role": role, "content": out_parts})
+    return {
+        "model": settings.llm_model,
+        "max_tokens": settings.llm_max_tokens,
+        "messages": converted,
+    }
+
+
+def _parse_anthropic(payload: dict) -> LLMResponse:
+    content = payload.get("content")
+    if not isinstance(content, list):
+        raise LLMError("The model returned an unexpected response shape (no content).",
+                       code="llm_bad_response")
+    text = "".join(
+        block.get("text", "") for block in content
+        if isinstance(block, dict) and block.get("type") == "text"
+    ).strip()
+    if not text:
+        raise LLMError("The model returned an empty response.", code="llm_bad_response")
+    return LLMResponse(text=text, stop_reason=payload.get("stop_reason"), style="anthropic")
+
+
+def _parse_openai(payload: dict) -> LLMResponse:
+    try:
+        choice = payload["choices"][0]
+        text = (choice.get("message") or {}).get("content") or ""
+    except (KeyError, IndexError, TypeError) as exc:
+        raise LLMError("The model returned an unexpected response shape.",
+                       code="llm_bad_response") from exc
+    text = text.strip()
+    if not text:
+        raise LLMError("The model returned an empty response.", code="llm_bad_response")
+    return LLMResponse(text=text, stop_reason=choice.get("finish_reason"), style="openai")
+
+
+class LLMClient:
+    """One configured provider client. Instantiate per job or share."""
+
+    def __init__(self, settings: Settings, http: httpx.AsyncClient | None = None) -> None:
+        self.settings = settings
+        self._http = http
+
+    async def complete_vision(
+        self,
+        *,
+        system: str,
+        messages: list[dict],
+    ) -> LLMResponse:
+        style_pref = self.settings.llm_api_style
+        styles = ["anthropic", "openai"] if style_pref == "auto" else [style_pref]
+
+        last_error: LLMError | None = None
+        for index, style in enumerate(styles):
+            try:
+                return await self._call(style, system, messages)
+            except LLMError as exc:
+                last_error = exc
+                # Only fall over to the other protocol when the endpoint
+                # plainly does not speak it.
+                if exc.status == 404 and index < len(styles) - 1:
+                    continue
+                raise
+        raise last_error or LLMError("No LLM API style available.", code="llm_error")
+
+    async def _call(self, style: str, system: str,
+                    messages: list[dict]) -> LLMResponse:
+        settings = self.settings
+        if style == "anthropic":
+            url = _messages_url(settings.llm_base_url)
+            body = _anthropic_body(settings, system, messages)
+        else:
+            url = _chat_completions_url(settings.llm_base_url)
+            body = _openai_body(settings, system, messages)
+
+        timeout = httpx.Timeout(connect=10.0, read=settings.llm_timeout_s,
+                                write=30.0, pool=10.0)
+        close_client = False
+        http = self._http
+        if http is None:
+            http = httpx.AsyncClient(timeout=timeout)
+            close_client = True
+
+        attempts = max(1, settings.llm_max_retries + 1)
+        delay = 2.0
+        try:
+            for attempt in range(attempts):
+                try:
+                    response = await http.post(url, headers=_headers(settings, style), json=body)
+                except httpx.HTTPError as exc:
+                    if attempt + 1 >= attempts:
+                        raise LLMError(
+                            f"The model endpoint could not be reached ({type(exc).__name__}).",
+                            code="llm_unreachable") from exc
+                    await asyncio.sleep(delay + random.uniform(0, delay))
+                    delay = min(delay * 4, 32.0)
+                    continue
+
+                if response.status_code == 404:
+                    raise LLMError("The model endpoint returned 404 (unknown path/model).",
+                                   code="llm_not_found", status=404)
+                if response.status_code in (400, 401, 403):
+                    detail = _safe_error_detail(response)
+                    raise LLMError(
+                        f"The model endpoint rejected the request "
+                        f"(HTTP {response.status_code}). {detail}",
+                        code="llm_rejected", status=response.status_code)
+                if response.status_code in _RETRYABLE_STATUS:
+                    if attempt + 1 >= attempts:
+                        raise LLMError(
+                            f"The model endpoint is unavailable "
+                            f"(HTTP {response.status_code} after {attempts} attempts).",
+                            code="llm_unavailable", status=response.status_code)
+                    retry_after = response.headers.get("retry-after")
+                    wait = delay + random.uniform(0, delay)
+                    if retry_after:
+                        try:
+                            wait = max(wait, float(retry_after))
+                        except ValueError:
+                            pass
+                    await asyncio.sleep(wait)
+                    delay = min(delay * 4, 32.0)
+                    continue
+                if response.status_code >= 400:
+                    raise LLMError(
+                        f"The model endpoint returned HTTP {response.status_code}.",
+                        code="llm_error", status=response.status_code)
+
+                try:
+                    payload = response.json()
+                except json.JSONDecodeError as exc:
+                    raise LLMError("The model endpoint returned non-JSON.",
+                                   code="llm_bad_response") from exc
+                parsed = _parse_anthropic(payload) if style == "anthropic" else _parse_openai(payload)
+                if parsed.stop_reason in {"max_tokens", "length"}:
+                    raise LLMError(
+                        "The model's reply was truncated (max_tokens reached). "
+                        "Increase LLM_MAX_TOKENS or simplify the subject.",
+                        code="llm_truncated")
+                return parsed
+        finally:
+            if close_client:
+                await http.aclose()
+        raise LLMError("The model call failed unexpectedly.", code="llm_error")
+
+
+def _safe_error_detail(response: httpx.Response) -> str:
+    """Extract a short, credential-free detail string from an error body."""
+    try:
+        payload = response.json()
+        message = payload.get("error", {})
+        if isinstance(message, dict):
+            message = message.get("message") or message.get("type") or ""
+        if isinstance(message, str) and message:
+            return message[:200]
+    except Exception:
+        pass
+    return ""
+
+
+_FENCE_RE = re.compile(r"^```(?:json)?\s*|\s*```$", re.MULTILINE)
+
+
+def extract_json_object(text: str) -> dict:
+    """Parse a JSON object from an LLM reply, tolerating markdown fences
+    and leading/trailing prose. Raises LLMError on failure."""
+    candidate = _FENCE_RE.sub("", text).strip()
+    try:
+        parsed = json.loads(candidate)
+    except json.JSONDecodeError:
+        start = candidate.find("{")
+        end = candidate.rfind("}")
+        if start == -1 or end == -1 or end <= start:
+            raise LLMError("The model did not return a JSON object.",
+                           code="llm_bad_json")
+        try:
+            parsed = json.loads(candidate[start:end + 1])
+        except json.JSONDecodeError as exc:
+            raise LLMError(f"The model returned malformed JSON ({exc.msg}).",
+                           code="llm_bad_json") from exc
+    if not isinstance(parsed, dict):
+        raise LLMError("The model returned JSON that is not an object.",
+                       code="llm_bad_json")
+    return parsed

app/main.py

@@ -0,0 +1,478 @@
+"""FastAPI application for the img2threejs Hugging Face Docker Space.
+
+Routes
+  GET  /                                  SPA (static/index.html)
+  GET  /static/*                          static assets
+  GET  /health                            liveness + readiness signal
+  GET  /api/config                        public, credential-free config view
+  POST /api/jobs                          start a conversion job (multipart image)
+  GET  /api/jobs/{job_id}                 job status snapshot
+  GET  /api/jobs/{job_id}/events          SSE stream of pipeline events
+  GET  /api/jobs/{job_id}/artifacts/{n}   whitelisted per-job artifacts
+
+Binding: 0.0.0.0 on $PORT (default 7860) per the HF Docker Space contract.
+One uvicorn worker: the job registry is in-memory by design.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+import time
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import (FileResponse, JSONResponse, Response,
+                               StreamingResponse)
+from fastapi.staticfiles import StaticFiles
+from starlette.datastructures import UploadFile
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from .config import load_settings
+from .image_guard import ImageRejected
+from .llm import LLMClient
+from .pipeline import ARTIFACT_NAMES, JobRegistry, run_job
+from .ratelimit import RateLimiter, client_key
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s %(message)s",
+)
+logger = logging.getLogger("img2threejs")
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+
+settings = load_settings()
+registry = JobRegistry(Path(settings.runs_dir))
+limiter = RateLimiter(settings.rate_limit_jobs_per_hour)
+job_semaphore = asyncio.Semaphore(settings.max_concurrent_jobs)
+
+# Multipart boundary + the small ``hint`` field. The image itself still has
+# the tighter ``max_upload_bytes`` limit below.
+MULTIPART_OVERHEAD_BYTES = 256 * 1024
+
+
+class _RequestBodyTooLarge(Exception):
+    pass
+
+
+class UploadBodyLimitMiddleware:
+    """Cap the /api/jobs request stream before multipart parsing.
+
+    ``UploadFile`` avoids retaining large files in RAM, but without an ASGI
+    stream cap a caller could still force the multipart parser to spool an
+    unbounded request. Content-Length is a cheap early rejection; counting
+    receive chunks enforces the same limit when that header is absent or
+    false.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] != "http"
+            or scope.get("method") != "POST"
+            or scope.get("path") != "/api/jobs"
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        body_limit = settings.max_upload_bytes + MULTIPART_OVERHEAD_BYTES
+        declared_length: int | None = None
+        for name, value in scope.get("headers", []):
+            if name.lower() == b"content-length":
+                try:
+                    declared_length = int(value)
+                except (TypeError, ValueError):
+                    declared_length = None
+                break
+        if declared_length is not None and declared_length > body_limit:
+            await self._reject(scope, receive, send, body_limit)
+            return
+
+        received = 0
+
+        async def limited_receive():
+            nonlocal received
+            message = await receive()
+            if message.get("type") == "http.request":
+                received += len(message.get("body", b""))
+                if received > body_limit:
+                    raise _RequestBodyTooLarge
+            return message
+
+        try:
+            await self.app(scope, limited_receive, send)
+        except _RequestBodyTooLarge:
+            await self._reject(scope, receive, send, body_limit)
+
+    @staticmethod
+    async def _reject(
+        scope: Scope, receive: Receive, send: Send, body_limit: int
+    ) -> None:
+        response = JSONResponse(
+            status_code=413,
+            content={
+                "error": "request_too_large",
+                "detail": (
+                    "The multipart request exceeds the configured upload "
+                    f"boundary ({body_limit} bytes including form overhead)."
+                ),
+            },
+        )
+        await response(scope, receive, send)
+
+
+# A reservation covers the period between the cheap admission check and
+# JobRegistry.create(). It closes the race where many multipart bodies could
+# all pass the queue check while awaiting parsing.
+_queue_guard = threading.Lock()
+_pending_uploads = 0
+
+
+def _reserve_job_slot() -> tuple[bool, int]:
+    global _pending_uploads
+    with _queue_guard:
+        in_flight = sum(1 for job in registry.jobs.values() if job.status == "running")
+        occupied = in_flight + _pending_uploads
+        if occupied >= settings.max_in_flight_jobs:
+            return False, occupied
+        _pending_uploads += 1
+        return True, occupied
+
+
+def _release_job_slot() -> None:
+    global _pending_uploads
+    with _queue_guard:
+        _pending_uploads = max(0, _pending_uploads - 1)
+
+
+def _create_reserved_job():
+    """Atomically convert one upload reservation into a registry job."""
+    global _pending_uploads
+    with _queue_guard:
+        job = registry.create()
+        _pending_uploads = max(0, _pending_uploads - 1)
+        return job
+
+
+app = FastAPI(title="img2threejs", docs_url=None, redoc_url=None, openapi_url=None)
+app.add_middleware(UploadBodyLimitMiddleware)
+# Factory for the per-job LLM client; tests substitute a mock.
+app.state.llm_factory = lambda s: LLMClient(s)  # noqa: E731
+
+CSP = (
+    "default-src 'self'; script-src 'self' blob:; style-src 'self' 'unsafe-inline'; "
+    "img-src 'self' data: blob:; connect-src 'self'; frame-src 'self'; "
+    "object-src 'none'; base-uri 'none'"
+)
+
+# The sandboxed viewer shell runs LLM-influenced code inside an inline module
+# script and blob: imports — its own policy. Sending the app-wide CSP on this
+# path would intersect with the document's meta policy and block the shell
+# (multiple CSPs intersect; 'self' never matches an opaque origin anyway).
+VIEWER_CSP = (
+    "default-src 'none'; script-src 'unsafe-inline' blob:; "
+    "style-src 'unsafe-inline'; img-src blob: data:; worker-src blob:; "
+    "frame-ancestors 'self'; sandbox allow-scripts"
+)
+VIEWER_PATH = "/static/viewer.html"
+
+
+@app.middleware("http")
+async def security_headers(request: Request, call_next):
+    response = await call_next(request)
+    if request.url.path == VIEWER_PATH:
+        response.headers["Content-Security-Policy"] = VIEWER_CSP
+    else:
+        response.headers.setdefault("Content-Security-Policy", CSP)
+    response.headers.setdefault("X-Content-Type-Options", "nosniff")
+    response.headers.setdefault("Referrer-Policy", "no-referrer")
+    return response
+
+
+@app.on_event("startup")
+async def startup() -> None:
+    Path(settings.runs_dir).mkdir(parents=True, exist_ok=True)
+    logger.info(
+        "startup: llm_configured=%s model=%s base_url=%s port=%s space=%s",
+        settings.llm_configured, settings.llm_model or "(unset)",
+        settings.llm_base_url, settings.port, settings.space_id or "(local)",
+    )
+
+    async def reaper() -> None:
+        while True:
+            await asyncio.sleep(600)
+            doomed = registry.reap(settings.job_ttl_s)
+            if doomed:
+                logger.info("reaper: evicted %d expired jobs", len(doomed))
+
+    asyncio.create_task(reaper())
+
+
+# ---------------------------------------------------------------------------
+# Health + config
+# ---------------------------------------------------------------------------
+
+@app.get("/health")
+async def health() -> JSONResponse:
+    """Liveness + lightweight readiness. The LLM is deliberately NOT probed:
+    a failing provider must not mark the container down — it is surfaced in
+    the UI instead."""
+    return JSONResponse({
+        "status": "ok",
+        "llm_configured": settings.llm_configured,
+        "space_id": settings.space_id,
+        "time": int(time.time()),
+    })
+
+
+@app.get("/api/config")
+async def config() -> JSONResponse:
+    """Public config view. Never includes the API key or any secret value."""
+    return JSONResponse({
+        "llm_configured": settings.llm_configured,
+        "missing_llm_vars": settings.missing_llm_vars,
+        "model": settings.llm_model if settings.llm_configured else None,
+        "max_upload_bytes": settings.max_upload_bytes,
+        "rate_limit_jobs_per_hour": settings.rate_limit_jobs_per_hour,
+        "space_host": settings.space_host,
+    })
+
+
+# ---------------------------------------------------------------------------
+# Jobs
+# ---------------------------------------------------------------------------
+
+@app.post("/api/jobs", status_code=202)
+async def create_job(request: Request) -> JSONResponse:
+    if not settings.llm_configured:
+        missing = ", ".join(settings.missing_llm_vars)
+        return JSONResponse(status_code=503, content={
+            "error": "llm_not_configured",
+            "detail": (
+                f"This Space needs vision-LLM credentials to author the sculpt spec: set "
+                f"{missing} and LLM_BASE_URL as Space Secrets (Settings → Secrets), then "
+                "restart the Space. No model was generated — results are never fabricated."
+            ),
+        })
+
+    # Reserve capacity *before* parsing multipart data. Without this
+    # reservation, concurrent requests can all retain/spool their complete
+    # images while waiting to create an unbounded number of tasks.
+    reserved, occupied = _reserve_job_slot()
+    if not reserved:
+        return JSONResponse(
+            status_code=503,
+            headers={"Retry-After": "60"},
+            content={
+                "error": "queue_full",
+                "detail": (
+                    f"The Space is busy ({occupied} jobs in flight, max "
+                    f"{settings.max_in_flight_jobs}). Try again shortly."
+                ),
+            },
+        )
+
+    reservation_active = True
+    try:
+        # Uvicorn resolves forwarding headers only from configured trusted
+        # proxies; do not reinterpret raw X-Forwarded-For in application code.
+        key = client_key(request.client.host if request.client else None)
+        retry_after = limiter.check(key)
+        if retry_after is not None:
+            return JSONResponse(
+                status_code=429,
+                headers={"Retry-After": str(retry_after)},
+                content={
+                    "error": "rate_limited",
+                    "detail": (
+                        f"At most {settings.rate_limit_jobs_per_hour} jobs per hour "
+                        f"per client. Try again in {retry_after}s."
+                    ),
+                },
+            )
+
+        request_content_type = request.headers.get("content-type", "").lower()
+        if request_content_type and not request_content_type.startswith("multipart/form-data"):
+            return JSONResponse(status_code=415, content={
+                "error": "unsupported_media_type",
+                "detail": "Expected multipart form data containing an image file.",
+            })
+
+        # Parse only after admission. max_files/max_fields constrain multipart
+        # metadata; UploadBodyLimitMiddleware constrains the complete stream.
+        async with request.form(max_files=1, max_fields=2, max_part_size=64 * 1024) as form:
+            file = form.get("file")
+            if not isinstance(file, UploadFile):
+                return JSONResponse(status_code=422, content={
+                    "error": "file_required",
+                    "detail": "A multipart image field named 'file' is required.",
+                })
+            declared = (file.content_type or "").lower()
+            if declared and not declared.startswith("image/"):
+                return JSONResponse(status_code=415, content={
+                    "error": "unsupported_media_type",
+                    "detail": "Expected an image upload (PNG, JPEG, WebP, GIF or BMP).",
+                })
+            raw = await file.read(settings.max_upload_bytes + 1)
+            if len(raw) > settings.max_upload_bytes:
+                return JSONResponse(status_code=413, content={
+                    "error": "file_too_large",
+                    "detail": (
+                        "The upload exceeds the "
+                        f"{settings.max_upload_bytes // (1024 * 1024)} MiB limit."
+                    ),
+                })
+            hint_value = form.get("hint")
+            hint = hint_value if isinstance(hint_value, str) else None
+
+        job = _create_reserved_job()
+        reservation_active = False
+        object_hint = (hint or "").strip()[:80] or None
+    finally:
+        if reservation_active:
+            _release_job_slot()
+
+    async def runner() -> None:
+        async with job_semaphore:
+            await run_job(job, raw_upload=raw, object_hint=object_hint,
+                          settings=settings,
+                          llm=app.state.llm_factory(settings))
+
+    asyncio.create_task(runner())
+    return JSONResponse(status_code=202, content={
+        "job_id": job.id,
+        "events_url": f"/api/jobs/{job.id}/events",
+        "status_url": f"/api/jobs/{job.id}",
+    }, headers={"Cache-Control": "no-store"})
+
+
+@app.get("/api/jobs/{job_id}")
+async def job_status(job_id: str) -> JSONResponse:
+    job = registry.get(job_id)
+    if job is None:
+        return JSONResponse(
+            status_code=404,
+            content={"error": "job_not_found"},
+            headers={"Cache-Control": "no-store"},
+        )
+    return JSONResponse({
+        "job_id": job.id,
+        "status": job.status,
+        "stage": job.stage,
+        "result": job.result,
+        "error": job.error,
+    }, headers={"Cache-Control": "no-store"})
+
+
+def _is_terminal(event: dict) -> bool:
+    """An event ends the SSE stream: any error, or the final done/done."""
+    return event.get("status") == "error" or (
+        event.get("status") == "done" and event.get("stage") == "done"
+    )
+
+
+@app.get("/api/jobs/{job_id}/events", response_model=None)
+async def job_events(job_id: str, request: Request) -> Response:
+    job = registry.get(job_id)
+    if job is None:
+        return JSONResponse(
+            status_code=404,
+            content={"error": "job_not_found"},
+            headers={"Cache-Control": "no-store"},
+        )
+
+    async def stream():
+        cursor = 0
+        while True:
+            # Replay any events not yet sent (covers reconnects).
+            while cursor < len(job.events):
+                event = job.events[cursor]
+                cursor += 1
+                yield f"data: {json.dumps(event)}\n\n"
+                if _is_terminal(event):
+                    return
+            if job.status != "running":
+                return
+            if await request.is_disconnected():
+                return
+            try:
+                await asyncio.wait_for(job.waiter.wait(), timeout=15)
+            except asyncio.TimeoutError:
+                yield ": heartbeat\n\n"
+
+    return StreamingResponse(
+        stream(),
+        media_type="text/event-stream",
+        headers={"Cache-Control": "no-store", "X-Accel-Buffering": "no"},
+    )
+
+
+@app.get("/api/jobs/{job_id}/artifacts/{name}")
+async def job_artifact(job_id: str, name: str, download: bool = False) -> Response:
+    job = registry.get(job_id)
+    if job is None:
+        return JSONResponse(
+            status_code=404,
+            content={"error": "job_not_found"},
+            headers={"Cache-Control": "no-store"},
+        )
+    if name not in ARTIFACT_NAMES:
+        return JSONResponse(
+            status_code=404,
+            content={"error": "artifact_not_found"},
+            headers={"Cache-Control": "no-store"},
+        )
+    path = (job.dir / name).resolve()
+    # Containment: the artifact must live inside this job's directory.
+    if not path.is_file() or path.parent != job.dir.resolve():
+        return JSONResponse(
+            status_code=404,
+            content={"error": "artifact_not_found"},
+            headers={"Cache-Control": "no-store"},
+        )
+    headers = {"Cache-Control": "no-store"}
+    if download or name in {"factory.ts", "standalone.html"}:
+        headers["Content-Disposition"] = f'attachment; filename="{name}"'
+    media_type = ARTIFACT_NAMES[name].split(";")[0]
+    return FileResponse(path, media_type=media_type, headers=headers)
+
+
+# ---------------------------------------------------------------------------
+# Static SPA
+# ---------------------------------------------------------------------------
+
+@app.get("/", include_in_schema=False)
+async def index() -> FileResponse:
+    return FileResponse(STATIC_DIR / "index.html")
+
+
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+@app.exception_handler(ImageRejected)
+async def image_rejected_handler(_: Request, exc: ImageRejected) -> JSONResponse:
+    return JSONResponse(status_code=422, content={"error": exc.code, "detail": exc.reason})
+
+
+def main() -> None:
+    """Console entry: python -m app.main"""
+    import uvicorn
+
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=settings.port,
+        workers=1,
+        proxy_headers=True,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()

app/pipeline.py

@@ -0,0 +1,530 @@
+"""Job orchestration: image in -> ObjectSculptSpec -> Three.js factory -> bundle.
+
+This preserves the upstream repository's intended conversion flow
+(image -> probe -> LLM-authored ObjectSculptSpec -> strict-quality gate ->
+an inspectable Three.js preview) and adapts the interactive agent loop to a
+hosted request/response service:
+
+  * the LLM (vision) authors the spec, exactly as the skill intends;
+  * validate_sculpt_spec.py --strict-quality gates it; validator and hosted
+    compiler errors are fed back for up to ``spec_repair_rounds`` repairs;
+  * the original spec remains locked and unreviewed. A separate compile-only
+    manifest gathers its validated components into an explicitly unreviewed
+    hosted preview pass; it contains no invented scores or screenshot paths;
+  * the emitted TypeScript factory is bundled (esbuild, three included) into
+    a single ESM artifact plus a self-contained standalone HTML export.
+
+Every failure path returns an honest error; nothing is ever fabricated.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import re
+import shutil
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from . import forge_bridge
+from .config import Settings
+from .image_guard import ImageRejected, validate_and_normalize
+from .llm import LLMClient, LLMError, extract_json_object
+from .prompt import build_repair_prompt, build_system_prompt, build_user_prompt
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+
+TARGET_NAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9 ]{0,38}$")
+MAX_SPEC_BYTES = 512 * 1024
+
+ARTIFACT_NAMES = {
+    "reference.png": "image/png",
+    "probe.json": "application/json",
+    "spec.json": "application/json",
+    "compile-spec.json": "application/json",
+    "validation.json": "application/json",
+    "factory.ts": "text/plain; charset=utf-8",
+    "model.bundle.js": "text/javascript; charset=utf-8",
+    "standalone.html": "text/html; charset=utf-8",
+    "events.jsonl": "application/x-ndjson; charset=utf-8",
+}
+
+
+class PipelineError(Exception):
+    """Honest, user-presentable pipeline failure."""
+
+    def __init__(self, message: str, *, code: str = "pipeline_error",
+                 stage: str = "", detail: Any = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.stage = stage
+        self.detail = detail
+
+
+@dataclass
+class Job:
+    id: str
+    dir: Path
+    created: float = field(default_factory=time.time)
+    finished: float | None = None
+    status: str = "running"  # running | done | error
+    stage: str = "queued"
+    seq: int = 0
+    events: list[dict] = field(default_factory=list)
+    result: dict | None = None
+    error: dict | None = None
+    waiter: asyncio.Event = field(default_factory=asyncio.Event)
+
+    def emit(self, stage: str, status: str, message: str, **data: Any) -> dict:
+        self.seq += 1
+        self.stage = stage
+        event = {
+            "seq": self.seq,
+            "ts": round(time.time(), 3),
+            "stage": stage,
+            "status": status,  # started | progress | done | error
+            "message": message,
+        }
+        if data:
+            event["data"] = data
+        self.events.append(event)
+        try:
+            with (self.dir / "events.jsonl").open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(event) + "\n")
+        except OSError:
+            pass
+        self.waiter.set()
+        self.waiter.clear()
+        return event
+
+
+class JobRegistry:
+    def __init__(self, runs_dir: Path) -> None:
+        self.runs_dir = runs_dir
+        self.jobs: dict[str, Job] = {}
+
+    def create(self) -> Job:
+        job_id = uuid.uuid4().hex
+        job_dir = self.runs_dir / job_id
+        job_dir.mkdir(parents=True, exist_ok=False)
+        job = Job(id=job_id, dir=job_dir)
+        self.jobs[job_id] = job
+        return job
+
+    def get(self, job_id: str) -> Job | None:
+        if not re.fullmatch(r"[0-9a-f]{32}", job_id or ""):
+            return None
+        return self.jobs.get(job_id)
+
+    def evict(self, job_id: str) -> None:
+        job = self.jobs.pop(job_id, None)
+        if job is not None:
+            shutil.rmtree(job.dir, ignore_errors=True)
+
+    def reap(self, ttl_s: int) -> list[str]:
+        now = time.time()
+        doomed = [
+            j.id for j in self.jobs.values()
+            if j.finished is not None and now - j.finished > ttl_s
+        ]
+        for job_id in doomed:
+            self.evict(job_id)
+        # Also sweep orphaned directories (e.g. after a crash).
+        if self.runs_dir.exists():
+            known = {j.dir for j in self.jobs.values()}
+            for child in self.runs_dir.iterdir():
+                if (
+                    child.is_dir()
+                    and child not in known
+                    and re.fullmatch(r"[0-9a-f]{32}", child.name)
+                ):
+                    try:
+                        if now - child.stat().st_mtime > ttl_s:
+                            shutil.rmtree(child, ignore_errors=True)
+                    except OSError:
+                        pass
+        return doomed
+
+
+def sanitize_spec(spec: dict) -> dict:
+    """Clamp LLM-authored values that the generator/validator treat strictly."""
+    name = spec.get("targetName")
+    if not isinstance(name, str) or not TARGET_NAME_RE.fullmatch(name.strip()):
+        spec["targetName"] = "Object"
+    else:
+        spec["targetName"] = name.strip()
+    spec["schemaVersion"] = "2.0"
+    suitability = spec.get("suitability")
+    if suitability not in {"pass", "conditional", "reject"}:
+        spec["suitability"] = "conditional"
+    spec["reviewHistory"] = []  # LLM must not pre-approve its own passes
+    return spec
+
+
+async def run_job(
+    job: Job,
+    *,
+    raw_upload: bytes,
+    object_hint: str | None,
+    settings: Settings,
+    llm: LLMClient,
+) -> None:
+    """Execute the full conversion for one job. Never raises: failures are
+    recorded on the job and emitted as terminal error events."""
+    started = time.time()
+    try:
+        async with asyncio.timeout(settings.job_timeout_s):
+            await _run(job, raw_upload=raw_upload, object_hint=object_hint,
+                       settings=settings, llm=llm, started=started)
+    except TimeoutError:
+        _fail(
+            job, stage=job.stage, code="job_timeout",
+            message=(
+                f"The conversion exceeded the {max(1, round(settings.job_timeout_s / 60))}-minute "
+                "job deadline and was stopped. No unverified model was returned."
+            ),
+        )
+    except ImageRejected as exc:
+        _fail(job, stage="intake", code=exc.code, message=exc.reason)
+    except LLMError as exc:
+        _fail(job, stage="spec-authoring", code=exc.code, message=str(exc))
+    except PipelineError as exc:
+        _fail(job, stage=exc.stage or job.stage, code=exc.code, message=str(exc),
+              detail=exc.detail)
+    except Exception as exc:  # pragma: no cover - defensive catch-all
+        _fail(job, stage=job.stage, code="internal_error",
+              message=f"Unexpected internal error: {type(exc).__name__}. "
+                      "Nothing was generated.")
+
+
+async def _run(job: Job, *, raw_upload: bytes, object_hint: str | None,
+               settings: Settings, llm: LLMClient, started: float) -> None:
+    # -- stage 1: intake -----------------------------------------------------
+    job.emit("intake", "started", "Validating and normalising the uploaded image.")
+    normalized = await asyncio.to_thread(
+        validate_and_normalize, raw_upload,
+        max_bytes=settings.max_upload_bytes,
+        max_pixels=settings.max_image_pixels,
+        normalize_max_side=settings.normalize_max_side,
+    )
+    reference = job.dir / "reference.png"
+    reference.write_bytes(normalized.png_bytes)
+    probe = await asyncio.to_thread(forge_bridge.probe_image, reference)
+    (job.dir / "probe.json").write_text(json.dumps(probe, indent=2), encoding="utf-8")
+    job.emit(
+        "intake", "done",
+        f"Image accepted: {normalized.original_format} "
+        f"{normalized.original_width}x{normalized.original_height}px"
+        + (" (downscaled for processing)" if normalized.downscaled else ""),
+        probe={"width": probe.get("width"), "height": probe.get("height"),
+               "warnings": probe.get("warnings", [])},
+    )
+
+    # -- stage 2: LLM authors the ObjectSculptSpec ---------------------------
+    system = build_system_prompt()
+    from .llm import assistant_turn, user_turn
+    messages: list[dict] = []
+    spec: dict | None = None
+    validation: dict = {}
+    repair_rounds = max(0, settings.spec_repair_rounds)
+    max_attempts = 1 + repair_rounds
+    for attempt in range(1, max_attempts + 1):
+        if attempt == 1:
+            job.emit(
+                "spec-authoring", "started",
+                f"The vision model ({settings.llm_model}) is studying the image and "
+                "authoring the ObjectSculptSpec (components, materials, proportions).",
+                attempt=attempt, maxAttempts=max_attempts,
+            )
+            messages.append(user_turn(
+                build_user_prompt(probe, object_hint=object_hint),
+                image_png=normalized.png_bytes,
+            ))
+        else:
+            job.emit(
+                "spec-authoring", "progress",
+                f"Validator rejected the spec; the model is repairing it "
+                f"(attempt {attempt} of {max_attempts}).",
+                attempt=attempt, maxAttempts=max_attempts,
+                validatorErrors=(validation.get("errors") or [])[:8],
+            )
+            messages.append(user_turn(build_repair_prompt(
+                validation.get("errors") or [], validation.get("warnings") or [])))
+
+        reply = await llm.complete_vision(system=system, messages=messages)
+        messages.append(assistant_turn(reply.text))
+        try:
+            candidate = extract_json_object(reply.text)
+        except LLMError as exc:
+            if exc.code != "llm_bad_json":
+                raise
+            validation = {
+                "ok": False,
+                "errors": [
+                    "The model response was not one complete parseable JSON object."
+                ],
+                "warnings": [],
+            }
+            (job.dir / "validation.json").write_text(
+                json.dumps(validation, indent=2), encoding="utf-8")
+            continue
+        if len(json.dumps(candidate)) > MAX_SPEC_BYTES:
+            raise PipelineError(
+                "The model produced an unreasonably large spec (>512 KB). "
+                "Try a simpler subject or crop the image.",
+                code="spec_too_large", stage="spec-authoring")
+        candidate = sanitize_spec(candidate)
+
+        # Suitability "reject" is an honest, valid pipeline outcome.
+        if candidate.get("suitability") == "reject":
+            (job.dir / "spec.json").write_text(json.dumps(candidate, indent=2),
+                                               encoding="utf-8")
+            raise PipelineError(
+                "The model judged this image unsuitable for a faithful procedural "
+                "reconstruction (suitability: reject). Try a single object with a "
+                "clear silhouette on a plain background. No model was generated.",
+                code="unsuitable_image", stage="spec-authoring",
+                detail={"specUrl": f"/api/jobs/{job.id}/artifacts/spec.json"})
+
+        spec_path = job.dir / "spec.json"
+        spec_path.write_text(json.dumps(candidate, indent=2), encoding="utf-8")
+        validation = await asyncio.to_thread(
+            forge_bridge.validate_spec, spec_path, strict=True)
+        hosted_errors = forge_bridge.hosted_spec_errors(candidate)
+        if hosted_errors:
+            validation["ok"] = False
+            validation["errors"] = list(validation.get("errors") or []) + hosted_errors
+        (job.dir / "validation.json").write_text(json.dumps(validation, indent=2),
+                                                 encoding="utf-8")
+        if validation.get("ok"):
+            spec = candidate
+            job.emit(
+                "spec-authoring", "done",
+                f"Spec accepted by the strict-quality gate on round {attempt}: "
+                f"{candidate.get('targetName', 'Object')} — "
+                f"{len(candidate.get('componentTree', []))} components, "
+                f"{len(candidate.get('materials', []))} materials.",
+                attempt=attempt,
+                warnings=validation.get("warnings") or [],
+            )
+            break
+    if spec is None:
+        raise PipelineError(
+            f"The spec failed the deterministic strict-quality gate after "
+            f"{max_attempts} attempts ({repair_rounds} repair rounds). This is the "
+            "gate working as designed, not a crash. "
+            "No model was generated.",
+            code="spec_validation_failed", stage="spec-authoring",
+            detail={"errors": (validation.get("errors") or [])[:20],
+                    "validationUrl": f"/api/jobs/{job.id}/artifacts/validation.json"})
+
+    # -- stage 3: honest compile-only hosted preview -------------------------
+    order = forge_bridge.pass_order(spec)
+    job.emit("generation", "started",
+             "Strict gate passed. Preparing an unreviewed procedural preview; "
+             "the upstream pass order remains locked pending real screenshots "
+             f"and visual review ({' -> '.join(order)}).")
+
+    ts_path = job.dir / "factory.ts"
+    generated_pass = forge_bridge.HOSTED_PREVIEW_PASS
+    preview_spec = forge_bridge.prepare_hosted_preview(spec)
+    preview_path = job.dir / "compile-spec.json"
+    preview_path.write_text(json.dumps(preview_spec, indent=2), encoding="utf-8")
+    try:
+        await asyncio.to_thread(
+            forge_bridge.generate_factory,
+            preview_path,
+            ts_path,
+            pass_id=generated_pass,
+        )
+    except forge_bridge.ForgeError as exc:
+        raise PipelineError(
+            "The strict-validated spec could not be compiled into the hosted "
+            f"preview ({exc.stderr.strip()[:300] or 'generator refusal'}). "
+            "No model was generated.",
+            code="generation_failed", stage="generation",
+        ) from exc
+
+    ts_source = ts_path.read_text(encoding="utf-8")
+    if "TODO:" in ts_source:
+        raise PipelineError(
+            "The generator attempted to emit placeholder geometry. The preview "
+            "was refused instead of returning a fabricated shape.",
+            code="generation_failed", stage="generation",
+        )
+    export_name = forge_bridge.factory_export_name(ts_source)
+    if not export_name:
+        raise PipelineError(
+            "The generated factory has no create<Name>Model export. "
+            "No model was generated.",
+            code="generation_failed", stage="generation")
+
+    # -- stage 4: bundle for the browser (esbuild) ---------------------------
+    job.emit("bundling", "started",
+             "Unreviewed preview factory emitted. Bundling with three.js "
+             "for the in-browser viewer.")
+    entry = job.dir / "entry.js"
+    pascal = re.sub(r"^create|Model$", "", export_name)
+    entry.write_text(
+        f'export {{ {export_name} as makeModel, '
+        f'create{pascal}LookDevLights as makeLights }} from "./factory.ts";\n'
+        f'export {{ mountViewer }} from {json.dumps(str(STATIC_DIR / "viewer-core.js"))};\n',
+        encoding="utf-8")
+    bundle_path = job.dir / "model.bundle.js"
+    await _run_esbuild(job, entry, bundle_path, settings)
+
+    # Self-contained standalone export (works offline, single file).
+    bundle_text = bundle_path.read_text(encoding="utf-8")
+    standalone = _build_standalone(bundle_text, spec.get("targetName", "Object"))
+    (job.dir / "standalone.html").write_text(standalone, encoding="utf-8")
+
+    job.emit("bundling", "done", "Browser bundle and standalone export ready.")
+
+    # -- done ------------------------------------------------------------------
+    elapsed = round(time.time() - started, 1)
+    components = spec.get("componentTree", [])
+    result = {
+        "jobId": job.id,
+        "targetName": spec.get("targetName", "Object"),
+        "generatedPass": generated_pass,
+        "generationMode": "hosted-unreviewed-preview",
+        "reviewStatus": "unreviewed",
+        "passOrder": order,
+        "completedPasses": [],
+        "components": len(components),
+        "materials": len(spec.get("materials", [])),
+        "validationWarnings": validation.get("warnings") or [],
+        "elapsedSeconds": elapsed,
+        "artifacts": {name: f"/api/jobs/{job.id}/artifacts/{name}"
+                      for name in ARTIFACT_NAMES if (job.dir / name).exists()},
+        "honesty": [
+            "Approximate procedural reconstruction from one image; hidden geometry "
+            "is a model inference, not an observation or measurement.",
+            "This is an unreviewed hosted preview. The original spec has no pass "
+            "approvals, screenshot comparisons, or visual-fidelity scores.",
+            "Use the upstream render/comparison/review loop before treating any "
+            "build pass as visually accepted.",
+            "The factory is the upstream generator's procedural scaffold: "
+            "proportions, materials and structure come from the LLM-authored spec; "
+            "fine surface artistry is out of scope for v1.",
+        ],
+    }
+    job.result = result
+    job.status = "done"
+    job.finished = time.time()
+    job.emit("done", "done",
+             f"Done in {elapsed}s — {result['targetName']} "
+             f"({result['components']} components, pass '{generated_pass}').",
+             result=result)
+
+
+def _fail(job: Job, *, stage: str, code: str, message: str,
+          detail: Any = None) -> None:
+    job.status = "error"
+    job.finished = time.time()
+    job.error = {"code": code, "message": message, "stage": stage,
+                 **({"detail": detail} if detail else {})}
+    job.emit(stage, "error", message, code=code, **({"detail": detail} if detail else {}))
+
+
+async def _run_esbuild(job: Job, entry: Path, out: Path, settings: Settings) -> None:
+    esbuild = REPO_ROOT / settings.esbuild_entry
+    if not esbuild.exists():
+        raise PipelineError(
+            "The esbuild bundler is missing from this deployment (build misconfiguration).",
+            code="bundler_missing", stage="bundling")
+    # Let esbuild resolve `three` from the image's node_modules.
+    link = job.dir / "node_modules"
+    if not link.exists():
+        try:
+            link.symlink_to(REPO_ROOT / "node_modules", target_is_directory=True)
+        except OSError:
+            pass
+    argv = [
+        str(esbuild), str(entry),
+        "--bundle", "--format=esm", "--target=es2022", "--minify",
+        f"--outfile={out}",
+    ]
+    env = {"PATH": "/usr/local/bin:/usr/bin:/bin",
+           "NODE_PATH": str(REPO_ROOT / "node_modules")}
+    proc = await asyncio.create_subprocess_exec(
+        *argv, cwd=str(job.dir), env=env,
+        stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+    try:
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=120)
+    except asyncio.TimeoutError as exc:
+        proc.kill()
+        raise PipelineError("esbuild timed out.", code="bundler_failed",
+                            stage="bundling") from exc
+    if proc.returncode != 0:
+        raise PipelineError(
+            f"esbuild failed: {stderr.decode('utf-8', 'replace')[:300]}",
+            code="bundler_failed", stage="bundling")
+    if not out.exists() or out.stat().st_size == 0:
+        raise PipelineError("esbuild produced an empty bundle.",
+                            code="bundler_failed", stage="bundling")
+
+
+def _build_standalone(bundle_text: str, target_name: str) -> str:
+    """Single self-contained HTML file with a base64-embedded ESM bundle."""
+    encoded = base64.b64encode(bundle_text.encode("utf-8")).decode("ascii")
+    title = re.sub(r"[^A-Za-z0-9 ]", "", target_name) or "Object"
+    return STANDALONE_TEMPLATE.replace("__TITLE__", title).replace(
+        "__BUNDLE_BASE64__", encoded)
+
+
+STANDALONE_TEMPLATE = """<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__TITLE__ — img2threejs standalone model</title>
+<!--
+  Generated by the img2threejs Hugging Face Space (https://huggingface.co/spaces/Mike0021/img2threejs)
+  from a single reference image. Approximate procedural reconstruction;
+  hidden sides are inferred, not measured. Built on hoainho/img2threejs (MIT).
+  three.js is MIT.
+-->
+<style>
+  html,body{margin:0;height:100%;background:#16181d;color:#e6e8ee;
+    font:14px/1.5 system-ui,sans-serif}
+  #viewer{position:fixed;inset:0}
+  .tag{position:fixed;left:12px;bottom:10px;font-size:12px;color:#9aa0ad;
+    background:rgba(22,24,29,.7);padding:4px 8px;border-radius:6px}
+  #fallback{padding:2rem;max-width:60ch}
+</style>
+</head>
+<body>
+<div id="viewer" role="region" aria-label="3D model viewer"></div>
+<div class="tag">__TITLE__ — procedural Three.js reconstruction (img2threejs). Drag to orbit, scroll to zoom.</div>
+<noscript><div id="fallback">This model needs JavaScript + WebGL to render.</div></noscript>
+<script type="module">
+let url;
+try {
+  const bytes = Uint8Array.from(atob('__BUNDLE_BASE64__'), (char) => char.charCodeAt(0));
+  url = URL.createObjectURL(new Blob([bytes], { type: 'text/javascript' }));
+  const mod = await import(url);
+  const el = document.getElementById('viewer');
+  if (!document.createElement('canvas').getContext('webgl2') &&
+      !document.createElement('canvas').getContext('webgl')) {
+    throw new Error('WebGL is not available in this browser/GPU.');
+  }
+  mod.mountViewer(el, mod.makeModel,
+    typeof mod.makeLights === 'function' ? mod.makeLights : null, {});
+} catch (err) {
+  const div = document.createElement('div');
+  div.id = 'fallback';
+  div.textContent = 'The generated model failed to render here: ' + (err && err.message || err);
+  document.body.appendChild(div);
+} finally {
+  if (url) URL.revokeObjectURL(url);
+}
+</script>
+</body>
+</html>
+"""

app/prompt.py

@@ -0,0 +1,140 @@
+"""Prompt construction for the LLM spec-authoring step.
+
+The upstream project is an interactive agent skill: a vision-capable agent
+authors an ``ObjectSculptSpec`` JSON describing the object in the reference
+image, and the deterministic forge scripts gate and compile it. The Space
+replaces the interactive agent with a single prompted vision call (plus
+validator-feedback repair rounds). The system prompt therefore carries:
+
+  * the strict-quality contract, distilled from the validator
+    (forge/stage2_spec/validate_sculpt_spec.py) and the grimoire rubrics;
+  * a complete, verified strict-passing exemplar spec (app/exemplar_spec.json)
+    so the model imitates an exact working shape instead of guessing;
+  * hard output rules (JSON only, primitives subset, honesty rules).
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+EXEMPLAR_PATH = Path(__file__).resolve().parent / "exemplar_spec.json"
+
+
+@lru_cache(maxsize=1)
+def _exemplar() -> str:
+    return EXEMPLAR_PATH.read_text(encoding="utf-8")
+
+
+RULES = """\
+You author exactly ONE JSON object: an ObjectSculptSpec (schemaVersion "2.0") describing the \
+single main object in the reference image. A deterministic validator will strict-gate your spec; \
+a compiler turns it into a procedural Three.js factory. Follow the exemplar's STRUCTURE exactly, \
+but invent content that faithfully matches THIS image.
+
+HARD RULES (each is enforced by the validator; violations waste a round):
+1. Output JSON only. No markdown fences, no prose, no comments.
+2. Required top-level keys: targetName (1-3 words, letters/spaces only), targetId, schemaVersion \
+"2.0", suitability ("pass" or "conditional"), sourceImage, coordinateFrame, silhouette, \
+preSpecAssessment, qualityContract, qualityTargets, actionReadiness, selfCorrectLoop, \
+featureReviewTargets, buildPasses, sculptPipeline, lookDevTargets, lightingFromPhoto, \
+componentTree, materials, proceduralStrategy, viewEvidence.
+3. preSpecAssessment.objectClass: primaryType (specific noun, e.g. "vessel", "hand-tool"), \
+primaryDomain "object", and NON-EMPTY formLanguage, structureKind, motionPotential, \
+materialFamilies. complexity.tier: use "simple" unless the object genuinely has 6+ distinct \
+parts, then "moderate". specDepthDecision.requiredDepth must equal the tier. \
+unknowns: [] (empty list).
+4. qualityContract: qualityBar (match tier), definitionOfDone (>=2 concrete checks), \
+minimumSpecDepth (macroComponents>=1, mesoComponents>=1, microComponents>=0, minMaterials>=1, \
+minRepetitionSystems>=0, reviewViewpoints>=2), featureGroups (>=3 groups each with id, name, \
+qualityCriteria list), visualDeltaChecks (>=2), antiShallowSpecRules (>=2).
+5. qualityTargets.reviewViewpoints: >=2 named viewpoints. actionReadiness: filled like the exemplar.
+6. selfCorrectLoop.visualAcceptance: reviewer, threshold 0.7, featureReviewPolicy \
+{enabled true, maxCritical 5, maxImportant 3, thresholds}.
+7. featureReviewTargets: 2-4 REAL identity-defining features of THIS object (never the generic \
+starter ids from the exemplar) with tier critical/important, passIds, minimumScore.
+8. buildPasses: exactly ["blockout", "structural-pass", "material-pass"] in that order, each with \
+id, label, goal, acceptanceCriteria list. sculptPipeline: passGateMode "locked-sequential", \
+passOrder identical, currentPass "blockout", completedPasses [].
+9. lookDevTargets.qualityPriority: ALWAYS "balanced" (never "reference-fidelity").
+10. lightingFromPhoto: >=3 strings that between them name a key/fill/rim light AND contain the \
+words "exposure" and "tone" (tone mapping) AND the phrase "contact shadow".
+11. detailInventory: targetMinDetails 3 (simple) or 6 (moderate); details list of that many \
+entries {id, kind, description, mapsTo:{ref}} where kind comes from the taxonomy (gloss, bevel, \
+fastener, linework, contour, seam, stitch, stain, scratch, chip, decal, emissive, hole, groove, \
+ridge) and every mapsTo.ref resolves to a REAL id in your spec: a component id, a \
+component localFeatures id, a material id, or a material localOverrides id. A "gloss" detail \
+requires some material with roughness base < 0.35 or a clearcoat block. A "fastener" detail \
+requires a repetitionSystems entry or a micro-level component.
+12. componentTree: 2-8 components. Each: unique id (kebab-case), name, role, primitive from ONLY \
+{box, sphere, ellipsoid, cylinder, cone, capsule, torus, plane-card} (other primitives are \
+rejected by the hosted compiler), level macro|meso|micro, parent (null for the root, else an \
+existing component id), material (a declared material id), transform {position, rotation, \
+scale} as [x,y,z] numbers, dimensions, importance, confidence. Proportions and positions must \
+match the image as closely as you can infer them. Root positions are in object space; a child's \
+position is LOCAL to its parent pivot (do not repeat the parent's world-space offset).
+13. ATTACHMENT CONTRACT: any component with a parent whose primitive is cylinder, cone, capsule \
+or torus, or whose role/name implies handle/limb/tube, MUST include a complete "attachment": \
+{parentId, parentSocket, localStart [x,y,z], localEnd [x,y,z], contactType \
+("embed"|"overlap"|"flush"), embedDepth > 0 (or overlap > 0), gapTolerance}. Nothing floats in \
+mid-air. If you give a component actionProfile.sockets, each socket has id, name, position \
+[x,y,z], purpose.
+14. materials: >=1 entry {id, name, baseColor "#RRGGBB", roughness {base, variation} (or number), \
+metalness, colorVariation {palette: >=2 hex colours}, localOverrides: >=1 entry {id, ...}, \
+ambientOcclusion {cavityStrength}}. Colours must be sampled from the image, not invented.
+15. viewEvidence: >=1 entry {id, description}. reviewHistory: []. risks: optional.
+16. Honesty: a single image cannot reveal hidden sides. Mark unseen geometry as an inference in \
+proceduralStrategy notes; never claim it was observed or measured. Use suitability "conditional" when the image is \
+ambiguous; never claim detail you cannot see.
+
+EXEMPLAR (a verified strict-passing spec for a mug -- imitate its shape, depth and field style, \
+not its content):
+"""
+
+
+def build_system_prompt() -> str:
+    return RULES + _exemplar()
+
+
+def build_user_prompt(probe: dict, *, object_hint: str | None = None) -> str:
+    parts = [
+        "Author the ObjectSculptSpec JSON for the main object in this reference image.",
+        "",
+        "Deterministic image probe (metadata only, not a visual analysis):",
+        json.dumps({
+            "type": probe.get("type"),
+            "width": probe.get("width"),
+            "height": probe.get("height"),
+            "megapixels": probe.get("megapixels"),
+            "warnings": probe.get("warnings"),
+        }, indent=2),
+    ]
+    if object_hint:
+        parts += ["", f"The user says the object is: {object_hint!r}. Honour this unless the image clearly contradicts it."]
+    parts += [
+        "",
+        "Remember: JSON only. Follow the exemplar structure. Match the image's real proportions, "
+        "colours and parts. targetName must be specific to this object.",
+    ]
+    return "\n".join(parts)
+
+
+def build_repair_prompt(errors: list[str], warnings: list[str] | None = None) -> str:
+    shown = [e for e in errors if isinstance(e, str)][:20]
+    lines = [
+        "Your previous spec was REJECTED by the deterministic validator "
+        "(validate_sculpt_spec.py --strict-quality). Fix every error below and return the "
+        "complete corrected spec as JSON only:",
+        "",
+    ]
+    lines += [f"- {e}" for e in shown]
+    if warnings:
+        lines += ["", "Warnings (non-fatal, fix if cheap):"]
+        lines += [f"- {w}" for w in warnings[:10] if isinstance(w, str)]
+    lines += [
+        "",
+        "Return the ENTIRE corrected JSON object (not a diff). Keep everything that was not "
+        "flagged. JSON only.",
+    ]
+    return "\n".join(lines)

app/ratelimit.py

@@ -0,0 +1,53 @@
+"""In-memory per-client rate limiting (token window) for job creation.
+
+Single-process Spaces need no external store. The limiter is deliberately
+simple: a fixed 1-hour window of timestamps per client key.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import OrderedDict, deque
+
+
+class RateLimiter:
+    """Fixed-window limiter with a strict LRU bound on client buckets."""
+
+    def __init__(self, max_per_hour: int, *, max_clients: int = 4096) -> None:
+        self.max_per_hour = max(1, int(max_per_hour))
+        self.max_clients = max(1, min(int(max_clients), 4096))
+        self._hits: OrderedDict[str, deque[float]] = OrderedDict()
+
+    def check(self, key: str) -> int | None:
+        """Record a hit. Returns None when allowed, else seconds until the
+        oldest hit expires (for Retry-After)."""
+        now = time.time()
+        key = (key or "?")[:128]
+        window = self._hits.get(key)
+        if window is None:
+            # Bound memory even when every request presents a new peer. LRU
+            # eviction is deterministic and happens *before* insertion, so
+            # the map can never transiently exceed max_clients.
+            if len(self._hits) >= self.max_clients:
+                self._hits.popitem(last=False)
+            window = deque()
+            self._hits[key] = window
+        else:
+            self._hits.move_to_end(key)
+        while window and now - window[0] > 3600:
+            window.popleft()
+        if len(window) >= self.max_per_hour:
+            return int(3600 - (now - window[0])) + 1
+        window.append(now)
+        return None
+
+
+def client_key(peer_host: str | None) -> str:
+    """Return only the ASGI socket peer resolved by the trusted server.
+
+    Raw ``X-Forwarded-For`` is intentionally not accepted here. Uvicorn may
+    resolve trusted proxy headers into ``request.client`` according to its
+    own proxy policy; application code must not reinterpret caller-controlled
+    forwarding headers.
+    """
+    return (peer_host or "?")[:128]

app/static/app.js

@@ -0,0 +1,367 @@
+// img2threejs Space — client application.
+// Upload -> SSE progress -> sandboxed three.js viewer + downloads.
+// Every error state is explicit; nothing is ever simulated client-side.
+
+const $ = (id) => document.getElementById(id);
+
+const panels = {
+  upload: $('panel-upload'),
+  progress: $('panel-progress'),
+  result: $('panel-result'),
+  error: $('panel-error'),
+};
+
+const STAGE_LABELS = {
+  intake: 'Intake — validate image + deterministic probe',
+  'spec-authoring': 'Spec authoring — vision model writes the ObjectSculptSpec',
+  generation: 'Generation — strict gate + unreviewed hosted preview',
+  bundling: 'Bundling — esbuild + three.js for the browser',
+  done: 'Done',
+};
+
+let pickedFile = null;
+let eventSource = null;
+let viewerSession = null; // {frame, ready, stats}
+
+function showPanel(name) {
+  for (const [key, el] of Object.entries(panels)) el.hidden = key !== name;
+}
+
+function logLine(text) {
+  const log = $('log');
+  log.textContent += text + '\n';
+  log.scrollTop = log.scrollHeight;
+}
+
+// --------------------------------------------------------------------------
+// Config / LLM badge
+// --------------------------------------------------------------------------
+async function loadConfig() {
+  try {
+    const res = await fetch('/api/config');
+    const cfg = await res.json();
+    const badge = $('llm-badge');
+    if (cfg.llm_configured) {
+      badge.textContent = 'LLM ready';
+      badge.className = 'badge badge-ok';
+      badge.title = `Model: ${cfg.model || 'unknown'}`;
+    } else {
+      badge.textContent = 'LLM not configured';
+      badge.className = 'badge badge-bad';
+      showError(
+        'LLM credentials are not configured',
+        'This Space needs a vision-capable LLM to author the sculpt spec. The Space owner must set '
+        + `${cfg.missing_llm_vars.join(' and ')} (plus LLM_BASE_URL) in Settings → Secrets, then restart. `
+        + 'No model can be generated until then — we never fabricate results.',
+        null,
+      );
+      $('run-btn').disabled = true;
+      return cfg;
+    }
+  } catch (err) {
+    $('llm-badge').textContent = 'config unavailable';
+    $('llm-badge').className = 'badge badge-bad';
+  }
+  return null;
+}
+
+// --------------------------------------------------------------------------
+// Upload handling
+// --------------------------------------------------------------------------
+function acceptFile(file) {
+  if (!file) return;
+  if (!/^image\//.test(file.type || '')) {
+    showError('Unsupported file', 'Please pick an image file (PNG, JPEG, WebP, GIF or BMP).', null);
+    return;
+  }
+  pickedFile = file;
+  const url = URL.createObjectURL(file);
+  $('preview').src = url;
+  $('preview-name').textContent = `${file.name || 'pasted image'} — ${(file.size / 1024).toFixed(0)} KiB`;
+  $('preview-row').hidden = false;
+  $('preview').onload = () => {
+    drawPalette($('preview'));
+    URL.revokeObjectURL(url);
+  };
+}
+
+function drawPalette(img) {
+  // Client-side dominant-colour swatches, honestly labelled approximate.
+  const canvas = document.createElement('canvas');
+  const size = 48;
+  canvas.width = size; canvas.height = size;
+  const ctx = canvas.getContext('2d', { willReadFrequently: true });
+  ctx.drawImage(img, 0, 0, size, size);
+  const { data } = ctx.getImageData(0, 0, size, size);
+  const buckets = new Map();
+  for (let i = 0; i < data.length; i += 4) {
+    const key = [data[i] >> 5, data[i + 1] >> 5, data[i + 2] >> 5].join(',');
+    buckets.set(key, (buckets.get(key) || 0) + 1);
+  }
+  const top = [...buckets.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6);
+  const palette = $('palette');
+  palette.textContent = '';
+  for (const [key] of top) {
+    const [r, g, b] = key.split(',').map((v) => (Number(v) << 5) + 16);
+    const sw = document.createElement('span');
+    sw.className = 'swatch';
+    sw.style.background = `rgb(${r},${g},${b})`;
+    sw.title = `≈ rgb(${r}, ${g}, ${b})`;
+    palette.appendChild(sw);
+  }
+}
+
+// --------------------------------------------------------------------------
+// Job lifecycle
+// --------------------------------------------------------------------------
+async function startJob() {
+  if (!pickedFile) return;
+  $('run-btn').disabled = true;
+  showPanel('progress');
+  $('stages').textContent = '';
+  $('log').textContent = '';
+
+  const form = new FormData();
+  form.append('file', pickedFile, pickedFile.name || 'image.png');
+  const hint = $('hint').value.trim();
+  if (hint) form.append('hint', hint);
+
+  let jobId;
+  try {
+    const res = await fetch('/api/jobs', { method: 'POST', body: form });
+    const payload = await res.json().catch(() => ({}));
+    if (res.status === 503 && payload.error === 'llm_not_configured') {
+      showError('LLM credentials are not configured', payload.detail || payload.message, null);
+      return;
+    }
+    if (!res.ok) {
+      showError('Upload rejected', payload.detail || payload.message || `HTTP ${res.status}`, null);
+      return;
+    }
+    jobId = payload.job_id;
+  } catch (err) {
+    showError('Network error', `Could not start the job: ${err.message || err}`, null);
+    return;
+  }
+  followJob(jobId);
+}
+
+function stageItem(stage) {
+  const li = document.createElement('li');
+  li.id = `stage-${stage}`;
+  li.className = 'stage stage-pending';
+  li.innerHTML = `<span class="stage-dot"></span><span class="stage-name">${STAGE_LABELS[stage] || stage}</span><span class="stage-note"></span>`;
+  return li;
+}
+
+function followJob(jobId) {
+  const stagesEl = $('stages');
+  stagesEl.textContent = '';
+  for (const stage of ['intake', 'spec-authoring', 'generation', 'bundling', 'done']) {
+    stagesEl.appendChild(stageItem(stage));
+  }
+  if (eventSource) eventSource.close();
+  eventSource = new EventSource(`/api/jobs/${jobId}/events`);
+
+  eventSource.onmessage = (msg) => {
+    let event;
+    try { event = JSON.parse(msg.data); } catch { return; }
+    handleEvent(event, jobId);
+  };
+  eventSource.onerror = () => {
+    // EventSource auto-reconnects; if the job vanished we get a 404 and the
+    // stream ends — poll once to find out.
+    if (eventSource.readyState === EventSource.CLOSED) return;
+    fetch(`/api/jobs/${jobId}`).then(async (res) => {
+      if (res.status === 404) {
+        eventSource.close();
+        showError('Job expired', 'The job registry entry is gone (Space restarted or TTL elapsed). Please run again.', null);
+      }
+    }).catch(() => {});
+  };
+}
+
+function setStage(stage, status, note) {
+  const li = $(`stage-${stage}`);
+  if (!li) return;
+  li.className = `stage stage-${status}`;
+  if (note) li.querySelector('.stage-note').textContent = note;
+}
+
+function handleEvent(event, jobId) {
+  const when = new Date(event.ts * 1000).toLocaleTimeString();
+  logLine(`[${when}] ${event.stage}: ${event.message}`);
+  const li = $(`stage-${event.stage}`);
+  if (event.status === 'started' || event.status === 'progress') {
+    setStage(event.stage, 'active', event.status === 'progress' ? event.message : '');
+  } else if (event.status === 'done' && event.stage !== 'done') {
+    setStage(event.stage, 'done');
+  }
+  if (event.stage === 'done' && event.status === 'done') {
+    eventSource.close();
+    setStage('done', 'done');
+    showResult(event.data.result);
+  } else if (event.status === 'error') {
+    eventSource.close();
+    for (const s of document.querySelectorAll('.stage-active')) setStage(s.id.replace('stage-', ''), 'failed');
+    showError(
+      errorTitle(event.data && event.data.code),
+      event.message,
+      event.data && event.data.detail ? JSON.stringify(event.data.detail, null, 2) : null,
+    );
+  }
+  if (li && event.status === 'done') setStage(event.stage, 'done');
+}
+
+function errorTitle(code) {
+  switch (code) {
+    case 'unsuitable_image': return 'This image is not a viable 3D target';
+    case 'spec_validation_failed': return 'The quality gate rejected the spec';
+    case 'llm_rejected': return 'The model endpoint rejected the request';
+    case 'llm_unavailable': case 'llm_unreachable': return 'The model endpoint is unavailable';
+    case 'llm_truncated': return 'The model reply was truncated';
+    case 'generation_failed': return 'Factory generation failed';
+    case 'queue_full': return 'The conversion queue is full';
+    case 'job_timeout': return 'The conversion reached its time limit';
+    default: return 'The pipeline stopped honestly';
+  }
+}
+
+// --------------------------------------------------------------------------
+// Result + viewer
+// --------------------------------------------------------------------------
+function showResult(result) {
+  showPanel('result');
+  $('result-title').textContent = result.targetName;
+  $('result-sub').textContent =
+    `${result.components} components · ${result.materials} materials · ` +
+    `unreviewed hosted preview generated in ${result.elapsedSeconds}s · ` +
+    `upstream review status: ${result.reviewStatus || 'unreviewed'}`;
+
+  const art = result.artifacts;
+  $('dl-ts').href = `${art['factory.ts']}?download=1`;
+  $('dl-ts').setAttribute('download', `create${result.targetName.replace(/\s+/g, '')}Model.ts`);
+  $('dl-spec').href = `${art['spec.json']}?download=1`;
+  $('dl-standalone').href = `${art['standalone.html']}?download=1`;
+  $('dl-standalone').setAttribute('download', `${result.targetName.replace(/\s+/g, '-').toLowerCase()}-standalone.html`);
+
+  const warnings = result.validationWarnings || [];
+  if (warnings.length) {
+    $('warnings-box').hidden = false;
+    $('warnings-list').textContent = '';
+    for (const w of warnings.slice(0, 12)) {
+      const li = document.createElement('li');
+      li.textContent = w;
+      $('warnings-list').appendChild(li);
+    }
+  }
+  $('honesty-list').textContent = '';
+  for (const note of result.honesty || []) {
+    const li = document.createElement('li');
+    li.textContent = note;
+    $('honesty-list').appendChild(li);
+  }
+
+  mountViewerFrame(art['model.bundle.js']);
+  $('dl-shot').onclick = captureScreenshot;
+}
+
+function mountViewerFrame(bundleUrl) {
+  const frame = $('viewer-frame');
+  const overlay = $('viewer-overlay');
+  overlay.textContent = 'Starting viewer…';
+  overlay.style.display = 'flex';
+  if (viewerSession && viewerSession.listener) {
+    window.removeEventListener('message', viewerSession.listener);
+  }
+  viewerSession = { frame, ready: false, stats: null, listener: null, captureWaiter: null };
+
+  const watchdog = setTimeout(() => {
+    if (!viewerSession.ready) {
+      overlay.textContent = 'The generated model did not start rendering within 45s. '
+        + 'Your downloads below still work — the .ts factory is the primary artifact.';
+    }
+  }, 45000);
+
+  const listener = async (event) => {
+    if (event.source !== frame.contentWindow) return;
+    const data = event.data || {};
+    if (data.type === 'shell-ready') {
+      try {
+        const res = await fetch(bundleUrl);
+        const bundleText = await res.text();
+        frame.contentWindow.postMessage({ type: 'init', bundleText }, '*');
+      } catch (err) {
+        overlay.textContent = `Could not load the model bundle: ${err.message || err}`;
+      }
+    } else if (data.type === 'ready') {
+      clearTimeout(watchdog);
+      viewerSession.ready = true;
+      viewerSession.stats = data.stats || {};
+      overlay.style.display = 'none';
+    } else if (data.type === 'error') {
+      clearTimeout(watchdog);
+      overlay.textContent = `Viewer error: ${data.message}. Downloads still work.`;
+    } else if (data.type === 'capture' && viewerSession.captureWaiter) {
+      viewerSession.captureWaiter(data.dataUrl);
+      viewerSession.captureWaiter = null;
+    }
+  };
+  viewerSession.listener = listener;
+  window.addEventListener('message', listener);
+  frame.src = '/static/viewer.html';
+}
+
+function captureScreenshot() {
+  if (!viewerSession || !viewerSession.ready) return;
+  viewerSession.captureWaiter = (dataUrl) => {
+    const a = document.createElement('a');
+    a.href = dataUrl;
+    a.download = 'render.png';
+    a.click();
+  };
+  viewerSession.frame.contentWindow.postMessage({ type: 'capture' }, '*');
+}
+
+// --------------------------------------------------------------------------
+// Errors
+// --------------------------------------------------------------------------
+function showError(title, message, detail) {
+  showPanel('error');
+  $('error-title').textContent = title;
+  $('error-message').textContent = message || '';
+  const pre = $('error-detail');
+  if (detail) { pre.hidden = false; pre.textContent = detail; } else { pre.hidden = true; }
+}
+
+function reset() {
+  if (eventSource) { eventSource.close(); eventSource = null; }
+  pickedFile = null;
+  $('preview-row').hidden = true;
+  $('file-input').value = '';
+  $('run-btn').disabled = false;
+  showPanel('upload');
+}
+
+// --------------------------------------------------------------------------
+// Wiring
+// --------------------------------------------------------------------------
+$('dropzone').addEventListener('click', () => $('file-input').click());
+$('dropzone').addEventListener('keydown', (e) => { if (e.key === 'Enter' || e.key === ' ') $('file-input').click(); });
+$('file-input').addEventListener('change', (e) => acceptFile(e.target.files[0]));
+$('dropzone').addEventListener('dragover', (e) => { e.preventDefault(); e.currentTarget.classList.add('drag'); });
+$('dropzone').addEventListener('dragleave', (e) => e.currentTarget.classList.remove('drag'));
+$('dropzone').addEventListener('drop', (e) => {
+  e.preventDefault();
+  e.currentTarget.classList.remove('drag');
+  acceptFile(e.dataTransfer.files && e.dataTransfer.files[0]);
+});
+window.addEventListener('paste', (e) => {
+  const item = [...(e.clipboardData ? e.clipboardData.items : [])].find((i) => i.type.startsWith('image/'));
+  if (item) acceptFile(item.getAsFile());
+});
+$('run-btn').addEventListener('click', startJob);
+$('again-btn').addEventListener('click', reset);
+$('error-again-btn').addEventListener('click', reset);
+
+loadConfig();

app/static/index.html

@@ -0,0 +1,109 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>img2threejs — image to procedural Three.js</title>
+<meta name="description" content="Turn a reference image into an inspectable procedural Three.js draft written as code.">
+<link rel="icon" href="/static/logo.svg" type="image/svg+xml">
+<link rel="stylesheet" href="/static/styles.css">
+</head>
+<body>
+<header class="site-header">
+  <img src="/static/logo.svg" alt="" width="34" height="34">
+  <div>
+    <h1>img2threejs</h1>
+    <p class="tagline">One reference image → an inspectable procedural Three.js draft, written as code.</p>
+  </div>
+  <span id="llm-badge" class="badge badge-unknown" title=""></span>
+</header>
+
+<main>
+  <section id="panel-upload" class="panel">
+    <div id="dropzone" class="dropzone" tabindex="0" role="button"
+         aria-label="Upload a reference image">
+      <p class="drop-title">Drop a reference image here</p>
+      <p class="drop-sub">or click to browse / paste from clipboard — PNG, JPEG, WebP, GIF, BMP · ≤ 10 MiB</p>
+      <input id="file-input" type="file" accept="image/png,image/jpeg,image/webp,image/gif,image/bmp" hidden>
+    </div>
+    <div id="preview-row" class="preview-row" hidden>
+      <img id="preview" alt="Uploaded reference preview">
+      <div class="preview-meta">
+        <div id="preview-name" class="preview-name"></div>
+        <div id="palette" class="palette" title="Dominant colours (approximate, client-side)"></div>
+        <label class="hint-label" for="hint">What is the object? <span>(optional hint for the model)</span></label>
+        <input id="hint" type="text" maxlength="80" placeholder="e.g. a red diesel locomotive">
+        <button id="run-btn" class="primary" type="button">Generate a Three.js preview</button>
+      </div>
+    </div>
+    <p class="honesty-note">
+      Honesty first: the result is an <em>approximate, unreviewed</em> procedural reconstruction from a
+      single image. Hidden geometry is inferred by the model, not observed or measured.
+      If the image cannot support a faithful reconstruction, the pipeline says so instead of
+      faking confidence. A hosted preview is not an approved upstream build pass.
+    </p>
+  </section>
+
+  <section id="panel-progress" class="panel" hidden>
+    <h2>Pipeline</h2>
+    <p class="progress-note">A vision model is authoring and validating a structured sculpt spec.
+      Provider latency and repair rounds can take several minutes. Stages advance only when real work
+      completes; there are no fake progress bars.</p>
+    <ol id="stages" class="stages" aria-live="polite"></ol>
+    <details class="log-drawer">
+      <summary>Live log</summary>
+      <pre id="log" class="log"></pre>
+    </details>
+  </section>
+
+  <section id="panel-result" class="panel" hidden>
+    <div class="result-grid">
+      <div class="viewer-column">
+        <div id="viewer-frame-wrap" class="viewer-frame-wrap">
+          <iframe id="viewer-frame" title="Generated 3D model viewer"
+                  sandbox="allow-scripts" referrerpolicy="no-referrer"></iframe>
+          <div id="viewer-overlay" class="viewer-overlay">Starting viewer…</div>
+        </div>
+        <p class="viewer-help">Drag to orbit · scroll to zoom · right-drag to pan</p>
+      </div>
+      <aside class="result-rail">
+        <h2 id="result-title">Result</h2>
+        <p id="result-sub" class="result-sub"></p>
+        <div class="downloads">
+          <a id="dl-ts" class="button" download>Factory (.ts)</a>
+          <a id="dl-spec" class="button" download>Spec (.json)</a>
+          <a id="dl-standalone" class="button" download>Standalone viewer (.html)</a>
+          <button id="dl-shot" class="button" type="button">Screenshot (.png)</button>
+        </div>
+        <details id="warnings-box" class="warnings-box" hidden>
+          <summary>Validator notes</summary>
+          <ul id="warnings-list"></ul>
+        </details>
+        <div class="honesty-box">
+          <h3>Honesty notes</h3>
+          <ul id="honesty-list"></ul>
+        </div>
+        <button id="again-btn" class="secondary" type="button">Start over</button>
+      </aside>
+    </div>
+  </section>
+
+  <section id="panel-error" class="panel panel-error" hidden>
+    <h2 id="error-title">Something went wrong</h2>
+    <p id="error-message"></p>
+    <pre id="error-detail" class="error-detail" hidden></pre>
+    <button id="error-again-btn" class="secondary" type="button">Start over</button>
+  </section>
+</main>
+
+<footer class="site-footer">
+  <p>
+    Built on <a href="https://github.com/hoainho/img2threejs">hoainho/img2threejs</a> (MIT) ·
+    reconstruction-by-code, not photogrammetry ·
+    <a href="https://huggingface.co/spaces/Mike0021/img2threejs">HF Space</a>
+  </p>
+</footer>
+
+<script type="module" src="/static/app.js"></script>
+</body>
+</html>

app/static/styles.css

@@ -0,0 +1,135 @@
+/* img2threejs Space — dark theme (three.js-editor convention). */
+:root {
+  --bg: #16181d;
+  --panel: #1e2128;
+  --panel-2: #23262f;
+  --grid: #262a33;
+  --text: #e6e8ee;
+  --muted: #9aa0ad;
+  --accent: #e8a33d;
+  --error: #e05d5d;
+  --success: #5dbb8a;
+  --radius: 10px;
+}
+
+* { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+body {
+  background: var(--bg); color: var(--text);
+  font: 15px/1.55 system-ui, -apple-system, "Segoe UI", sans-serif;
+  min-height: 100vh; display: flex; flex-direction: column;
+}
+
+a { color: var(--accent); }
+button, .button {
+  font: inherit; border-radius: 8px; border: 1px solid #3a3f4a;
+  background: var(--panel-2); color: var(--text);
+  padding: 0.55rem 0.9rem; cursor: pointer; text-decoration: none;
+  display: inline-block; text-align: center;
+}
+button:hover, .button:hover { border-color: var(--accent); }
+button:disabled { opacity: 0.45; cursor: not-allowed; }
+button.primary {
+  background: var(--accent); border-color: var(--accent);
+  color: #1a1206; font-weight: 650; width: 100%;
+}
+button.secondary { width: 100%; margin-top: 1rem; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+
+.site-header {
+  display: flex; align-items: center; gap: 0.9rem;
+  padding: 1rem 1.4rem; border-bottom: 1px solid var(--grid);
+}
+.site-header h1 { font-size: 1.25rem; margin: 0; }
+.tagline { margin: 0; color: var(--muted); font-size: 0.88rem; }
+.badge { margin-left: auto; padding: 0.25rem 0.7rem; border-radius: 999px; font-size: 0.8rem; }
+.badge-ok { background: rgba(93, 187, 138, 0.15); color: var(--success); border: 1px solid var(--success); }
+.badge-bad { background: rgba(224, 93, 93, 0.15); color: var(--error); border: 1px solid var(--error); }
+.badge-unknown { color: var(--muted); }
+
+main { flex: 1; width: min(1120px, 100%); margin: 0 auto; padding: 1.4rem; }
+.panel { background: var(--panel); border: 1px solid var(--grid); border-radius: var(--radius); padding: 1.3rem; }
+.panel h2 { margin-top: 0; }
+
+.dropzone {
+  border: 2px dashed #3a3f4a; border-radius: var(--radius);
+  padding: 3rem 1rem; text-align: center; cursor: pointer;
+  transition: border-color 0.15s, background 0.15s;
+}
+.dropzone:hover, .dropzone.drag { border-color: var(--accent); background: rgba(232, 163, 61, 0.06); }
+.drop-title { font-size: 1.1rem; font-weight: 600; margin: 0 0 0.3rem; }
+.drop-sub { color: var(--muted); margin: 0; font-size: 0.86rem; }
+
+.preview-row { display: flex; gap: 1.2rem; margin-top: 1.2rem; align-items: flex-start; flex-wrap: wrap; }
+.preview-row img {
+  width: 220px; max-height: 220px; object-fit: contain;
+  border-radius: 8px; border: 1px solid var(--grid); background: #0f1114;
+}
+.preview-meta { flex: 1; min-width: 240px; display: flex; flex-direction: column; gap: 0.6rem; }
+.preview-name { color: var(--muted); font-size: 0.85rem; word-break: break-all; }
+.palette { display: flex; gap: 6px; }
+.swatch { width: 26px; height: 26px; border-radius: 6px; border: 1px solid rgba(255,255,255,0.12); }
+.hint-label { font-size: 0.9rem; }
+.hint-label span { color: var(--muted); font-size: 0.8rem; }
+#hint {
+  font: inherit; padding: 0.5rem 0.7rem; border-radius: 8px;
+  border: 1px solid #3a3f4a; background: var(--panel-2); color: var(--text);
+}
+
+.honesty-note { color: var(--muted); font-size: 0.85rem; margin: 1.2rem 0 0; border-top: 1px solid var(--grid); padding-top: 0.9rem; }
+
+.progress-note { color: var(--muted); font-size: 0.85rem; margin-top: -0.4rem; }
+.stages { list-style: none; margin: 0 0 1rem; padding: 0; }
+.stage { display: flex; align-items: baseline; gap: 0.7rem; padding: 0.55rem 0.2rem; border-bottom: 1px solid var(--grid); }
+.stage-dot { width: 10px; height: 10px; border-radius: 50%; background: #3a3f4a; flex: none; align-self: center; }
+.stage-active .stage-dot { background: var(--accent); animation: pulse 1.2s infinite; }
+.stage-done .stage-dot { background: var(--success); }
+.stage-failed .stage-dot { background: var(--error); }
+.stage-pending .stage-name { color: var(--muted); }
+.stage-note { color: var(--muted); font-size: 0.82rem; margin-left: auto; max-width: 55%; text-align: right; }
+@keyframes pulse { 50% { opacity: 0.35; } }
+
+.log-drawer summary { cursor: pointer; color: var(--muted); }
+.log {
+  background: #0f1114; border: 1px solid var(--grid); border-radius: 8px;
+  padding: 0.8rem; max-height: 260px; overflow: auto;
+  font: 12px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace; color: #b7bcc7;
+  white-space: pre-wrap; word-break: break-word;
+}
+
+.result-grid { display: grid; grid-template-columns: 1.5fr 1fr; gap: 1.2rem; }
+@media (max-width: 860px) { .result-grid { grid-template-columns: 1fr; } }
+.viewer-frame-wrap {
+  position: relative; aspect-ratio: 4 / 3; min-height: 320px;
+  background: #0f1114; border: 1px solid var(--grid); border-radius: 8px; overflow: hidden;
+}
+#viewer-frame { width: 100%; height: 100%; border: 0; display: block; }
+.viewer-overlay {
+  position: absolute; inset: 0; display: flex; align-items: center; justify-content: center;
+  color: var(--muted); background: rgba(15, 17, 20, 0.85); padding: 1rem; text-align: center;
+}
+.viewer-help { color: var(--muted); font-size: 0.8rem; text-align: center; }
+.result-rail h2 { margin-bottom: 0.2rem; word-break: break-word; }
+.result-sub { color: var(--muted); font-size: 0.85rem; }
+.downloads { display: grid; gap: 0.5rem; margin: 1rem 0; }
+.warnings-box, .honesty-box {
+  border: 1px solid var(--grid); border-radius: 8px; padding: 0.7rem 0.9rem;
+  margin-bottom: 0.8rem; font-size: 0.85rem; background: var(--panel-2);
+}
+.warnings-box summary { cursor: pointer; }
+.honesty-box h3 { margin: 0 0 0.4rem; font-size: 0.9rem; color: var(--accent); }
+.honesty-box ul, .warnings-box ul { margin: 0; padding-left: 1.1rem; color: var(--muted); }
+
+.panel-error { border-color: var(--error); }
+.panel-error h2 { color: var(--error); }
+.error-detail {
+  background: #0f1114; border: 1px solid var(--grid); border-radius: 8px;
+  padding: 0.8rem; max-height: 300px; overflow: auto;
+  font: 12px/1.6 ui-monospace, Menlo, monospace; white-space: pre-wrap; word-break: break-word;
+}
+
+.site-footer { padding: 1rem 1.4rem; border-top: 1px solid var(--grid); color: var(--muted); font-size: 0.82rem; text-align: center; }
+
+@media (prefers-reduced-motion: reduce) {
+  .stage-active .stage-dot { animation: none; }
+}

app/static/viewer-core.js

@@ -0,0 +1,152 @@
+// viewer-core.js — three.js scene harness for generated img2threejs factories.
+// Bundled into every per-job model bundle by esbuild (three included), and
+// called with the generated factory exports. Runs inside the sandboxed
+// viewer iframe (and inside standalone.html exports).
+//
+// Design notes:
+//  * Generated factories emit `import * as THREE from 'three'` and construct
+//    procedural canvas textures at call time, so this must run in a real
+//    browser (the factory falls back to flat materials when document is
+//    absent — the node smoke test relies on that).
+//  * RoomEnvironment + ACES keeps MeshPhysicalMaterial metals/clearcoat
+//    readable; the generated LookDevLights rig (neutral) is the rig the
+//    upstream review rubric assumes.
+
+import * as THREE from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+
+export function mountViewer(el, makeModel, makeLights, opts = {}) {
+  if (typeof makeModel !== 'function') {
+    throw new Error('No create*Model export found in the generated factory.');
+  }
+  const renderer = new THREE.WebGLRenderer({ antialias: true, preserveDrawingBuffer: true });
+  renderer.toneMapping = THREE.ACESFilmicToneMapping;
+  renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+  el.appendChild(renderer.domElement);
+  renderer.domElement.style.display = 'block';
+
+  const scene = new THREE.Scene();
+  scene.background = new THREE.Color(0x16181d);
+  const pmrem = new THREE.PMREMGenerator(renderer);
+  scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
+
+  const model = makeModel({
+    textureSize: opts.textureSize || 512,
+    qualityPriority: 'balanced',
+    ...(opts.factoryOptions || {}),
+  });
+  scene.add(model);
+
+  let lights = null;
+  try {
+    lights = typeof makeLights === 'function' ? makeLights('neutral') : null;
+  } catch (_) {
+    lights = null;
+  }
+  if (lights) {
+    lights.traverse((node) => {
+      if (node.isDirectionalLight && node.shadow && node.shadow.mapSize) {
+        node.shadow.mapSize.set(2048, 2048);
+      }
+    });
+    scene.add(lights);
+  } else {
+    scene.add(new THREE.HemisphereLight(0xffffff, 0x363b42, 1.1));
+  }
+  // Ambient floor so a spec that zeroes lights still shows silhouettes.
+  scene.add(new THREE.AmbientLight(0xffffff, 0.15));
+
+  const box = new THREE.Box3().setFromObject(model);
+  const sphere = box.getBoundingSphere(new THREE.Sphere());
+  const radius = Math.max(sphere.radius, 1e-3);
+
+  const grid = new THREE.GridHelper(radius * 4, 20, 0x3a3f4a, 0x262a33);
+  grid.position.y = box.min.y;
+  scene.add(grid);
+
+  const ground = new THREE.Mesh(
+    new THREE.CircleGeometry(radius * 2.5, 48),
+    new THREE.ShadowMaterial({ opacity: 0.35 }),
+  );
+  ground.rotation.x = -Math.PI / 2;
+  ground.position.y = box.min.y - 0.001;
+  ground.receiveShadow = true;
+  scene.add(ground);
+
+  const camera = new THREE.PerspectiveCamera(40, 1, radius / 100, radius * 100);
+  const dir = new THREE.Vector3(1, 0.6, 1.4).normalize();
+  const distance = (radius / Math.sin(THREE.MathUtils.degToRad(20))) * 1.1;
+  camera.position.copy(sphere.center).addScaledVector(dir, distance);
+
+  const controls = new OrbitControls(camera, renderer.domElement);
+  controls.target.copy(sphere.center);
+  controls.enableDamping = true;
+  controls.update();
+
+  renderer.shadowMap.enabled = true;
+  renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+
+  const fit = () => {
+    const w = el.clientWidth || 640;
+    const h = el.clientHeight || 420;
+    renderer.setSize(w, h, false);
+    camera.aspect = w / h;
+    camera.updateProjectionMatrix();
+  };
+  const observer = new ResizeObserver(fit);
+  observer.observe(el);
+  fit();
+
+  let meshes = 0;
+  model.traverse((node) => { if (node.isMesh) meshes += 1; });
+
+  renderer.setAnimationLoop(() => {
+    controls.update();
+    renderer.render(scene, camera);
+  });
+
+  const capture = () => new Promise((resolve, reject) => {
+    renderer.render(scene, camera);
+    renderer.domElement.toBlob((blob) => {
+      if (!blob) return reject(new Error('capture failed'));
+      const reader = new FileReader();
+      reader.onload = () => resolve(reader.result);
+      reader.onerror = () => reject(new Error('capture read failed'));
+      reader.readAsDataURL(blob);
+    }, 'image/png');
+  });
+
+  const dispose = () => {
+    observer.disconnect();
+    renderer.setAnimationLoop(null);
+    scene.traverse((node) => {
+      if (node.geometry) node.geometry.dispose();
+      if (node.material) {
+        for (const material of Array.isArray(node.material) ? node.material : [node.material]) {
+          for (const key of Object.keys(material)) {
+            const value = material[key];
+            if (value && value.isTexture) value.dispose();
+          }
+          material.dispose();
+        }
+      }
+    });
+    pmrem.dispose();
+    renderer.dispose();
+    renderer.domElement.remove();
+  };
+
+  return {
+    capture,
+    dispose,
+    stats: {
+      meshes,
+      topLevelChildren: model.children.length,
+      boundingSphereRadius: Number(radius.toFixed(4)),
+      runtimeNodes: Object.keys(
+        (model.userData && model.userData.sculptRuntime && model.userData.sculptRuntime.nodes) || {},
+      ).length,
+    },
+  };
+}

app/static/viewer.html

@@ -0,0 +1,90 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta http-equiv="Content-Security-Policy"
+      content="default-src 'none'; script-src 'unsafe-inline' blob:; style-src 'unsafe-inline'; img-src blob: data:; worker-src blob:">
+<title>img2threejs viewer</title>
+<style>
+  html, body { margin: 0; height: 100%; background: #16181d; overflow: hidden; }
+  #viewer { position: fixed; inset: 0; }
+  #status {
+    position: fixed; inset: 0; display: flex; align-items: center; justify-content: center;
+    color: #9aa0ad; font: 14px/1.5 system-ui, sans-serif; text-align: center; padding: 1rem;
+  }
+</style>
+</head>
+<body>
+<div id="viewer" role="region" aria-label="3D model viewer"></div>
+<div id="status">Loading model…</div>
+<script type="module">
+// Sandboxed viewer shell. This document runs in an opaque origin
+// (sandbox="allow-scripts", no allow-same-origin): the LLM-influenced
+// generated code cannot touch the parent application's origin, cookies or
+// storage. Communication with the parent is postMessage-only.
+//
+// Protocol (parent -> iframe):
+//   {type:'init', bundleText, targetName}   — full ESM bundle source
+//   {type:'capture'}                        — request a PNG screenshot
+// Protocol (iframe -> parent):
+//   {type:'ready', stats}
+//   {type:'error', message}
+//   {type:'capture', dataUrl}
+const status = document.getElementById('status');
+const viewerEl = document.getElementById('viewer');
+let session = null;
+
+function post(message) {
+  // The parent's origin is unknown to us (opaque origin); '*' is acceptable
+  // here because the payloads contain no secrets and the parent validates
+  // event.source. Model code never sees these messages.
+  parent.postMessage(message, '*');
+}
+
+async function boot(bundleText) {
+  const blob = new Blob([bundleText], { type: 'text/javascript' });
+  const url = URL.createObjectURL(blob);
+  try {
+    const mod = await import(url);
+    if (!document.createElement('canvas').getContext('webgl2') &&
+        !document.createElement('canvas').getContext('webgl')) {
+      throw new Error('WebGL is not available in this browser or GPU.');
+    }
+    session = mod.mountViewer(viewerEl, mod.makeModel,
+      typeof mod.makeLights === 'function' ? mod.makeLights : null, {});
+    status.remove();
+    post({ type: 'ready', stats: session.stats });
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+window.addEventListener('message', async (event) => {
+  if (event.source !== parent) return;
+  const data = event.data;
+  if (!data || typeof data !== 'object') return;
+  if (data.type === 'init' && typeof data.bundleText === 'string') {
+    try {
+      await boot(data.bundleText);
+    } catch (err) {
+      status.textContent = 'The generated model failed to render: ' +
+        ((err && err.message) || String(err));
+      post({ type: 'error', message: (err && err.message) || String(err) });
+    }
+  } else if (data.type === 'capture') {
+    try {
+      if (!session) throw new Error('viewer not ready');
+      const dataUrl = await session.capture();
+      post({ type: 'capture', dataUrl });
+    } catch (err) {
+      post({ type: 'error', message: 'capture failed: ' + ((err && err.message) || String(err)) });
+    }
+  }
+});
+
+// Signal to the parent that the shell itself loaded (watchdog baseline).
+post({ type: 'shell-ready' });
+</script>
+</body>
+</html>

docs/SECURITY.md

@@ -0,0 +1,116 @@
+# Security model
+
+This public Space accepts untrusted images, sends normalized image content to a
+configured external LLM provider, and renders generated procedural code in a
+visitor's browser. The controls and remaining limitations are explicit below.
+
+## Upload boundary
+
+`app/image_guard.py` and `app/main.py` enforce:
+
+- A 10 MiB default byte cap while reading, before image decode.
+- Pillow content sniffing; filename, extension, and declared MIME type are not
+  treated as proof of format.
+- PNG, JPEG, WebP, GIF (first frame), and BMP only. SVG is rejected because it
+  is scriptable XML.
+- Pillow decompression-bomb protection, a 40 MP default pixel cap, and an
+  8192 px longest-side decode cap.
+- EXIF orientation normalization followed by RGB PNG re-encoding, which strips
+  original metadata. The normalized image is downscaled to at most 1024 px
+  before forge/LLM processing.
+- Server-generated job IDs and artifact names. The artifact route uses an
+  explicit filename allowlist and verifies that the resolved file remains
+  directly inside its job directory.
+
+The normalized image is sent to the operator-configured LLM endpoint. Users
+must treat that provider as a data processor; this Space does not make a local
+model privacy claim.
+
+## Generated code and browser isolation
+
+- The LLM authors JSON spec values, not executable TypeScript. A deterministic
+  vendored generator emits code and JSON-escapes spec-derived literals.
+- The hosted compiler accepts only its implemented primitive allowlist and
+  rejects parent cycles. Generation fails if a TODO fallback is detected; an
+  unsupported primitive is never silently represented as a placeholder box.
+- The interactive viewer runs in `<iframe sandbox="allow-scripts">` without
+  `allow-same-origin`. It has an opaque origin and cannot access parent cookies,
+  storage, or same-origin DOM. Parent/iframe communication is `postMessage`;
+  the parent validates `event.source`.
+- Normal application responses use a restrictive policy including
+  `default-src 'self'`, `script-src 'self' blob:`, `object-src 'none'`, and
+  `base-uri 'none'`. `/static/viewer.html` receives a separate explicit CSP
+  permitting only its required inline bootstrap and blob module import.
+- Generated artifacts are served as files. Standalone HTML base64-embeds the
+  bundle, creates a blob URL, and accesses module exports through
+  `await import(url)` rather than assuming export aliases are local bindings.
+
+Browser sandboxing limits access to the Space origin; it is not a proof that
+arbitrary generated code is harmless in every browser implementation. Keep the
+sandbox and CSP in place when embedding or modifying the viewer.
+
+## Server-side process boundary
+
+`app/forge_bridge.py` invokes forge and esbuild with:
+
+- list-form argv and `shell=False`;
+- per-call timeouts and bounded captured output;
+- a scrubbed child environment that omits `LLM_*` and `ANTHROPIC_*` variables;
+- server-controlled files inside a per-job temporary directory.
+
+The strict-validated original spec remains locked and unreviewed. A deep-copied
+`hosted-unreviewed-preview` manifest is used only to compile all supported
+components for inspection. It carries no reviewer, screenshot, comparison
+image, score, or upstream `continue` decision.
+
+## Secrets and deployment
+
+- Runtime credentials are read from environment variables at startup and are
+  never logged or returned by `/api/config`.
+- Hugging Face injects Space Secrets at runtime; no credential is a Docker
+  build argument or image layer.
+- `scripts/deploy_space.py` uses the authenticated local `hf` CLI store, stages
+  a deterministic file allowlist, and performs one upload from that sanitized
+  directory.
+- Environment-derived secret values are written only to a temporary mode-0600
+  secrets file, passed via `hf spaces secrets add --secrets-file`, and removed
+  in a `finally` block. Logs and process arguments contain secret names only.
+
+## Abuse and resource control
+
+- The default per-client limit is 10 accepted jobs per hour with
+  `Retry-After`. The in-memory client map has an LRU size bound.
+- Client identity comes from the ASGI socket peer as resolved by the trusted
+  Uvicorn proxy configuration. Application code does not reinterpret a raw,
+  caller-controlled `X-Forwarded-For` header.
+- Two jobs run concurrently by default and queued plus running jobs are capped
+  at eight. A full queue returns `queue_full` with `Retry-After`; queued uploads
+  therefore cannot pin unbounded memory.
+- Provider retries apply only to transient statuses, not 400/401/403.
+- Terminal jobs have a two-hour default TTL. The reaper does not delete a
+  running job solely because it was created a long time ago.
+
+All abuse controls are process-local. They reduce accidental/public-demo load;
+they are not a distributed quota system.
+
+## Container boundary
+
+- The service runs as non-root UID 1000 under `tini` on
+  `python:3.12-slim-bookworm` and binds to `0.0.0.0:7860`.
+- The final Docker stage copies only runtime dependencies, `app/`, required
+  `forge/` code, and `LICENSE`.
+- `.dockerignore`, the runtime COPY allowlist, and Docker verification exclude
+  VCS state, virtual environments, rollouts, caches, tests, scripts,
+  `upstream-src`, and local verification artifacts from the final image.
+- Rebuild the image regularly to pick up base-image security updates.
+
+## Accepted limitations
+
+- A single image does not reveal hidden geometry. Results are approximate and
+  hidden sides are inferred, not observed or measured.
+- A strict-valid spec is not visually approved. The hosted result is explicitly
+  unreviewed; production use requires the upstream screenshot/comparison review
+  loop.
+- Job artifacts live in ephemeral `/tmp` and expire; there is no persistent
+  user-content store.
+- Rate limiting and job state reset when the single process restarts.

forge/_shared/feature_acceptance_policy.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Shared feature-level acceptance logic for visual sculpt passes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def feature_review_policy(spec: dict[str, Any]) -> dict[str, Any]:
+    loop = spec.get("selfCorrectLoop")
+    if not isinstance(loop, dict):
+        return {}
+    acceptance = loop.get("visualAcceptance")
+    if not isinstance(acceptance, dict):
+        return {}
+    policy = acceptance.get("featureReviewPolicy")
+    return policy if isinstance(policy, dict) else {}
+
+
+def feature_targets_for_pass(spec: dict[str, Any], pass_id: str) -> list[dict[str, Any]]:
+    targets = spec.get("featureReviewTargets", [])
+    if not isinstance(targets, list):
+        return []
+    applicable: list[dict[str, Any]] = []
+    for target in targets:
+        if not isinstance(target, dict):
+            continue
+        pass_ids = target.get("passIds", [])
+        if isinstance(pass_ids, list) and pass_id in pass_ids:
+            applicable.append(target)
+    return applicable
+
+
+def feature_gate_failures(
+    spec: dict[str, Any],
+    entry: dict[str, Any],
+    pass_id: str,
+) -> list[str]:
+    policy = feature_review_policy(spec)
+    if policy.get("enabled") is not True:
+        return []
+
+    targets = feature_targets_for_pass(spec, pass_id)
+    critical = [
+        target
+        for target in targets
+        if target.get("tier") == "critical" or target.get("mustPass") is True
+    ]
+    max_critical = policy.get("maxCriticalFeaturesPerPass", 5)
+    failures: list[str] = []
+    if is_number(max_critical) and len(critical) > int(max_critical):
+        failures.append(
+            f"pass {pass_id!r} defines {len(critical)} critical features; "
+            f"group them into at most {int(max_critical)} semantic systems"
+        )
+    important = [target for target in targets if target.get("tier") == "important"]
+    max_important = policy.get("maxImportantFeaturesPerPass", 3)
+    if is_number(max_important) and len(important) > int(max_important):
+        failures.append(
+            f"pass {pass_id!r} defines {len(important)} important features; "
+            f"keep only the {int(max_important)} most uncertain or high-value systems"
+        )
+
+    reviews = entry.get("featureReviews", [])
+    review_by_id = {
+        review.get("id"): review
+        for review in reviews
+        if isinstance(review, dict) and isinstance(review.get("id"), str)
+    } if isinstance(reviews, list) else {}
+
+    default_threshold = policy.get("criticalDefaultThreshold", 0.8)
+    for target in critical:
+        target_id = target.get("id")
+        if not isinstance(target_id, str) or not target_id:
+            continue
+        review = review_by_id.get(target_id)
+        if not isinstance(review, dict):
+            failures.append(f"critical feature {target_id!r} has no AI vision review")
+            continue
+        if review.get("visible") is False:
+            failures.append(f"critical feature {target_id!r} is not visible in the review view")
+            continue
+        score = review.get("score")
+        minimum = target.get("minimumScore", default_threshold)
+        if not is_number(score):
+            failures.append(f"critical feature {target_id!r} has no numeric score")
+        elif not is_number(minimum) or float(score) < float(minimum):
+            failures.append(
+                f"critical feature {target_id!r} score {score} is below {minimum}"
+            )
+    important_ids = {
+        target.get("id")
+        for target in targets
+        if target.get("tier") == "important" and isinstance(target.get("id"), str)
+    }
+    important_scores = [
+        float(review["score"])
+        for feature_id, review in review_by_id.items()
+        if feature_id in important_ids and is_number(review.get("score"))
+    ]
+    important_threshold = policy.get("importantAverageThreshold", 0.65)
+    if important_scores and is_number(important_threshold):
+        average = sum(important_scores) / len(important_scores)
+        if average < float(important_threshold):
+            failures.append(
+                f"reviewed important features average {average:.3f} is below "
+                f"{float(important_threshold):.3f}"
+            )
+    return failures

forge/requirements.txt

@@ -0,0 +1,6 @@
+# Three.js Object Sculptor scripts have NO third-party dependencies.
+# Everything uses the Python 3.10+ standard library only (json, argparse, struct,
+# zlib, pathlib, math, subprocess). PNG maps and comparison sheets are written with
+# struct/zlib directly — no Pillow/numpy/OpenCV/Playwright required.
+#
+# Requires: python >= 3.10

forge/stage1_intake/build_detail_inventory.py

@@ -0,0 +1,336 @@
+#!/usr/bin/env python3
+"""Slice a reference image into inspection zones and scaffold a detailInventory to fill in.
+
+Scans the reference zone by zone (a uniform grid, or named component regions) so small
+identity-defining marks are not missed by a single glance at the whole image. Writes one
+crop PNG per zone plus a detailInventory skeleton JSON (see docs/UPGRADE_PLAN.md 4.1 and
+grimoire/intake/detail_inventory.md) with one detail stub per zone for the agent to classify,
+describe, and link to a component/material field. This script only scaffolds zones and
+crops; it does not judge what is in them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+from pathlib import Path
+
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+TARGET_MIN_DETAILS = {
+    "simple": 3,
+    "moderate": 6,
+    "complex": 10,
+    "ultra-complex": 16,
+}
+
+DEFAULT_COMPONENT_ZONES = [
+    ("upper", 0.0, 0.0, 1.0, 1.0 / 3),
+    ("middle", 0.0, 1.0 / 3, 1.0, 1.0 / 3),
+    ("lower", 0.0, 2.0 / 3, 1.0, 1.0 / 3),
+]
+
+
+def paeth_predictor(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa = abs(p - a)
+    pb = abs(p - b)
+    pc = abs(p - c)
+    if pa <= pb and pa <= pc:
+        return a
+    if pb <= pc:
+        return b
+    return c
+
+
+def read_png(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise ValueError("not a PNG file")
+    cursor = len(PNG_SIGNATURE)
+    width = height = bit_depth = color_type = interlace = None
+    idat = bytearray()
+    while cursor + 8 <= len(data):
+        length = struct.unpack(">I", data[cursor : cursor + 4])[0]
+        chunk_type = data[cursor + 4 : cursor + 8]
+        chunk_data = data[cursor + 8 : cursor + 8 + length]
+        cursor += 12 + length
+        if chunk_type == b"IHDR":
+            width, height, bit_depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", chunk_data)
+        elif chunk_type == b"IDAT":
+            idat.extend(chunk_data)
+        elif chunk_type == b"IEND":
+            break
+    if width is None or height is None or bit_depth != 8 or interlace != 0:
+        raise ValueError("unsupported PNG; expected 8-bit non-interlaced image")
+    channels_by_type = {0: 1, 2: 3, 4: 2, 6: 4}
+    if color_type not in channels_by_type:
+        raise ValueError("unsupported PNG color type; convert to RGB/RGBA first")
+    channels = channels_by_type[color_type]
+    row_bytes = width * channels
+    raw = zlib.decompress(bytes(idat))
+    rows: list[bytearray] = []
+    offset = 0
+    previous = bytearray(row_bytes)
+    for _ in range(height):
+        filter_type = raw[offset]
+        offset += 1
+        row = bytearray(raw[offset : offset + row_bytes])
+        offset += row_bytes
+        for index in range(row_bytes):
+            left = row[index - channels] if index >= channels else 0
+            up = previous[index]
+            up_left = previous[index - channels] if index >= channels else 0
+            if filter_type == 1:
+                row[index] = (row[index] + left) & 0xFF
+            elif filter_type == 2:
+                row[index] = (row[index] + up) & 0xFF
+            elif filter_type == 3:
+                row[index] = (row[index] + ((left + up) // 2)) & 0xFF
+            elif filter_type == 4:
+                row[index] = (row[index] + paeth_predictor(left, up, up_left)) & 0xFF
+            elif filter_type != 0:
+                raise ValueError(f"unsupported PNG filter {filter_type}")
+        rows.append(row)
+        previous = row
+    pixels: list[tuple[int, int, int, int]] = []
+    for row in rows:
+        for x in range(width):
+            base = x * channels
+            if color_type == 0:
+                gray = row[base]
+                pixels.append((gray, gray, gray, 255))
+            elif color_type == 2:
+                pixels.append((row[base], row[base + 1], row[base + 2], 255))
+            elif color_type == 4:
+                gray = row[base]
+                pixels.append((gray, gray, gray, row[base + 1]))
+            elif color_type == 6:
+                pixels.append((row[base], row[base + 1], row[base + 2], row[base + 3]))
+    return width, height, pixels
+
+
+def write_png_rgb(path: Path, width: int, height: int, pixels: list[tuple[int, int, int]]) -> None:
+    if len(pixels) != width * height:
+        raise ValueError("pixel payload has the wrong size")
+
+    def chunk(kind: bytes, payload: bytes) -> bytes:
+        checksum = zlib.crc32(kind)
+        checksum = zlib.crc32(payload, checksum) & 0xFFFFFFFF
+        return struct.pack(">I", len(payload)) + kind + payload + struct.pack(">I", checksum)
+
+    scanlines = bytearray()
+    for y in range(height):
+        scanlines.append(0)
+        for red, green, blue in pixels[y * width : (y + 1) * width]:
+            scanlines.extend((red, green, blue))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(
+        PNG_SIGNATURE
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(bytes(scanlines), level=6))
+        + chunk(b"IEND", b"")
+    )
+
+
+def load_image(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    try:
+        return read_png(path)
+    except Exception as direct_error:
+        sips = shutil.which("sips")
+        if not sips:
+            raise ValueError(f"could not decode {path.name} as PNG and sips is unavailable: {direct_error}") from direct_error
+        with tempfile.TemporaryDirectory() as tmpdir:
+            converted = Path(tmpdir) / "converted.png"
+            result = subprocess.run(
+                [sips, "-s", "format", "png", str(path), "--out", str(converted)],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode != 0:
+                raise ValueError(result.stderr.strip() or result.stdout.strip() or "sips conversion failed")
+            return read_png(converted)
+
+
+def composite_over_white(pixel: tuple[int, int, int, int]) -> tuple[int, int, int]:
+    red, green, blue, alpha = pixel
+    mix = alpha / 255.0
+    return (
+        round(red * mix + 255 * (1 - mix)),
+        round(green * mix + 255 * (1 - mix)),
+        round(blue * mix + 255 * (1 - mix)),
+    )
+
+
+def parse_components(spec: str) -> list[tuple[str, float, float, float, float]]:
+    zones: list[tuple[str, float, float, float, float]] = []
+    for part in spec.split(";"):
+        part = part.strip()
+        if not part:
+            continue
+        name, sep, coords = part.partition(":")
+        if not sep:
+            raise ValueError(f"malformed --components entry (expected name:x,y,w,h): {part!r}")
+        values = [float(v) for v in coords.split(",")]
+        if len(values) != 4:
+            raise ValueError(f"malformed --components entry (expected 4 normalized values): {part!r}")
+        x, y, w, h = values
+        zones.append((name.strip(), x, y, w, h))
+    if not zones:
+        raise ValueError("--components produced no zones")
+    return zones
+
+
+def build_zones(mode: str, components_spec: str | None) -> list[dict]:
+    if mode == "component-zones":
+        zones_spec = parse_components(components_spec) if components_spec else DEFAULT_COMPONENT_ZONES
+        return [
+            {"id": name, "region": {"x": x, "y": y, "width": w, "height": h, "units": "normalized"}}
+            for name, x, y, w, h in zones_spec
+        ]
+    grid = 3 if mode == "grid-3x3" else 4
+    step = 1.0 / grid
+    zones = []
+    for row in range(grid):
+        for col in range(grid):
+            zones.append(
+                {
+                    "id": f"zone-r{row}c{col}",
+                    "region": {
+                        "x": round(col * step, 4),
+                        "y": round(row * step, 4),
+                        "width": round(step, 4),
+                        "height": round(step, 4),
+                        "units": "normalized",
+                    },
+                }
+            )
+    return zones
+
+
+def make_detail_stub(zone: dict, crop_path: Path) -> dict:
+    return {
+        "id": zone["id"],
+        "kind": "",
+        "description": "",
+        "region": zone["region"],
+        "scale": "",
+        "affects": "",
+        "mapsTo": {"type": "", "ref": ""},
+        "evidenceRef": str(crop_path),
+        "confidence": 0.0,
+    }
+
+
+def build_inventory(
+    image: Path,
+    mode: str,
+    out_dir: Path,
+    target_min_details: int,
+    components_spec: str | None,
+) -> dict:
+    width, height, pixels = load_image(image)
+    zones = build_zones(mode, components_spec)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    details = []
+    for zone in zones:
+        region = zone["region"]
+        x0 = round(region["x"] * width)
+        y0 = round(region["y"] * height)
+        x1 = min(width, x0 + max(1, round(region["width"] * width)))
+        y1 = min(height, y0 + max(1, round(region["height"] * height)))
+        crop_w = max(1, x1 - x0)
+        crop_h = max(1, y1 - y0)
+        crop_pixels = []
+        for y in range(y0, y0 + crop_h):
+            source_y = min(height - 1, y)
+            for x in range(x0, x0 + crop_w):
+                source_x = min(width - 1, x)
+                crop_pixels.append(composite_over_white(pixels[source_y * width + source_x]))
+        crop_path = out_dir / f"{zone['id']}.png"
+        write_png_rgb(crop_path, crop_w, crop_h, crop_pixels)
+        details.append(make_detail_stub(zone, crop_path))
+    return {
+        "scanMethod": mode,
+        "targetMinDetails": target_min_details,
+        "details": details,
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", type=Path)
+    parser.add_argument(
+        "--mode",
+        choices=["grid-3x3", "grid-4x4", "component-zones"],
+        default="grid-3x3",
+        help="Zone layout to scan (default: grid-3x3)",
+    )
+    parser.add_argument(
+        "--out-dir",
+        type=Path,
+        help="Directory to write zone crop PNGs (default: <image-stem>-zones next to the image)",
+    )
+    parser.add_argument(
+        "--out",
+        type=Path,
+        help="Output detailInventory skeleton JSON path (default: <out-dir>/detail-inventory.json)",
+    )
+    parser.add_argument(
+        "--complexity",
+        choices=sorted(TARGET_MIN_DETAILS),
+        default="moderate",
+        help="Sets targetMinDetails from the complexity tier; overridden by --target-min-details",
+    )
+    parser.add_argument("--target-min-details", type=int, help="Override targetMinDetails directly")
+    parser.add_argument(
+        "--components",
+        help="component-zones only: 'name:x,y,w,h;name2:x,y,w,h' normalized regions "
+        "(default: upper/middle/lower thirds)",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing output JSON")
+    args = parser.parse_args(argv)
+
+    image = args.image.expanduser().resolve()
+    if not image.exists():
+        parser.error(f"{image} does not exist")
+    out_dir = (args.out_dir or image.with_name(f"{image.stem}-zones")).expanduser().resolve()
+    out_path = (args.out or out_dir / "detail-inventory.json").expanduser().resolve()
+    if out_path.exists() and not args.force:
+        parser.error(f"{out_path} already exists; use --force to overwrite")
+    target_min_details = args.target_min_details or TARGET_MIN_DETAILS[args.complexity]
+
+    try:
+        inventory = build_inventory(image, args.mode, out_dir, target_min_details, args.components)
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    payload = {
+        "sourceImage": str(image),
+        "zonesDir": str(out_dir),
+        "detailInventory": inventory,
+        "authoringInstruction": (
+            "Open each zone crop under zonesDir and replace every detail stub's kind, description, "
+            "scale, affects, mapsTo, and confidence with what is actually observed. Add more detail "
+            "entries per zone if a single zone contains multiple distinct marks; do not leave stubs "
+            "unfilled or unlinked (mapsTo must reference a real component.localFeatures or "
+            "material.localOverrides entry)."
+        ),
+    }
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(out_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage1_intake/delight_albedo.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+"""Approximate a neutral (de-lit) albedo from a single reference photo.
+
+This is an approximation, not true inverse rendering. A single photo bakes
+together albedo, direct light, ambient occlusion, and specular response
+into one signal, and there is no way to fully separate those from pixels
+alone. This script applies a per-pixel normalization against a low-frequency
+luminance estimate (a box-blur "lighting" proxy): pixels darker than their
+local neighborhood get brightened, pixels brighter than their neighborhood
+get darkened, pulling the image toward flat, even lighting. Strong specular
+hotspots, deep occlusion shadows, and directional cues that vary faster than
+the blur radius will not be fully removed. Always review the output next to
+the source image before treating it as a projection albedo.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+from pathlib import Path
+from typing import Any
+
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def clamp(value: float, minimum: float, maximum: float) -> float:
+    return max(minimum, min(maximum, value))
+
+
+def clamp01(value: float) -> float:
+    return clamp(value, 0.0, 1.0)
+
+
+def srgb_luma(rgb: tuple[int, int, int]) -> float:
+    red, green, blue = rgb
+    return (0.2126 * red + 0.7152 * green + 0.0722 * blue) / 255.0
+
+
+def percentile(values: list[float], fraction: float, fallback: float = 0.0) -> float:
+    if not values:
+        return fallback
+    ordered = sorted(values)
+    index = int(round(clamp01(fraction) * (len(ordered) - 1)))
+    return ordered[index]
+
+
+def paeth_predictor(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa = abs(p - a)
+    pb = abs(p - b)
+    pc = abs(p - c)
+    if pa <= pb and pa <= pc:
+        return a
+    if pb <= pc:
+        return b
+    return c
+
+
+def read_png(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise ValueError("not a PNG file")
+    cursor = len(PNG_SIGNATURE)
+    width = height = bit_depth = color_type = None
+    idat = bytearray()
+    interlace = 0
+    while cursor + 8 <= len(data):
+        length = struct.unpack(">I", data[cursor : cursor + 4])[0]
+        chunk_type = data[cursor + 4 : cursor + 8]
+        chunk_data = data[cursor + 8 : cursor + 8 + length]
+        cursor += 12 + length
+        if chunk_type == b"IHDR":
+            width, height, bit_depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", chunk_data)
+        elif chunk_type == b"IDAT":
+            idat.extend(chunk_data)
+        elif chunk_type == b"IEND":
+            break
+    if width is None or height is None or bit_depth != 8 or interlace != 0:
+        raise ValueError("unsupported PNG; expected 8-bit non-interlaced image")
+    channels_by_type = {0: 1, 2: 3, 4: 2, 6: 4}
+    if color_type not in channels_by_type:
+        raise ValueError("unsupported PNG color type; convert to RGB/RGBA first")
+    channels = channels_by_type[color_type]
+    row_bytes = width * channels
+    raw = zlib.decompress(bytes(idat))
+    rows: list[bytearray] = []
+    offset = 0
+    previous = bytearray(row_bytes)
+    for _ in range(height):
+        filter_type = raw[offset]
+        offset += 1
+        row = bytearray(raw[offset : offset + row_bytes])
+        offset += row_bytes
+        for index in range(row_bytes):
+            left = row[index - channels] if index >= channels else 0
+            up = previous[index]
+            up_left = previous[index - channels] if index >= channels else 0
+            if filter_type == 1:
+                row[index] = (row[index] + left) & 0xFF
+            elif filter_type == 2:
+                row[index] = (row[index] + up) & 0xFF
+            elif filter_type == 3:
+                row[index] = (row[index] + ((left + up) // 2)) & 0xFF
+            elif filter_type == 4:
+                predictor = paeth_predictor(left, up, up_left)
+                row[index] = (row[index] + predictor) & 0xFF
+            elif filter_type != 0:
+                raise ValueError(f"unsupported PNG filter {filter_type}")
+        rows.append(row)
+        previous = row
+    pixels: list[tuple[int, int, int, int]] = []
+    for row in rows:
+        for x in range(width):
+            base = x * channels
+            if color_type == 0:
+                gray = row[base]
+                pixels.append((gray, gray, gray, 255))
+            elif color_type == 2:
+                pixels.append((row[base], row[base + 1], row[base + 2], 255))
+            elif color_type == 4:
+                gray = row[base]
+                pixels.append((gray, gray, gray, row[base + 1]))
+            elif color_type == 6:
+                pixels.append((row[base], row[base + 1], row[base + 2], row[base + 3]))
+    return width, height, pixels
+
+
+def write_png_rgba(path: Path, width: int, height: int, rgba: bytes) -> None:
+    if len(rgba) != width * height * 4:
+        raise ValueError("RGBA payload has the wrong size")
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    def chunk(kind: bytes, payload: bytes) -> bytes:
+        checksum = zlib.crc32(kind)
+        checksum = zlib.crc32(payload, checksum) & 0xFFFFFFFF
+        return struct.pack(">I", len(payload)) + kind + payload + struct.pack(">I", checksum)
+
+    scanlines = bytearray()
+    stride = width * 4
+    for y in range(height):
+        scanlines.append(0)
+        scanlines.extend(rgba[y * stride : (y + 1) * stride])
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)
+    path.write_bytes(
+        PNG_SIGNATURE
+        + chunk(b"IHDR", ihdr)
+        + chunk(b"IDAT", zlib.compress(bytes(scanlines), level=6))
+        + chunk(b"IEND", b"")
+    )
+
+
+def load_image(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]], list[str]]:
+    warnings: list[str] = []
+    try:
+        return (*read_png(path), warnings)
+    except Exception as direct_error:
+        sips = shutil.which("sips")
+        if not sips:
+            raise ValueError(
+                f"could not decode {path.name} as PNG and macOS sips is unavailable: {direct_error}"
+            ) from direct_error
+        with tempfile.TemporaryDirectory() as tmpdir:
+            converted = Path(tmpdir) / "converted.png"
+            command = [sips, "-s", "format", "png", str(path), "--out", str(converted)]
+            result = subprocess.run(command, capture_output=True, text=True, check=False)
+            if result.returncode != 0:
+                raise ValueError(result.stderr.strip() or result.stdout.strip() or "sips conversion failed")
+            warnings.append("source image was converted to PNG with macOS sips before pixel extraction")
+            width, height, pixels = read_png(converted)
+            return width, height, pixels, warnings
+
+
+def blur_scalar(values: list[float], width: int, height: int, radius: int) -> list[float]:
+    if radius <= 0:
+        return values[:]
+    horizontal = [0.0] * (width * height)
+    for y in range(height):
+        row_offset = y * width
+        running = 0.0
+        count = 0
+        for x in range(-radius, width + radius):
+            if 0 <= x < width:
+                running += values[row_offset + x]
+                count += 1
+            remove = x - radius * 2 - 1
+            if 0 <= remove < width:
+                running -= values[row_offset + remove]
+                count -= 1
+            write_x = x - radius
+            if 0 <= write_x < width:
+                horizontal[row_offset + write_x] = running / max(1, count)
+    vertical = [0.0] * (width * height)
+    for x in range(width):
+        running = 0.0
+        count = 0
+        for y in range(-radius, height + radius):
+            if 0 <= y < height:
+                running += horizontal[y * width + x]
+                count += 1
+            remove = y - radius * 2 - 1
+            if 0 <= remove < height:
+                running -= horizontal[remove * width + x]
+                count -= 1
+            write_y = y - radius
+            if 0 <= write_y < height:
+                vertical[write_y * width + x] = running / max(1, count)
+    return vertical
+
+
+def delight(
+    width: int,
+    height: int,
+    pixels: list[tuple[int, int, int, int]],
+    strength: float,
+    blur_radius: int,
+) -> tuple[bytes, dict[str, Any]]:
+    lumas = [srgb_luma(pixel[:3]) for pixel in pixels]
+    target = percentile(lumas, 0.5, 0.5)
+    low_frequency = blur_scalar(lumas, width, height, blur_radius)
+    out = bytearray()
+    corrections: list[float] = []
+    for (red, green, blue, alpha), low in zip(pixels, low_frequency):
+        shade = clamp(low, 0.05, 1.0)
+        raw_scale = target / shade
+        # strength blends between no correction (1.0) and the full normalization
+        scale = 1.0 + (raw_scale - 1.0) * clamp01(strength)
+        scale = clamp(scale, 0.35, 2.6)
+        corrections.append(scale)
+        out.extend(
+            (
+                round(clamp(red * scale, 0, 255)),
+                round(clamp(green * scale, 0, 255)),
+                round(clamp(blue * scale, 0, 255)),
+                alpha,
+            )
+        )
+    luma_before_range = percentile(lumas, 0.95, 0.8) - percentile(lumas, 0.05, 0.2)
+    stats = {
+        "targetLuma": round(target, 4),
+        "blurRadius": blur_radius,
+        "lumaRangeBefore": round(luma_before_range, 4),
+        "meanCorrectionScale": round(sum(corrections) / max(1, len(corrections)), 4),
+        "maxCorrectionScale": round(max(corrections, default=1.0), 4),
+        "minCorrectionScale": round(min(corrections, default=1.0), 4),
+    }
+    return bytes(out), stats
+
+
+def estimate_confidence(stats: dict[str, Any], strength: float, warnings: list[str]) -> tuple[float, list[str]]:
+    notes: list[str] = []
+    luma_range = float(stats.get("lumaRangeBefore", 0.4))
+    # a very large baked lighting range means more got corrected but also more
+    # residual error is likely, since the box blur is only a crude lighting proxy
+    range_penalty = clamp01((luma_range - 0.35) * 0.6)
+    strength_bonus = clamp01(strength) * 0.15
+    confidence = clamp01(0.55 - range_penalty * 0.25 + strength_bonus - min(0.1, len(warnings) * 0.04))
+    confidence = min(0.72, confidence)  # single-image de-lighting is always capped
+    notes.append("single-image de-lighting cannot separate true albedo from baked light/AO/specular; confidence is capped")
+    if luma_range > 0.5:
+        notes.append("wide baked lighting range detected; expect visible residual shading after correction")
+    return round(confidence, 3), notes
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("image", type=Path)
+    parser.add_argument("--out", type=Path, required=True, help="Output de-lit PNG path")
+    parser.add_argument("--report", type=Path, help="Write the JSON report to this path (also printed to stdout)")
+    parser.add_argument(
+        "--strength",
+        type=float,
+        default=0.6,
+        help="0.0 = no correction (passthrough), 1.0 = full normalization against the blurred luminance proxy (default 0.6)",
+    )
+    parser.add_argument(
+        "--blur-radius",
+        type=int,
+        default=0,
+        help="Box-blur radius in pixels for the low-frequency lighting estimate; 0 = auto from image size",
+    )
+    args = parser.parse_args(argv)
+
+    image = args.image.expanduser().resolve()
+    if not image.exists():
+        parser.error(f"{image} does not exist")
+    out_path = args.out.expanduser().resolve()
+
+    try:
+        width, height, pixels, load_warnings = load_image(image)
+        blur_radius = args.blur_radius if args.blur_radius > 0 else max(6, min(48, min(width, height) // 20))
+        strength = clamp01(args.strength)
+        delit_rgba, stats = delight(width, height, pixels, strength, blur_radius)
+        write_png_rgba(out_path, width, height, delit_rgba)
+
+        confidence, confidence_notes = estimate_confidence(stats, strength, load_warnings)
+        report = {
+            "delightReference": {
+                "version": "1.0",
+                "sourceImage": str(image),
+                "outputImage": str(out_path),
+                "method": (
+                    "per-pixel normalization against a box-blurred luminance proxy; an approximation of "
+                    "de-lighting, not physically based inverse rendering or true light/albedo separation"
+                ),
+                "strength": strength,
+                "confidence": confidence,
+                "stats": stats,
+                "limitations": [
+                    "this is an approximation, not true inverse rendering; it cannot recover ground-truth albedo",
+                    "sharp specular highlights and hard shadow edges narrower than the blur radius will remain baked in",
+                    "deep occlusion shadows (creases, undercuts) are only partially lifted",
+                    "must be reviewed visually next to the source image before use as a projection albedo",
+                ]
+                + confidence_notes
+                + load_warnings,
+                "note": (
+                    "If shadows or highlights are still visible in the output, try a larger --strength or a "
+                    "smaller --blur-radius so the correction responds to tighter lighting gradients, then "
+                    "re-review; this script does not know when the correction is visually sufficient."
+                ),
+            }
+        }
+        text = json.dumps(report, indent=2, ensure_ascii=False)
+        if args.report:
+            report_path = args.report.expanduser().resolve()
+            report_path.parent.mkdir(parents=True, exist_ok=True)
+            report_path.write_text(text + "\n", encoding="utf-8")
+        print(text)
+        return 0
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage1_intake/extract_landmarks.py

@@ -0,0 +1,447 @@
+#!/usr/bin/env python3
+"""Overlay a labelled proportion/landmark guide grid on a reference image and scaffold anatomy.
+
+Draws head-unit ticks, a rule-of-thirds grid, a center symmetry axis, default face-line
+guides (hairline/eye/nose/mouth), and default shoulder/hip lines onto a copy of the
+reference (see docs/UPGRADE_PLAN.md 5.3-5.4 and grimoire/character/reconstruction.md),
+then emits an anatomy skeleton JSON for the agent to fill from what the overlay reveals.
+The drawn lines are generic starting positions, not measurements - the agent's vision
+supplies the actual proportions, pose, and landmark coordinates.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+from pathlib import Path
+
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+MARGIN = 44
+
+COLOR_THIRDS = (150, 150, 150)
+COLOR_HEAD_UNIT = (60, 120, 220)
+COLOR_HAIRLINE = (210, 80, 210)
+COLOR_EYELINE = (230, 60, 60)
+COLOR_NOSEBASE = (240, 150, 30)
+COLOR_MOUTHLINE = (40, 170, 90)
+COLOR_SHOULDER = (30, 140, 200)
+COLOR_HIP = (170, 110, 40)
+COLOR_CENTER = (20, 20, 20)
+
+FONT_3X5 = {
+    "0": ["###", "#.#", "#.#", "#.#", "###"],
+    "1": [".#.", "##.", ".#.", ".#.", "###"],
+    "2": ["###", "..#", "###", "#..", "###"],
+    "3": ["###", "..#", "###", "..#", "###"],
+    "4": ["#.#", "#.#", "###", "..#", "..#"],
+    "5": ["###", "#..", "###", "..#", "###"],
+    "6": ["###", "#..", "###", "#.#", "###"],
+    "7": ["###", "..#", "..#", "..#", "..#"],
+    "8": ["###", "#.#", "###", "#.#", "###"],
+    "9": ["###", "#.#", "###", "..#", "###"],
+    "H": ["#.#", "#.#", "###", "#.#", "#.#"],
+    "E": ["###", "#..", "##.", "#..", "###"],
+    "N": ["#.#", "##.", "#.#", ".##", "#.#"],
+    "M": ["#.#", "###", "###", "#.#", "#.#"],
+    "S": [".##", "#..", ".#.", "..#", "##."],
+    "P": ["##.", "#.#", "##.", "#..", "#.."],
+    "C": [".##", "#..", "#..", "#..", ".##"],
+}
+
+
+def paeth_predictor(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa = abs(p - a)
+    pb = abs(p - b)
+    pc = abs(p - c)
+    if pa <= pb and pa <= pc:
+        return a
+    if pb <= pc:
+        return b
+    return c
+
+
+def read_png(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise ValueError("not a PNG file")
+    cursor = len(PNG_SIGNATURE)
+    width = height = bit_depth = color_type = interlace = None
+    idat = bytearray()
+    while cursor + 8 <= len(data):
+        length = struct.unpack(">I", data[cursor : cursor + 4])[0]
+        chunk_type = data[cursor + 4 : cursor + 8]
+        chunk_data = data[cursor + 8 : cursor + 8 + length]
+        cursor += 12 + length
+        if chunk_type == b"IHDR":
+            width, height, bit_depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", chunk_data)
+        elif chunk_type == b"IDAT":
+            idat.extend(chunk_data)
+        elif chunk_type == b"IEND":
+            break
+    if width is None or height is None or bit_depth != 8 or interlace != 0:
+        raise ValueError("unsupported PNG; expected 8-bit non-interlaced image")
+    channels_by_type = {0: 1, 2: 3, 4: 2, 6: 4}
+    if color_type not in channels_by_type:
+        raise ValueError("unsupported PNG color type; convert to RGB/RGBA first")
+    channels = channels_by_type[color_type]
+    row_bytes = width * channels
+    raw = zlib.decompress(bytes(idat))
+    rows: list[bytearray] = []
+    offset = 0
+    previous = bytearray(row_bytes)
+    for _ in range(height):
+        filter_type = raw[offset]
+        offset += 1
+        row = bytearray(raw[offset : offset + row_bytes])
+        offset += row_bytes
+        for index in range(row_bytes):
+            left = row[index - channels] if index >= channels else 0
+            up = previous[index]
+            up_left = previous[index - channels] if index >= channels else 0
+            if filter_type == 1:
+                row[index] = (row[index] + left) & 0xFF
+            elif filter_type == 2:
+                row[index] = (row[index] + up) & 0xFF
+            elif filter_type == 3:
+                row[index] = (row[index] + ((left + up) // 2)) & 0xFF
+            elif filter_type == 4:
+                row[index] = (row[index] + paeth_predictor(left, up, up_left)) & 0xFF
+            elif filter_type != 0:
+                raise ValueError(f"unsupported PNG filter {filter_type}")
+        rows.append(row)
+        previous = row
+    pixels: list[tuple[int, int, int, int]] = []
+    for row in rows:
+        for x in range(width):
+            base = x * channels
+            if color_type == 0:
+                gray = row[base]
+                pixels.append((gray, gray, gray, 255))
+            elif color_type == 2:
+                pixels.append((row[base], row[base + 1], row[base + 2], 255))
+            elif color_type == 4:
+                gray = row[base]
+                pixels.append((gray, gray, gray, row[base + 1]))
+            elif color_type == 6:
+                pixels.append((row[base], row[base + 1], row[base + 2], row[base + 3]))
+    return width, height, pixels
+
+
+def write_png_rgb(path: Path, width: int, height: int, pixels: list[tuple[int, int, int]]) -> None:
+    if len(pixels) != width * height:
+        raise ValueError("pixel payload has the wrong size")
+
+    def chunk(kind: bytes, payload: bytes) -> bytes:
+        checksum = zlib.crc32(kind)
+        checksum = zlib.crc32(payload, checksum) & 0xFFFFFFFF
+        return struct.pack(">I", len(payload)) + kind + payload + struct.pack(">I", checksum)
+
+    scanlines = bytearray()
+    for y in range(height):
+        scanlines.append(0)
+        for red, green, blue in pixels[y * width : (y + 1) * width]:
+            scanlines.extend((red, green, blue))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(
+        PNG_SIGNATURE
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(bytes(scanlines), level=6))
+        + chunk(b"IEND", b"")
+    )
+
+
+def load_image(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    try:
+        return read_png(path)
+    except Exception as direct_error:
+        sips = shutil.which("sips")
+        if not sips:
+            raise ValueError(f"could not decode {path.name} as PNG and sips is unavailable: {direct_error}") from direct_error
+        with tempfile.TemporaryDirectory() as tmpdir:
+            converted = Path(tmpdir) / "converted.png"
+            result = subprocess.run(
+                [sips, "-s", "format", "png", str(path), "--out", str(converted)],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode != 0:
+                raise ValueError(result.stderr.strip() or result.stdout.strip() or "sips conversion failed")
+            return read_png(converted)
+
+
+def composite_over_white(pixel: tuple[int, int, int, int]) -> tuple[int, int, int]:
+    red, green, blue, alpha = pixel
+    mix = alpha / 255.0
+    return (
+        round(red * mix + 255 * (1 - mix)),
+        round(green * mix + 255 * (1 - mix)),
+        round(blue * mix + 255 * (1 - mix)),
+    )
+
+
+def set_pixel(canvas: list[tuple[int, int, int]], width: int, height: int, x: int, y: int, color: tuple[int, int, int]) -> None:
+    if 0 <= x < width and 0 <= y < height:
+        canvas[y * width + x] = color
+
+
+def draw_glyph(
+    canvas: list[tuple[int, int, int]],
+    width: int,
+    height: int,
+    x0: int,
+    y0: int,
+    glyph: list[str],
+    color: tuple[int, int, int],
+    scale: int,
+) -> None:
+    for row_index, row in enumerate(glyph):
+        for col_index, mark in enumerate(row):
+            if mark != "#":
+                continue
+            for dy in range(scale):
+                for dx in range(scale):
+                    set_pixel(canvas, width, height, x0 + col_index * scale + dx, y0 + row_index * scale + dy, color)
+
+
+def draw_text(
+    canvas: list[tuple[int, int, int]],
+    width: int,
+    height: int,
+    x0: int,
+    y0: int,
+    text: str,
+    color: tuple[int, int, int],
+    scale: int = 2,
+) -> None:
+    cursor_x = x0
+    for character in text:
+        glyph = FONT_3X5.get(character)
+        if glyph:
+            draw_glyph(canvas, width, height, cursor_x, y0, glyph, color, scale)
+        cursor_x += 3 * scale + scale
+
+
+def draw_hline(
+    canvas: list[tuple[int, int, int]],
+    width: int,
+    height: int,
+    y: int,
+    x_start: int,
+    x_end: int,
+    color: tuple[int, int, int],
+    dash: int = 0,
+) -> None:
+    if not (0 <= y < height):
+        return
+    row = y * width
+    for x in range(max(0, x_start), min(width, x_end)):
+        if dash and (x // dash) % 2 == 1:
+            continue
+        canvas[row + x] = color
+
+
+def draw_vline(
+    canvas: list[tuple[int, int, int]],
+    width: int,
+    height: int,
+    x: int,
+    y_start: int,
+    y_end: int,
+    color: tuple[int, int, int],
+    dash: int = 0,
+) -> None:
+    if not (0 <= x < width):
+        return
+    for y in range(max(0, y_start), min(height, y_end)):
+        if dash and (y // dash) % 2 == 1:
+            continue
+        canvas[y * width + x] = color
+
+
+def build_overlay(image: Path, overlay_path: Path, heads: int) -> dict:
+    width, height, pixels = load_image(image)
+    base = [composite_over_white(pixel) for pixel in pixels]
+    canvas_w = width + MARGIN
+    canvas_h = height
+    canvas: list[tuple[int, int, int]] = [(255, 255, 255)] * (canvas_w * canvas_h)
+    for y in range(height):
+        source_row = y * width
+        dest_row = y * canvas_w + MARGIN
+        canvas[dest_row : dest_row + width] = base[source_row : source_row + width]
+
+    for fraction in (1.0 / 3, 2.0 / 3):
+        y = round(fraction * height)
+        draw_hline(canvas, canvas_w, canvas_h, y, MARGIN, canvas_w, COLOR_THIRDS, dash=6)
+    for fraction in (1.0 / 3, 2.0 / 3):
+        x = MARGIN + round(fraction * width)
+        draw_vline(canvas, canvas_w, canvas_h, x, 0, height, COLOR_THIRDS, dash=6)
+
+    center_x = MARGIN + width // 2
+    draw_vline(canvas, canvas_w, canvas_h, center_x, 0, height, COLOR_CENTER)
+    draw_text(canvas, canvas_w, canvas_h, 4, max(0, min(height - 6, height // 2 - 3)), "C", COLOR_CENTER)
+
+    step = height / heads
+    for i in range(1, heads):
+        y = round(i * step)
+        draw_hline(canvas, canvas_w, canvas_h, y, MARGIN, canvas_w, COLOR_HEAD_UNIT, dash=10)
+        draw_text(canvas, canvas_w, canvas_h, 4, max(0, y - 3), str(i), COLOR_HEAD_UNIT)
+
+    band = step
+    face_lines = [
+        ("H", COLOR_HAIRLINE, 0.05),
+        ("E", COLOR_EYELINE, 0.50),
+        ("N", COLOR_NOSEBASE, 0.65),
+        ("M", COLOR_MOUTHLINE, 0.80),
+    ]
+    for label, color, fraction in face_lines:
+        y = round(fraction * band)
+        draw_hline(canvas, canvas_w, canvas_h, y, MARGIN, MARGIN + width, color, dash=4)
+        draw_text(canvas, canvas_w, canvas_h, 4, max(0, y - 3), label, color)
+
+    shoulder_y = round(0.28 * height)
+    hip_y = round(0.55 * height)
+    draw_hline(canvas, canvas_w, canvas_h, shoulder_y, MARGIN, canvas_w, COLOR_SHOULDER, dash=14)
+    draw_text(canvas, canvas_w, canvas_h, 4, max(0, shoulder_y - 3), "S", COLOR_SHOULDER)
+    draw_hline(canvas, canvas_w, canvas_h, hip_y, MARGIN, canvas_w, COLOR_HIP, dash=14)
+    draw_text(canvas, canvas_w, canvas_h, 4, max(0, hip_y - 3), "P", COLOR_HIP)
+
+    write_png_rgb(overlay_path, canvas_w, canvas_h, canvas)
+    return {
+        "overlayImage": str(overlay_path),
+        "imageWidth": width,
+        "imageHeight": height,
+        "headUnitCount": heads,
+        "legend": {
+            "C": "center symmetry axis",
+            "1..N": "head-unit horizontal ticks (blue, dashed)",
+            "H": "hairline guide (default fraction of the first head-unit band)",
+            "E": "eye line guide",
+            "N": "nose base guide",
+            "M": "mouth line guide",
+            "S": "shoulder line guide (default fraction, adjust to observed pose)",
+            "P": "hip line guide (default fraction, adjust to observed pose)",
+            "grayDashed": "rule-of-thirds compositional grid",
+        },
+        "note": "Guide lines are generic starting positions, not measurements. Read the overlay "
+        "against the actual reference and fill anatomy with observed normalized values.",
+    }
+
+
+def make_anatomy_skeleton(style_heads: float) -> dict:
+    joint_names = [
+        "neck",
+        "leftShoulder",
+        "rightShoulder",
+        "leftElbow",
+        "rightElbow",
+        "leftWrist",
+        "rightWrist",
+        "leftHip",
+        "rightHip",
+        "leftKnee",
+        "rightKnee",
+        "leftAnkle",
+        "rightAnkle",
+    ]
+    return {
+        "styleHeads": style_heads,
+        "proportions": {
+            "headUnit": None,
+            "torso": None,
+            "legs": None,
+            "shoulderWidth": None,
+            "hipWidth": None,
+        },
+        "pose": {
+            "type": "",
+            "jointAngles": {name: [0, 0, 0] for name in joint_names},
+        },
+        "faceLandmarks": {
+            "hairline": None,
+            "eyeLine": None,
+            "eyeSpacing": None,
+            "noseBase": None,
+            "mouthLine": None,
+            "earTop": None,
+            "earBottom": None,
+        },
+        "features": [],
+        "confidence": 0.0,
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", type=Path)
+    parser.add_argument(
+        "--out",
+        type=Path,
+        help="Output anatomy skeleton JSON path (default: <image-stem>-anatomy.json next to the image)",
+    )
+    parser.add_argument(
+        "--overlay",
+        type=Path,
+        help="Output overlay PNG path (default: <image-stem>-landmarks.png next to the image)",
+    )
+    parser.add_argument(
+        "--style-heads",
+        type=float,
+        default=6.0,
+        help="Initial head-unit estimate driving the overlay grid "
+        "(realistic ~7.5, stylized ~5-6, chibi/figurine ~2-3); refine after visual inspection",
+    )
+    parser.add_argument(
+        "--heads",
+        type=int,
+        help="Override number of head-unit tick lines drawn (default: round(--style-heads))",
+    )
+    parser.add_argument("--force", action="store_true", help="Overwrite existing outputs")
+    args = parser.parse_args(argv)
+
+    image = args.image.expanduser().resolve()
+    if not image.exists():
+        parser.error(f"{image} does not exist")
+    overlay_path = (args.overlay or image.with_name(f"{image.stem}-landmarks.png")).expanduser().resolve()
+    out_path = (args.out or image.with_name(f"{image.stem}-anatomy.json")).expanduser().resolve()
+    if not args.force:
+        for existing in (overlay_path, out_path):
+            if existing.exists():
+                parser.error(f"{existing} already exists; use --force to overwrite")
+    heads = args.heads or max(1, round(args.style_heads))
+
+    try:
+        overlay_meta = build_overlay(image, overlay_path, heads)
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    payload = {
+        "sourceImage": str(image),
+        "overlayImage": str(overlay_path),
+        "overlayLegend": overlay_meta["legend"],
+        "anatomy": make_anatomy_skeleton(args.style_heads),
+        "authoringInstruction": (
+            "Open overlayImage and read the reference against its head-unit ticks, thirds grid, "
+            "face-line guides, shoulder/hip lines, and center axis. Replace every null/placeholder "
+            "value in anatomy with normalized coordinates or joint angles actually observed; the "
+            "drawn guide lines are generic starting positions, not measurements."
+        ),
+    }
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(out_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage1_intake/extract_pbr_evidence.py

@@ -0,0 +1,834 @@
+#!/usr/bin/env python3
+"""Extract reference-derived PBR map evidence from an object image.
+
+This is not photogrammetry and it does not claim exact inverse rendering from a
+single image. It extracts pixel evidence that is useful for procedural PBR:
+albedo palette, de-lit albedo, roughness estimate, height, normal, and AO maps.
+If the estimated confidence is below the requested target, the script exits
+non-zero and refuses to patch the sculpt spec unless --allow-low-confidence is
+passed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def slugify(value: str) -> str:
+    parts: list[str] = []
+    last_dash = False
+    for char in value.strip().lower():
+        if char.isalnum():
+            parts.append(char)
+            last_dash = False
+        elif not last_dash:
+            parts.append("-")
+            last_dash = True
+    return "".join(parts).strip("-") or "material"
+
+
+def clamp(value: float, minimum: float, maximum: float) -> float:
+    return max(minimum, min(maximum, value))
+
+
+def clamp01(value: float) -> float:
+    return clamp(value, 0.0, 1.0)
+
+
+def srgb_luma(rgb: tuple[int, int, int]) -> float:
+    red, green, blue = rgb
+    return (0.2126 * red + 0.7152 * green + 0.0722 * blue) / 255.0
+
+
+def color_distance(a: tuple[int, int, int], b: tuple[int, int, int]) -> float:
+    return math.sqrt(sum((a[index] - b[index]) ** 2 for index in range(3)))
+
+
+def saturation(rgb: tuple[int, int, int]) -> float:
+    high = max(rgb)
+    low = min(rgb)
+    return 0.0 if high <= 0 else (high - low) / high
+
+
+def percentile(values: list[float], fraction: float, fallback: float = 0.0) -> float:
+    if not values:
+        return fallback
+    ordered = sorted(values)
+    index = int(round(clamp01(fraction) * (len(ordered) - 1)))
+    return ordered[index]
+
+
+def median_color(samples: list[tuple[int, int, int]]) -> tuple[int, int, int]:
+    if not samples:
+        return (255, 255, 255)
+    return tuple(
+        int(percentile([float(sample[channel]) for sample in samples], 0.5))
+        for channel in range(3)
+    )  # type: ignore[return-value]
+
+
+def read_png(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise ValueError("not a PNG file")
+    cursor = len(PNG_SIGNATURE)
+    width = height = bit_depth = color_type = None
+    idat = bytearray()
+    interlace = 0
+    while cursor + 8 <= len(data):
+        length = struct.unpack(">I", data[cursor : cursor + 4])[0]
+        chunk_type = data[cursor + 4 : cursor + 8]
+        chunk_data = data[cursor + 8 : cursor + 8 + length]
+        cursor += 12 + length
+        if chunk_type == b"IHDR":
+            width, height, bit_depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", chunk_data)
+        elif chunk_type == b"IDAT":
+            idat.extend(chunk_data)
+        elif chunk_type == b"IEND":
+            break
+    if width is None or height is None or bit_depth != 8 or interlace != 0:
+        raise ValueError("unsupported PNG; expected 8-bit non-interlaced image")
+    channels_by_type = {0: 1, 2: 3, 4: 2, 6: 4}
+    if color_type not in channels_by_type:
+        raise ValueError("unsupported PNG color type; convert to RGB/RGBA first")
+    channels = channels_by_type[color_type]
+    row_bytes = width * channels
+    raw = zlib.decompress(bytes(idat))
+    rows: list[bytearray] = []
+    offset = 0
+    previous = bytearray(row_bytes)
+    for _ in range(height):
+        filter_type = raw[offset]
+        offset += 1
+        row = bytearray(raw[offset : offset + row_bytes])
+        offset += row_bytes
+        for index in range(row_bytes):
+            left = row[index - channels] if index >= channels else 0
+            up = previous[index]
+            up_left = previous[index - channels] if index >= channels else 0
+            if filter_type == 1:
+                row[index] = (row[index] + left) & 0xFF
+            elif filter_type == 2:
+                row[index] = (row[index] + up) & 0xFF
+            elif filter_type == 3:
+                row[index] = (row[index] + ((left + up) // 2)) & 0xFF
+            elif filter_type == 4:
+                predictor = paeth_predictor(left, up, up_left)
+                row[index] = (row[index] + predictor) & 0xFF
+            elif filter_type != 0:
+                raise ValueError(f"unsupported PNG filter {filter_type}")
+        rows.append(row)
+        previous = row
+    pixels: list[tuple[int, int, int, int]] = []
+    for row in rows:
+        for x in range(width):
+            base = x * channels
+            if color_type == 0:
+                gray = row[base]
+                pixels.append((gray, gray, gray, 255))
+            elif color_type == 2:
+                pixels.append((row[base], row[base + 1], row[base + 2], 255))
+            elif color_type == 4:
+                gray = row[base]
+                pixels.append((gray, gray, gray, row[base + 1]))
+            elif color_type == 6:
+                pixels.append((row[base], row[base + 1], row[base + 2], row[base + 3]))
+    return width, height, pixels
+
+
+def paeth_predictor(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa = abs(p - a)
+    pb = abs(p - b)
+    pc = abs(p - c)
+    if pa <= pb and pa <= pc:
+        return a
+    if pb <= pc:
+        return b
+    return c
+
+
+def write_png_rgb(path: Path, width: int, height: int, rgb: bytes) -> None:
+    if len(rgb) != width * height * 3:
+        raise ValueError("RGB payload has the wrong size")
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    def chunk(kind: bytes, payload: bytes) -> bytes:
+        checksum = zlib.crc32(kind)
+        checksum = zlib.crc32(payload, checksum) & 0xFFFFFFFF
+        return struct.pack(">I", len(payload)) + kind + payload + struct.pack(">I", checksum)
+
+    scanlines = bytearray()
+    stride = width * 3
+    for y in range(height):
+        scanlines.append(0)
+        scanlines.extend(rgb[y * stride : (y + 1) * stride])
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    path.write_bytes(
+        PNG_SIGNATURE
+        + chunk(b"IHDR", ihdr)
+        + chunk(b"IDAT", zlib.compress(bytes(scanlines), level=6))
+        + chunk(b"IEND", b"")
+    )
+
+
+def load_image(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]], list[str]]:
+    warnings: list[str] = []
+    try:
+        return (*read_png(path), warnings)
+    except Exception as direct_error:
+        sips = shutil.which("sips")
+        if not sips:
+            raise ValueError(
+                f"could not decode {path.name} as PNG and macOS sips is unavailable: {direct_error}"
+            ) from direct_error
+        with tempfile.TemporaryDirectory() as tmpdir:
+            converted = Path(tmpdir) / "converted.png"
+            command = [sips, "-s", "format", "png", str(path), "--out", str(converted)]
+            result = subprocess.run(command, capture_output=True, text=True, check=False)
+            if result.returncode != 0:
+                raise ValueError(result.stderr.strip() or result.stdout.strip() or "sips conversion failed")
+            warnings.append("source image was converted to PNG with macOS sips before pixel extraction")
+            width, height, pixels = read_png(converted)
+            return width, height, pixels, warnings
+
+
+def sample_corner_background(
+    width: int,
+    height: int,
+    pixels: list[tuple[int, int, int, int]],
+) -> tuple[tuple[int, int, int], float]:
+    radius = max(3, min(width, height) // 40)
+    samples: list[tuple[int, int, int]] = []
+    corner_ranges = [
+        (0, radius, 0, radius),
+        (width - radius, width, 0, radius),
+        (0, radius, height - radius, height),
+        (width - radius, width, height - radius, height),
+    ]
+    for x0, x1, y0, y1 in corner_ranges:
+        for y in range(max(0, y0), min(height, y1)):
+            for x in range(max(0, x0), min(width, x1)):
+                red, green, blue, alpha = pixels[y * width + x]
+                if alpha > 16:
+                    samples.append((red, green, blue))
+    background = median_color(samples)
+    noise = percentile([color_distance(sample, background) for sample in samples], 0.75, 0.0)
+    return background, noise
+
+
+def build_foreground_mask(
+    width: int,
+    height: int,
+    pixels: list[tuple[int, int, int, int]],
+) -> tuple[list[bool], dict[str, Any], list[str]]:
+    warnings: list[str] = []
+    alpha_values = [pixel[3] for pixel in pixels]
+    transparent_fraction = sum(1 for alpha in alpha_values if alpha < 245) / max(1, len(alpha_values))
+    background, background_noise = sample_corner_background(width, height, pixels)
+    threshold = max(24.0, background_noise * 2.4)
+    mask: list[bool] = []
+    if transparent_fraction > 0.03:
+        for red, green, blue, alpha in pixels:
+            mask.append(alpha > 24)
+    else:
+        for red, green, blue, alpha in pixels:
+            rgb = (red, green, blue)
+            distance = color_distance(rgb, background)
+            sat = saturation(rgb)
+            luma = srgb_luma(rgb)
+            mask.append(alpha > 16 and (distance > threshold or (sat > 0.16 and luma < 0.94)))
+    coverage = sum(1 for value in mask if value) / max(1, len(mask))
+    if coverage < 0.035:
+        warnings.append("foreground mask is tiny; material extraction is likely unreliable")
+        mask = [pixel[3] > 16 for pixel in pixels]
+        coverage = sum(1 for value in mask if value) / max(1, len(mask))
+    if coverage > 0.9:
+        warnings.append("image is not clearly isolated from background; using most pixels as material evidence")
+    return (
+        mask,
+        {
+            "backgroundColor": rgb_to_hex(background),
+            "backgroundNoise": round(background_noise, 3),
+            "transparentPixelFraction": round(transparent_fraction, 4),
+            "foregroundCoverage": round(coverage, 4),
+        },
+        warnings,
+    )
+
+
+def mask_bbox(width: int, height: int, mask: list[bool]) -> tuple[int, int, int, int]:
+    xs: list[int] = []
+    ys: list[int] = []
+    for index, value in enumerate(mask):
+        if value:
+            ys.append(index // width)
+            xs.append(index % width)
+    if not xs or not ys:
+        return (0, 0, width, height)
+    padding = max(2, min(width, height) // 80)
+    x0 = max(0, min(xs) - padding)
+    y0 = max(0, min(ys) - padding)
+    x1 = min(width, max(xs) + padding + 1)
+    y1 = min(height, max(ys) + padding + 1)
+    return (x0, y0, max(1, x1 - x0), max(1, y1 - y0))
+
+
+def resample_crop(
+    width: int,
+    height: int,
+    pixels: list[tuple[int, int, int, int]],
+    mask: list[bool],
+    bbox: tuple[int, int, int, int],
+    size: int,
+) -> tuple[list[tuple[int, int, int]], list[bool]]:
+    x0, y0, crop_w, crop_h = bbox
+    sampled_pixels: list[tuple[int, int, int]] = []
+    sampled_mask: list[bool] = []
+    for y in range(size):
+        source_y = y0 + (y + 0.5) * crop_h / size
+        sy = min(height - 1, max(0, int(source_y)))
+        for x in range(size):
+            source_x = x0 + (x + 0.5) * crop_w / size
+            sx = min(width - 1, max(0, int(source_x)))
+            index = sy * width + sx
+            red, green, blue, alpha = pixels[index]
+            sampled_pixels.append((red, green, blue))
+            sampled_mask.append(mask[index] and alpha > 16)
+    return sampled_pixels, sampled_mask
+
+
+def representative_samples(
+    pixels: list[tuple[int, int, int]],
+    mask: list[bool],
+    limit: int = 7000,
+) -> list[tuple[int, int, int]]:
+    candidates = [pixel for pixel, keep in zip(pixels, mask) if keep]
+    if not candidates:
+        candidates = pixels
+    if len(candidates) <= limit:
+        return candidates
+    step = max(1, len(candidates) // limit)
+    return candidates[::step][:limit]
+
+
+def kmeans_palette(samples: list[tuple[int, int, int]], k: int = 5) -> list[str]:
+    if not samples:
+        return ["#8A7A5F"]
+    ordered = sorted(samples, key=lambda rgb: (srgb_luma(rgb), rgb[0], rgb[1], rgb[2]))
+    centers = [
+        ordered[int((index + 0.5) * (len(ordered) - 1) / k)]
+        for index in range(k)
+    ]
+    for _ in range(8):
+        groups: list[list[tuple[int, int, int]]] = [[] for _ in centers]
+        for sample in samples:
+            nearest = min(range(len(centers)), key=lambda idx: color_distance(sample, centers[idx]))
+            groups[nearest].append(sample)
+        new_centers: list[tuple[int, int, int]] = []
+        for group, center in zip(groups, centers):
+            if not group:
+                new_centers.append(center)
+                continue
+            new_centers.append(
+                tuple(int(round(sum(sample[channel] for sample in group) / len(group))) for channel in range(3))
+            )  # type: ignore[arg-type]
+        centers = new_centers
+    counts = Counter(
+        min(range(len(centers)), key=lambda idx: color_distance(sample, centers[idx]))
+        for sample in samples
+    )
+    palette = [rgb_to_hex(centers[index]) for index, _ in counts.most_common()]
+    return palette[:k]
+
+
+def rgb_to_hex(rgb: tuple[int, int, int]) -> str:
+    return "#{:02X}{:02X}{:02X}".format(*rgb)
+
+
+def blur_scalar(values: list[float], size: int, radius: int) -> list[float]:
+    if radius <= 0:
+        return values[:]
+    horizontal = [0.0] * (size * size)
+    for y in range(size):
+        row_offset = y * size
+        running = 0.0
+        count = 0
+        for x in range(-radius, size + radius):
+            if 0 <= x < size:
+                running += values[row_offset + x]
+                count += 1
+            remove = x - radius * 2 - 1
+            if 0 <= remove < size:
+                running -= values[row_offset + remove]
+                count -= 1
+            write_x = x - radius
+            if 0 <= write_x < size:
+                horizontal[row_offset + write_x] = running / max(1, count)
+    vertical = [0.0] * (size * size)
+    for x in range(size):
+        running = 0.0
+        count = 0
+        for y in range(-radius, size + radius):
+            if 0 <= y < size:
+                running += horizontal[y * size + x]
+                count += 1
+            remove = y - radius * 2 - 1
+            if 0 <= remove < size:
+                running -= horizontal[remove * size + x]
+                count -= 1
+            write_y = y - radius
+            if 0 <= write_y < size:
+                vertical[write_y * size + x] = running / max(1, count)
+    return vertical
+
+
+def make_maps(
+    pixels: list[tuple[int, int, int]],
+    mask: list[bool],
+    size: int,
+    palette: list[str],
+) -> tuple[dict[str, bytes], dict[str, Any]]:
+    masked_lumas = [srgb_luma(pixel) for pixel, keep in zip(pixels, mask) if keep]
+    fallback_luma = percentile(masked_lumas, 0.5, 0.55)
+    fallback_color = hex_to_rgb(palette[0] if palette else "#8A7A5F")
+    lumas = [srgb_luma(pixel) if keep else fallback_luma for pixel, keep in zip(pixels, mask)]
+    blur_radius = max(4, min(28, size // 48))
+    low_frequency = blur_scalar(lumas, size, blur_radius)
+    p05 = percentile(masked_lumas, 0.05, 0.2)
+    p95 = percentile(masked_lumas, 0.95, 0.8)
+    value_range = max(0.08, p95 - p05)
+    high_pass = [
+        clamp((luma - low + value_range * 0.5) / value_range, 0.0, 1.0)
+        for luma, low in zip(lumas, low_frequency)
+    ]
+    height = blur_scalar(high_pass, size, max(1, size // 256))
+    gradient_values: list[float] = []
+    for y in range(size):
+        for x in range(size):
+            left = height[y * size + max(0, x - 1)]
+            right = height[y * size + min(size - 1, x + 1)]
+            up = height[max(0, y - 1) * size + x]
+            down = height[min(size - 1, y + 1) * size + x]
+            gradient_values.append(math.sqrt((right - left) ** 2 + (down - up) ** 2))
+    grad_p90 = percentile(gradient_values, 0.9, 0.0)
+    normal_strength = clamp(10.0 + grad_p90 * 75.0, 10.0, 38.0)
+    albedo = bytearray()
+    roughness = bytearray()
+    height_map = bytearray()
+    normal = bytearray()
+    ao = bytearray()
+    roughness_values: list[float] = []
+    for index, ((red, green, blue), keep) in enumerate(zip(pixels, mask)):
+        luma = lumas[index]
+        shade = clamp(low_frequency[index], 0.08, 1.0)
+        scale = clamp((fallback_luma / shade) ** 0.42, 0.72, 1.35)
+        if keep:
+            out_r = clamp(red * scale, 0, 255)
+            out_g = clamp(green * scale, 0, 255)
+            out_b = clamp(blue * scale, 0, 255)
+        else:
+            out_r, out_g, out_b = fallback_color
+        albedo.extend((round(out_r), round(out_g), round(out_b)))
+        h = height[index]
+        local_gradient = gradient_values[index]
+        bright_highlight = max(0.0, luma - p95) / max(0.02, 1.0 - p95)
+        rough = clamp01(0.68 + min(0.22, local_gradient * 2.6) + (0.5 - h) * 0.12 - bright_highlight * 0.22)
+        roughness_values.append(rough)
+        rough_byte = round(rough * 255)
+        roughness.extend((rough_byte, rough_byte, rough_byte))
+        height_byte = round(h * 255)
+        height_map.extend((height_byte, height_byte, height_byte))
+    for y in range(size):
+        for x in range(size):
+            index = y * size + x
+            left = height[y * size + max(0, x - 1)]
+            right = height[y * size + min(size - 1, x + 1)]
+            up = height[max(0, y - 1) * size + x]
+            down = height[min(size - 1, y + 1) * size + x]
+            dx = (right - left) * normal_strength
+            dy = (down - up) * normal_strength
+            inv_len = 1.0 / math.sqrt(dx * dx + dy * dy + 1.0)
+            nx = -dx * inv_len
+            ny = -dy * inv_len
+            nz = inv_len
+            normal.extend(
+                (
+                    round((nx * 0.5 + 0.5) * 255),
+                    round((ny * 0.5 + 0.5) * 255),
+                    round((nz * 0.5 + 0.5) * 255),
+                )
+            )
+            neighbors = (
+                left
+                + right
+                + up
+                + down
+            ) * 0.25
+            cavity = max(0.0, neighbors - height[index])
+            ao_value = clamp01(1.0 - cavity * 8.0 - max(0.0, 0.35 - height[index]) * 0.16)
+            ao_byte = round(ao_value * 255)
+            ao.extend((ao_byte, ao_byte, ao_byte))
+    return (
+        {
+            "albedo": bytes(albedo),
+            "roughness": bytes(roughness),
+            "height": bytes(height_map),
+            "normal": bytes(normal),
+            "ao": bytes(ao),
+        },
+        {
+            "valueRange": round(value_range, 4),
+            "heightP90Gradient": round(grad_p90, 5),
+            "roughnessBase": round(percentile(roughness_values, 0.5, 0.72), 3),
+            "roughnessVariation": round(max(0.05, percentile(roughness_values, 0.85, 0.82) - percentile(roughness_values, 0.15, 0.62)), 3),
+            "normalStrength": round(normal_strength / 64.0, 3),
+            "blurRadius": blur_radius,
+        },
+    )
+
+
+def hex_to_rgb(value: str) -> tuple[int, int, int]:
+    if len(value) == 4 and value.startswith("#"):
+        return tuple(int(char * 2, 16) for char in value[1:])  # type: ignore[return-value]
+    if len(value) == 7 and value.startswith("#"):
+        return (int(value[1:3], 16), int(value[3:5], 16), int(value[5:7], 16))
+    return (138, 122, 95)
+
+
+def surface_bands_from_stats(stats: dict[str, Any]) -> list[dict[str, Any]]:
+    value_range = float(stats.get("valueRange", 0.4))
+    detail = float(stats.get("heightP90Gradient", 0.02))
+    return [
+        {
+            "id": "macro",
+            "frequency": 2.0,
+            "amplitude": round(clamp(0.28 + value_range * 0.35, 0.22, 0.52), 3),
+            "role": "reference-derived broad albedo and height breakup",
+        },
+        {
+            "id": "meso",
+            "frequency": 14.0,
+            "amplitude": round(clamp(0.15 + detail * 4.2, 0.12, 0.35), 3),
+            "role": "reference-derived cracks, ridges, pores, grain, or leaf clusters",
+        },
+        {
+            "id": "micro",
+            "frequency": 72.0,
+            "amplitude": round(clamp(0.055 + detail * 2.4, 0.045, 0.14), 3),
+            "role": "reference-derived micro highlight breakup under grazing light",
+        },
+    ]
+
+
+def estimate_confidence(
+    width: int,
+    height: int,
+    mask_diagnostics: dict[str, Any],
+    stats: dict[str, Any],
+    warnings: list[str],
+    single_image: bool,
+) -> tuple[float, list[str]]:
+    confidence_notes: list[str] = []
+    min_dim = min(width, height)
+    resolution_score = clamp(min_dim / 1024.0, 0.35, 1.0)
+    coverage = float(mask_diagnostics.get("foregroundCoverage", 1.0))
+    if 0.08 <= coverage <= 0.82:
+        mask_score = 1.0
+    elif 0.035 <= coverage < 0.08:
+        mask_score = 0.55
+        confidence_notes.append("foreground mask is very small")
+    elif coverage > 0.9:
+        mask_score = 0.68
+        confidence_notes.append("object/background separation is weak")
+    else:
+        mask_score = 0.78
+    value_range = float(stats.get("valueRange", 0.0))
+    dynamic_score = clamp(value_range / 0.48, 0.35, 1.0)
+    detail_score = clamp(float(stats.get("heightP90Gradient", 0.0)) * 52.0, 0.35, 1.0)
+    warning_penalty = min(0.16, len(warnings) * 0.035)
+    single_image_cap = 0.86 if single_image else 0.93
+    confidence = (
+        0.44
+        + resolution_score * 0.14
+        + mask_score * 0.14
+        + dynamic_score * 0.12
+        + detail_score * 0.16
+        - warning_penalty
+    )
+    confidence = min(single_image_cap, clamp01(confidence))
+    if single_image:
+        confidence_notes.append("single-image inverse rendering cannot prove true physical PBR; confidence is capped")
+    if dynamic_score < 0.5:
+        confidence_notes.append("low value range weakens height/roughness inference")
+    if detail_score < 0.5:
+        confidence_notes.append("low high-frequency detail weakens normal/roughness inference")
+    return round(confidence, 3), confidence_notes
+
+
+def map_url(url_prefix: str, filename: str) -> str:
+    if not url_prefix:
+        return filename
+    return url_prefix.rstrip("/") + "/" + filename
+
+
+def material_patch(
+    material_id: str,
+    image: Path,
+    out_dir: Path,
+    url_prefix: str,
+    size: int,
+    threshold: float,
+    confidence: float,
+    verdict: str,
+    palette: list[str],
+    map_stats: dict[str, Any],
+    diagnostics: dict[str, Any],
+    warnings: list[str],
+) -> dict[str, Any]:
+    prefix = slugify(material_id)
+    maps = {
+        channel: {
+            "path": str((out_dir / f"{prefix}_{channel}.png").resolve()),
+            "url": map_url(url_prefix, f"{prefix}_{channel}.png"),
+            "channel": channel,
+            "source": "reference-pixel-extraction",
+        }
+        for channel in ("albedo", "roughness", "height", "normal", "ao")
+    }
+    usable = confidence >= threshold
+    return {
+        "referencePbr": {
+            "version": "1.0",
+            "sourceImage": str(image.resolve()),
+            "extractor": "stage1_intake/extract_pbr_evidence.py",
+            "method": "single-image pixel evidence with de-lighting estimate; not photogrammetry",
+            "usable": usable,
+            "verdict": verdict,
+            "confidence": confidence,
+            "estimatedFidelity": confidence,
+            "targetThreshold": threshold,
+            "hardLimit": "A single image cannot uniquely recover true albedo/roughness/normal/AO; maps are reference-derived estimates.",
+            "maps": maps,
+            "diagnostics": diagnostics,
+            "warnings": warnings,
+        },
+        "textureResolution": size,
+        "albedo": {
+            "dominant": palette[0],
+            "secondary": palette[1:4],
+            "samplingNotes": "Reference-derived from foreground pixels; de-lit to reduce baked shadows/highlights.",
+            "map": maps["albedo"],
+        },
+        "colorVariation": {
+            "palette": palette,
+            "pattern": "reference-derived pixel palette",
+            "amplitude": round(clamp(float(map_stats.get("valueRange", 0.4)) * 0.42, 0.08, 0.35), 3),
+            "heightCorrelation": 0.42,
+        },
+        "roughness": {
+            "base": map_stats["roughnessBase"],
+            "variation": map_stats["roughnessVariation"],
+            "map": maps["roughness"],
+            "localResponse": "reference-derived roughness estimate; cavities and textured zones trend rougher, bright highlights trend smoother",
+        },
+        "normal": {
+            "pattern": "reference-derived height-gradient normal map",
+            "strength": map_stats["normalStrength"],
+            "map": maps["normal"],
+            "heightSource": maps["height"],
+            "space": "tangent",
+        },
+        "bump": {
+            "pattern": "reference-derived height field",
+            "amplitude": round(clamp(float(map_stats.get("heightP90Gradient", 0.02)) * 0.45, 0.01, 0.08), 3),
+            "map": maps["height"],
+        },
+        "ambientOcclusion": {
+            "cavityStrength": 0.38,
+            "contactShadowBias": 0.35,
+            "map": maps["ao"],
+            "notes": "Reference-derived cavity estimate from local height minima; verify against grazing-light screenshot.",
+        },
+        "surfaceFrequencyBands": surface_bands_from_stats(map_stats),
+        "localOverrides": [
+            {
+                "id": "reference-pbr-pixel-evidence",
+                "type": "material-map-evidence",
+                "evidenceRefs": ["full-object"],
+                "channels": ["albedo", "roughness", "height", "normal", "ambient-occlusion"],
+                "notes": "Use generated maps as material evidence, then refine after browser screenshot comparison.",
+            }
+        ],
+        "shaderNotes": [
+            "Reference-derived maps are estimates from image pixels; verify with neutral, grazing, and reference-matched renders.",
+            "Do not treat baked image shadows as final albedo; rerun extraction with a tighter material crop if highlights/shadows pollute the maps.",
+        ],
+    }
+
+
+def merge_material_patch(spec: dict[str, Any], material_id: str, patch: dict[str, Any]) -> None:
+    materials = spec.get("materials")
+    if not isinstance(materials, list):
+        raise ValueError("spec.materials must be an array")
+    material = next(
+        (item for item in materials if isinstance(item, dict) and item.get("id") == material_id),
+        None,
+    )
+    if material is None:
+        raise ValueError(f"could not find material {material_id!r} in spec")
+    for key, value in patch.items():
+        if key == "localOverrides" and isinstance(material.get(key), list) and isinstance(value, list):
+            material[key].extend(value)
+        elif key == "shaderNotes" and isinstance(material.get(key), list) and isinstance(value, list):
+            material[key].extend(value)
+        else:
+            material[key] = value
+    history = spec.setdefault("pbrExtractionHistory", [])
+    if isinstance(history, list):
+        history.append(
+            {
+                "materialId": material_id,
+                "confidence": patch["referencePbr"]["confidence"],
+                "verdict": patch["referencePbr"]["verdict"],
+                "usable": patch["referencePbr"]["usable"],
+                "maps": patch["referencePbr"]["maps"],
+            }
+        )
+
+
+def extract(args: argparse.Namespace) -> tuple[dict[str, Any], dict[str, Any]]:
+    image = args.image.expanduser().resolve()
+    if not image.exists():
+        raise ValueError(f"{image} does not exist")
+    size = int(2 ** round(math.log2(args.size)))
+    size = max(256, min(2048, size))
+    out_dir = args.out_dir.expanduser().resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    width, height, source_pixels, load_warnings = load_image(image)
+    mask, mask_diag, mask_warnings = build_foreground_mask(width, height, source_pixels)
+    bbox = mask_bbox(width, height, mask)
+    sampled_pixels, sampled_mask = resample_crop(width, height, source_pixels, mask, bbox, size)
+    samples = representative_samples(sampled_pixels, sampled_mask)
+    palette = kmeans_palette(samples, max(2, min(6, args.palette_size)))
+    maps, map_stats = make_maps(sampled_pixels, sampled_mask, size, palette)
+    for channel, payload in maps.items():
+        write_png_rgb(out_dir / f"{slugify(args.material_id)}_{channel}.png", size, size, payload)
+    warnings = load_warnings + mask_warnings
+    diagnostics = {
+        "sourceWidth": width,
+        "sourceHeight": height,
+        "mapSize": size,
+        "cropBBoxPixels": {
+            "x": bbox[0],
+            "y": bbox[1],
+            "width": bbox[2],
+            "height": bbox[3],
+        },
+        "mask": mask_diag,
+        "mapStats": map_stats,
+        "palette": palette,
+    }
+    confidence, confidence_notes = estimate_confidence(
+        width,
+        height,
+        mask_diag,
+        map_stats,
+        warnings,
+        single_image=not args.multi_view_reference,
+    )
+    warnings.extend(confidence_notes)
+    threshold = clamp01(args.target_threshold)
+    verdict = "pass" if confidence >= threshold else ("conditional" if confidence >= threshold - 0.12 else "reject")
+    patch = material_patch(
+        args.material_id,
+        image,
+        out_dir,
+        args.url_prefix,
+        size,
+        threshold,
+        confidence,
+        verdict,
+        palette,
+        map_stats,
+        diagnostics,
+        warnings,
+    )
+    report = {
+        "ok": confidence >= threshold,
+        "verdict": verdict,
+        "confidence": confidence,
+        "estimatedFidelity": confidence,
+        "targetThreshold": threshold,
+        "materialId": args.material_id,
+        "sourceImage": str(image),
+        "outDir": str(out_dir),
+        "palette": palette,
+        "maps": patch["referencePbr"]["maps"],
+        "diagnostics": diagnostics,
+        "warnings": warnings,
+        "limitation": "single-image PBR extraction is an estimate; 70%+ extraction confidence still needs render screenshot review",
+    }
+    return report, patch
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", type=Path)
+    parser.add_argument("--out-dir", type=Path, required=True)
+    parser.add_argument("--material-id", default="base")
+    parser.add_argument("--size", type=int, default=1024)
+    parser.add_argument("--palette-size", type=int, default=5)
+    parser.add_argument("--target-threshold", type=float, default=0.7)
+    parser.add_argument("--url-prefix", default="")
+    parser.add_argument("--spec", type=Path, help="Optional ObjectSculptSpec JSON to patch")
+    parser.add_argument("--in-place", action="store_true", help="Patch --spec in place when confidence passes")
+    parser.add_argument("--out-spec", type=Path, help="Write patched spec to this path")
+    parser.add_argument("--report", type=Path, help="Write extraction report JSON")
+    parser.add_argument("--allow-low-confidence", action="store_true", help="Patch/write even when confidence is below threshold")
+    parser.add_argument("--multi-view-reference", action="store_true", help="Raise confidence cap when image belongs to a multi-view reference set")
+    args = parser.parse_args(argv)
+
+    try:
+        report, patch = extract(args)
+        if args.report:
+            args.report.expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+            args.report.expanduser().resolve().write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        if args.spec:
+            if not report["ok"] and not args.allow_low_confidence:
+                raise ValueError(
+                    f"PBR extraction confidence {report['confidence']} is below target "
+                    f"{report['targetThreshold']}; spec was not patched"
+                )
+            spec_path = args.spec.expanduser().resolve()
+            spec = json.loads(spec_path.read_text(encoding="utf-8"))
+            if not isinstance(spec, dict):
+                raise ValueError("spec must be a JSON object")
+            merge_material_patch(spec, args.material_id, patch)
+            output = spec_path if args.in_place else (args.out_spec.expanduser().resolve() if args.out_spec else None)
+            if output:
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_text(json.dumps(spec, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+        return 0 if report["ok"] or args.allow_low_confidence else 1
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage1_intake/probe_image.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Probe basic technical properties of a reference image before visual analysis."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import struct
+import sys
+from pathlib import Path
+
+
+def png_size(data: bytes) -> tuple[int, int] | None:
+    if data.startswith(b"\x89PNG\r\n\x1a\n") and len(data) >= 24:
+        return struct.unpack(">II", data[16:24])
+    return None
+
+
+def gif_size(data: bytes) -> tuple[int, int] | None:
+    if data[:6] in {b"GIF87a", b"GIF89a"} and len(data) >= 10:
+        return struct.unpack("<HH", data[6:10])
+    return None
+
+
+def jpeg_size(data: bytes) -> tuple[int, int] | None:
+    if not data.startswith(b"\xff\xd8"):
+        return None
+    index = 2
+    while index + 9 < len(data):
+        if data[index] != 0xFF:
+            index += 1
+            continue
+        marker = data[index + 1]
+        index += 2
+        if marker in {0xD8, 0xD9}:
+            continue
+        if index + 2 > len(data):
+            return None
+        length = struct.unpack(">H", data[index : index + 2])[0]
+        if length < 2 or index + length > len(data):
+            return None
+        if marker in {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}:
+            if length >= 7:
+                height, width = struct.unpack(">HH", data[index + 3 : index + 7])
+                return width, height
+        index += length
+    return None
+
+
+def webp_size(data: bytes) -> tuple[int, int] | None:
+    if len(data) < 30 or data[:4] != b"RIFF" or data[8:12] != b"WEBP":
+        return None
+    chunk = data[12:16]
+    if chunk == b"VP8X" and len(data) >= 30:
+        width = 1 + int.from_bytes(data[24:27], "little")
+        height = 1 + int.from_bytes(data[27:30], "little")
+        return width, height
+    if chunk == b"VP8 " and len(data) >= 30:
+        start = data.find(b"\x9d\x01\x2a")
+        if start != -1 and start + 7 <= len(data):
+            width, height = struct.unpack("<HH", data[start + 3 : start + 7])
+            return width & 0x3FFF, height & 0x3FFF
+    return None
+
+
+def bmp_size(data: bytes) -> tuple[int, int] | None:
+    if len(data) >= 26 and data[:2] == b"BM":
+        width = struct.unpack("<I", data[18:22])[0]
+        height = abs(struct.unpack("<i", data[22:26])[0])
+        return width, height
+    return None
+
+
+def tiff_size(data: bytes) -> tuple[int, int] | None:
+    if len(data) < 8:
+        return None
+    if data[:4] == b"II*\x00":
+        endian = "<"
+    elif data[:4] == b"MM\x00*":
+        endian = ">"
+    else:
+        return None
+    offset = struct.unpack(f"{endian}I", data[4:8])[0]
+    if offset + 2 > len(data):
+        return None
+    entries = struct.unpack(f"{endian}H", data[offset : offset + 2])[0]
+    width = height = None
+    cursor = offset + 2
+    for _ in range(entries):
+        if cursor + 12 > len(data):
+            return None
+        tag, value_type, count, raw_value = struct.unpack(f"{endian}HHII", data[cursor : cursor + 12])
+        if value_type in {3, 4} and count == 1:
+            value = raw_value if value_type == 4 else raw_value & 0xFFFF
+            if tag == 256:
+                width = value
+            elif tag == 257:
+                height = value
+        cursor += 12
+    if width and height:
+        return width, height
+    return None
+
+
+def detect_image_type(data: bytes) -> str | None:
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "png"
+    if data.startswith(b"\xff\xd8"):
+        return "jpeg"
+    if data[:6] in {b"GIF87a", b"GIF89a"}:
+        return "gif"
+    if len(data) >= 12 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        return "webp"
+    if data.startswith(b"BM"):
+        return "bmp"
+    if data[:4] in {b"II*\x00", b"MM\x00*"}:
+        return "tiff"
+    return None
+
+
+def detect_size(data: bytes) -> tuple[int, int] | None:
+    return png_size(data) or jpeg_size(data) or gif_size(data) or webp_size(data) or bmp_size(data) or tiff_size(data)
+
+
+def probe(path: Path) -> dict:
+    data = path.read_bytes()
+    image_type = detect_image_type(data)
+    size = detect_size(data)
+    warnings: list[str] = []
+    if not image_type:
+        warnings.append("unknown image type")
+    if not size:
+        warnings.append("could not read image dimensions")
+        width = height = None
+        aspect = None
+    else:
+        width, height = size
+        aspect = width / height if height else None
+        if width < 512 or height < 512:
+            warnings.append("low resolution; small geometry/material details may be unreliable")
+        if aspect and (aspect > 3.0 or aspect < 0.33):
+            warnings.append("extreme aspect ratio; object may be cropped or surrounded by empty space")
+    return {
+        "path": str(path),
+        "type": image_type,
+        "bytes": len(data),
+        "width": width,
+        "height": height,
+        "aspectRatio": aspect,
+        "technicalSuitability": "conditional" if warnings else "pass",
+        "warnings": warnings,
+        "note": "This is only technical image probing. Semantic object suitability still requires visual inspection.",
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", type=Path)
+    args = parser.parse_args(argv)
+    path = args.image.expanduser().resolve()
+    if not path.exists():
+        parser.error(f"{path} does not exist")
+    print(json.dumps(probe(path), indent=2, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage1_intake/solve_camera_pose.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Estimate a starting referenceCamera block for a reference image.
+
+This is not camera calibration and it does not solve for the true focal
+length, sensor, or 6-DoF pose that produced the photo. A single 2D image
+under-constrains that problem. Instead this script emits a reasonable
+default guess (FOV) plus image-derived facts (aspect ratio) and explicit
+agent-fill placeholders (orientation, position) that the agent is expected
+to refine by rendering the fitted mesh from this camera and visually
+overlaying it against the reference image until silhouettes line up. The
+`agentFill` flag on each field marks what still needs that visual pass.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import struct
+import sys
+from pathlib import Path
+from typing import Any
+
+
+def png_size(data: bytes) -> tuple[int, int] | None:
+    if data.startswith(b"\x89PNG\r\n\x1a\n") and len(data) >= 24:
+        return struct.unpack(">II", data[16:24])
+    return None
+
+
+def gif_size(data: bytes) -> tuple[int, int] | None:
+    if data[:6] in {b"GIF87a", b"GIF89a"} and len(data) >= 10:
+        return struct.unpack("<HH", data[6:10])
+    return None
+
+
+def jpeg_size(data: bytes) -> tuple[int, int] | None:
+    if not data.startswith(b"\xff\xd8"):
+        return None
+    index = 2
+    while index + 9 < len(data):
+        if data[index] != 0xFF:
+            index += 1
+            continue
+        marker = data[index + 1]
+        index += 2
+        if marker in {0xD8, 0xD9}:
+            continue
+        if index + 2 > len(data):
+            return None
+        length = struct.unpack(">H", data[index : index + 2])[0]
+        if length < 2 or index + length > len(data):
+            return None
+        if marker in {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}:
+            if length >= 7:
+                height, width = struct.unpack(">HH", data[index + 3 : index + 7])
+                return width, height
+        index += length
+    return None
+
+
+def webp_size(data: bytes) -> tuple[int, int] | None:
+    if len(data) < 30 or data[:4] != b"RIFF" or data[8:12] != b"WEBP":
+        return None
+    chunk = data[12:16]
+    if chunk == b"VP8X" and len(data) >= 30:
+        width = 1 + int.from_bytes(data[24:27], "little")
+        height = 1 + int.from_bytes(data[27:30], "little")
+        return width, height
+    if chunk == b"VP8 " and len(data) >= 30:
+        start = data.find(b"\x9d\x01\x2a")
+        if start != -1 and start + 7 <= len(data):
+            width, height = struct.unpack("<HH", data[start + 3 : start + 7])
+            return width & 0x3FFF, height & 0x3FFF
+    return None
+
+
+def bmp_size(data: bytes) -> tuple[int, int] | None:
+    if len(data) >= 26 and data[:2] == b"BM":
+        width = struct.unpack("<I", data[18:22])[0]
+        height = abs(struct.unpack("<i", data[22:26])[0])
+        return width, height
+    return None
+
+
+def detect_size(data: bytes) -> tuple[int, int] | None:
+    return png_size(data) or jpeg_size(data) or gif_size(data) or webp_size(data) or bmp_size(data)
+
+
+def clamp(value: float, minimum: float, maximum: float) -> float:
+    return max(minimum, min(maximum, value))
+
+
+def estimate_fov(aspect: float | None) -> tuple[float, str]:
+    """Return a default vertical FOV guess plus the rationale.
+
+    Most product/character reference photos are shot on a phone or a short
+    telephoto lens at a comfortable working distance, which lands roughly in
+    the 30-45 degree vertical FOV band. There is no way to recover the true
+    lens from pixels alone, so this is a fixed default, not a measurement.
+    """
+    if aspect is not None and aspect < 0.75:
+        return 38.0, "default guess for a portrait-oriented photo (typical phone/short-tele framing)"
+    return 35.0, "default guess for a landscape/square photo (typical phone/short-tele framing)"
+
+
+def build_camera(image: Path, args: argparse.Namespace) -> dict[str, Any]:
+    data = image.read_bytes()
+    size = detect_size(data)
+    warnings: list[str] = []
+    if size is None:
+        warnings.append("could not read image dimensions; aspect defaults to 1.0")
+        width = height = None
+        aspect = 1.0
+    else:
+        width, height = size
+        aspect = round(width / height, 4) if height else 1.0
+
+    default_fov, fov_rationale = estimate_fov(aspect)
+    fov_degrees = args.fov_degrees if args.fov_degrees is not None else default_fov
+    fov_source = "user-supplied" if args.fov_degrees is not None else "default-guess"
+
+    distance = args.distance if args.distance is not None else 2.5
+    distance_source = "user-supplied" if args.distance is not None else "placeholder"
+
+    camera: dict[str, Any] = {
+        "version": "1.0",
+        "sourceImage": str(image),
+        "solver": "stage1_intake/solve_camera_pose.py",
+        "method": (
+            "heuristic default-guess camera, not solved from image content; image dimensions give an "
+            "exact aspect ratio, everything else is a starting point for agent refinement"
+        ),
+        "imageWidth": width,
+        "imageHeight": height,
+        "fovDegrees": {
+            "value": round(fov_degrees, 2),
+            "source": fov_source,
+            "agentFill": fov_source == "default-guess",
+            "rationale": fov_rationale,
+        },
+        "aspect": {
+            "value": aspect,
+            "source": "image-dimensions" if size else "fallback-default",
+            "agentFill": size is None,
+        },
+        "orientation": {
+            "yawDegrees": {"value": args.yaw, "source": "placeholder", "agentFill": True},
+            "pitchDegrees": {"value": args.pitch, "source": "placeholder", "agentFill": True},
+            "rollDegrees": {"value": args.roll, "source": "placeholder", "agentFill": True},
+            "note": "0/0/0 assumes a straight-on, level shot; adjust by eye against the reference image.",
+        },
+        "position": {
+            "hint": [0.0, args.height_offset, distance],
+            "distance": {"value": distance, "source": distance_source, "agentFill": distance_source == "placeholder"},
+            "note": "Position hint assumes the subject is centered at the origin and the camera looks down -Z.",
+        },
+        "confidence": 0.35 if size else 0.15,
+        "limitations": [
+            "no true camera calibration is performed; focal length/FOV/orientation are not recovered from pixels",
+            "fovDegrees is a genre default, not a measurement; wrong FOV distorts perceived proportions under overlay",
+            "orientation and position are placeholders and will almost always need manual/agent adjustment",
+            "this script cannot detect lens distortion, perspective foreshortening, or non-zero roll",
+        ]
+        + warnings,
+        "note": (
+            "Final camera match must be confirmed by overlay review: render the fitted mesh from this "
+            "camera, place it beside or over the reference image, and adjust fovDegrees/orientation/"
+            "position until silhouette and landmark alignment match before trusting projected texture bakes."
+        ),
+    }
+    return camera
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("image", type=Path)
+    parser.add_argument("--fov-degrees", type=float, default=None, help="Override the default FOV guess")
+    parser.add_argument("--yaw", type=float, default=0.0, help="Orientation placeholder, degrees")
+    parser.add_argument("--pitch", type=float, default=0.0, help="Orientation placeholder, degrees")
+    parser.add_argument("--roll", type=float, default=0.0, help="Orientation placeholder, degrees")
+    parser.add_argument("--distance", type=float, default=None, help="Camera distance hint, scene units")
+    parser.add_argument("--height-offset", type=float, default=0.0, help="Camera Y offset hint, scene units")
+    parser.add_argument("--out", type=Path, help="Write the referenceCamera JSON block to this path")
+    args = parser.parse_args(argv)
+
+    image = args.image.expanduser().resolve()
+    if not image.exists():
+        parser.error(f"{image} does not exist")
+
+    camera = build_camera(image, args)
+    payload = {"referenceCamera": camera}
+    text = json.dumps(payload, indent=2, ensure_ascii=False)
+    if args.out:
+        out_path = args.out.expanduser().resolve()
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(text + "\n", encoding="utf-8")
+    print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage2_spec/new_pre_spec_assessment.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Create a pre-spec assessment and quality contract skeleton before ObjectSculptSpec authoring."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from new_sculpt_spec import make_pre_spec_assessment, make_quality_contract
+
+
+COMPLEXITY_MINIMUMS = {
+    "simple": {
+        "macroComponents": 1,
+        "mesoComponents": 0,
+        "microFeatureGroups": 0,
+        "materialLayers": 1,
+        "repetitionSystems": 0,
+        "reviewViewpoints": 2,
+    },
+    "moderate": {
+        "macroComponents": 2,
+        "mesoComponents": 3,
+        "microFeatureGroups": 2,
+        "materialLayers": 2,
+        "repetitionSystems": 0,
+        "reviewViewpoints": 3,
+    },
+    "complex": {
+        "macroComponents": 3,
+        "mesoComponents": 8,
+        "microFeatureGroups": 5,
+        "materialLayers": 3,
+        "repetitionSystems": 1,
+        "reviewViewpoints": 4,
+    },
+    "ultra-complex": {
+        "macroComponents": 5,
+        "mesoComponents": 16,
+        "microFeatureGroups": 8,
+        "materialLayers": 4,
+        "repetitionSystems": 2,
+        "reviewViewpoints": 5,
+    },
+}
+
+
+DETAIL_MINIMUMS = {
+    "simple": 3,
+    "moderate": 6,
+    "complex": 10,
+    "ultra-complex": 16,
+}
+
+
+def make_payload(target_name: str, image: str | None, complexity: str) -> dict:
+    assessment = make_pre_spec_assessment(target_name)
+    contract = make_quality_contract()
+    assessment["sourceImage"] = image or ""
+    assessment["complexity"]["tier"] = complexity
+    assessment["specDepthDecision"]["requiredDepth"] = complexity
+    assessment["detailInventory"]["targetMinDetails"] = DETAIL_MINIMUMS[complexity]
+    if complexity in {"complex", "ultra-complex"}:
+        assessment["specDepthDecision"]["needsRepetitionSystems"] = True
+        assessment["specDepthDecision"]["needsMaterialLocalOverrides"] = True
+        assessment["specDepthDecision"]["minimumComponentLevels"] = ["macro", "meso", "micro"]
+    elif complexity == "moderate":
+        assessment["specDepthDecision"]["minimumComponentLevels"] = ["macro", "meso"]
+    contract["qualityBar"] = complexity
+    contract["minimumSpecDepth"] = COMPLEXITY_MINIMUMS[complexity]
+    return {
+        "targetName": target_name,
+        "sourceImage": image or "",
+        "preSpecAssessment": assessment,
+        "qualityContract": contract,
+        "authoringInstruction": (
+            "Fill observed object class, complexity reasoning, featureGroups, visualDeltaChecks, "
+            "and unknowns before generating or implementing ObjectSculptSpec."
+        ),
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("target_name", help="Human-readable object name")
+    parser.add_argument("--image", help="Reference image path or URL")
+    parser.add_argument(
+        "--complexity",
+        choices=sorted(COMPLEXITY_MINIMUMS),
+        default="moderate",
+        help="Initial complexity estimate. Refine after visual inspection.",
+    )
+    parser.add_argument("--out", type=Path, help="Output JSON path")
+    parser.add_argument("--force", action="store_true", help="Overwrite output file")
+    args = parser.parse_args(argv)
+
+    payload = json.dumps(make_payload(args.target_name, args.image, args.complexity), indent=2, ensure_ascii=False) + "\n"
+    if args.out:
+        output = args.out.expanduser().resolve()
+        if output.exists() and not args.force:
+            parser.error(f"{output} already exists; use --force to overwrite")
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(payload, encoding="utf-8")
+        print(output)
+    else:
+        print(payload, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage2_spec/new_sculpt_spec.py

@@ -0,0 +1,1129 @@
+#!/usr/bin/env python3
+"""Create a starter ObjectSculptSpec JSON file."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^A-Za-z0-9]+", "-", value.strip().lower()).strip("-")
+    return slug or "object"
+
+
+def make_pre_spec_assessment(target_name: str) -> dict:
+    return {
+        "objectClass": {
+            "primaryType": "unassessed",
+            "primaryDomain": "unassessed",
+            "formLanguage": [],
+            "structureKind": [],
+            "motionPotential": [],
+            "materialFamilies": [],
+            "notes": "Fill from direct visual inspection before writing the final spec. Do not use fixed domain profiles. Set primaryDomain to object, character, or hybrid.",
+        },
+        "complexity": {
+            "tier": "unassessed",
+            "scores": {
+                "silhouetteComplexity": 0,
+                "componentCount": 0,
+                "hierarchyDepth": 0,
+                "repetitionDensity": 0,
+                "materialLayerCount": 0,
+                "localDetailDensity": 0,
+                "occlusionRisk": 0,
+                "actionReadinessNeed": 0,
+            },
+            "estimatedCounts": {
+                "macroComponents": 1,
+                "mesoComponents": 0,
+                "microFeatureGroups": 0,
+                "materialLayers": 1,
+                "repetitionSystems": 0,
+            },
+            "reasoning": [
+                f"Assess {target_name!r} from the image before finalizing componentTree/materials.",
+            ],
+        },
+        "specDepthDecision": {
+            "requiredDepth": "unassessed",
+            "minimumComponentLevels": ["macro"],
+            "needsRepetitionSystems": False,
+            "needsMaterialLocalOverrides": False,
+            "needsMultipleReviewViews": True,
+            "needsActionReadyHierarchy": True,
+            "rationale": "Choose simple/moderate/complex/ultra-complex from observed structure, not from a hardcoded domain.",
+        },
+        "unknownsToResolveBeforeImplementation": [],
+        "detailInventory": {
+            "scanMethod": "component-zones",
+            "targetMinDetails": 0,
+            "note": (
+                "Enumerate every identity-defining small detail before authoring the spec. "
+                "Each detail must map to a component.localFeatures entry or material.localOverrides entry, "
+                "never prose only. Use forge/stage1_intake/build_detail_inventory.py to scan zones."
+            ),
+            "details": [],
+        },
+        "anatomy": {
+            "applies": False,
+            "styleHeads": 0.0,
+            "proportions": {
+                "headUnit": 0.0,
+                "torso": 0.0,
+                "legs": 0.0,
+                "shoulderWidth": 0.0,
+                "hipWidth": 0.0,
+            },
+            "pose": {"type": "unassessed", "jointAngles": {}},
+            "faceLandmarks": {
+                "eyeLine": 0.0,
+                "eyeSpacing": 0.0,
+                "noseBase": 0.0,
+                "mouthLine": 0.0,
+                "hairline": 0.0,
+            },
+            "features": [],
+            "confidence": 0.0,
+            "note": (
+                "Only meaningful when objectClass.primaryDomain is character or hybrid. "
+                "Set applies=true and fill from forge/stage1_intake/extract_landmarks.py. "
+                "See grimoire/character/reconstruction.md and grimoire/character/likeness_maximization.md."
+            ),
+        },
+    }
+
+
+def make_quality_contract() -> dict:
+    return {
+        "qualityBar": "unassessed",
+        "definitionOfDone": [
+            "The rendered model matches the reference silhouette, primary proportions, visible component hierarchy, material response, and most recognizable local features for the selected fidelity tier.",
+        ],
+        "minimumSpecDepth": {
+            "macroComponents": 1,
+            "mesoComponents": 0,
+            "microFeatureGroups": 0,
+            "materialLayers": 1,
+            "repetitionSystems": 0,
+            "reviewViewpoints": 3,
+        },
+        "featureGroups": [
+            {
+                "id": "overall-silhouette",
+                "name": "Overall silhouette and proportions",
+                "required": True,
+                "qualityCriteria": [
+                    "Bounding shape, dominant curves, negative spaces, and scale relationships are explicitly described.",
+                ],
+                "evidenceRefs": ["full-object"],
+                "failureModes": [
+                    "model reads as a generic placeholder instead of the reference object",
+                    "major proportions are guessed without evidence",
+                ],
+            },
+            {
+                "id": "primary-structure",
+                "name": "Primary structure and hierarchy",
+                "required": True,
+                "qualityCriteria": [
+                    "Major parts, joints, seams, contact points, and parent-child relationships are named before code generation.",
+                ],
+                "evidenceRefs": ["full-object"],
+                "failureModes": [
+                    "large visible parts are merged into one mesh",
+                    "component hierarchy is too shallow for the observed complexity",
+                ],
+            },
+            {
+                "id": "attachment-joint-correctness",
+                "name": "Attachment and joint correctness",
+                "required": True,
+                "qualityCriteria": [
+                    "Every visible child appendage, branch, limb, handle, connector, tube, cable, horn, wing, leg, or hinged part has an attachment contract with parent socket, localStart/localEnd, contact type, embed/overlap, and gap tolerance.",
+                ],
+                "evidenceRefs": ["full-object"],
+                "failureModes": [
+                    "child part root floats away from the parent",
+                    "branch/limb/tube is centered in space instead of pivoting from its root",
+                    "parent-child transform mixes world and local coordinates",
+                ],
+            },
+            {
+                "id": "surface-material-response",
+                "name": "Surface material response",
+                "required": True,
+                "qualityCriteria": [
+                    "Albedo zones, roughness, normal/bump/displacement intent, cavity dirt, edge wear, and local overrides are specified where visible.",
+                    "Important materials define independent albedo, roughness, height/normal, and AO responses instead of reusing one texture for unrelated PBR channels.",
+                    "Surface response is decomposed into macro, meso, and micro frequency bands with scale and amplitude tied to object scale.",
+                ],
+                "evidenceRefs": ["full-object"],
+                "failureModes": [
+                    "surface looks like flat plastic",
+                    "local material variation is missing or not tied to image evidence",
+                ],
+            },
+            {
+                "id": "reference-lookdev",
+                "name": "Reference color, material, and lighting response",
+                "required": True,
+                "qualityCriteria": [
+                    "Material-pass names the reference-derived albedo palette, roughness variation, tactile normal/bump/displacement response, and local masks.",
+                    "When a source image is available, run reference PBR extraction and require confidence >= 0.7 before treating maps as implementation-ready.",
+                    "Lighting-pass names key/fill/rim or environment light, exposure, tone mapping, background, and contact shadow behavior.",
+                    "Neutral, grazing-angle, and reference-matched renders prove that surface relief survives relighting and is not painted into albedo.",
+                ],
+                "evidenceRefs": ["full-object"],
+                "failureModes": [
+                    "model has acceptable shape but reads as flat shaded or plastic",
+                    "colors are a generic average instead of reference-observed local color zones",
+                    "lighting is evenly ambient and cannot reproduce the source value range",
+                ],
+            },
+        ],
+        "visualDeltaChecks": [
+            "silhouette and negative-space delta",
+            "component hierarchy depth delta",
+            "repetition density and distribution delta",
+            "material albedo/roughness/normal response delta",
+            "local feature placement and scale delta",
+        ],
+        "antiShallowSpecRules": [
+            "Do not proceed to code if qualityContract.qualityBar is unassessed.",
+            "Do not proceed to code if the spec only contains a root component for a moderate or complex object.",
+            "Do not proceed to code if required featureGroups are not represented by componentTree, materials, or repetitionSystems.",
+            "Do not proceed to code if visible local features are described only in prose and not attached to components/materials/evidenceRefs.",
+            "Do not proceed past structural-pass if attached child parts lack attachment.parentSocket, localStart, localEnd, embedDepth/overlap, and gapTolerance.",
+            "Do not pass material look-dev when albedo is reused as roughness, height, normal, or AO.",
+            "Do not pass material look-dev without macro, meso, and micro surface frequency bands for close-up materials.",
+            "Do not pass reference-fidelity material look-dev from a source image without usable referencePbr maps or an explicit documented limitation.",
+            "Do not patch a spec with extracted PBR maps when extraction confidence is below the target threshold unless the user explicitly accepts lower fidelity.",
+        ],
+    }
+
+
+def load_assessment(path: Path | None) -> dict | None:
+    if path is None:
+        return None
+    payload = json.loads(path.expanduser().read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("assessment must be a JSON object")
+    return payload
+
+
+def _cnode(cid, name, primitive, parent, position, scale,
+           material="skin", role="body", level="meso", rotation=(0, 0, 0),
+           importance=0.7, sockets=None, local_features=None, anim_role="static",
+           pivot_mode="center", evidence=None):
+    """Build a full schema-valid componentTree node with humanoid-friendly defaults."""
+    return {
+        "id": cid, "name": name, "level": level, "role": role,
+        "importance": importance, "confidence": 0.8, "primitive": primitive,
+        "geometryDescriptor": {
+            "topologyIntent": "stylized character part",
+            "edgeTreatment": {"type": "none", "bevelRadius": 0.0, "segments": 1},
+            "deformationStack": [], "uvStrategy": "generated procedural coordinates",
+            "normalStrategy": "smooth vertex normals",
+        },
+        "parent": parent, "attachment": None,
+        "dimensions": {"width": float(scale[0]), "height": float(scale[1]),
+                       "depth": float(scale[2]), "units": "relative", "confidence": 0.8},
+        "transform": {"position": list(position), "rotation": list(rotation), "scale": list(scale)},
+        "actionProfile": {
+            "animationRole": anim_role,
+            "pivot": {"mode": pivot_mode, "localPosition": [0, 0, 0], "axis": [0, 1, 0], "confidence": 0.7},
+            "transformChannels": {"translate": True, "rotate": True, "scale": True,
+                                  "bend": False, "twist": False, "detach": False,
+                                  "visibility": True, "materialState": False},
+            "sockets": sockets or [],
+            "collider": {"type": "box", "offset": [0, 0, 0], "scale": [1, 1, 1],
+                         "isTrigger": False, "notes": "box proxy"},
+            "constraints": [],
+            "destruction": {"breakable": False, "fractureGroup": cid, "seamRefs": [],
+                            "detachableFragments": [], "breakImpulse": 0.0, "debrisMaterial": material},
+        },
+        "material": material, "materialLayers": [material], "deformations": [], "joints": [],
+        "seams": [], "localFeatures": local_features or [],
+        "surfaceDetail": {"macroRoughness": 0.0, "microRoughness": 0.0, "bumpAmplitude": 0.0,
+                          "normalPattern": "", "displacementPattern": "", "occlusionPattern": "",
+                          "edgeWearPattern": "", "notes": ""},
+        "evidenceRefs": evidence or ["full-object"], "details": [], "fidelityTier": "blockout",
+    }
+
+
+def make_character_component_tree(anatomy: dict | None = None) -> list:
+    """A stylized humanoid bust template (head/neck/torso/arms + hair, glasses, headphones,
+    face features). Head-unit driven; HU ~= 0.28 world units.
+
+    The generator nests children under a parent node whose transform (incl. scale) cascades,
+    so non-uniform parent scale would distort descendants. To avoid that, every visible part is
+    authored with a logical parent + local offset, then FLATTENED to world space and parented to
+    a hidden, unit-scaled root. Parents used for offsets (torso, head) are unrotated, so summing
+    offsets is exact. Parts use primitives the generator already supports."""
+    hu = 0.28
+    # (id, name, primitive, logical_parent, offset, scale, material, role, level, rotation, importance, features)
+    parts = [
+        ("torso", "Torso (shirt)", "capsule", "root", (0, 0.55 * hu, 0), (2.4 * hu, 2.2 * hu, 1.5 * hu), "shirt", "shell", "macro", (0, 0, 0), 1.0, []),
+        ("shirt-decal", "Chest graphic (Orioles)", "plane-card", "torso", (0, 0.1 * hu, 0.78 * hu), (1.5 * hu, 0.9 * hu, 1.0), "shirt-decal", "decal", "micro", (0, 0, 0), 0.7, ["cursive orange team wordmark with white outline"]),
+        ("neck", "Neck", "cylinder", "root", (0, 1.65 * hu, 0), (0.55 * hu, 0.7 * hu, 0.55 * hu), "skin", "support", "meso", (0, 0, 0), 0.6, []),
+        ("head", "Head", "ellipsoid", "root", (0, 2.5 * hu, 0.02 * hu), (0.92 * hu, 1.12 * hu, 0.98 * hu), "skin", "body", "macro", (0, 0, 0), 1.0, []),
+        ("hair", "Hair (side-swept)", "ellipsoid", "head", (0, 0.28 * hu, -0.04 * hu), (1.06 * hu, 0.82 * hu, 1.08 * hu), "hair", "hair", "meso", (0, 0, 0), 0.9, ["short sides, longer swept-back top"]),
+        ("hair-front", "Hair front mass", "ellipsoid", "head", (0.12 * hu, 0.34 * hu, 0.34 * hu), (0.7 * hu, 0.5 * hu, 0.6 * hu), "hair", "hair", "micro", (0, 0, 0), 0.6, []),
+        ("brow-l", "Eyebrow L", "box", "head", (0.2 * hu, 0.12 * hu, 0.46 * hu), (0.22 * hu, 0.04 * hu, 0.06 * hu), "hair", "detail", "micro", (0, 0, 0), 0.4, []),
+        ("brow-r", "Eyebrow R", "box", "head", (-0.2 * hu, 0.12 * hu, 0.46 * hu), (0.22 * hu, 0.04 * hu, 0.06 * hu), "hair", "detail", "micro", (0, 0, 0), 0.4, []),
+        ("nose", "Nose", "cone", "head", (0, -0.04 * hu, 0.5 * hu), (0.14 * hu, 0.28 * hu, 0.18 * hu), "skin", "detail", "micro", (1.4, 0, 0), 0.4, []),
+        ("mouth", "Mouth", "box", "head", (0, -0.34 * hu, 0.46 * hu), (0.24 * hu, 0.04 * hu, 0.05 * hu), "lips", "detail", "micro", (0, 0, 0), 0.4, []),
+        ("glasses-frame-l", "Glasses frame L", "torus", "head", (0.21 * hu, 0.02 * hu, 0.48 * hu), (0.26 * hu, 0.22 * hu, 0.08 * hu), "glasses-frame", "connector", "meso", (0, 0, 0), 0.85, []),
+        ("glasses-frame-r", "Glasses frame R", "torus", "head", (-0.21 * hu, 0.02 * hu, 0.48 * hu), (0.26 * hu, 0.22 * hu, 0.08 * hu), "glasses-frame", "connector", "meso", (0, 0, 0), 0.85, []),
+        ("glasses-bridge", "Glasses bridge", "box", "head", (0, 0.04 * hu, 0.5 * hu), (0.12 * hu, 0.04 * hu, 0.04 * hu), "glasses-frame", "connector", "micro", (0, 0, 0), 0.5, []),
+        ("lens-l", "Lens L", "plane-card", "head", (0.21 * hu, 0.02 * hu, 0.485 * hu), (0.22 * hu, 0.18 * hu, 1.0), "glasses-lens", "panel", "micro", (0, 0, 0), 0.5, []),
+        ("lens-r", "Lens R", "plane-card", "head", (-0.21 * hu, 0.02 * hu, 0.485 * hu), (0.22 * hu, 0.18 * hu, 1.0), "glasses-lens", "panel", "micro", (0, 0, 0), 0.5, []),
+        ("hp-band", "Headphone band", "torus", "root", (0, 1.78 * hu, 0.05 * hu), (0.95 * hu, 0.62 * hu, 0.7 * hu), "headphone", "ring", "meso", (1.2, 0, 0), 0.85, []),
+        ("hp-cup-l", "Ear cup L", "cylinder", "root", (0.5 * hu, 1.52 * hu, 0.35 * hu), (0.42 * hu, 0.28 * hu, 0.42 * hu), "headphone", "detail", "meso", (0, 0, 1.57), 0.7, []),
+        ("hp-cup-r", "Ear cup R", "cylinder", "root", (-0.5 * hu, 1.52 * hu, 0.35 * hu), (0.42 * hu, 0.28 * hu, 0.42 * hu), "headphone", "detail", "meso", (0, 0, 1.57), 0.7, []),
+        ("arm-l", "Upper arm L", "capsule", "torso", (1.15 * hu, -0.35 * hu, 0.1 * hu), (0.55 * hu, 1.5 * hu, 0.55 * hu), "shirt", "arm", "meso", (0, 0, 0.25), 0.7, []),
+        ("arm-r", "Upper arm R", "capsule", "torso", (-1.15 * hu, -0.35 * hu, 0.1 * hu), (0.55 * hu, 1.5 * hu, 0.55 * hu), "shirt", "arm", "meso", (0, 0, -0.25), 0.7, []),
+    ]
+    offsets = {"root": (0.0, 0.0, 0.0)}
+    for pid, _n, _p, parent, off, *_rest in parts:
+        offsets[pid] = off  # local offset; world resolved below
+
+    def world_pos(pid, parent, off):
+        x, y, z = off
+        cur = parent
+        # walk up the logical parent chain (parents are unrotated), summing offsets
+        while cur and cur != "root":
+            po = offsets.get(cur, (0.0, 0.0, 0.0))
+            x += po[0]; y += po[1]; z += po[2]
+            cur = parent_of.get(cur, "root")
+        return (x, y, z)
+
+    parent_of = {p[0]: p[3] for p in parts}
+    tree = [_cnode("root", "Character (root)", "box", None, (0, 0, 0), (1, 1, 1),
+                   material="hidden", role="body", level="macro", importance=1.0, anim_role="root")]
+    for pid, name, prim, parent, off, scale, mat, role, level, rot, imp, feats in parts:
+        tree.append(_cnode(pid, name, prim, "root", world_pos(pid, parent, off), scale,
+                           material=mat, role=role, level=level, rotation=rot, importance=imp,
+                           local_features=feats))
+    return tree
+
+
+def _shade_hex(hex_color: str, factor: float) -> str:
+    """Return a slightly darker/lighter shade of a #RRGGBB color (factor<1 darker)."""
+    h = hex_color.lstrip("#")
+    if len(h) != 6:
+        return hex_color
+    r, g, b = (int(h[i:i + 2], 16) for i in (0, 2, 4))
+    r, g, b = (max(0, min(255, round(c * factor))) for c in (r, g, b))
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
+CHARACTER_MATERIALS = [
+    {"id": "hidden", "baseColor": "#000000", "roughness": {"base": 1.0, "variation": 0.0}, "opacity": {"base": 0.0}},
+    {"id": "skin", "baseColor": "#e8b98f", "roughness": {"base": 0.55, "variation": 0.08}},
+    {"id": "hair", "baseColor": "#171310", "roughness": {"base": 0.42, "variation": 0.1}},
+    {"id": "shirt", "baseColor": "#20202a", "roughness": {"base": 0.85, "variation": 0.12}},
+    {"id": "shirt-decal", "baseColor": "#d24a20", "roughness": {"base": 0.7, "variation": 0.05}},
+    {"id": "glasses-frame", "baseColor": "#111114", "roughness": {"base": 0.35, "variation": 0.05}},
+    {"id": "glasses-lens", "baseColor": "#a9c6d8", "roughness": {"base": 0.08, "variation": 0.02}},
+    {"id": "headphone", "baseColor": "#0e0e10", "roughness": {"base": 0.5, "variation": 0.08}},
+    {"id": "lips", "baseColor": "#c98070", "roughness": {"base": 0.5, "variation": 0.05}},
+]
+
+
+def make_character_build_passes() -> list:
+    base = make_pre_spec_assessment  # noqa: reference to keep import graph obvious
+    passes = [
+        {"id": "blockout", "goal": "Match head-unit proportions and pose silhouette.",
+         "componentRefs": ["root"], "acceptance": ["Bust proportions and 3/4 pose read correctly without materials."]},
+        {"id": "proportion-lock", "goal": "Lock head/torso/limb head-unit ratios and pose angles.",
+         "componentRefs": ["root", "head", "torso"], "acceptance": ["Head-unit ratios match anatomy; silhouette matches reference."]},
+        {"id": "feature-placement", "goal": "Place facial features, hair, glasses, headphones to landmarks.",
+         "componentRefs": ["head", "hair", "glasses-frame-l", "hp-band"],
+         "acceptance": ["Eyeline/nose/mouth on landmark lines; glasses and headphones placed as in reference."]},
+        {"id": "material-pass", "goal": "Match skin/hair/cloth/metal color and roughness.",
+         "componentRefs": ["root"], "acceptance": ["Skin, hair, shirt, decal, glasses, headphone materials match reference palette."]},
+        {"id": "lighting-pass", "goal": "Soft key from reference direction plus rim.",
+         "componentRefs": ["root"], "acceptance": ["Readable under neutral light; reference-matched lighting added."]},
+        {"id": "interaction-pass", "goal": "Rig-ready pivots and sockets.",
+         "componentRefs": ["root"], "acceptance": ["Head/neck/arm pivots and face socket exposed."]},
+        {"id": "optimization-pass", "goal": "Protect runtime performance.",
+         "componentRefs": ["root"], "acceptance": ["Triangle/draw-call budget documented."]},
+    ]
+    del base
+    return passes
+
+
+def make_character_feature_targets() -> list:
+    return [
+        {"id": "anatomy-proportion", "name": "Head-unit proportions and pose", "tier": "critical",
+         "passIds": ["blockout", "proportion-lock"], "minimumScore": 0.78, "mustPass": True,
+         "componentRefs": ["root", "head", "torso"], "evidenceRefs": ["full-object"]},
+        {"id": "face-landmark-placement", "name": "Face landmarks + glasses placement", "tier": "critical",
+         "passIds": ["feature-placement"], "minimumScore": 0.75, "mustPass": True,
+         "componentRefs": ["head", "glasses-frame-l"], "evidenceRefs": ["full-object"]},
+        {"id": "pose-silhouette", "name": "Pose and bust silhouette", "tier": "critical",
+         "passIds": ["blockout", "proportion-lock"], "minimumScore": 0.75, "mustPass": True,
+         "componentRefs": ["root", "arm-l"], "evidenceRefs": ["full-object"]},
+        {"id": "outfit-and-palette", "name": "Outfit + accessories + palette", "tier": "important",
+         "passIds": ["material-pass"], "minimumScore": 0.7, "mustPass": False,
+         "componentRefs": ["shirt-decal", "headphone", "glasses-frame-l"], "evidenceRefs": ["full-object"]},
+    ]
+
+
+def apply_character_template(spec: dict, anatomy: dict | None = None) -> dict:
+    """Swap in the humanoid componentTree, character materials, build passes, and feature
+    targets. Object specs are untouched; only called when primaryDomain is character/hybrid."""
+    spec["componentTree"] = make_character_component_tree(anatomy)
+    existing = {m.get("id"): m for m in spec.get("materials", []) if isinstance(m, dict)}
+    for mat in CHARACTER_MATERIALS:
+        merged = dict(existing.get("base", {}))
+        merged.update(mat)
+        merged.setdefault("name", mat["id"])
+        merged.setdefault("type", "standard")
+        # the generator colours meshes from `color`/`albedo`, so keep them in sync with baseColor
+        base_color = mat.get("baseColor")
+        if base_color:
+            shade = _shade_hex(base_color, 0.82)
+            merged["color"] = base_color
+            # the generator only honours a palette with >= 2 entries (else it blends in beige
+            # fallback tones), so provide two near-identical shades of the intended colour.
+            merged["albedo"] = {"dominant": base_color, "secondary": [shade]}
+            merged["colorVariation"] = {"palette": [base_color, shade], "pattern": "flat",
+                                         "amplitude": 0.05, "heightCorrelation": 0.0}
+        existing[mat["id"]] = merged
+    spec["materials"] = list(existing.values())
+    spec["buildPasses"] = make_character_build_passes()
+    # A humanoid is reviewed as a whole each pass, so every pass renders all parts
+    # (unlike the object pipeline where passes add parts incrementally).
+    all_ids = [c["id"] for c in spec["componentTree"] if isinstance(c, dict) and c.get("id")]
+    for build_pass in spec["buildPasses"]:
+        build_pass["componentRefs"] = all_ids
+    spec["featureReviewTargets"] = make_character_feature_targets()
+    pipeline = spec.setdefault("sculptPipeline", {})
+    pipeline["passOrder"] = [p["id"] for p in spec["buildPasses"]]
+    pipeline["currentPass"] = "blockout"
+    return spec
+
+
+def make_spec(target_name: str, image: str | None, assessment_payload: dict | None = None) -> dict:
+    target_id = slugify(target_name)
+    pre_spec_assessment = make_pre_spec_assessment(target_name)
+    quality_contract = make_quality_contract()
+    if assessment_payload:
+        incoming_assessment = assessment_payload.get("preSpecAssessment")
+        incoming_contract = assessment_payload.get("qualityContract")
+        if isinstance(incoming_assessment, dict):
+            pre_spec_assessment = incoming_assessment
+        if isinstance(incoming_contract, dict):
+            quality_contract = incoming_contract
+    return {
+        "targetName": target_name,
+        "targetId": target_id,
+        "schemaVersion": "2.0",
+        "terminologyProfile": {
+            "domain": "real-time procedural Three.js asset",
+            "geometryTerms": [
+                "silhouette",
+                "topology",
+                "primitive",
+                "bevel",
+                "chamfer",
+                "taper",
+                "bend",
+                "boolean cut",
+                "edge loop",
+                "surface normal",
+                "displacement",
+            ],
+            "materialTerms": [
+                "albedo",
+                "baseColor",
+                "roughness",
+                "metalness",
+                "normal map",
+                "bump map",
+                "ambient occlusion",
+                "cavity dirt",
+                "edge wear",
+                "clearcoat",
+            ],
+            "lightingTerms": [
+                "key light",
+                "fill light",
+                "rim light",
+                "HDRI/environment reflection",
+                "contact shadow",
+            ],
+            "descriptionRule": "Use measurable 3D graphics terms. Avoid vague words unless they are paired with concrete geometry/material/shader parameters.",
+        },
+        "sourceImage": image or "",
+        "referenceCamera": {
+            "solved": False,
+            "fovDegrees": 40.0,
+            "aspect": 1.0,
+            "orientation": {"yaw": 0.0, "pitch": 0.0, "roll": 0.0},
+            "positionHint": [0.0, 0.0, 3.0],
+            "note": (
+                "For likeness work, solve the reference camera (forge/stage1_intake/solve_camera_pose.py) so the "
+                "review render aligns with the photo and the reference can be projected. Confirm by overlay review."
+            ),
+        },
+        "suitability": "conditional",
+        "scores": {
+            "object_isolation": 0,
+            "silhouette_readability": 0,
+            "depth_inference": 0,
+            "primitive_decomposition": 0,
+            "material_procedurality": 0,
+            "occlusion_risk": 0,
+            "interaction_fit": 0,
+        },
+        "preSpecAssessment": pre_spec_assessment,
+        "qualityContract": quality_contract,
+        "qualityTargets": {
+            "targetFidelity": 0.7,
+            "mustMatch": [
+                "macro silhouette and proportions",
+                "primary material albedo/roughness response",
+                "reference-derived PBR material response at or above 0.7 confidence when source pixels are usable",
+                "most recognizable local features",
+            ],
+            "niceToHave": [
+                "micro scratches, stains, chips, and dirt masks",
+                "secondary lighting match",
+            ],
+            "fpsTarget": 60,
+            "reviewViewpoints": ["front", "three-quarter", "side"],
+        },
+        "selfCorrectLoop": {
+            "enabled": True,
+            "visualAcceptance": {
+                "reviewer": "ai-vision",
+                "threshold": 0.7,
+                "comparisonArtifactRequired": True,
+                "layerScoresRequired": True,
+                "codePixelDiffIsAcceptanceAuthority": False,
+                "scoringRule": "AI vision must inspect a side-by-side reference/render sheet and score the current pass from 0 to 1. Pixel-diff code may assist diagnostics but cannot approve a pass.",
+                "requiredLayerScores": [
+                    "silhouetteProportion",
+                    "componentStructure",
+                    "formDetail",
+                    "materialSurface",
+                    "lightingCamera",
+                ],
+                "featureReviewPolicy": {
+                    "enabled": True,
+                    "reviewUnit": "semantic-subsystem",
+                    "maxCriticalFeaturesPerPass": 5,
+                    "maxImportantFeaturesPerPass": 3,
+                    "criticalDefaultThreshold": 0.8,
+                    "importantAverageThreshold": 0.65,
+                    "adaptiveEscalation": True,
+                    "singleImagePairOnly": True,
+                    "selectionRule": "Choose only the most visually salient, identity-defining, user-prioritized, or high-risk semantic systems. Group repeated parts instead of reviewing every mesh. AI vision scores every selected feature from the same full reference/render pair.",
+                },
+            },
+            "reviewAfterPasses": [
+                "blockout",
+                "structural-pass",
+                "form-refinement",
+                "material-pass",
+                "surface-pass",
+                "lighting-pass",
+                "interaction-pass",
+                "optimization-pass",
+            ],
+            "allowedActions": [
+                "continue",
+                "refine-spec",
+                "refine-code",
+                "request-input",
+                "stop",
+            ],
+            "specRefineTriggers": [
+                "missing component",
+                "wrong primitive family",
+                "wrong proportions",
+                "material layer under-specified",
+                "local feature not traceable to viewEvidence",
+                "reference ambiguity discovered during implementation",
+            ],
+            "codeRefineTriggers": [
+                "spec is adequate but generated geometry/material does not match",
+                "browser render differs from reference",
+                "performance budget exceeded",
+                "lighting hides geometry or material response",
+            ],
+            "stopCriteria": [
+                "target fidelity reached or user accepts current approximation",
+                "remaining gaps require new reference images or manual art",
+            ],
+            "screenshotPolicy": {
+                "requiredForPasses": [
+                    "blockout",
+                    "structural-pass",
+                    "form-refinement",
+                    "material-pass",
+                    "surface-pass",
+                    "lighting-pass",
+                    "interaction-pass",
+                ],
+                "preferredCapture": "in-app-browser-screenshot",
+                "fallbackCapture": "user-supplied-screenshot-path",
+                "minimumEvidence": "Each visual pass needs a reference image, rendered screenshot, side-by-side comparison sheet, AI vision score, layer scores, and critique before choosing continue.",
+                "reviewPairRule": "Compare the same camera/viewpoint whenever possible; do not judge a front reference against a random render angle.",
+                "acceptanceAuthority": "AI vision review of the comparison sheet. Code-generated pixel similarity is not sufficient evidence.",
+            },
+        },
+        "featureReviewTargets": [
+            {
+                "id": "overall-silhouette",
+                "name": "Overall silhouette and proportion system",
+                "tier": "critical",
+                "passIds": ["blockout"],
+                "minimumScore": 0.8,
+                "mustPass": True,
+                "componentRefs": ["root"],
+                "evidenceRefs": ["full-object"],
+            },
+            {
+                "id": "primary-structure",
+                "name": "Primary identity-defining structure",
+                "tier": "critical",
+                "passIds": ["structural-pass", "form-refinement"],
+                "minimumScore": 0.8,
+                "mustPass": True,
+                "componentRefs": ["root"],
+                "evidenceRefs": ["full-object"],
+            },
+            {
+                "id": "reference-material-system",
+                "name": "Primary reference material and surface response",
+                "tier": "critical",
+                "passIds": ["material-pass", "surface-pass"],
+                "minimumScore": 0.75,
+                "mustPass": True,
+                "componentRefs": ["root"],
+                "evidenceRefs": ["full-object"],
+            },
+        ],
+        "sculptPipeline": {
+            "passGateMode": "locked-sequential",
+            "passOrder": [
+                "blockout",
+                "structural-pass",
+                "form-refinement",
+                "material-pass",
+                "surface-pass",
+                "lighting-pass",
+                "interaction-pass",
+                "optimization-pass",
+            ],
+            "currentPass": "blockout",
+            "completedPasses": [],
+            "lastCompletedPass": "",
+            "blockedReason": "blockout requires a browser screenshot and self-correction review before structural-pass unlocks",
+            "nextRequiredEvidence": [
+                "blockout browser render screenshot from your agent's browser/screenshot tool",
+                "side-by-side reference/render comparison sheet",
+                "AI vision score >= 0.7 with layer scores and mismatch critique",
+                "critical semantic feature scores from the same image pair meeting their individual thresholds",
+                "reviewHistory entry for blockout with action=continue",
+            ],
+        },
+        "lookDevTargets": {
+            "qualityPriority": "reference-fidelity",
+            "materialPass": {
+                "albedoPaletteRequired": True,
+                "roughnessVariationRequired": True,
+                "normalOrBumpRequired": True,
+                "localOverridesRequired": True,
+                "minimumTextureResolution": 1024,
+                "preferredTextureResolution": 2048,
+                "independentMapChannels": [
+                    "albedo",
+                    "roughness",
+                    "height",
+                    "normal",
+                    "ambient-occlusion",
+                ],
+                "requiredSurfaceFrequencyBands": ["macro", "meso", "micro"],
+                "geometryReliefRequiredWhenSilhouetteAffected": True,
+                "referencePbrExtraction": {
+                    "requiredWhenSourceImagePresent": True,
+                    "targetThreshold": 0.7,
+                    "stopOnLowConfidence": True,
+                    "script": "forge/stage1_intake/extract_pbr_evidence.py",
+                    "acceptedLimitation": "single-image extraction is reference-derived inference, not exact photogrammetry",
+                },
+                "mustAvoid": [
+                    "single flat albedo per material",
+                    "uniform roughness",
+                    "albedo texture reused as roughness/height/normal/AO",
+                    "single-frequency random noise",
+                    "plastic-looking smooth bark, stone, cloth, foliage, or aged material",
+                    "local color/detail described only in prose without material masks",
+                    "claiming exact PBR recovery when confidence is below the target threshold",
+                ],
+            },
+            "lightingPass": {
+                "requiredTerms": [
+                    "key light",
+                    "fill light",
+                    "rim or environment light",
+                    "exposure",
+                    "tone mapping",
+                    "background",
+                    "contact shadow",
+                ],
+                "mustAvoid": [
+                    "ambient-only lighting",
+                    "flat value range",
+                    "missing contact shadow",
+                    "reference lighting copied without separating material readability",
+                ],
+            },
+            "screenshotReview": [
+                "Compare albedo palette and local color zones.",
+                "Compare roughness/normal/bump response under light.",
+                "Compare cavity dirt, edge wear, stains, moss, scratches, or other local masks.",
+                "Compare key/fill/rim structure, exposure, tone mapping, background, and contact shadows.",
+                "Capture a neutral-light render to verify material readability without reference lighting.",
+                "Capture a grazing-light close-up to expose flat normals, uniform roughness, tiling, and plastic highlights.",
+                "Capture a reference-matched render from the same camera framing as the source.",
+            ],
+        },
+        "actionReadiness": {
+            "contract": "Every macro/meso component should be generated as a stable named Object3D pivot node with a mesh child, action metadata, optional sockets, collider proxy, and destruction metadata.",
+            "defaultRigType": "action-ready-static-rig",
+            "rootMotionNode": "root",
+            "requiredComponentFields": [
+                "id",
+                "parent",
+                "transform",
+                "attachment for child appendages, connectors, limbs, tubes, handles, legs, horns, wings, branches, or cables",
+                "actionProfile.animationRole",
+                "actionProfile.pivot",
+                "actionProfile.collider",
+                "actionProfile.destruction",
+            ],
+            "transformChannels": [
+                "translate",
+                "rotate",
+                "scale",
+                "bend",
+                "twist",
+                "detach",
+                "visibility",
+                "material-state",
+            ],
+            "authoringRules": [
+                "Do not collapse independently movable parts into one mesh.",
+                "Put transforms on component pivot groups, not only on raw meshes.",
+                "For attached child parts, put the pivot at the semantic root/socket and build visible geometry from localStart to localEnd.",
+                "Represent hinge, socket, detachable, and breakable intent even when no animation is implemented yet.",
+                "Use simplified collider proxies for runtime physics instead of visual mesh colliders by default.",
+            ],
+            "destructionPolicy": {
+                "defaultBreakable": False,
+                "fractureGroupNaming": "Use stable semantic names such as body-shell, left-hinge, glass-panel, branch-segment.",
+                "debrisStrategy": "Prefer detachable component groups and a small number of procedural fragments over random mesh explosion.",
+            },
+        },
+        "assumptions": [],
+        "coordinateFrame": {
+            "front": "camera-facing side in the reference image",
+            "up": "image up direction",
+            "scaleReference": "unit scale; adjust after first browser render",
+        },
+        "silhouette": {
+            "boundingShape": "",
+            "aspectRatios": [],
+            "symmetry": "",
+            "dominantCurves": [],
+            "negativeSpaces": [],
+            "landmarks": [],
+        },
+        "viewEvidence": [
+            {
+                "id": "full-object",
+                "view": "primary",
+                "imageRegion": {
+                    "x": 0.0,
+                    "y": 0.0,
+                    "width": 1.0,
+                    "height": 1.0,
+                    "units": "normalized",
+                },
+                "observations": [],
+                "confidence": 0.5,
+            }
+        ],
+        "componentTree": [
+            {
+                "id": "root",
+                "name": target_name,
+                "level": "macro",
+                "role": "body",
+                "importance": 1.0,
+                "confidence": 0.5,
+                "primitive": "box",
+                "geometryDescriptor": {
+                    "topologyIntent": "low-poly blockout with bevel-ready edges",
+                    "edgeTreatment": {
+                        "type": "none",
+                        "bevelRadius": 0.0,
+                        "segments": 1,
+                    },
+                    "deformationStack": [],
+                    "uvStrategy": "generated procedural coordinates",
+                    "normalStrategy": "vertex normals from generated geometry",
+                },
+                "parent": None,
+                "attachment": None,
+                "dimensions": {
+                    "width": 1.0,
+                    "height": 1.0,
+                    "depth": 1.0,
+                    "units": "relative",
+                    "confidence": 0.5,
+                },
+                "transform": {
+                    "position": [0, 0, 0],
+                    "rotation": [0, 0, 0],
+                    "scale": [1, 1, 1],
+                },
+                "actionProfile": {
+                    "animationRole": "root",
+                    "pivot": {
+                        "mode": "center",
+                        "localPosition": [0, 0, 0],
+                        "axis": [0, 1, 0],
+                        "confidence": 0.5,
+                    },
+                    "transformChannels": {
+                        "translate": True,
+                        "rotate": True,
+                        "scale": True,
+                        "bend": False,
+                        "twist": False,
+                        "detach": False,
+                        "visibility": True,
+                        "materialState": True,
+                    },
+                    "sockets": [],
+                    "collider": {
+                        "type": "box",
+                        "offset": [0, 0, 0],
+                        "scale": [1, 1, 1],
+                        "isTrigger": False,
+                        "notes": "Replace with sphere/capsule/compound proxy when the object shape demands it.",
+                    },
+                    "constraints": [],
+                    "destruction": {
+                        "breakable": False,
+                        "fractureGroup": "root",
+                        "seamRefs": [],
+                        "detachableFragments": [],
+                        "breakImpulse": 0.0,
+                        "debrisMaterial": "base",
+                    },
+                },
+                "material": "base",
+                "materialLayers": ["base"],
+                "deformations": [],
+                "joints": [],
+                "seams": [],
+                "localFeatures": [],
+                "surfaceDetail": {
+                    "macroRoughness": 0.0,
+                    "microRoughness": 0.0,
+                    "bumpAmplitude": 0.0,
+                    "normalPattern": "",
+                    "displacementPattern": "",
+                    "occlusionPattern": "",
+                    "edgeWearPattern": "",
+                    "notes": "",
+                },
+                "evidenceRefs": ["full-object"],
+                "details": [],
+                "fidelityTier": "blockout",
+            }
+        ],
+        "materials": [
+            {
+                "id": "base",
+                "name": "Base material",
+                "type": "standard",
+                "shaderModel": "MeshStandardMaterial / PBR approximation",
+                "baseColor": "#8A7A5F",
+                "color": "#8A7A5F",
+                "albedo": {
+                    "dominant": "#8A7A5F",
+                    "secondary": ["#6E614B", "#A08F70"],
+                    "samplingNotes": "Use image-observed local color zones, not a single averaged color.",
+                },
+                "colorVariation": {
+                    "palette": ["#8A7A5F", "#6E614B", "#A08F70"],
+                    "pattern": "mottled",
+                    "amplitude": 0.15,
+                    "heightCorrelation": 0.3,
+                },
+                "textureResolution": 1024,
+                "textureProjection": {
+                    "mode": "uv",
+                    "repeat": [2.0, 2.0],
+                    "anisotropy": 8,
+                    "texelDensityIntent": "Preserve stable world/object-scale detail; do not stretch micro detail with component scale.",
+                },
+                "surfaceFrequencyBands": [
+                    {
+                        "id": "macro",
+                        "frequency": 2.0,
+                        "amplitude": 0.42,
+                        "role": "broad color and height breakup",
+                    },
+                    {
+                        "id": "meso",
+                        "frequency": 12.0,
+                        "amplitude": 0.22,
+                        "role": "ridges, pores, grain, dents, or equivalent visible relief",
+                    },
+                    {
+                        "id": "micro",
+                        "frequency": 56.0,
+                        "amplitude": 0.08,
+                        "role": "highlight breakup visible under grazing light",
+                    },
+                ],
+                "roughness": {
+                    "base": 0.75,
+                    "variation": 0.15,
+                    "map": "independent-procedural-field",
+                    "localResponse": "higher roughness in cavities, lower roughness on worn edges",
+                },
+                "metalness": {
+                    "base": 0.0,
+                    "variation": 0.0,
+                },
+                "normal": {
+                    "pattern": "derived-from-independent-height-field",
+                    "strength": 0.35,
+                    "scale": 24.0,
+                    "space": "tangent",
+                },
+                "bump": {
+                    "pattern": "none",
+                    "amplitude": 0.0,
+                    "scale": 1.0,
+                },
+                "displacement": {
+                    "pattern": "none",
+                    "amplitude": 0.0,
+                    "scale": 1.0,
+                    "silhouetteAffects": False,
+                },
+                "ambientOcclusion": {
+                    "cavityStrength": 0.25,
+                    "contactShadowBias": 0.35,
+                    "notes": "Darken creases, seams, intersections, and recessed local features.",
+                },
+                "wear": {
+                    "edgeWear": 0.0,
+                    "scratches": [],
+                    "chips": [],
+                },
+                "dirt": {
+                    "amount": 0.0,
+                    "cavityBias": 0.0,
+                    "color": "#2F2A22",
+                },
+                "localOverrides": [],
+                "shaderNotes": [
+                    "Prefer MeshPhysicalMaterial when clearcoat, sheen, transmission, or thin-surface response is observed; otherwise use MeshStandardMaterial-compatible PBR channels.",
+                    "Generate albedo, roughness, height/normal, and AO independently; never alias albedo into roughness.",
+                    "Use normal/bump/displacement only when they map to observed surface relief.",
+                    "Use displacement geometry when the observed relief changes the close-up silhouette; texture-only relief is insufficient there.",
+                ],
+                "notes": "Replace with image-derived color, roughness, noise, and edge-wear notes.",
+            }
+        ],
+        "repetitionSystems": [],
+        "buildPasses": [
+            {
+                "id": "blockout",
+                "goal": "Match macro silhouette and proportions.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "Silhouette reads correctly without materials.",
+                    "Quality contract has named all required macro feature groups before code generation.",
+                    "AI vision comparison score meets selfCorrectLoop.visualAcceptance.threshold.",
+                ],
+            },
+            {
+                "id": "structural-pass",
+                "goal": "Build the component hierarchy implied by the pre-spec complexity assessment.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "Macro, meso, and repeated structures meet qualityContract.minimumSpecDepth.",
+                    "Parent-child relations, joints, seams, sockets, and contact points are explicit.",
+                    "Every attached child appendage/connector has parentSocket, localStart/localEnd, contactType, embedDepth or overlap, and gapTolerance.",
+                    "AI vision comparison score meets selfCorrectLoop.visualAcceptance.threshold.",
+                ],
+            },
+            {
+                "id": "form-refinement",
+                "goal": "Refine shape, deformation, bevels, tapers, curves, asymmetry, and visible local geometry.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "Important visible forms are represented in component geometryDescriptor, deformations, localFeatures, or repetitionSystems.",
+                    "Endpoint-based child parts are rooted at their attachment sockets and do not visibly float away from parents.",
+                    "AI vision comparison score meets selfCorrectLoop.visualAcceptance.threshold.",
+                ],
+            },
+            {
+                "id": "material-pass",
+                "goal": "Match material color, roughness, bump, and local variation.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "Reference-derived albedo palette records dominant, secondary, and accent colors per visible material.",
+                    "Each important material defines roughness variation and at least one normal/bump/displacement response.",
+                    "Local material overrides, dirt/wear/stains/moss/chips/scratches or equivalent masks are tied to evidenceRefs.",
+                    "Thin, transparent, reflective, wet, or fibrous materials document alpha/transmission/clearcoat/metalness/fiber response when relevant.",
+                    "Generated preview uses procedural albedo/roughness/bump texture or vertex color variation instead of one flat color.",
+                    "Generated preview uses independent PBR maps at 1024px or higher for the quality-first tier.",
+                    "If source pixels are available, referencePbr extraction passed at confidence >= 0.7 or the pass is stopped/requesting better references.",
+                    "Macro, meso, and micro surface frequency bands are visible at the intended review distance without obvious tiling.",
+                    "AI vision comparison score meets selfCorrectLoop.visualAcceptance.threshold.",
+                ],
+            },
+            {
+                "id": "surface-pass",
+                "goal": "Add procedural surface locality such as normal/bump/displacement, AO, dirt, stains, chips, grain, moss, scratches, and wear.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "Every required material feature group has local overrides or surfaceDetail tied to evidenceRefs.",
+                    "A grazing-angle close-up proves that normal/height detail breaks highlights naturally and does not read as smooth plastic.",
+                    "AI vision comparison score meets selfCorrectLoop.visualAcceptance.threshold.",
+                ],
+            },
+            {
+                "id": "lighting-pass",
+                "goal": "Make material and form readable under neutral turntable lighting plus optional reference lighting.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "lightingFromPhoto identifies key light direction/color/intensity, fill light, rim or environment light, and ambient color.",
+                    "Exposure, tone mapping, background color/gradient, shadow softness, and contact shadow behavior are specified.",
+                    "Lighting does not hide geometry/material gaps and screenshots can be compared fairly to the reference.",
+                    "Neutral, grazing, and reference-matched lighting checks distinguish material errors from lighting errors.",
+                    "AI vision comparison score meets selfCorrectLoop.visualAcceptance.threshold.",
+                ],
+            },
+            {
+                "id": "interaction-pass",
+                "goal": "Make the model ready for future animation, transformation, physics, or destruction.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "Macro and movable meso components have stable pivot nodes.",
+                    "Sockets, collider proxies, and destruction metadata are present for future runtime actions.",
+                    "AI vision comparison score meets selfCorrectLoop.visualAcceptance.threshold.",
+                ],
+            },
+            {
+                "id": "optimization-pass",
+                "goal": "Protect runtime performance after visual fidelity is accepted.",
+                "componentRefs": ["root"],
+                "acceptance": [
+                    "Triangle count, draw calls, instancing, LOD strategy, and FPS target are documented or verified.",
+                    "Repeated detail is instanced or simplified where possible without breaking silhouette/material believability.",
+                ],
+            },
+        ],
+        "visualEvidence": [],
+        "reviewHistory": [],
+        "lodPlan": [
+            {
+                "tier": "near",
+                "distance": 0,
+                "strategy": "full component tree and material layers",
+            },
+            {
+                "tier": "far",
+                "distance": 30,
+                "strategy": "merge static components and reduce local feature geometry",
+            },
+        ],
+        "performanceBudget": {
+            "qualityPriority": "reference-fidelity",
+            "targetTriangles": 250000,
+            "maxDrawCalls": 160,
+            "textureSize": 2048,
+            "fpsTarget": 30,
+            "optimizationPolicy": "Reach accepted visual fidelity first, then optimize without removing reference-critical geometry or surface layers.",
+        },
+        "lightingFromPhoto": [],
+        "proceduralStrategy": [
+            "Block out macro silhouette first.",
+            "Add component hierarchy and joints.",
+            "Create stable pivot groups, sockets, collider proxies, and destruction metadata before visual polish.",
+            "Refine forms with bevels, tapers, bends, and procedural noise.",
+            "Run reference PBR extraction for important source-image materials and stop when confidence is below the target threshold.",
+            "Add material variation before adding expensive micro-geometry.",
+        ],
+        "animationAnchors": [
+            "root pivot node supports whole-object translation, rotation, scale, and visibility changes",
+            "component pivot groups support later local transforms without rebuilding geometry",
+        ],
+        "destructionAnchors": [
+            "actionProfile.destruction.fractureGroup marks detachable or breakable component sets",
+            "component seams and sockets define plausible break points instead of random explosions",
+        ],
+        "risks": [],
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("target_name", help="Human-readable object name")
+    parser.add_argument("--image", help="Reference image path or URL")
+    parser.add_argument("--assessment", type=Path, help="Pre-spec assessment JSON from stage2_spec/new_pre_spec_assessment.py")
+    parser.add_argument("--out", type=Path, help="Output JSON path")
+    parser.add_argument("--force", action="store_true", help="Overwrite output file")
+    parser.add_argument("--character", action="store_true",
+                        help="Use the humanoid character template (auto-enabled when the assessment primaryDomain is character/hybrid)")
+    args = parser.parse_args(argv)
+
+    assessment = load_assessment(args.assessment)
+    spec = make_spec(args.target_name, args.image, assessment)
+    domain = None
+    if isinstance(assessment, dict):
+        pre = assessment.get("preSpecAssessment", {})
+        oc = pre.get("objectClass", {}) if isinstance(pre, dict) else {}
+        domain = oc.get("primaryDomain") if isinstance(oc, dict) else None
+    if args.character or domain in {"character", "hybrid"}:
+        anatomy = None
+        if isinstance(assessment, dict) and isinstance(assessment.get("preSpecAssessment"), dict):
+            anatomy = assessment["preSpecAssessment"].get("anatomy")
+        apply_character_template(spec, anatomy)
+    payload = json.dumps(spec, indent=2, ensure_ascii=False) + "\n"
+
+    if args.out:
+        output = args.out.expanduser().resolve()
+        if output.exists() and not args.force:
+            parser.error(f"{output} already exists; use --force to overwrite")
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(payload, encoding="utf-8")
+        print(output)
+    else:
+        print(payload, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage2_spec/validate_sculpt_spec.py

@@ -0,0 +1,1730 @@
+#!/usr/bin/env python3
+"""Validate an ObjectSculptSpec JSON file for procedural Three.js generation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_shared"))
+from feature_acceptance_policy import feature_gate_failures, feature_review_policy
+
+
+REQUIRED_TOP_LEVEL = {
+    "targetName": str,
+    "suitability": str,
+    "coordinateFrame": dict,
+    "silhouette": dict,
+    "componentTree": list,
+    "materials": list,
+    "proceduralStrategy": list,
+}
+VALID_SUITABILITY = {"pass", "conditional", "reject"}
+VALID_PRIMITIVES = {
+    "box",
+    "sphere",
+    "ellipsoid",
+    "cylinder",
+    "cone",
+    "capsule",
+    "torus",
+    "tube",
+    "lathe",
+    "extrude",
+    "curve-sweep",
+    "plane-card",
+    "instanced-cluster",
+}
+VALID_COMPONENT_LEVELS = {"macro", "meso", "micro"}
+VALID_COMPLEXITY_TIERS = {"unassessed", "simple", "moderate", "complex", "ultra-complex"}
+TERMINOLOGY_LIST_FIELDS = {"geometryTerms", "materialTerms", "lightingTerms"}
+VALID_REVIEW_ACTIONS = {"continue", "refine-spec", "refine-code", "request-input", "stop"}
+VISUAL_PASS_IDS = {
+    "blockout",
+    "structural-pass",
+    "form-refinement",
+    "material-pass",
+    "surface-pass",
+    "lighting-pass",
+    "interaction-pass",
+}
+VALID_PIPELINE_PASS_IDS = VISUAL_PASS_IDS | {"optimization-pass"}
+ATTACHMENT_ROLES = {
+    "appendage",
+    "branch",
+    "limb",
+    "arm",
+    "leg",
+    "handle",
+    "connector",
+    "tube",
+    "cable",
+    "horn",
+    "wing",
+    "tail",
+    "root",
+    "fork",
+    "rib",
+    "support",
+    "hinge",
+    "socket",
+    "pipe",
+}
+ATTACHMENT_PRIMITIVES = {"cylinder", "cone", "capsule", "tube", "curve-sweep"}
+
+
+def is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def validate_unit_interval(value: Any, label: str, errors: list[str]) -> None:
+    if not is_number(value) or value < 0 or value > 1:
+        errors.append(f"{label} must be a number from 0 to 1")
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"invalid JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("spec must be a JSON object")
+    return payload
+
+
+def as_number_list(value: Any, length: int) -> bool:
+    return (
+        isinstance(value, list)
+        and len(value) == length
+        and all(isinstance(item, (int, float)) for item in value)
+    )
+
+
+def validate_score_block(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    scores = spec.get("scores")
+    if scores is None:
+        warnings.append("missing scores block; image validation evidence will be weaker")
+        return
+    if not isinstance(scores, dict):
+        errors.append("scores must be an object")
+        return
+    for key, value in scores.items():
+        if not isinstance(value, int) or value < 0 or value > 3:
+            errors.append(f"score {key!r} must be an integer from 0 to 3")
+
+
+def validate_nonnegative_int(value: Any, label: str, errors: list[str]) -> None:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        errors.append(f"{label} must be a non-negative integer")
+
+
+def validate_pre_spec_assessment(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    assessment = spec.get("preSpecAssessment")
+    if assessment is None:
+        warnings.append("quality: missing preSpecAssessment; spec may be shallow because complexity was not assessed first")
+        return
+    if not isinstance(assessment, dict):
+        errors.append("preSpecAssessment must be an object")
+        return
+    object_class = assessment.get("objectClass")
+    if not isinstance(object_class, dict):
+        errors.append("preSpecAssessment.objectClass must be an object")
+    else:
+        primary_type = object_class.get("primaryType")
+        if primary_type is not None and not isinstance(primary_type, str):
+            errors.append("preSpecAssessment.objectClass.primaryType must be a string")
+        if primary_type in {None, "", "unassessed"}:
+            warnings.append("quality: preSpecAssessment.objectClass.primaryType is unassessed")
+        for field in ("formLanguage", "structureKind", "motionPotential", "materialFamilies"):
+            validate_string_array(object_class.get(field), f"preSpecAssessment.objectClass.{field}", errors)
+            if isinstance(object_class.get(field), list) and not object_class[field]:
+                warnings.append(f"quality: preSpecAssessment.objectClass.{field} is empty")
+    complexity = assessment.get("complexity")
+    if not isinstance(complexity, dict):
+        errors.append("preSpecAssessment.complexity must be an object")
+    else:
+        tier = complexity.get("tier")
+        if tier not in VALID_COMPLEXITY_TIERS:
+            errors.append(f"preSpecAssessment.complexity.tier must be one of: {', '.join(sorted(VALID_COMPLEXITY_TIERS))}")
+        if tier == "unassessed":
+            warnings.append("quality: preSpecAssessment.complexity.tier is unassessed")
+        scores = complexity.get("scores")
+        if not isinstance(scores, dict):
+            errors.append("preSpecAssessment.complexity.scores must be an object")
+        else:
+            for key, value in scores.items():
+                if not isinstance(value, int) or value < 0 or value > 3:
+                    errors.append(f"preSpecAssessment.complexity.scores.{key} must be an integer from 0 to 3")
+        estimated = complexity.get("estimatedCounts")
+        if not isinstance(estimated, dict):
+            errors.append("preSpecAssessment.complexity.estimatedCounts must be an object")
+        else:
+            for field in ("macroComponents", "mesoComponents", "microFeatureGroups", "materialLayers", "repetitionSystems"):
+                if field in estimated:
+                    validate_nonnegative_int(estimated[field], f"preSpecAssessment.complexity.estimatedCounts.{field}", errors)
+        validate_string_array(complexity.get("reasoning"), "preSpecAssessment.complexity.reasoning", errors)
+    decision = assessment.get("specDepthDecision")
+    if not isinstance(decision, dict):
+        errors.append("preSpecAssessment.specDepthDecision must be an object")
+    else:
+        required_depth = decision.get("requiredDepth")
+        if required_depth not in VALID_COMPLEXITY_TIERS:
+            errors.append("preSpecAssessment.specDepthDecision.requiredDepth must be a valid complexity tier")
+        if required_depth == "unassessed":
+            warnings.append("quality: preSpecAssessment.specDepthDecision.requiredDepth is unassessed")
+        validate_string_array(decision.get("minimumComponentLevels"), "preSpecAssessment.specDepthDecision.minimumComponentLevels", errors)
+        for field in (
+            "needsRepetitionSystems",
+            "needsMaterialLocalOverrides",
+            "needsMultipleReviewViews",
+            "needsActionReadyHierarchy",
+        ):
+            if field in decision and not isinstance(decision[field], bool):
+                errors.append(f"preSpecAssessment.specDepthDecision.{field} must be boolean")
+    unknowns = assessment.get("unknownsToResolveBeforeImplementation")
+    validate_string_array(unknowns, "preSpecAssessment.unknownsToResolveBeforeImplementation", errors)
+    if isinstance(unknowns, list) and unknowns:
+        warnings.append("quality: preSpecAssessment has unresolved unknowns before implementation")
+
+
+def validate_terminology_profile(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    profile = spec.get("terminologyProfile")
+    if profile is None:
+        warnings.append("missing terminologyProfile; descriptions may drift into vague non-3D language")
+        return
+    if not isinstance(profile, dict):
+        errors.append("terminologyProfile must be an object")
+        return
+    for field in TERMINOLOGY_LIST_FIELDS:
+        value = profile.get(field)
+        if value is None:
+            warnings.append(f"terminologyProfile.{field} is missing")
+            continue
+        if not isinstance(value, list) or not all(isinstance(item, str) and item.strip() for item in value):
+            errors.append(f"terminologyProfile.{field} must be an array of non-empty strings")
+    rule = profile.get("descriptionRule")
+    if rule is not None and not isinstance(rule, str):
+        errors.append("terminologyProfile.descriptionRule must be a string")
+
+
+def validate_evidence(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> set[str]:
+    refs: set[str] = set()
+    evidence = spec.get("viewEvidence", [])
+    if evidence is None:
+        return refs
+    if not isinstance(evidence, list):
+        errors.append("viewEvidence must be an array when present")
+        return refs
+    for index, item in enumerate(evidence):
+        if not isinstance(item, dict):
+            errors.append(f"viewEvidence[{index}] must be an object")
+            continue
+        evidence_id = item.get("id")
+        if not isinstance(evidence_id, str) or not evidence_id.strip():
+            errors.append(f"viewEvidence[{index}].id is required")
+            continue
+        if evidence_id in refs:
+            errors.append(f"duplicate viewEvidence id {evidence_id!r}")
+        refs.add(evidence_id)
+        confidence = item.get("confidence")
+        if confidence is not None:
+            validate_unit_interval(confidence, f"viewEvidence {evidence_id!r} confidence", errors)
+        region = item.get("imageRegion")
+        if region is not None:
+            if not isinstance(region, dict):
+                errors.append(f"viewEvidence {evidence_id!r} imageRegion must be an object")
+            else:
+                for key in ("x", "y", "width", "height"):
+                    if key in region and not is_number(region[key]):
+                        errors.append(f"viewEvidence {evidence_id!r} imageRegion.{key} must be numeric")
+    if not refs:
+        warnings.append("missing viewEvidence; local visual claims cannot be traced back to image regions")
+    return refs
+
+
+def validate_material_scalar_or_layer(value: Any, label: str, errors: list[str]) -> None:
+    if value is None:
+        return
+    if is_number(value):
+        return
+    if not isinstance(value, dict):
+        errors.append(f"{label} must be a number or object")
+        return
+    base = value.get("base")
+    if base is not None and not is_number(base):
+        errors.append(f"{label}.base must be numeric")
+    variation = value.get("variation")
+    if variation is not None and not is_number(variation):
+        errors.append(f"{label}.variation must be numeric")
+
+
+def validate_reference_pbr_map(value: Any, label: str, errors: list[str]) -> None:
+    if not isinstance(value, dict):
+        errors.append(f"{label} must be an object")
+        return
+    has_locator = False
+    for field in ("path", "url"):
+        item = value.get(field)
+        if item is not None:
+            if not isinstance(item, str) or not item.strip():
+                errors.append(f"{label}.{field} must be a non-empty string when present")
+            else:
+                has_locator = True
+    if not has_locator:
+        errors.append(f"{label} needs a path or url")
+    channel = value.get("channel")
+    if channel is not None and not isinstance(channel, str):
+        errors.append(f"{label}.channel must be a string")
+
+
+def validate_reference_pbr(material_id: str, value: Any, errors: list[str], warnings: list[str]) -> None:
+    if value is None:
+        return
+    if not isinstance(value, dict):
+        errors.append(f"material {material_id!r} referencePbr must be an object")
+        return
+    for field in ("version", "sourceImage", "extractor", "method", "verdict", "hardLimit"):
+        item = value.get(field)
+        if item is not None and not isinstance(item, str):
+            errors.append(f"material {material_id!r} referencePbr.{field} must be a string")
+    usable = value.get("usable")
+    if usable is not None and not isinstance(usable, bool):
+        errors.append(f"material {material_id!r} referencePbr.usable must be boolean")
+    for field in ("confidence", "estimatedFidelity", "targetThreshold"):
+        item = value.get(field)
+        if item is not None:
+            validate_unit_interval(item, f"material {material_id!r} referencePbr.{field}", errors)
+    maps = value.get("maps")
+    if maps is None:
+        warnings.append(f"quality: material {material_id!r} referencePbr is missing maps")
+        return
+    if not isinstance(maps, dict):
+        errors.append(f"material {material_id!r} referencePbr.maps must be an object")
+        return
+    required = ("albedo", "roughness", "height", "normal", "ao")
+    for channel in required:
+        if channel not in maps:
+            warnings.append(f"quality: material {material_id!r} referencePbr.maps missing {channel}")
+        else:
+            validate_reference_pbr_map(maps[channel], f"material {material_id!r} referencePbr.maps.{channel}", errors)
+
+
+def validate_materials(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> set[str]:
+    material_ids: set[str] = set()
+    for index, material in enumerate(spec.get("materials", [])):
+        if not isinstance(material, dict):
+            errors.append(f"materials[{index}] must be an object")
+            continue
+        material_id = material.get("id")
+        if not isinstance(material_id, str) or not material_id.strip():
+            errors.append(f"materials[{index}].id is required")
+            continue
+        if material_id in material_ids:
+            errors.append(f"duplicate material id {material_id!r}")
+        material_ids.add(material_id)
+        color = material.get("baseColor", material.get("color"))
+        if color is not None and not (isinstance(color, str) and color.startswith("#") and len(color) in {4, 7}):
+            errors.append(f"material {material_id!r} baseColor/color should be #RGB or #RRGGBB")
+        for field in ("shaderModel", "type"):
+            value = material.get(field)
+            if value is not None and not isinstance(value, str):
+                errors.append(f"material {material_id!r} {field} must be a string")
+        for field in ("albedo", "ambientOcclusion"):
+            value = material.get(field)
+            if value is not None and not isinstance(value, dict):
+                errors.append(f"material {material_id!r} {field} must be an object")
+        validate_material_scalar_or_layer(material.get("roughness"), f"material {material_id!r} roughness", errors)
+        validate_material_scalar_or_layer(material.get("metalness"), f"material {material_id!r} metalness", errors)
+        for field in ("normal", "bump", "displacement", "wear", "dirt"):
+            value = material.get(field)
+            if value is not None and not isinstance(value, dict):
+                errors.append(f"material {material_id!r} {field} must be an object")
+        texture_resolution = material.get("textureResolution")
+        if texture_resolution is not None and (
+            not isinstance(texture_resolution, int)
+            or isinstance(texture_resolution, bool)
+            or texture_resolution < 64
+            or texture_resolution > 4096
+        ):
+            errors.append(f"material {material_id!r} textureResolution must be an integer from 64 to 4096")
+        projection = material.get("textureProjection")
+        if projection is not None:
+            if not isinstance(projection, dict):
+                errors.append(f"material {material_id!r} textureProjection must be an object")
+            else:
+                mode = projection.get("mode")
+                if mode is not None and not isinstance(mode, str):
+                    errors.append(f"material {material_id!r} textureProjection.mode must be a string")
+                repeat = projection.get("repeat")
+                if repeat is not None and not (
+                    isinstance(repeat, list)
+                    and len(repeat) == 2
+                    and all(is_number(item) and item > 0 for item in repeat)
+                ):
+                    errors.append(f"material {material_id!r} textureProjection.repeat must contain two positive numbers")
+                anisotropy = projection.get("anisotropy")
+                if anisotropy is not None and (not is_number(anisotropy) or anisotropy < 1):
+                    errors.append(f"material {material_id!r} textureProjection.anisotropy must be >= 1")
+        frequency_bands = material.get("surfaceFrequencyBands")
+        if frequency_bands is not None:
+            if not isinstance(frequency_bands, list):
+                errors.append(f"material {material_id!r} surfaceFrequencyBands must be an array")
+            else:
+                seen_band_ids: set[str] = set()
+                for band_index, band in enumerate(frequency_bands):
+                    if not isinstance(band, dict):
+                        errors.append(
+                            f"material {material_id!r} surfaceFrequencyBands[{band_index}] must be an object"
+                        )
+                        continue
+                    band_id = band.get("id")
+                    if not isinstance(band_id, str) or not band_id.strip():
+                        errors.append(
+                            f"material {material_id!r} surfaceFrequencyBands[{band_index}].id is required"
+                        )
+                    elif band_id in seen_band_ids:
+                        errors.append(f"material {material_id!r} has duplicate surface band {band_id!r}")
+                    else:
+                        seen_band_ids.add(band_id)
+                    for field in ("frequency", "amplitude"):
+                        value = band.get(field)
+                        if not is_number(value) or value <= 0:
+                            errors.append(
+                                f"material {material_id!r} surfaceFrequencyBands[{band_index}].{field} "
+                                "must be a positive number"
+                            )
+        local_overrides = material.get("localOverrides", [])
+        if local_overrides is not None and not isinstance(local_overrides, list):
+            errors.append(f"material {material_id!r} localOverrides must be an array")
+        shader_notes = material.get("shaderNotes")
+        if shader_notes is not None:
+            validate_string_array(shader_notes, f"material {material_id!r} shaderNotes", errors)
+        validate_reference_pbr(material_id, material.get("referencePbr"), errors, warnings)
+    if not material_ids:
+        errors.append("at least one material is required")
+    return material_ids
+
+
+def validate_dimensions(component_id: str, dimensions: Any, errors: list[str]) -> None:
+    if dimensions is None:
+        return
+    if not isinstance(dimensions, dict):
+        errors.append(f"component {component_id!r} dimensions must be an object")
+        return
+    for field in ("width", "height", "depth", "radius", "length"):
+        if field in dimensions and not is_number(dimensions[field]):
+            errors.append(f"component {component_id!r} dimensions.{field} must be numeric")
+    confidence = dimensions.get("confidence")
+    if confidence is not None:
+        validate_unit_interval(confidence, f"component {component_id!r} dimensions.confidence", errors)
+
+
+def validate_geometry_descriptor(component_id: str, descriptor: Any, errors: list[str]) -> None:
+    if descriptor is None:
+        return
+    if not isinstance(descriptor, dict):
+        errors.append(f"component {component_id!r} geometryDescriptor must be an object")
+        return
+    for field in ("topologyIntent", "uvStrategy", "normalStrategy"):
+        value = descriptor.get(field)
+        if value is not None and not isinstance(value, str):
+            errors.append(f"component {component_id!r} geometryDescriptor.{field} must be a string")
+    edge = descriptor.get("edgeTreatment")
+    if edge is not None:
+        if not isinstance(edge, dict):
+            errors.append(f"component {component_id!r} geometryDescriptor.edgeTreatment must be an object")
+        else:
+            if "bevelRadius" in edge and not is_number(edge["bevelRadius"]):
+                errors.append(f"component {component_id!r} edgeTreatment.bevelRadius must be numeric")
+            if "segments" in edge and not isinstance(edge["segments"], int):
+                errors.append(f"component {component_id!r} edgeTreatment.segments must be an integer")
+    stack = descriptor.get("deformationStack")
+    if stack is not None and not isinstance(stack, list):
+        errors.append(f"component {component_id!r} geometryDescriptor.deformationStack must be an array")
+
+
+def validate_bool_object(value: Any, label: str, errors: list[str]) -> None:
+    if value is None:
+        return
+    if not isinstance(value, dict):
+        errors.append(f"{label} must be an object")
+        return
+    for key, item in value.items():
+        if not isinstance(key, str):
+            errors.append(f"{label} keys must be strings")
+        if not isinstance(item, bool):
+            errors.append(f"{label}.{key} must be boolean")
+
+
+def validate_action_profile(component_id: str, profile: Any, errors: list[str], warnings: list[str]) -> None:
+    if profile is None:
+        warnings.append(f"component {component_id!r} is missing actionProfile; future animation/destruction may require refactor")
+        return
+    if not isinstance(profile, dict):
+        errors.append(f"component {component_id!r} actionProfile must be an object")
+        return
+    role = profile.get("animationRole")
+    if role is not None and not isinstance(role, str):
+        errors.append(f"component {component_id!r} actionProfile.animationRole must be a string")
+    pivot = profile.get("pivot")
+    if pivot is not None:
+        if not isinstance(pivot, dict):
+            errors.append(f"component {component_id!r} actionProfile.pivot must be an object")
+        else:
+            mode = pivot.get("mode")
+            if mode is not None and not isinstance(mode, str):
+                errors.append(f"component {component_id!r} actionProfile.pivot.mode must be a string")
+            for field in ("localPosition", "axis"):
+                if field in pivot and not as_number_list(pivot[field], 3):
+                    errors.append(f"component {component_id!r} actionProfile.pivot.{field} must be [number, number, number]")
+            confidence = pivot.get("confidence")
+            if confidence is not None:
+                validate_unit_interval(confidence, f"component {component_id!r} actionProfile.pivot.confidence", errors)
+    validate_bool_object(profile.get("transformChannels"), f"component {component_id!r} actionProfile.transformChannels", errors)
+    sockets = profile.get("sockets")
+    if sockets is not None:
+        if not isinstance(sockets, list):
+            errors.append(f"component {component_id!r} actionProfile.sockets must be an array")
+        else:
+            for socket_index, socket in enumerate(sockets):
+                if not isinstance(socket, dict):
+                    errors.append(f"component {component_id!r} actionProfile.sockets[{socket_index}] must be an object")
+                    continue
+                socket_id = socket.get("id")
+                if socket_id is not None and not isinstance(socket_id, str):
+                    errors.append(f"component {component_id!r} actionProfile.sockets[{socket_index}].id must be a string")
+                for field in ("localPosition", "position", "localRotation", "rotation"):
+                    if field in socket and not as_number_list(socket[field], 3):
+                        errors.append(
+                            f"component {component_id!r} actionProfile.sockets[{socket_index}].{field} must be [number, number, number]"
+                        )
+    collider = profile.get("collider")
+    if collider is not None:
+        if not isinstance(collider, dict):
+            errors.append(f"component {component_id!r} actionProfile.collider must be an object")
+        else:
+            collider_type = collider.get("type")
+            if collider_type is not None and not isinstance(collider_type, str):
+                errors.append(f"component {component_id!r} actionProfile.collider.type must be a string")
+            for field in ("offset", "scale"):
+                if field in collider and not as_number_list(collider[field], 3):
+                    errors.append(f"component {component_id!r} actionProfile.collider.{field} must be [number, number, number]")
+            if "isTrigger" in collider and not isinstance(collider["isTrigger"], bool):
+                errors.append(f"component {component_id!r} actionProfile.collider.isTrigger must be boolean")
+    constraints = profile.get("constraints")
+    if constraints is not None and not isinstance(constraints, list):
+        errors.append(f"component {component_id!r} actionProfile.constraints must be an array")
+    destruction = profile.get("destruction")
+    if destruction is not None:
+        if not isinstance(destruction, dict):
+            errors.append(f"component {component_id!r} actionProfile.destruction must be an object")
+        else:
+            if "breakable" in destruction and not isinstance(destruction["breakable"], bool):
+                errors.append(f"component {component_id!r} actionProfile.destruction.breakable must be boolean")
+            if "breakImpulse" in destruction and not is_number(destruction["breakImpulse"]):
+                errors.append(f"component {component_id!r} actionProfile.destruction.breakImpulse must be numeric")
+            for field in ("fractureGroup", "debrisMaterial"):
+                value = destruction.get(field)
+                if value is not None and not isinstance(value, str):
+                    errors.append(f"component {component_id!r} actionProfile.destruction.{field} must be a string")
+            for field in ("seamRefs", "detachableFragments"):
+                validate_string_array(destruction.get(field), f"component {component_id!r} actionProfile.destruction.{field}", errors)
+
+
+def component_requires_attachment(component: dict[str, Any]) -> bool:
+    if not component.get("parent"):
+        return False
+    role = str(component.get("role") or "").lower()
+    name = str(component.get("name") or component.get("id") or "").lower()
+    primitive = str(component.get("primitive") or "").lower()
+    profile = component.get("actionProfile") if isinstance(component.get("actionProfile"), dict) else {}
+    animation_role = str(profile.get("animationRole") or "").lower()
+    tokens = {role, animation_role} | set(re.findall(r"[a-z0-9]+", name))
+    return bool(tokens & ATTACHMENT_ROLES) or primitive in ATTACHMENT_PRIMITIVES
+
+
+def has_attachment_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def attachment_is_complete(attachment: dict[str, Any]) -> bool:
+    has_endpoint = as_number_list(attachment.get("localStart"), 3) and as_number_list(attachment.get("localEnd"), 3)
+    has_socket = isinstance(attachment.get("parentSocket"), str) and bool(attachment["parentSocket"].strip())
+    has_parent_id = isinstance(attachment.get("parentId"), str) and bool(attachment["parentId"].strip())
+    has_contact = isinstance(attachment.get("contactType"), str) and bool(attachment["contactType"].strip())
+    has_overlap = (
+        has_attachment_number(attachment.get("embedDepth"))
+        and float(attachment["embedDepth"]) > 0
+    ) or (
+        has_attachment_number(attachment.get("overlap"))
+        and float(attachment["overlap"]) > 0
+    )
+    has_tolerance = has_attachment_number(attachment.get("gapTolerance"))
+    return has_endpoint and (has_socket or has_parent_id) and has_contact and has_overlap and has_tolerance
+
+
+def validate_attachment(
+    component_id: str,
+    parent: str | None,
+    attachment: Any,
+    required: bool,
+    errors: list[str],
+    warnings: list[str],
+) -> None:
+    if attachment is None:
+        if required:
+            warnings.append(
+                f"quality: component {component_id!r} requires attachment.parentSocket, localStart/localEnd, "
+                "contactType, embedDepth or overlap, and gapTolerance"
+            )
+        return
+    if not isinstance(attachment, dict):
+        errors.append(f"component {component_id!r} attachment must be an object")
+        return
+    for field in ("parentId", "parentSocket", "contactType"):
+        value = attachment.get(field)
+        if value is not None and not isinstance(value, str):
+            errors.append(f"component {component_id!r} attachment.{field} must be a string")
+    if parent and isinstance(attachment.get("parentId"), str) and attachment["parentId"] != parent:
+        warnings.append(
+            f"quality: component {component_id!r} attachment.parentId {attachment['parentId']!r} "
+            f"does not match parent {parent!r}"
+        )
+    for field in ("localStart", "localEnd", "contactNormal"):
+        value = attachment.get(field)
+        if value is not None and not as_number_list(value, 3):
+            errors.append(f"component {component_id!r} attachment.{field} must be [number, number, number]")
+    for field in ("embedDepth", "overlap", "gapTolerance", "baseRadius", "endRadius"):
+        value = attachment.get(field)
+        if value is not None and (not has_attachment_number(value) or float(value) < 0):
+            errors.append(f"component {component_id!r} attachment.{field} must be a non-negative number")
+    validate_string_array(attachment.get("evidenceRefs"), f"component {component_id!r} attachment.evidenceRefs", errors)
+    if required and not attachment_is_complete(attachment):
+        warnings.append(
+            f"quality: component {component_id!r} requires attachment.parentSocket, localStart/localEnd, "
+            "contactType, embedDepth or overlap, and gapTolerance"
+        )
+
+
+def validate_string_array(value: Any, label: str, errors: list[str]) -> None:
+    if value is None:
+        return
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        errors.append(f"{label} must be an array of strings")
+
+
+def validate_components(
+    spec: dict[str, Any],
+    material_ids: set[str],
+    evidence_ids: set[str],
+    errors: list[str],
+    warnings: list[str],
+) -> None:
+    components = spec.get("componentTree", [])
+    ids: set[str] = set()
+    parent_refs: list[tuple[str, str]] = []
+    for index, component in enumerate(components):
+        if not isinstance(component, dict):
+            errors.append(f"componentTree[{index}] must be an object")
+            continue
+        component_id = component.get("id")
+        if not isinstance(component_id, str) or not component_id.strip():
+            errors.append(f"componentTree[{index}].id is required")
+            continue
+        if component_id in ids:
+            errors.append(f"duplicate component id {component_id!r}")
+        ids.add(component_id)
+        primitive = component.get("primitive")
+        if primitive not in VALID_PRIMITIVES:
+            errors.append(
+                f"component {component_id!r} primitive must be one of: {', '.join(sorted(VALID_PRIMITIVES))}"
+            )
+        level = component.get("level")
+        if level is not None and level not in VALID_COMPONENT_LEVELS:
+            errors.append(f"component {component_id!r} level must be macro, meso, or micro")
+        for field in ("importance", "confidence"):
+            value = component.get(field)
+            if value is not None:
+                validate_unit_interval(value, f"component {component_id!r} {field}", errors)
+        parent = component.get("parent")
+        if parent:
+            if not isinstance(parent, str):
+                errors.append(f"component {component_id!r} parent must be a string or null")
+            else:
+                parent_refs.append((component_id, parent))
+        material = component.get("material")
+        if material and material not in material_ids:
+            errors.append(f"component {component_id!r} references unknown material {material!r}")
+        validate_geometry_descriptor(component_id, component.get("geometryDescriptor"), errors)
+        material_layers = component.get("materialLayers")
+        if material_layers is not None:
+            validate_string_array(material_layers, f"component {component_id!r} materialLayers", errors)
+            if isinstance(material_layers, list):
+                for material_layer in material_layers:
+                    if material_layer not in material_ids:
+                        errors.append(
+                            f"component {component_id!r} materialLayers references unknown material {material_layer!r}"
+                        )
+        validate_dimensions(component_id, component.get("dimensions"), errors)
+        transform = component.get("transform", {})
+        if transform is not None and not isinstance(transform, dict):
+            errors.append(f"component {component_id!r} transform must be an object")
+        elif isinstance(transform, dict):
+            for field in ("position", "rotation", "scale"):
+                if field in transform and not as_number_list(transform[field], 3):
+                    errors.append(f"component {component_id!r} transform.{field} must be [number, number, number]")
+        validate_action_profile(component_id, component.get("actionProfile"), errors, warnings)
+        validate_attachment(
+            component_id,
+            parent if isinstance(parent, str) else None,
+            component.get("attachment"),
+            component_requires_attachment(component),
+            errors,
+            warnings,
+        )
+        for field in ("deformations", "joints", "seams", "localFeatures"):
+            value = component.get(field)
+            if value is not None and not isinstance(value, list):
+                errors.append(f"component {component_id!r} {field} must be an array")
+        surface = component.get("surfaceDetail")
+        if surface is not None:
+            if not isinstance(surface, dict):
+                errors.append(f"component {component_id!r} surfaceDetail must be an object")
+            else:
+                for field in ("macroRoughness", "microRoughness", "bumpAmplitude"):
+                    if field in surface and not is_number(surface[field]):
+                        errors.append(f"component {component_id!r} surfaceDetail.{field} must be numeric")
+        evidence_refs = component.get("evidenceRefs")
+        if evidence_refs is not None:
+            validate_string_array(evidence_refs, f"component {component_id!r} evidenceRefs", errors)
+            if isinstance(evidence_refs, list):
+                for evidence_ref in evidence_refs:
+                    if evidence_ids and evidence_ref not in evidence_ids:
+                        errors.append(f"component {component_id!r} references missing evidence {evidence_ref!r}")
+    for component_id, parent in parent_refs:
+        if parent not in ids:
+            errors.append(f"component {component_id!r} references missing parent {parent!r}")
+    if not ids:
+        errors.append("at least one component is required")
+    if len(ids) == 1:
+        warnings.append("only one component found; this is likely still blockout quality")
+
+
+def validate_quality_targets(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    targets = spec.get("qualityTargets")
+    if targets is None:
+        warnings.append("missing qualityTargets; self-correction loop has no explicit fidelity bar")
+        return
+    if not isinstance(targets, dict):
+        errors.append("qualityTargets must be an object")
+        return
+    target_fidelity = targets.get("targetFidelity")
+    if target_fidelity is not None:
+        validate_unit_interval(target_fidelity, "qualityTargets.targetFidelity", errors)
+    for field in ("mustMatch", "niceToHave", "reviewViewpoints"):
+        validate_string_array(targets.get(field), f"qualityTargets.{field}", errors)
+
+
+def validate_quality_contract(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    contract = spec.get("qualityContract")
+    if contract is None:
+        warnings.append("quality: missing qualityContract; no explicit definition of done prevents shallow specs")
+        return
+    if not isinstance(contract, dict):
+        errors.append("qualityContract must be an object")
+        return
+    quality_bar = contract.get("qualityBar")
+    if quality_bar is not None and not isinstance(quality_bar, str):
+        errors.append("qualityContract.qualityBar must be a string")
+    if quality_bar in {None, "", "unassessed"}:
+        warnings.append("quality: qualityContract.qualityBar is unassessed")
+    validate_string_array(contract.get("definitionOfDone"), "qualityContract.definitionOfDone", errors)
+    if isinstance(contract.get("definitionOfDone"), list) and not contract["definitionOfDone"]:
+        warnings.append("quality: qualityContract.definitionOfDone is empty")
+    minimums = contract.get("minimumSpecDepth")
+    if not isinstance(minimums, dict):
+        errors.append("qualityContract.minimumSpecDepth must be an object")
+    else:
+        for field in (
+            "macroComponents",
+            "mesoComponents",
+            "microFeatureGroups",
+            "materialLayers",
+            "repetitionSystems",
+            "reviewViewpoints",
+        ):
+            if field in minimums:
+                validate_nonnegative_int(minimums[field], f"qualityContract.minimumSpecDepth.{field}", errors)
+    feature_groups = contract.get("featureGroups")
+    if not isinstance(feature_groups, list):
+        errors.append("qualityContract.featureGroups must be an array")
+    else:
+        if len(feature_groups) < 3:
+            warnings.append("quality: qualityContract.featureGroups has fewer than 3 groups; spec may miss important visual layers")
+        for index, group in enumerate(feature_groups):
+            if not isinstance(group, dict):
+                errors.append(f"qualityContract.featureGroups[{index}] must be an object")
+                continue
+            for field in ("id", "name"):
+                value = group.get(field)
+                if not isinstance(value, str) or not value.strip():
+                    errors.append(f"qualityContract.featureGroups[{index}].{field} is required")
+            if "required" in group and not isinstance(group["required"], bool):
+                errors.append(f"qualityContract.featureGroups[{index}].required must be boolean")
+            validate_string_array(group.get("qualityCriteria"), f"qualityContract.featureGroups[{index}].qualityCriteria", errors)
+            validate_string_array(group.get("evidenceRefs"), f"qualityContract.featureGroups[{index}].evidenceRefs", errors)
+            validate_string_array(group.get("failureModes"), f"qualityContract.featureGroups[{index}].failureModes", errors)
+            if group.get("required") is True and not group.get("qualityCriteria"):
+                warnings.append(f"quality: required feature group {group.get('id', index)!r} has no qualityCriteria")
+    for field in ("visualDeltaChecks", "antiShallowSpecRules"):
+        validate_string_array(contract.get(field), f"qualityContract.{field}", errors)
+        if isinstance(contract.get(field), list) and not contract[field]:
+            warnings.append(f"quality: qualityContract.{field} is empty")
+
+
+def validate_quality_depth(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    contract = spec.get("qualityContract")
+    if not isinstance(contract, dict) or not isinstance(contract.get("minimumSpecDepth"), dict):
+        return
+    minimums = contract["minimumSpecDepth"]
+    components = [item for item in spec.get("componentTree", []) if isinstance(item, dict)]
+    level_counts = {
+        "macroComponents": sum(1 for item in components if item.get("level") == "macro"),
+        "mesoComponents": sum(1 for item in components if item.get("level") == "meso"),
+        "microFeatureGroups": sum(
+            len(item.get("localFeatures", []))
+            for item in components
+            if isinstance(item.get("localFeatures", []), list)
+        ),
+        "materialLayers": len([item for item in spec.get("materials", []) if isinstance(item, dict)]),
+        "repetitionSystems": len([item for item in spec.get("repetitionSystems", []) if isinstance(item, dict)]),
+        "reviewViewpoints": len(spec.get("qualityTargets", {}).get("reviewViewpoints", []))
+        if isinstance(spec.get("qualityTargets"), dict)
+        and isinstance(spec.get("qualityTargets", {}).get("reviewViewpoints"), list)
+        else 0,
+    }
+    for field, actual in level_counts.items():
+        required = minimums.get(field)
+        if isinstance(required, int) and actual < required:
+            warnings.append(f"quality: {field} below qualityContract minimum ({actual} < {required})")
+
+
+def validate_action_readiness(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    readiness = spec.get("actionReadiness")
+    if readiness is None:
+        warnings.append("missing actionReadiness; generated model may not be ready for animation/transformation/destruction")
+        return
+    if not isinstance(readiness, dict):
+        errors.append("actionReadiness must be an object")
+        return
+    for field in ("contract", "defaultRigType", "rootMotionNode"):
+        value = readiness.get(field)
+        if value is not None and not isinstance(value, str):
+            errors.append(f"actionReadiness.{field} must be a string")
+    for field in ("requiredComponentFields", "transformChannels", "authoringRules"):
+        validate_string_array(readiness.get(field), f"actionReadiness.{field}", errors)
+    policy = readiness.get("destructionPolicy")
+    if policy is not None and not isinstance(policy, dict):
+        errors.append("actionReadiness.destructionPolicy must be an object")
+
+
+def validate_self_correct_loop(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    loop = spec.get("selfCorrectLoop")
+    if loop is None:
+        warnings.append("missing selfCorrectLoop; construction may not review/refine after each pass")
+        return
+    if not isinstance(loop, dict):
+        errors.append("selfCorrectLoop must be an object")
+        return
+    enabled = loop.get("enabled")
+    if enabled is not None and not isinstance(enabled, bool):
+        errors.append("selfCorrectLoop.enabled must be boolean")
+    for field in ("reviewAfterPasses", "allowedActions", "specRefineTriggers", "codeRefineTriggers", "stopCriteria"):
+        validate_string_array(loop.get(field), f"selfCorrectLoop.{field}", errors)
+    actions = loop.get("allowedActions", [])
+    if isinstance(actions, list):
+        for action in actions:
+            if action not in VALID_REVIEW_ACTIONS:
+                errors.append(f"selfCorrectLoop.allowedActions contains invalid action {action!r}")
+    visual_acceptance = loop.get("visualAcceptance")
+    if visual_acceptance is None:
+        warnings.append("quality: selfCorrectLoop.visualAcceptance is missing; AI vision cannot enforce visual fidelity")
+    elif not isinstance(visual_acceptance, dict):
+        errors.append("selfCorrectLoop.visualAcceptance must be an object")
+    else:
+        reviewer = visual_acceptance.get("reviewer")
+        if reviewer is not None and not isinstance(reviewer, str):
+            errors.append("selfCorrectLoop.visualAcceptance.reviewer must be a string")
+        threshold = visual_acceptance.get("threshold")
+        if threshold is None:
+            warnings.append("quality: selfCorrectLoop.visualAcceptance.threshold is missing")
+        else:
+            validate_unit_interval(threshold, "selfCorrectLoop.visualAcceptance.threshold", errors)
+        for field in (
+            "comparisonArtifactRequired",
+            "layerScoresRequired",
+            "codePixelDiffIsAcceptanceAuthority",
+        ):
+            value = visual_acceptance.get(field)
+            if value is not None and not isinstance(value, bool):
+                errors.append(f"selfCorrectLoop.visualAcceptance.{field} must be boolean")
+        scoring_rule = visual_acceptance.get("scoringRule")
+        if scoring_rule is not None and not isinstance(scoring_rule, str):
+            errors.append("selfCorrectLoop.visualAcceptance.scoringRule must be a string")
+        validate_string_array(
+            visual_acceptance.get("requiredLayerScores"),
+            "selfCorrectLoop.visualAcceptance.requiredLayerScores",
+            errors,
+        )
+        feature_policy = visual_acceptance.get("featureReviewPolicy")
+        if feature_policy is None:
+            warnings.append("quality: visualAcceptance.featureReviewPolicy is missing")
+        elif not isinstance(feature_policy, dict):
+            errors.append("selfCorrectLoop.visualAcceptance.featureReviewPolicy must be an object")
+        else:
+            for field in (
+                "enabled",
+                "adaptiveEscalation",
+                "singleImagePairOnly",
+            ):
+                value = feature_policy.get(field)
+                if value is not None and not isinstance(value, bool):
+                    errors.append(
+                        f"selfCorrectLoop.visualAcceptance.featureReviewPolicy.{field} must be boolean"
+                    )
+            for field in ("maxCriticalFeaturesPerPass", "maxImportantFeaturesPerPass"):
+                value = feature_policy.get(field)
+                if value is not None:
+                    validate_nonnegative_int(
+                        value,
+                        f"selfCorrectLoop.visualAcceptance.featureReviewPolicy.{field}",
+                        errors,
+                    )
+            for field in ("criticalDefaultThreshold", "importantAverageThreshold"):
+                value = feature_policy.get(field)
+                if value is not None:
+                    validate_unit_interval(
+                        value,
+                        f"selfCorrectLoop.visualAcceptance.featureReviewPolicy.{field}",
+                        errors,
+                    )
+            for field in ("reviewUnit", "selectionRule"):
+                value = feature_policy.get(field)
+                if value is not None and not isinstance(value, str):
+                    errors.append(
+                        f"selfCorrectLoop.visualAcceptance.featureReviewPolicy.{field} must be a string"
+                    )
+    policy = loop.get("screenshotPolicy")
+    if policy is None:
+        warnings.append("selfCorrectLoop.screenshotPolicy is missing; visual review may drift without screenshots")
+    elif not isinstance(policy, dict):
+        errors.append("selfCorrectLoop.screenshotPolicy must be an object")
+    else:
+        validate_string_array(policy.get("requiredForPasses"), "selfCorrectLoop.screenshotPolicy.requiredForPasses", errors)
+        for field in (
+            "preferredCapture",
+            "fallbackCapture",
+            "minimumEvidence",
+            "reviewPairRule",
+            "acceptanceAuthority",
+        ):
+            value = policy.get(field)
+            if value is not None and not isinstance(value, str):
+                errors.append(f"selfCorrectLoop.screenshotPolicy.{field} must be a string")
+
+
+def validate_visual_evidence_item(item: Any, label: str, errors: list[str]) -> None:
+    if not isinstance(item, dict):
+        errors.append(f"{label} must be an object")
+        return
+    for field in (
+        "passId",
+        "referenceScreenshot",
+        "renderScreenshot",
+        "comparisonImage",
+        "cameraView",
+        "notes",
+        "aiVisionNotes",
+    ):
+        value = item.get(field)
+        if value is not None and not isinstance(value, str):
+            errors.append(f"{label}.{field} must be a string")
+    fidelity = item.get("estimatedFidelity")
+    if fidelity is not None:
+        validate_unit_interval(fidelity, f"{label}.estimatedFidelity", errors)
+    score = item.get("aiVisionScore")
+    if score is not None:
+        validate_unit_interval(score, f"{label}.aiVisionScore", errors)
+    threshold = item.get("visualAcceptanceThreshold")
+    if threshold is not None:
+        validate_unit_interval(threshold, f"{label}.visualAcceptanceThreshold", errors)
+    layer_scores = item.get("layerScores")
+    if layer_scores is not None:
+        if not isinstance(layer_scores, dict):
+            errors.append(f"{label}.layerScores must be an object")
+        else:
+            for key, value in layer_scores.items():
+                if not isinstance(key, str):
+                    errors.append(f"{label}.layerScores keys must be strings")
+                if not is_number(value) or value < 0 or value > 1:
+                    errors.append(f"{label}.layerScores.{key} must be a number from 0 to 1")
+
+
+def validate_feature_review_targets(
+    spec: dict[str, Any],
+    errors: list[str],
+    warnings: list[str],
+) -> None:
+    targets = spec.get("featureReviewTargets")
+    policy = feature_review_policy(spec)
+    if targets is None:
+        if policy.get("enabled") is True:
+            errors.append("featureReviewTargets must be an array when feature review is enabled")
+        else:
+            warnings.append("quality: featureReviewTargets is missing; feature-level visual gating is disabled")
+        return
+    if not isinstance(targets, list):
+        errors.append("featureReviewTargets must be an array")
+        return
+    if not targets:
+        warnings.append("quality: featureReviewTargets is empty; component-level visual gaps can hide in the overall score")
+        return
+    ids: set[str] = set()
+    critical_by_pass: dict[str, int] = {}
+    important_by_pass: dict[str, int] = {}
+    for index, target in enumerate(targets):
+        label = f"featureReviewTargets[{index}]"
+        if not isinstance(target, dict):
+            errors.append(f"{label} must be an object")
+            continue
+        target_id = target.get("id")
+        if not isinstance(target_id, str) or not target_id.strip():
+            errors.append(f"{label}.id is required")
+        elif target_id in ids:
+            errors.append(f"duplicate feature review target id {target_id!r}")
+        else:
+            ids.add(target_id)
+        if not isinstance(target.get("name"), str) or not target["name"].strip():
+            errors.append(f"{label}.name is required")
+        tier = target.get("tier")
+        if tier not in {"critical", "important", "detail"}:
+            errors.append(f"{label}.tier must be critical, important, or detail")
+        validate_string_array(target.get("passIds"), f"{label}.passIds", errors)
+        validate_string_array(target.get("componentRefs"), f"{label}.componentRefs", errors)
+        validate_string_array(target.get("evidenceRefs"), f"{label}.evidenceRefs", errors)
+        minimum = target.get("minimumScore")
+        if minimum is not None:
+            validate_unit_interval(minimum, f"{label}.minimumScore", errors)
+        for field in ("mustPass",):
+            value = target.get(field)
+            if value is not None and not isinstance(value, bool):
+                errors.append(f"{label}.{field} must be boolean")
+        if tier == "critical" or target.get("mustPass") is True:
+            pass_ids = target.get("passIds", [])
+            if isinstance(pass_ids, list):
+                for pass_id in pass_ids:
+                    if isinstance(pass_id, str):
+                        critical_by_pass[pass_id] = critical_by_pass.get(pass_id, 0) + 1
+        elif tier == "important":
+            pass_ids = target.get("passIds", [])
+            if isinstance(pass_ids, list):
+                for pass_id in pass_ids:
+                    if isinstance(pass_id, str):
+                        important_by_pass[pass_id] = important_by_pass.get(pass_id, 0) + 1
+    maximum = policy.get("maxCriticalFeaturesPerPass", 5)
+    if is_number(maximum):
+        for pass_id, count in critical_by_pass.items():
+            if count > int(maximum):
+                errors.append(
+                    f"pass {pass_id!r} has {count} critical feature targets; "
+                    f"maximum is {int(maximum)}"
+                )
+    important_maximum = policy.get("maxImportantFeaturesPerPass", 3)
+    if is_number(important_maximum):
+        for pass_id, count in important_by_pass.items():
+            if count > int(important_maximum):
+                errors.append(
+                    f"pass {pass_id!r} has {count} important feature targets; "
+                    f"maximum is {int(important_maximum)}"
+                )
+    assessment = spec.get("preSpecAssessment")
+    complexity = (
+        assessment.get("complexity", {}).get("tier")
+        if isinstance(assessment, dict) and isinstance(assessment.get("complexity"), dict)
+        else None
+    )
+    starter_ids = {
+        "overall-silhouette",
+        "primary-structure",
+        "reference-material-system",
+    }
+    if complexity in {"moderate", "complex", "ultra-complex"} and ids.issubset(starter_ids):
+        warnings.append(
+            "quality: replace generic starter featureReviewTargets with object-specific "
+            "identity-defining semantic systems before strict validation"
+        )
+
+
+def validate_feature_reviews(
+    entry: dict[str, Any],
+    label: str,
+    errors: list[str],
+) -> None:
+    reviews = entry.get("featureReviews")
+    if reviews is None:
+        return
+    if not isinstance(reviews, list):
+        errors.append(f"{label}.featureReviews must be an array")
+        return
+    ids: set[str] = set()
+    for index, review in enumerate(reviews):
+        item_label = f"{label}.featureReviews[{index}]"
+        if not isinstance(review, dict):
+            errors.append(f"{item_label} must be an object")
+            continue
+        feature_id = review.get("id")
+        if not isinstance(feature_id, str) or not feature_id.strip():
+            errors.append(f"{item_label}.id is required")
+        elif feature_id in ids:
+            errors.append(f"{label}.featureReviews has duplicate id {feature_id!r}")
+        else:
+            ids.add(feature_id)
+        score = review.get("score")
+        if score is not None:
+            validate_unit_interval(score, f"{item_label}.score", errors)
+        for field in ("notes",):
+            value = review.get(field)
+            if value is not None and not isinstance(value, str):
+                errors.append(f"{item_label}.{field} must be a string")
+        visible = review.get("visible")
+        if visible is not None and not isinstance(visible, bool):
+            errors.append(f"{item_label}.visible must be boolean")
+
+
+def validate_review_history(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    history = spec.get("reviewHistory", [])
+    if history is None:
+        return
+    if not isinstance(history, list):
+        errors.append("reviewHistory must be an array")
+        return
+    for index, entry in enumerate(history):
+        if not isinstance(entry, dict):
+            errors.append(f"reviewHistory[{index}] must be an object")
+            continue
+        action = entry.get("action")
+        if action is not None and action not in VALID_REVIEW_ACTIONS:
+            errors.append(f"reviewHistory[{index}].action is invalid")
+        fidelity = entry.get("estimatedFidelity")
+        if fidelity is not None:
+            validate_unit_interval(fidelity, f"reviewHistory[{index}].estimatedFidelity", errors)
+        for field in ("matched", "mismatches", "specFixes", "codeFixes", "evidence"):
+            validate_string_array(entry.get(field), f"reviewHistory[{index}].{field}", errors)
+        visual = entry.get("visualEvidence")
+        if visual is not None:
+            validate_visual_evidence_item(visual, f"reviewHistory[{index}].visualEvidence", errors)
+        validate_feature_reviews(entry, f"reviewHistory[{index}]", errors)
+        pass_id = entry.get("passId")
+        if (
+            pass_id in VISUAL_PASS_IDS
+            and action == "continue"
+            and not (isinstance(visual, dict) and visual.get("renderScreenshot"))
+        ):
+            warnings.append(
+                f"reviewHistory[{index}] continues visual pass {pass_id!r} without a render screenshot"
+            )
+        if pass_id in VISUAL_PASS_IDS and action == "continue":
+            if not isinstance(visual, dict) or not visual.get("comparisonImage"):
+                warnings.append(
+                    f"quality: reviewHistory[{index}] continues visual pass {pass_id!r} without an AI vision comparison image"
+                )
+            score = entry.get("aiVisionScore")
+            threshold = entry.get("visualAcceptanceThreshold", 0.7)
+            if not is_number(score):
+                warnings.append(
+                    f"quality: reviewHistory[{index}] continues visual pass {pass_id!r} without aiVisionScore"
+                )
+            elif is_number(threshold) and float(score) < float(threshold):
+                warnings.append(
+                    f"quality: reviewHistory[{index}] aiVisionScore {score} is below threshold {threshold}"
+                )
+            loop = spec.get("selfCorrectLoop")
+            acceptance = loop.get("visualAcceptance", {}) if isinstance(loop, dict) else {}
+            if isinstance(acceptance, dict) and acceptance.get("layerScoresRequired") is True:
+                layer_scores = entry.get("layerScores")
+                if not isinstance(layer_scores, dict) or not layer_scores:
+                    warnings.append(
+                        f"quality: reviewHistory[{index}] continues visual pass {pass_id!r} without layerScores"
+                    )
+                else:
+                    required_layers = acceptance.get("requiredLayerScores", [])
+                    if isinstance(required_layers, list):
+                        missing_layers = [
+                            layer
+                            for layer in required_layers
+                            if isinstance(layer, str) and layer not in layer_scores
+                        ]
+                        if missing_layers:
+                            warnings.append(
+                                f"quality: reviewHistory[{index}] layerScores missing: "
+                                + ", ".join(missing_layers)
+                            )
+            failures = feature_gate_failures(spec, entry, str(pass_id))
+            for failure in failures:
+                warnings.append(
+                    f"quality: reviewHistory[{index}] feature gate failed: {failure}"
+                )
+
+
+def validate_visual_evidence_history(spec: dict[str, Any], errors: list[str]) -> None:
+    visual_history = spec.get("visualEvidence", [])
+    if visual_history is None:
+        return
+    if not isinstance(visual_history, list):
+        errors.append("visualEvidence must be an array")
+        return
+    for index, item in enumerate(visual_history):
+        validate_visual_evidence_item(item, f"visualEvidence[{index}]", errors)
+
+
+def validate_build_passes(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> list[str]:
+    build_passes = spec.get("buildPasses")
+    if build_passes is None:
+        warnings.append("quality: missing buildPasses; model construction can skip blockout/structural/material gates")
+        return []
+    if not isinstance(build_passes, list):
+        errors.append("buildPasses must be an array")
+        return []
+    ids: list[str] = []
+    for index, item in enumerate(build_passes):
+        if not isinstance(item, dict):
+            errors.append(f"buildPasses[{index}] must be an object")
+            continue
+        pass_id = item.get("id")
+        if not isinstance(pass_id, str) or not pass_id.strip():
+            errors.append(f"buildPasses[{index}].id is required")
+            continue
+        if pass_id in ids:
+            errors.append(f"duplicate buildPasses id {pass_id!r}")
+        ids.append(pass_id)
+        for field in ("goal",):
+            value = item.get(field)
+            if value is not None and not isinstance(value, str):
+                errors.append(f"buildPasses[{index}].{field} must be a string")
+        validate_string_array(item.get("componentRefs"), f"buildPasses[{index}].componentRefs", errors)
+        validate_string_array(item.get("acceptance"), f"buildPasses[{index}].acceptance", errors)
+    if ids:
+        if ids[0] != "blockout":
+            warnings.append("quality: first build pass should be blockout")
+        if "structural-pass" not in ids:
+            warnings.append("quality: missing structural-pass; component hierarchy may be skipped")
+        if not ({"material-pass", "surface-pass"} & set(ids)):
+            warnings.append("quality: missing material/surface pass; model may stay as flat geometry")
+    return ids
+
+
+def review_completes_pass(
+    spec: dict[str, Any],
+    entry: dict[str, Any],
+    pass_id: str,
+) -> bool:
+    if entry.get("passId") != pass_id or entry.get("action") != "continue":
+        return False
+    visual = entry.get("visualEvidence")
+    if pass_id in VISUAL_PASS_IDS:
+        if not (
+            isinstance(visual, dict)
+            and visual.get("renderScreenshot")
+            and visual.get("comparisonImage")
+        ):
+            return False
+        score = entry.get("aiVisionScore")
+        threshold = entry.get("visualAcceptanceThreshold", 0.7)
+        if not is_number(score) or not is_number(threshold) or float(score) < float(threshold):
+            return False
+        if feature_gate_failures(spec, entry, pass_id):
+            return False
+    return True
+
+
+def completed_passes_from_history(spec: dict[str, Any], pass_ids: list[str]) -> list[str]:
+    history = spec.get("reviewHistory", [])
+    if not isinstance(history, list):
+        return []
+    completed: list[str] = []
+    for pass_id in pass_ids:
+        if any(
+            isinstance(entry, dict) and review_completes_pass(spec, entry, pass_id)
+            for entry in history
+        ):
+            completed.append(pass_id)
+        else:
+            break
+    return completed
+
+
+def validate_sculpt_pipeline(
+    spec: dict[str, Any],
+    build_pass_ids: list[str],
+    errors: list[str],
+    warnings: list[str],
+) -> None:
+    pipeline = spec.get("sculptPipeline")
+    if pipeline is None:
+        warnings.append("quality: missing sculptPipeline; pass order is not locked and generation can skip build passes")
+        return
+    if not isinstance(pipeline, dict):
+        errors.append("sculptPipeline must be an object")
+        return
+    pass_order = pipeline.get("passOrder")
+    if pass_order is None:
+        warnings.append("quality: sculptPipeline.passOrder is missing")
+        pass_order_ids = build_pass_ids
+    else:
+        validate_string_array(pass_order, "sculptPipeline.passOrder", errors)
+        pass_order_ids = [str(value) for value in pass_order] if isinstance(pass_order, list) else build_pass_ids
+    if build_pass_ids and pass_order_ids and pass_order_ids != build_pass_ids:
+        warnings.append("sculptPipeline.passOrder differs from buildPasses order; sync the pipeline before generation")
+    current = pipeline.get("currentPass")
+    if current is not None and current != "complete" and current not in (pass_order_ids or build_pass_ids):
+        errors.append("sculptPipeline.currentPass must be a known build pass or complete")
+    completed = pipeline.get("completedPasses", [])
+    validate_string_array(completed, "sculptPipeline.completedPasses", errors)
+    if isinstance(completed, list):
+        expected = completed_passes_from_history(spec, pass_order_ids or build_pass_ids)
+        if list(completed) != expected:
+            warnings.append("sculptPipeline.completedPasses is out of sync with reviewHistory; run stage3_build/orchestrate_passes.py sync")
+        for pass_id in completed:
+            if pass_id not in (pass_order_ids or build_pass_ids):
+                errors.append(f"sculptPipeline.completedPasses contains unknown pass {pass_id!r}")
+    gate_mode = pipeline.get("passGateMode")
+    if gate_mode != "locked-sequential":
+        warnings.append("quality: sculptPipeline.passGateMode should be locked-sequential")
+    validate_string_array(pipeline.get("nextRequiredEvidence"), "sculptPipeline.nextRequiredEvidence", errors)
+
+
+def has_non_empty_detail(value: Any) -> bool:
+    if isinstance(value, str):
+        return bool(value.strip()) and value.strip().lower() not in {"none", "unassessed", "n/a"}
+    if isinstance(value, list):
+        return any(has_non_empty_detail(item) for item in value)
+    if isinstance(value, dict):
+        return any(has_non_empty_detail(item) for item in value.values())
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return abs(float(value)) > 0
+    return False
+
+
+def layer_number(value: Any, keys: tuple[str, ...]) -> float:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    if isinstance(value, dict):
+        for key in keys:
+            item = value.get(key)
+            if isinstance(item, (int, float)) and not isinstance(item, bool):
+                return float(item)
+    return 0.0
+
+
+def reference_pbr_usable(material: dict[str, Any], threshold: float) -> tuple[bool, str]:
+    reference = material.get("referencePbr")
+    material_id = str(material.get("id") or "(unnamed)")
+    if not isinstance(reference, dict):
+        return False, f"material {material_id!r} needs usable referencePbr extracted from source pixels"
+    if reference.get("usable") is not True:
+        return False, f"material {material_id!r} referencePbr.usable must be true"
+    confidence = reference.get("confidence", reference.get("estimatedFidelity"))
+    if not is_number(confidence) or float(confidence) < threshold:
+        return False, f"material {material_id!r} referencePbr confidence must be >= {threshold}"
+    maps = reference.get("maps")
+    if not isinstance(maps, dict):
+        return False, f"material {material_id!r} referencePbr needs maps"
+    for channel in ("albedo", "roughness", "height", "normal", "ao"):
+        entry = maps.get(channel)
+        if not isinstance(entry, dict) or not has_non_empty_detail(entry.get("url") or entry.get("path")):
+            return False, f"material {material_id!r} referencePbr missing {channel} map path/url"
+    return True, ""
+
+
+def validate_look_dev_targets(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    targets = spec.get("lookDevTargets")
+    if targets is None:
+        warnings.append("quality: missing lookDevTargets; material/color/lighting passes may stay flat")
+    elif not isinstance(targets, dict):
+        errors.append("lookDevTargets must be an object")
+    materials = [item for item in spec.get("materials", []) if isinstance(item, dict)]
+    if materials:
+        has_palette = any(
+            has_non_empty_detail(item.get("colorVariation"))
+            or has_non_empty_detail(item.get("albedo", {}).get("secondary") if isinstance(item.get("albedo"), dict) else None)
+            for item in materials
+        )
+        has_response = any(
+            layer_number(item.get("roughness"), ("variation", "base")) > 0
+            or layer_number(item.get("normal"), ("strength", "amplitude")) > 0
+            or layer_number(item.get("bump"), ("amplitude", "strength")) > 0
+            or layer_number(item.get("displacement"), ("amplitude", "strength")) > 0
+            for item in materials
+        )
+        has_locality = any(
+            has_non_empty_detail(item.get("localOverrides"))
+            or (
+                isinstance(item.get("wear"), dict)
+                and (
+                    layer_number(item["wear"].get("edgeWear"), ("base", "amount")) > 0
+                    or has_non_empty_detail(item["wear"].get("scratches"))
+                    or has_non_empty_detail(item["wear"].get("chips"))
+                )
+            )
+            or (
+                isinstance(item.get("dirt"), dict)
+                and (
+                    layer_number(item["dirt"].get("amount"), ("base", "amount")) > 0
+                    or layer_number(item["dirt"].get("cavityBias"), ("base", "amount")) > 0
+                )
+            )
+            or has_non_empty_detail(item.get("moss"))
+            or has_non_empty_detail(item.get("stains"))
+            or has_non_empty_detail(item.get("scratches"))
+            or has_non_empty_detail(item.get("chips"))
+            or has_non_empty_detail(item.get("wetness"))
+            or has_non_empty_detail(item.get("patina"))
+            for item in materials
+        )
+        if not has_palette:
+            warnings.append("quality: material-pass needs reference-derived albedo palette or secondary/accent color zones")
+        if not has_response:
+            warnings.append("quality: material-pass needs roughness variation or normal/bump/displacement response")
+        if not has_locality:
+            warnings.append("quality: material-pass needs local overrides, AO, dirt, wear, stains, moss, chips, scratches, or equivalent masks")
+        quality_first = isinstance(targets, dict) and targets.get("qualityPriority") == "reference-fidelity"
+        if quality_first:
+            material_targets = targets.get("materialPass", {})
+            if not isinstance(material_targets, dict):
+                warnings.append("quality: quality-first lookDevTargets.materialPass must be an object")
+                material_targets = {}
+            minimum_resolution = material_targets.get("minimumTextureResolution", 1024)
+            if not isinstance(minimum_resolution, int) or isinstance(minimum_resolution, bool):
+                warnings.append("quality: minimumTextureResolution must be an integer")
+                minimum_resolution = 1024
+            required_channels = {
+                str(item).lower()
+                for item in material_targets.get("independentMapChannels", [])
+                if isinstance(item, str)
+            }
+            extraction_targets = material_targets.get("referencePbrExtraction", {})
+            if not isinstance(extraction_targets, dict):
+                extraction_targets = {}
+            pbr_required = (
+                extraction_targets.get("requiredWhenSourceImagePresent") is True
+                and has_non_empty_detail(spec.get("sourceImage"))
+            )
+            pbr_threshold = extraction_targets.get("targetThreshold", 0.7)
+            if not is_number(pbr_threshold):
+                pbr_threshold = 0.7
+            expected_channels = {"albedo", "roughness", "height", "normal", "ambient-occlusion"}
+            if not expected_channels.issubset(required_channels):
+                warnings.append(
+                    "quality: quality-first materialPass must require independent albedo, roughness, "
+                    "height, normal, and ambient-occlusion channels"
+                )
+            for material in materials:
+                if material.get("qualityTier") == "utility":
+                    continue
+                material_id = str(material.get("id") or "(unnamed)")
+                resolution = material.get("textureResolution")
+                if not isinstance(resolution, int) or isinstance(resolution, bool) or resolution < minimum_resolution:
+                    warnings.append(
+                        f"quality: material {material_id!r} textureResolution must be >= {minimum_resolution}"
+                    )
+                projection = material.get("textureProjection")
+                if not isinstance(projection, dict) or not has_non_empty_detail(projection.get("mode")):
+                    warnings.append(
+                        f"quality: material {material_id!r} needs textureProjection.mode and texel-density intent"
+                    )
+                bands = material.get("surfaceFrequencyBands")
+                band_ids = {
+                    str(item.get("id")).lower()
+                    for item in bands
+                    if isinstance(item, dict) and has_non_empty_detail(item.get("id"))
+                } if isinstance(bands, list) else set()
+                missing_bands = {"macro", "meso", "micro"} - band_ids
+                if missing_bands:
+                    warnings.append(
+                        f"quality: material {material_id!r} missing surface frequency bands: "
+                        + ", ".join(sorted(missing_bands))
+                    )
+                roughness = material.get("roughness")
+                roughness_map = roughness.get("map") if isinstance(roughness, dict) else None
+                if not has_non_empty_detail(roughness_map) or "albedo" in str(roughness_map).lower():
+                    warnings.append(f"quality: material {material_id!r} needs an independent roughness map")
+                if not has_non_empty_detail(material.get("ambientOcclusion")):
+                    warnings.append(
+                        f"quality: material {material_id!r} needs an independent ambient-occlusion response"
+                    )
+                if pbr_required:
+                    ok, message = reference_pbr_usable(material, float(pbr_threshold))
+                    if not ok:
+                        warnings.append(f"quality: {message}")
+    lighting = spec.get("lightingFromPhoto", [])
+    if not isinstance(lighting, list):
+        errors.append("lightingFromPhoto must be an array")
+    else:
+        meaningful = [item for item in lighting if has_non_empty_detail(item)]
+        if len(meaningful) < 3:
+            warnings.append("quality: lighting-pass needs concrete key/fill/rim or environment light entries")
+        lighting_text = " ".join(str(item).lower() for item in meaningful)
+        if meaningful and not any(term in lighting_text for term in ("exposure", "tone", "aces", "filmic")):
+            warnings.append("quality: lighting-pass needs exposure and tone mapping intent")
+        if meaningful and not any(term in lighting_text for term in ("contact shadow", "ground shadow", "ambient occlusion", "ao")):
+            warnings.append("quality: lighting-pass needs contact shadow or ground shadow behavior")
+
+
+VALID_DETAIL_KINDS = {
+    "gloss", "bevel", "fastener", "linework", "contour", "seam", "stitch",
+    "stain", "scratch", "chip", "decal", "emissive", "hole", "groove", "ridge",
+}
+
+
+def _detail_link_keys(spec: dict[str, Any]) -> set[str]:
+    """Collect keys a detailInventory item may map to: component ids, local feature ids,
+    material ids, and material localOverride ids (with and without owner prefix)."""
+    keys: set[str] = set()
+    for comp in spec.get("componentTree", []):
+        if not isinstance(comp, dict):
+            continue
+        cid = comp.get("id")
+        if isinstance(cid, str):
+            keys.add(cid)
+        for feat in comp.get("localFeatures", []) or []:
+            if isinstance(feat, str):
+                keys.add(feat)
+                if isinstance(cid, str):
+                    keys.add(f"{cid}/{feat}")
+            elif isinstance(feat, dict) and isinstance(feat.get("id"), str):
+                keys.add(feat["id"])
+                if isinstance(cid, str):
+                    keys.add(f"{cid}/{feat['id']}")
+    for mat in spec.get("materials", []):
+        if not isinstance(mat, dict):
+            continue
+        mid = mat.get("id")
+        if isinstance(mid, str):
+            keys.add(mid)
+        for over in mat.get("localOverrides", []) or []:
+            if isinstance(over, dict) and isinstance(over.get("id"), str):
+                keys.add(over["id"])
+                if isinstance(mid, str):
+                    keys.add(f"{mid}/{over['id']}")
+    return keys
+
+
+def _has_gloss_response(spec: dict[str, Any]) -> bool:
+    for mat in spec.get("materials", []):
+        if not isinstance(mat, dict):
+            continue
+        rough = mat.get("roughness")
+        base = rough.get("base") if isinstance(rough, dict) else rough
+        if is_number(base) and float(base) < 0.35:
+            return True
+        if is_number(mat.get("clearcoat")) or isinstance(mat.get("clearcoat"), dict):
+            return True
+        for over in mat.get("localOverrides", []) or []:
+            if isinstance(over, dict) and is_number(over.get("roughness")) and float(over["roughness"]) < 0.3:
+                return True
+    return False
+
+
+def _has_repetition_or_small_parts(spec: dict[str, Any]) -> bool:
+    if [r for r in spec.get("repetitionSystems", []) if isinstance(r, dict)]:
+        return True
+    return any(
+        isinstance(c, dict) and c.get("level") == "micro"
+        for c in spec.get("componentTree", [])
+    )
+
+
+def validate_detail_inventory(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    """Gate the detail inventory. Backward compatible: only enforced when a detailInventory
+    block with a positive targetMinDetails is present (new-pipeline specs)."""
+    assessment = spec.get("preSpecAssessment")
+    if not isinstance(assessment, dict):
+        return
+    inv = assessment.get("detailInventory")
+    if not isinstance(inv, dict):
+        return
+    details = inv.get("details", [])
+    if not isinstance(details, list):
+        errors.append("preSpecAssessment.detailInventory.details must be an array")
+        return
+    target = inv.get("targetMinDetails", 0)
+    if not (isinstance(target, int) and not isinstance(target, bool) and target > 0):
+        return  # not a new-pipeline spec; skip enforcement
+    if len(details) < target:
+        warnings.append(
+            f"quality: detailInventory has {len(details)} details but targetMinDetails is {target}; "
+            "enumerate identity-defining details (gloss, bevel, fasteners, linework, stains) before code generation"
+        )
+    link_keys = _detail_link_keys(spec)
+    has_gloss = has_fastener = False
+    for index, detail in enumerate(details):
+        if not isinstance(detail, dict):
+            errors.append(f"detailInventory.details[{index}] must be an object")
+            continue
+        did = detail.get("id", index)
+        kind = detail.get("kind")
+        if kind not in VALID_DETAIL_KINDS:
+            warnings.append(f"quality: detailInventory detail {did!r} has unknown kind {kind!r}")
+        maps = detail.get("mapsTo")
+        ref = maps.get("ref") if isinstance(maps, dict) else None
+        if not (isinstance(ref, str) and ref in link_keys):
+            warnings.append(
+                f"quality: detailInventory detail {did!r} does not map to a component.localFeatures "
+                "or material.localOverrides entry (no prose-only details)"
+            )
+        if kind == "gloss":
+            has_gloss = True
+        elif kind == "fastener":
+            has_fastener = True
+    if has_gloss and not _has_gloss_response(spec):
+        warnings.append(
+            "quality: detailInventory lists a gloss detail but no material provides low roughness or clearcoat response"
+        )
+    if has_fastener and not _has_repetition_or_small_parts(spec):
+        warnings.append(
+            "quality: detailInventory lists fastener details but no repetitionSystem/instancing or micro parts represent them"
+        )
+
+
+def validate_character_track(spec: dict[str, Any], errors: list[str], warnings: list[str]) -> None:
+    """Gate the character track. Backward compatible: only enforced when primaryDomain is
+    character or hybrid."""
+    assessment = spec.get("preSpecAssessment")
+    if not isinstance(assessment, dict):
+        return
+    object_class = assessment.get("objectClass")
+    domain = object_class.get("primaryDomain") if isinstance(object_class, dict) else None
+    if domain not in {"character", "hybrid"}:
+        return
+    anatomy = assessment.get("anatomy")
+    if not isinstance(anatomy, dict) or anatomy.get("applies") is not True:
+        warnings.append(
+            "quality: primaryDomain is character/hybrid but anatomy.applies is not true; "
+            "fill anatomy (styleHeads, proportions, pose, faceLandmarks) from the reference"
+        )
+        return
+    if not (is_number(anatomy.get("styleHeads")) and float(anatomy["styleHeads"]) > 0):
+        warnings.append("quality: character anatomy.styleHeads must be greater than 0 (head-unit proportion)")
+    proportions = anatomy.get("proportions")
+    if not (isinstance(proportions, dict) and any(
+        is_number(proportions.get(k)) and float(proportions[k]) > 0 for k in ("torso", "legs")
+    )):
+        warnings.append("quality: character anatomy.proportions must set torso/legs head-unit ratios")
+    landmarks = anatomy.get("faceLandmarks")
+    if not (isinstance(landmarks, dict) and any(
+        is_number(landmarks.get(k)) and float(landmarks[k]) > 0 for k in ("eyeLine", "noseBase", "mouthLine")
+    )):
+        warnings.append("quality: character anatomy.faceLandmarks must set eyeLine/noseBase/mouthLine from the reference")
+    targets = spec.get("featureReviewTargets", [])
+    character_ids = {"anatomy-proportion", "face-landmark-placement", "pose-silhouette", "outfit-and-palette"}
+    if not any(isinstance(t, dict) and t.get("id") in character_ids for t in targets):
+        warnings.append(
+            "quality: character track needs featureReviewTargets covering anatomy/face/pose/outfit "
+            "(add anatomy-proportion, face-landmark-placement, pose-silhouette, outfit-and-palette)"
+        )
+
+
+def validate_spec(spec: dict[str, Any]) -> tuple[list[str], list[str]]:
+    errors: list[str] = []
+    warnings: list[str] = []
+    for key, expected_type in REQUIRED_TOP_LEVEL.items():
+        if key not in spec:
+            errors.append(f"missing top-level field {key!r}")
+        elif not isinstance(spec[key], expected_type):
+            errors.append(f"field {key!r} must be {expected_type.__name__}")
+    suitability = spec.get("suitability")
+    if suitability not in VALID_SUITABILITY:
+        errors.append("suitability must be pass, conditional, or reject")
+    validate_pre_spec_assessment(spec, errors, warnings)
+    validate_terminology_profile(spec, errors, warnings)
+    validate_score_block(spec, errors, warnings)
+    validate_quality_targets(spec, errors, warnings)
+    validate_quality_contract(spec, errors, warnings)
+    validate_action_readiness(spec, errors, warnings)
+    validate_self_correct_loop(spec, errors, warnings)
+    validate_feature_review_targets(spec, errors, warnings)
+    validate_review_history(spec, errors, warnings)
+    validate_visual_evidence_history(spec, errors)
+    build_pass_ids = validate_build_passes(spec, errors, warnings)
+    validate_sculpt_pipeline(spec, build_pass_ids, errors, warnings)
+    validate_look_dev_targets(spec, errors, warnings)
+    evidence_ids = validate_evidence(spec, errors, warnings)
+    material_ids = validate_materials(spec, errors, warnings)
+    validate_components(spec, material_ids, evidence_ids, errors, warnings)
+    lod_plan = spec.get("lodPlan")
+    if lod_plan is not None and not isinstance(lod_plan, list):
+        errors.append("lodPlan must be an array")
+    performance = spec.get("performanceBudget")
+    if performance is not None and not isinstance(performance, dict):
+        errors.append("performanceBudget must be an object")
+    validate_quality_depth(spec, errors, warnings)
+    validate_detail_inventory(spec, errors, warnings)
+    validate_character_track(spec, errors, warnings)
+    if suitability == "pass" and spec.get("risks"):
+        warnings.append("suitability is pass but risks are present; confirm they are acceptable")
+    return errors, warnings
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("spec", type=Path)
+    parser.add_argument("--json", action="store_true", help="Print machine-readable result")
+    parser.add_argument(
+        "--strict-quality",
+        action="store_true",
+        help="Treat quality warnings as validation errors before implementation/generation",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        spec = load_spec(args.spec)
+        errors, warnings = validate_spec(spec)
+    except ValueError as exc:
+        errors, warnings = [str(exc)], []
+
+    if args.strict_quality:
+        errors.extend(
+            f"strict quality failure: {warning.removeprefix('quality: ').strip()}"
+            for warning in warnings
+            if warning.startswith("quality:")
+        )
+
+    ok = not errors
+    result = {
+        "ok": ok,
+        "errors": errors,
+        "warnings": warnings,
+        "summary": {
+            "targetName": spec.get("targetName") if "spec" in locals() else None,
+            "suitability": spec.get("suitability") if "spec" in locals() else None,
+            "components": len(spec.get("componentTree", [])) if "spec" in locals() else 0,
+            "materials": len(spec.get("materials", [])) if "spec" in locals() else 0,
+        },
+    }
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print("PASS" if ok else "FAIL")
+        for warning in warnings:
+            print(f"warning: {warning}")
+        for error in errors:
+            print(f"error: {error}")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage3_build/bake_projected_texture.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Emit a projection/UV-bake descriptor for photo-projected texturing.
+
+This script does not perform GPU projective texturing and it does not
+rasterize or bake any pixels. Actual camera-space projection of the
+(ideally de-lit) reference image onto the fitted mesh, and the bake of that
+projection into the mesh's UV space, is a Three.js runtime operation (a
+projective ShaderMaterial, e.g. the `three-projected-material` technique).
+What this script produces is the plan: a validated, versioned descriptor
+that records which camera, which source image(s), which mesh, and which
+projection settings the Three.js generator/agent should use to actually run
+that bake, plus the back/side inference strategy for regions the camera
+never saw.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+VALID_PROJECTION_MODES = ("perspective-camera-projection", "orthographic-front-projection", "triplanar-fallback")
+VALID_UNSEEN_STRATEGIES = ("mirror-symmetry", "palette-continue", "request-additional-view", "leave-unprojected")
+
+
+def clamp01(value: float) -> float:
+    return max(0.0, min(1.0, value))
+
+
+def load_camera(camera_arg: str | None) -> tuple[dict[str, Any] | None, list[str]]:
+    warnings: list[str] = []
+    if not camera_arg:
+        warnings.append("no --camera reference supplied; projection will use an identity/front camera assumption")
+        return None, warnings
+    path = Path(camera_arg).expanduser()
+    if not path.exists():
+        warnings.append(f"--camera path {camera_arg!r} does not exist; recording it as an opaque reference id instead")
+        return {"reference": camera_arg}, warnings
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        warnings.append(f"could not parse --camera JSON at {path}: {exc}; recording it as an opaque reference id")
+        return {"reference": camera_arg}, warnings
+    camera = data.get("referenceCamera", data) if isinstance(data, dict) else None
+    if not isinstance(camera, dict):
+        warnings.append(f"--camera JSON at {path} did not contain a referenceCamera object")
+        return {"reference": camera_arg}, warnings
+    return camera, warnings
+
+
+def build_descriptor(args: argparse.Namespace) -> dict[str, Any]:
+    camera, camera_warnings = load_camera(args.camera)
+    warnings = list(camera_warnings)
+
+    source_images: dict[str, str] = {"reference": str(Path(args.reference_image).expanduser())}
+    if args.delit_image:
+        source_images["delit"] = str(Path(args.delit_image).expanduser())
+    else:
+        warnings.append(
+            "no --delit-image supplied; projecting the raw reference will bake its lighting into the mesh "
+            "unless the runtime applies its own de-lighting pass first"
+        )
+
+    unseen_strategy = args.unseen_strategy
+    unseen_confidence = {
+        "mirror-symmetry": 0.45,
+        "palette-continue": 0.3,
+        "request-additional-view": 0.0,
+        "leave-unprojected": 0.0,
+    }[unseen_strategy]
+
+    bake_steps = [
+        "load the fitted mesh identified by targetMeshId and its UV layout",
+        "load sourceImages.delit if present, otherwise sourceImages.reference, as the projection source texture",
+        "construct a projection camera in the Three.js scene from the camera block (fovDegrees, aspect, orientation, position)",
+        f"apply {args.projection_mode} to project the source texture onto mesh surfaces facing the projection camera within tolerance",
+        f"for surfaces outside the camera's view frustum or facing away, apply the '{unseen_strategy}' strategy",
+        f"rasterize the resulting camera-space projection into a {args.texture_size}x{args.texture_size} UV-space texture",
+        "flag any UV texels that received no projected sample (fully unseen regions) in the bake output metadata",
+        "hand the baked texture back to the material pipeline as the projected albedo input",
+    ]
+
+    return {
+        "projectedTextureBake": {
+            "version": "1.0",
+            "generator": "stage3_build/bake_projected_texture.py",
+            "status": "descriptor-only; no pixels are baked or rasterized by this script",
+            "targetMeshId": args.mesh_id,
+            "projectionMode": args.projection_mode,
+            "textureSize": args.texture_size,
+            "camera": camera,
+            "sourceImages": source_images,
+            "unseenRegionStrategy": {
+                "mode": unseen_strategy,
+                "confidence": unseen_confidence,
+                "note": "Regions the reference camera never saw (back, occluded folds, underside) are inferred, not observed.",
+            },
+            "runtimeApproach": (
+                "actual projective texturing and UV bake happen in the Three.js runtime via a projective "
+                "ShaderMaterial (the three-projected-material approach) or an equivalent camera-space "
+                "projection shader; this descriptor only records the plan for that step"
+            ),
+            "bakeSteps": bake_steps,
+            "limitations": [
+                "this script performs no image sampling, projection math, or UV rasterization",
+                "camera accuracy is inherited from whatever produced the camera block; an unrefined camera will misalign the projection",
+                "unseen-region inference is a heuristic guess, not observed geometry or texture",
+                "the resulting bake still needs a rendered overlay review against the reference image before being trusted",
+            ]
+            + warnings,
+            "note": (
+                "Feed this descriptor to the Three.js generator/agent to run the actual projection and bake, "
+                "then re-render and visually compare the baked mesh against the reference image before "
+                "accepting the result as final."
+            ),
+        }
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--reference-image", required=True, help="Path to the original reference photo")
+    parser.add_argument("--delit-image", help="Path to a de-lit albedo produced by stage1_intake/delight_albedo.py, if available")
+    parser.add_argument("--camera", help="Path to a referenceCamera JSON produced by stage1_intake/solve_camera_pose.py")
+    parser.add_argument("--mesh-id", required=True, help="Identifier of the target mesh/node to project onto")
+    parser.add_argument(
+        "--projection-mode",
+        choices=VALID_PROJECTION_MODES,
+        default="perspective-camera-projection",
+        help="Projection technique the Three.js runtime should use (default perspective-camera-projection)",
+    )
+    parser.add_argument("--texture-size", type=int, default=1024, help="Target baked texture resolution (square)")
+    parser.add_argument(
+        "--unseen-strategy",
+        choices=VALID_UNSEEN_STRATEGIES,
+        default="mirror-symmetry",
+        help="How to handle mesh regions outside the reference camera's view (default mirror-symmetry)",
+    )
+    parser.add_argument("--out", type=Path, help="Write the descriptor JSON to this path")
+    args = parser.parse_args(argv)
+
+    if args.texture_size <= 0:
+        parser.error("--texture-size must be positive")
+
+    try:
+        descriptor = build_descriptor(args)
+        text = json.dumps(descriptor, indent=2, ensure_ascii=False)
+        if args.out:
+            out_path = args.out.expanduser().resolve()
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+            out_path.write_text(text + "\n", encoding="utf-8")
+        print(text)
+        return 0
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage3_build/generate_threejs_factory.py

@@ -0,0 +1,986 @@
+#!/usr/bin/env python3
+"""Generate a TypeScript Three.js factory skeleton from an ObjectSculptSpec."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from orchestrate_passes import pass_specific_gaps
+
+
+VALID_PRIMITIVES = {
+    "box",
+    "sphere",
+    "ellipsoid",
+    "cylinder",
+    "cone",
+    "capsule",
+    "torus",
+    "tube",
+    "lathe",
+    "extrude",
+    "curve-sweep",
+    "plane-card",
+    "instanced-cluster",
+}
+DEFAULT_PASS_ORDER = [
+    "blockout",
+    "structural-pass",
+    "form-refinement",
+    "material-pass",
+    "surface-pass",
+    "lighting-pass",
+    "interaction-pass",
+    "optimization-pass",
+]
+VISUAL_PASS_IDS = set(DEFAULT_PASS_ORDER) - {"optimization-pass"}
+PASS_LEVELS = {
+    "blockout": {"macro"},
+    "structural-pass": {"macro", "meso"},
+    "form-refinement": {"macro", "meso", "micro"},
+    "material-pass": {"macro", "meso", "micro"},
+    "surface-pass": {"macro", "meso", "micro"},
+    "lighting-pass": {"macro", "meso", "micro"},
+    "interaction-pass": {"macro", "meso", "micro"},
+    "optimization-pass": {"macro", "meso", "micro"},
+}
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("spec must be a JSON object")
+    return payload
+
+
+def pass_order(spec: dict[str, Any]) -> list[str]:
+    ids: list[str] = []
+    for item in spec.get("buildPasses", []):
+        if isinstance(item, dict) and isinstance(item.get("id"), str) and item["id"].strip():
+            ids.append(item["id"])
+    return ids or DEFAULT_PASS_ORDER.copy()
+
+
+def review_visual_evidence(entry: dict[str, Any]) -> dict[str, Any]:
+    visual = entry.get("visualEvidence")
+    return visual if isinstance(visual, dict) else {}
+
+
+def review_completes_pass(entry: dict[str, Any], pass_id: str) -> bool:
+    if entry.get("passId") != pass_id or entry.get("action") != "continue":
+        return False
+    if pass_id in VISUAL_PASS_IDS and not review_visual_evidence(entry).get("renderScreenshot"):
+        return False
+    return True
+
+
+def completed_passes(spec: dict[str, Any], ids: list[str]) -> list[str]:
+    history = spec.get("reviewHistory", [])
+    if not isinstance(history, list):
+        return []
+    completed: list[str] = []
+    for pass_id in ids:
+        if any(isinstance(entry, dict) and review_completes_pass(entry, pass_id) for entry in history):
+            completed.append(pass_id)
+        else:
+            break
+    return completed
+
+
+def unlocked_pass(spec: dict[str, Any]) -> str:
+    ids = pass_order(spec)
+    completed = completed_passes(spec, ids)
+    if len(completed) >= len(ids):
+        return ids[-1]
+    return ids[len(completed)]
+
+
+def assert_pass_unlocked(spec: dict[str, Any], requested_pass: str) -> None:
+    ids = pass_order(spec)
+    if requested_pass not in ids:
+        raise ValueError(f"unknown build pass {requested_pass!r}; expected one of: {', '.join(ids)}")
+    completed = completed_passes(spec, ids)
+    current = ids[-1] if len(completed) >= len(ids) else ids[len(completed)]
+    if requested_pass in completed or requested_pass == current:
+        return
+    previous_index = ids.index(requested_pass) - 1
+    previous = ids[previous_index] if previous_index >= 0 else ""
+    raise ValueError(
+        f"build pass {requested_pass!r} is locked; complete {previous!r} first with "
+        "stage4_review/append_review.py action=continue and browser screenshot evidence"
+    )
+
+
+def component_refs_for_pass(spec: dict[str, Any], pass_id: str) -> set[str]:
+    ids = pass_order(spec)
+    if pass_id not in ids:
+        return set()
+    allowed_ids = set(ids[: ids.index(pass_id) + 1])
+    refs: set[str] = set()
+    for item in spec.get("buildPasses", []):
+        if not isinstance(item, dict) or item.get("id") not in allowed_ids:
+            continue
+        component_refs = item.get("componentRefs", [])
+        if isinstance(component_refs, list):
+            refs.update(str(value) for value in component_refs if str(value).strip())
+    return refs
+
+
+def filter_components_for_pass(spec: dict[str, Any], components: list[dict[str, Any]], pass_id: str) -> list[dict[str, Any]]:
+    allowed_levels = PASS_LEVELS.get(pass_id, {"macro"})
+    explicit_refs = component_refs_for_pass(spec, pass_id)
+    included: list[dict[str, Any]] = []
+    included_ids: set[str] = set()
+    visiting_ids: set[str] = set()
+    component_by_id = {str(item.get("id")): item for item in components if item.get("id") is not None}
+
+    def include_component(component: dict[str, Any]) -> None:
+        component_id = str(component.get("id") or "")
+        if not component_id or component_id in included_ids:
+            return
+        if component_id in visiting_ids:
+            raise ValueError(f"component parent cycle contains {component_id!r}")
+        visiting_ids.add(component_id)
+        parent_id = component.get("parent")
+        if parent_id is not None and str(parent_id) in component_by_id:
+            include_component(component_by_id[str(parent_id)])
+        visiting_ids.remove(component_id)
+        included.append(component)
+        included_ids.add(component_id)
+
+    for component in components:
+        component_id = str(component.get("id") or "")
+        level = str(component.get("level") or "macro")
+        tier = str(component.get("fidelityTier") or "")
+        if component_id in explicit_refs or level in allowed_levels or tier == pass_id:
+            include_component(component)
+    if not included and components:
+        included.append(components[0])
+    return included
+
+
+def pascal_case(value: str) -> str:
+    parts = re.findall(r"[A-Za-z0-9]+", value)
+    return "".join(part[:1].upper() + part[1:] for part in parts) or "Object"
+
+
+def const_name(value: str) -> str:
+    name = re.sub(r"[^A-Za-z0-9_]", "_", value.strip())
+    if not name:
+        return "component"
+    if name[0].isdigit():
+        name = "_" + name
+    return name
+
+
+def local_var(prefix: str, value: str, index: int) -> str:
+    return f"{prefix}_{const_name(value)}_{index}"
+
+
+def hex_to_number(value: Any, fallback: str = "#8A7A5F") -> str:
+    color = value if isinstance(value, str) else fallback
+    if re.fullmatch(r"#[0-9A-Fa-f]{6}", color):
+        return "0x" + color[1:]
+    if re.fullmatch(r"#[0-9A-Fa-f]{3}", color):
+        return "0x" + "".join(ch * 2 for ch in color[1:])
+    return "0x" + fallback[1:]
+
+
+def material_base_value(value: Any, fallback: float) -> float:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    if isinstance(value, dict) and isinstance(value.get("base"), (int, float)):
+        return float(value["base"])
+    return fallback
+
+
+def json_literal(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def vector(values: Any, fallback: list[float]) -> str:
+    if (
+        isinstance(values, list)
+        and len(values) == 3
+        and all(isinstance(item, (int, float)) for item in values)
+    ):
+        return ", ".join(str(float(item)) for item in values)
+    return ", ".join(str(item) for item in fallback)
+
+
+def dimension_values(component: dict[str, Any]) -> tuple[float, float, float]:
+    dimensions = component.get("dimensions")
+    if isinstance(dimensions, dict):
+        radius = dimensions.get("radius")
+        diameter = float(radius) * 2 if isinstance(radius, (int, float)) and not isinstance(radius, bool) else 1.0
+        width = dimensions.get("width", diameter)
+        height = dimensions.get("height", dimensions.get("length", 1.0))
+        depth = dimensions.get("depth", diameter)
+        if all(
+            isinstance(item, (int, float))
+            and not isinstance(item, bool)
+            and float(item) > 0
+            for item in (width, height, depth)
+        ):
+            return float(width), float(height), float(depth)
+    return 1.0, 1.0, 1.0
+
+
+def dimension_scale_vector(component: dict[str, Any], primitive: str) -> str:
+    """Scale a normalized primitive to the spec dimensions.
+
+    Component transform.scale belongs on its pivot node; dimensions belong on
+    the mesh. Keeping them separate prevents a parent's physical dimensions
+    from multiplying child coordinates.
+    """
+    width, height, depth = dimension_values(component)
+    if primitive == "capsule":
+        values = [width / 0.7, height / 1.4, depth / 0.7]
+    elif primitive == "torus":
+        # TorusGeometry(0.4, 0.1) has a 1 x 1 x 0.2 bounding box.
+        values = [width, height, depth / 0.2]
+    elif primitive == "plane-card":
+        values = [width, height, 1.0]
+    else:
+        values = [width, height, depth]
+    return vector(values, [1, 1, 1])
+
+
+AXIS_ATTACHMENT_PRIMITIVES = {"cylinder", "cone", "capsule"}
+
+
+def attachment_for_geometry(component: dict[str, Any], primitive: str) -> dict[str, Any] | None:
+    attachment = component.get("attachment")
+    if primitive not in AXIS_ATTACHMENT_PRIMITIVES or not isinstance(attachment, dict):
+        return None
+    payload = dict(attachment)
+    width, _height, depth = dimension_values(component)
+    radius = max(0.005, min(width, depth) / 2)
+    payload.setdefault("baseRadius", radius)
+    payload.setdefault("endRadius", 0.003 if primitive == "cone" else radius)
+    return payload
+
+
+def geometry_for(primitive: str) -> str:
+    if primitive == "box":
+        return "new THREE.BoxGeometry(1, 1, 1, 12, 12, 12)"
+    if primitive in {"sphere", "ellipsoid"}:
+        return "new THREE.SphereGeometry(0.5, 64, 40)"
+    if primitive == "cylinder":
+        return "new THREE.CylinderGeometry(0.5, 0.5, 1, 48, 16)"
+    if primitive == "cone":
+        return "new THREE.ConeGeometry(0.5, 1, 48, 16)"
+    if primitive == "capsule":
+        return "new THREE.CapsuleGeometry(0.35, 0.7, 16, 32)"
+    if primitive == "torus":
+        return "new THREE.TorusGeometry(0.4, 0.1, 24, 96)"
+    if primitive == "plane-card":
+        return "new THREE.PlaneGeometry(1, 1, 24, 24)"
+    raise ValueError(f"primitive {primitive!r} has no implemented geometry")
+
+
+def attachment_geometry_for(primitive: str, endpoint_var: str) -> str:
+    if primitive == "cylinder":
+        return (
+            f"new THREE.CylinderGeometry({endpoint_var}.endRadius, "
+            f"{endpoint_var}.baseRadius, {endpoint_var}.length, 48, 16)"
+        )
+    if primitive == "cone":
+        return (
+            f"new THREE.ConeGeometry({endpoint_var}.baseRadius, "
+            f"{endpoint_var}.length, 48, 16)"
+        )
+    if primitive == "capsule":
+        radius = f"Math.min({endpoint_var}.baseRadius, {endpoint_var}.length / 2)"
+        return (
+            f"new THREE.CapsuleGeometry({radius}, "
+            f"Math.max(0.001, {endpoint_var}.length - 2 * {radius}), 16, 32)"
+        )
+    raise ValueError(f"primitive {primitive!r} cannot follow attachment endpoints")
+
+
+def generate(spec: dict[str, Any], pass_id: str) -> str:
+    target = str(spec.get("targetName") or "Procedural Object")
+    type_name = pascal_case(target)
+    function_name = f"create{type_name}Model"
+    materials = {
+        str(material.get("id") or f"material{index}"): material
+        for index, material in enumerate(spec.get("materials", []))
+        if isinstance(material, dict)
+    }
+    all_components = [item for item in spec.get("componentTree", []) if isinstance(item, dict)]
+    components = filter_components_for_pass(spec, all_components, pass_id)
+
+    lines: list[str] = [
+        "import * as THREE from 'three';",
+        "",
+        "export type ProceduralModelOptions = {",
+        "  wireframe?: boolean;",
+        "  castShadow?: boolean;",
+        "  receiveShadow?: boolean;",
+        "  textureSize?: number;",
+        "  textureAnisotropy?: number;",
+        "  qualityPriority?: 'reference-fidelity' | 'balanced';",
+        "};",
+        "",
+        "export type ProceduralModelRuntime = {",
+        "  nodes: Record<string, THREE.Object3D>;",
+        "  meshes: Record<string, THREE.Mesh>;",
+        "  sockets: Record<string, THREE.Object3D>;",
+        "  colliders: Record<string, unknown>;",
+        "  destructionGroups: Record<string, THREE.Object3D[]>;",
+        "};",
+        "",
+        "type SculptMaterialSpec = Record<string, any>;",
+        "",
+        "function hashString(value: string): number {",
+        "  let hash = 2166136261;",
+        "  for (let index = 0; index < value.length; index += 1) {",
+        "    hash ^= value.charCodeAt(index);",
+        "    hash = Math.imul(hash, 16777619);",
+        "  }",
+        "  return hash >>> 0;",
+        "}",
+        "",
+        "function readLayerNumber(value: unknown, keys: string[], fallback: number): number {",
+        "  if (typeof value === 'number') return value;",
+        "  if (value && typeof value === 'object') {",
+        "    const record = value as Record<string, unknown>;",
+        "    for (const key of keys) {",
+        "      if (typeof record[key] === 'number') return record[key] as number;",
+        "    }",
+        "  }",
+        "  return fallback;",
+        "}",
+        "",
+        "function hexToRgb(hex: string): [number, number, number] {",
+        "  const normalized = /^#[0-9a-f]{3}$/i.test(hex)",
+        "    ? '#' + hex.slice(1).split('').map((part) => part + part).join('')",
+        "    : hex;",
+        "  const value = /^#[0-9a-f]{6}$/i.test(normalized) ? Number.parseInt(normalized.slice(1), 16) : 0x8a7a5f;",
+        "  return [(value >> 16) & 255, (value >> 8) & 255, value & 255];",
+        "}",
+        "",
+        "function materialPalette(spec: SculptMaterialSpec): string[] {",
+        "  const palette = spec.colorVariation?.palette;",
+        "  if (Array.isArray(palette) && palette.length > 0) return palette.filter((value) => typeof value === 'string');",
+        "  const secondary = spec.albedo?.secondary;",
+        "  const colors = [spec.baseColor ?? spec.color ?? spec.albedo?.dominant, ...(Array.isArray(secondary) ? secondary : [])];",
+        "  return colors.filter((value): value is string => typeof value === 'string' && value.startsWith('#'));",
+        "}",
+        "",
+        "function clamp01(value: number): number {",
+        "  return Math.max(0, Math.min(1, value));",
+        "}",
+        "",
+        "function smoothCurve(value: number): number {",
+        "  return value * value * (3 - 2 * value);",
+        "}",
+        "",
+        "function periodicHash(x: number, y: number, seed: number, periodX: number, periodY: number): number {",
+        "  const wrappedX = ((x % periodX) + periodX) % periodX;",
+        "  const wrappedY = ((y % periodY) + periodY) % periodY;",
+        "  let value = Math.imul(wrappedX + seed * 17, 374761393) ^ Math.imul(wrappedY + seed * 31, 668265263);",
+        "  value = Math.imul(value ^ (value >>> 13), 1274126177);",
+        "  return ((value ^ (value >>> 16)) >>> 0) / 4294967295;",
+        "}",
+        "",
+        "function periodicValueNoise(u: number, v: number, seed: number, periodX: number, periodY: number): number {",
+        "  const x = u * periodX;",
+        "  const y = v * periodY;",
+        "  const x0 = Math.floor(x);",
+        "  const y0 = Math.floor(y);",
+        "  const tx = smoothCurve(x - x0);",
+        "  const ty = smoothCurve(y - y0);",
+        "  const a = periodicHash(x0, y0, seed, periodX, periodY);",
+        "  const b = periodicHash(x0 + 1, y0, seed, periodX, periodY);",
+        "  const c = periodicHash(x0, y0 + 1, seed, periodX, periodY);",
+        "  const d = periodicHash(x0 + 1, y0 + 1, seed, periodX, periodY);",
+        "  return THREE.MathUtils.lerp(THREE.MathUtils.lerp(a, b, tx), THREE.MathUtils.lerp(c, d, tx), ty);",
+        "}",
+        "",
+        "type SurfaceBand = {",
+        "  frequency: number;",
+        "  amplitude: number;",
+        "  stretchX: number;",
+        "  stretchY: number;",
+        "  ridge: boolean;",
+        "};",
+        "",
+        "function surfaceBands(spec: SculptMaterialSpec): SurfaceBand[] {",
+        "  const source = Array.isArray(spec.surfaceFrequencyBands) ? spec.surfaceFrequencyBands : [];",
+        "  const parsed = source.flatMap((item: unknown) => {",
+        "    if (!item || typeof item !== 'object') return [];",
+        "    const band = item as Record<string, unknown>;",
+        "    const frequency = typeof band.frequency === 'number' ? band.frequency : 0;",
+        "    const amplitude = typeof band.amplitude === 'number' ? band.amplitude : 0;",
+        "    if (frequency <= 0 || amplitude <= 0) return [];",
+        "    const stretch = Array.isArray(band.stretch) ? band.stretch : [1, 1];",
+        "    const description = `${String(band.pattern ?? '')} ${String(band.role ?? '')}`.toLowerCase();",
+        "    return [{",
+        "      frequency,",
+        "      amplitude,",
+        "      stretchX: typeof stretch[0] === 'number' ? Math.max(0.1, stretch[0]) : 1,",
+        "      stretchY: typeof stretch[1] === 'number' ? Math.max(0.1, stretch[1]) : 1,",
+        "      ridge: /(ridge|groove|grain|fiber|striated|crack)/.test(description),",
+        "    }];",
+        "  });",
+        "  return parsed.length > 0 ? parsed : [",
+        "    { frequency: 2, amplitude: 0.42, stretchX: 1, stretchY: 1, ridge: false },",
+        "    { frequency: 12, amplitude: 0.22, stretchX: 1, stretchY: 1, ridge: false },",
+        "    { frequency: 56, amplitude: 0.08, stretchX: 1, stretchY: 1, ridge: false },",
+        "  ];",
+        "}",
+        "",
+        "function sampleSurface(u: number, v: number, bands: SurfaceBand[], seed: number): number {",
+        "  let value = 0;",
+        "  let weight = 0;",
+        "  for (let index = 0; index < bands.length; index += 1) {",
+        "    const band = bands[index];",
+        "    const periodX = Math.max(1, Math.round(band.frequency * band.stretchX));",
+        "    const periodY = Math.max(1, Math.round(band.frequency * band.stretchY));",
+        "    let sample = periodicValueNoise(u, v, seed + index * 1013, periodX, periodY);",
+        "    if (band.ridge) sample = 1 - Math.abs(sample * 2 - 1);",
+        "    value += sample * band.amplitude;",
+        "    weight += band.amplitude;",
+        "  }",
+        "  return weight > 0 ? clamp01(value / weight) : 0.5;",
+        "}",
+        "",
+        "function mixPalette(colors: [number, number, number][], value: number): [number, number, number] {",
+        "  if (colors.length === 1) return colors[0];",
+        "  const scaled = clamp01(value) * (colors.length - 1);",
+        "  const index = Math.min(colors.length - 2, Math.floor(scaled));",
+        "  const mix = scaled - index;",
+        "  const a = colors[index];",
+        "  const b = colors[index + 1];",
+        "  return [",
+        "    Math.round(THREE.MathUtils.lerp(a[0], b[0], mix)),",
+        "    Math.round(THREE.MathUtils.lerp(a[1], b[1], mix)),",
+        "    Math.round(THREE.MathUtils.lerp(a[2], b[2], mix)),",
+        "  ];",
+        "}",
+        "",
+        "function writePixel(data: Uint8ClampedArray, offset: number, red: number, green: number, blue: number): void {",
+        "  data[offset] = Math.max(0, Math.min(255, Math.round(red)));",
+        "  data[offset + 1] = Math.max(0, Math.min(255, Math.round(green)));",
+        "  data[offset + 2] = Math.max(0, Math.min(255, Math.round(blue)));",
+        "  data[offset + 3] = 255;",
+        "}",
+        "",
+        "function makeCanvas(size: number): HTMLCanvasElement {",
+        "  const canvas = document.createElement('canvas');",
+        "  canvas.width = size;",
+        "  canvas.height = size;",
+        "  return canvas;",
+        "}",
+        "",
+        "function createMapTexture(",
+        "  canvas: HTMLCanvasElement,",
+        "  colorSpace: THREE.ColorSpace,",
+        "  spec: SculptMaterialSpec,",
+        "  options: ProceduralModelOptions,",
+        "): THREE.CanvasTexture {",
+        "  const texture = new THREE.CanvasTexture(canvas);",
+        "  const projection = spec.textureProjection && typeof spec.textureProjection === 'object' ? spec.textureProjection : {};",
+        "  const repeat = Array.isArray(projection.repeat) ? projection.repeat : [2, 2];",
+        "  texture.colorSpace = colorSpace;",
+        "  texture.wrapS = THREE.RepeatWrapping;",
+        "  texture.wrapT = THREE.RepeatWrapping;",
+        "  texture.repeat.set(",
+        "    typeof repeat[0] === 'number' ? repeat[0] : 2,",
+        "    typeof repeat[1] === 'number' ? repeat[1] : 2,",
+        "  );",
+        "  texture.anisotropy = Math.max(1, Math.round(options.textureAnisotropy ?? projection.anisotropy ?? 8));",
+        "  texture.needsUpdate = true;",
+        "  return texture;",
+        "}",
+        "",
+        "type ProceduralTextureSet = {",
+        "  albedo: THREE.Texture;",
+        "  roughness: THREE.Texture;",
+        "  height: THREE.Texture;",
+        "  normal: THREE.Texture;",
+        "  ao: THREE.Texture;",
+        "  source: 'reference-pixel-extraction' | 'procedural';",
+        "};",
+        "",
+        "function referenceMapUrl(spec: SculptMaterialSpec, channel: string): string | null {",
+        "  const reference = spec.referencePbr;",
+        "  if (!reference || typeof reference !== 'object') return null;",
+        "  if (reference.usable === false) return null;",
+        "  const confidence = typeof reference.confidence === 'number'",
+        "    ? reference.confidence",
+        "    : (typeof reference.estimatedFidelity === 'number' ? reference.estimatedFidelity : 0);",
+        "  const threshold = typeof reference.targetThreshold === 'number' ? reference.targetThreshold : 0.7;",
+        "  if (confidence < threshold) return null;",
+        "  const maps = reference.maps;",
+        "  if (!maps || typeof maps !== 'object') return null;",
+        "  const map = (maps as Record<string, unknown>)[channel];",
+        "  if (!map || typeof map !== 'object') return null;",
+        "  const record = map as Record<string, unknown>;",
+        "  const url = typeof record.url === 'string' && record.url.trim() ? record.url : record.path;",
+        "  return typeof url === 'string' && url.trim() ? url : null;",
+        "}",
+        "",
+        "function createLoadedMapTexture(",
+        "  url: string,",
+        "  colorSpace: THREE.ColorSpace,",
+        "  spec: SculptMaterialSpec,",
+        "  options: ProceduralModelOptions,",
+        "): THREE.Texture {",
+        "  const texture = new THREE.TextureLoader().load(url);",
+        "  const projection = spec.textureProjection && typeof spec.textureProjection === 'object' ? spec.textureProjection : {};",
+        "  const repeat = Array.isArray(projection.repeat) ? projection.repeat : [1, 1];",
+        "  texture.colorSpace = colorSpace;",
+        "  texture.wrapS = THREE.RepeatWrapping;",
+        "  texture.wrapT = THREE.RepeatWrapping;",
+        "  texture.repeat.set(",
+        "    typeof repeat[0] === 'number' ? repeat[0] : 1,",
+        "    typeof repeat[1] === 'number' ? repeat[1] : 1,",
+        "  );",
+        "  texture.anisotropy = Math.max(1, Math.round(options.textureAnisotropy ?? projection.anisotropy ?? 8));",
+        "  texture.needsUpdate = true;",
+        "  return texture;",
+        "}",
+        "",
+        "function makeReferenceTextureSet(spec: SculptMaterialSpec, options: ProceduralModelOptions): ProceduralTextureSet | null {",
+        "  const albedo = referenceMapUrl(spec, 'albedo');",
+        "  const roughness = referenceMapUrl(spec, 'roughness');",
+        "  const height = referenceMapUrl(spec, 'height');",
+        "  const normal = referenceMapUrl(spec, 'normal');",
+        "  const ao = referenceMapUrl(spec, 'ao');",
+        "  if (!albedo || !roughness || !height || !normal || !ao) return null;",
+        "  return {",
+        "    albedo: createLoadedMapTexture(albedo, THREE.SRGBColorSpace, spec, options),",
+        "    roughness: createLoadedMapTexture(roughness, THREE.NoColorSpace, spec, options),",
+        "    height: createLoadedMapTexture(height, THREE.NoColorSpace, spec, options),",
+        "    normal: createLoadedMapTexture(normal, THREE.NoColorSpace, spec, options),",
+        "    ao: createLoadedMapTexture(ao, THREE.NoColorSpace, spec, options),",
+        "    source: 'reference-pixel-extraction',",
+        "  };",
+        "}",
+        "",
+        "function makeProceduralTextureSet(",
+        "  id: string,",
+        "  spec: SculptMaterialSpec,",
+        "  options: ProceduralModelOptions,",
+        "): ProceduralTextureSet | null {",
+        "  if (typeof document === 'undefined') return null;",
+        "  const qualityFirst = (options.qualityPriority ?? 'reference-fidelity') === 'reference-fidelity';",
+        "  const requested = options.textureSize ?? spec.textureResolution;",
+        "  const requestedSize = typeof requested === 'number' && Number.isFinite(requested)",
+        "    ? requested",
+        "    : (qualityFirst ? 1024 : 512);",
+        "  const size = Math.max(256, Math.min(2048, 2 ** Math.round(Math.log2(requestedSize))));",
+        "  const canvases = {",
+        "    albedo: makeCanvas(size),",
+        "    roughness: makeCanvas(size),",
+        "    height: makeCanvas(size),",
+        "    normal: makeCanvas(size),",
+        "    ao: makeCanvas(size),",
+        "  };",
+        "  const contexts = {",
+        "    albedo: canvases.albedo.getContext('2d'),",
+        "    roughness: canvases.roughness.getContext('2d'),",
+        "    height: canvases.height.getContext('2d'),",
+        "    normal: canvases.normal.getContext('2d'),",
+        "    ao: canvases.ao.getContext('2d'),",
+        "  };",
+        "  if (!contexts.albedo || !contexts.roughness || !contexts.height || !contexts.normal || !contexts.ao) return null;",
+        "  const images = {",
+        "    albedo: contexts.albedo.createImageData(size, size),",
+        "    roughness: contexts.roughness.createImageData(size, size),",
+        "    height: contexts.height.createImageData(size, size),",
+        "    normal: contexts.normal.createImageData(size, size),",
+        "    ao: contexts.ao.createImageData(size, size),",
+        "  };",
+        "  const seed = hashString(id);",
+        "  const bands = surfaceBands(spec);",
+        "  const heightField = new Float32Array(size * size);",
+        "  const roughnessField = new Float32Array(size * size);",
+        "  const palette = materialPalette(spec);",
+        "  const fallback = typeof spec.baseColor === 'string' ? spec.baseColor : '#8A7A5F';",
+        "  const colors = (palette.length >= 2 ? palette : [fallback, '#6E614B', '#A08F70']).map(hexToRgb);",
+        "  const baseRoughness = clamp01(readLayerNumber(spec.roughness, ['base'], 0.76));",
+        "  const roughnessVariation = clamp01(readLayerNumber(spec.roughness, ['variation'], 0.18));",
+        "  const colorAmplitude = clamp01(readLayerNumber(spec.colorVariation, ['amplitude', 'variation'], 0.18));",
+        "  const heightCorrelation = clamp01(readLayerNumber(spec.colorVariation, ['heightCorrelation'], 0.3));",
+        "  for (let y = 0; y < size; y += 1) {",
+        "    const v = y / size;",
+        "    for (let x = 0; x < size; x += 1) {",
+        "      const u = x / size;",
+        "      const index = y * size + x;",
+        "      const height = sampleSurface(u, v, bands, seed + 101);",
+        "      const roughNoise = sampleSurface(u, v, bands, seed + 7001);",
+        "      const colorNoise = sampleSurface(u, v, bands, seed + 15013);",
+        "      heightField[index] = height;",
+        "      roughnessField[index] = clamp01(baseRoughness + (roughNoise - 0.5) * roughnessVariation * 2);",
+        "      const paletteValue = clamp01(",
+        "        0.5 + (colorNoise - 0.5) * colorAmplitude * 2 + (height - 0.5) * heightCorrelation",
+        "      );",
+        "      const color = mixPalette(colors, paletteValue);",
+        "      writePixel(images.albedo.data, index * 4, color[0], color[1], color[2]);",
+        "    }",
+        "  }",
+        "  const normalStrength = Math.max(0.05, readLayerNumber(spec.normal, ['strength', 'amplitude'], 0.35));",
+        "  const aoStrength = clamp01(readLayerNumber(spec.ambientOcclusion, ['cavityStrength', 'strength'], 0.35));",
+        "  for (let y = 0; y < size; y += 1) {",
+        "    const up = ((y - 1 + size) % size) * size;",
+        "    const down = ((y + 1) % size) * size;",
+        "    for (let x = 0; x < size; x += 1) {",
+        "      const left = (x - 1 + size) % size;",
+        "      const right = (x + 1) % size;",
+        "      const index = y * size + x;",
+        "      const center = heightField[index];",
+        "      const dx = (heightField[y * size + right] - heightField[y * size + left]) * normalStrength * 6;",
+        "      const dy = (heightField[down + x] - heightField[up + x]) * normalStrength * 6;",
+        "      const inverseLength = 1 / Math.sqrt(dx * dx + dy * dy + 1);",
+        "      const normalX = -dx * inverseLength;",
+        "      const normalY = -dy * inverseLength;",
+        "      const normalZ = inverseLength;",
+        "      const neighborAverage = (",
+        "        heightField[y * size + left] + heightField[y * size + right]",
+        "        + heightField[up + x] + heightField[down + x]",
+        "      ) * 0.25;",
+        "      const cavity = Math.max(0, neighborAverage - center);",
+        "      const ao = clamp01(1 - aoStrength * (cavity * 12 + (1 - center) * 0.16));",
+        "      const offset = index * 4;",
+        "      const heightByte = center * 255;",
+        "      const roughnessByte = roughnessField[index] * 255;",
+        "      writePixel(images.height.data, offset, heightByte, heightByte, heightByte);",
+        "      writePixel(images.roughness.data, offset, roughnessByte, roughnessByte, roughnessByte);",
+        "      writePixel(",
+        "        images.normal.data, offset,",
+        "        (normalX * 0.5 + 0.5) * 255,",
+        "        (normalY * 0.5 + 0.5) * 255,",
+        "        (normalZ * 0.5 + 0.5) * 255,",
+        "      );",
+        "      writePixel(images.ao.data, offset, ao * 255, ao * 255, ao * 255);",
+        "    }",
+        "  }",
+        "  contexts.albedo.putImageData(images.albedo, 0, 0);",
+        "  contexts.roughness.putImageData(images.roughness, 0, 0);",
+        "  contexts.height.putImageData(images.height, 0, 0);",
+        "  contexts.normal.putImageData(images.normal, 0, 0);",
+        "  contexts.ao.putImageData(images.ao, 0, 0);",
+        "  return {",
+        "    albedo: createMapTexture(canvases.albedo, THREE.SRGBColorSpace, spec, options),",
+        "    roughness: createMapTexture(canvases.roughness, THREE.NoColorSpace, spec, options),",
+        "    height: createMapTexture(canvases.height, THREE.NoColorSpace, spec, options),",
+        "    normal: createMapTexture(canvases.normal, THREE.NoColorSpace, spec, options),",
+        "    ao: createMapTexture(canvases.ao, THREE.NoColorSpace, spec, options),",
+        "    source: 'procedural',",
+        "  };",
+        "}",
+        "",
+        "function createSculptMaterial(id: string, spec: SculptMaterialSpec, options: ProceduralModelOptions): THREE.MeshPhysicalMaterial {",
+        "  const textures = makeReferenceTextureSet(spec, options) ?? makeProceduralTextureSet(id, spec, options);",
+        "  const material = new THREE.MeshPhysicalMaterial({",
+        "    color: textures ? 0xffffff : new THREE.Color(typeof spec.baseColor === 'string' ? spec.baseColor : '#8A7A5F'),",
+        "    roughness: textures ? 1 : clamp01(readLayerNumber(spec.roughness, ['base'], 0.76)),",
+        "    metalness: clamp01(readLayerNumber(spec.metalness, ['base'], 0.0)),",
+        "    clearcoat: clamp01(readLayerNumber(spec.clearcoat, ['base', 'amount'], 0)),",
+        "    clearcoatRoughness: clamp01(readLayerNumber(spec.clearcoatRoughness, ['base'], 0.25)),",
+        "    transmission: clamp01(readLayerNumber(spec.transmission, ['base', 'amount'], 0)),",
+        "    opacity: clamp01(readLayerNumber(spec.opacity, ['base'], 1)),",
+        "    transparent: readLayerNumber(spec.transmission, ['base', 'amount'], 0) > 0 || readLayerNumber(spec.opacity, ['base'], 1) < 1,",
+        "    alphaTest: Math.max(0, readLayerNumber(spec.alpha, ['cutoff', 'alphaTest'], 0)),",
+        "    wireframe: options.wireframe ?? false,",
+        "    side: spec.doubleSided === true ? THREE.DoubleSide : THREE.FrontSide,",
+        "  });",
+        "  if (textures) {",
+        "    material.map = textures.albedo;",
+        "    material.roughnessMap = textures.roughness;",
+        "    material.normalMap = textures.normal;",
+        "    material.normalScale.setScalar(Math.max(0.05, readLayerNumber(spec.normal, ['strength', 'amplitude'], 0.35)));",
+        "    material.aoMap = textures.ao;",
+        "    material.aoMap.channel = 0;",
+        "    material.aoMapIntensity = readLayerNumber(spec.ambientOcclusion, ['cavityStrength', 'strength'], 0.35);",
+        "    const bumpScale = Math.max(0, readLayerNumber(spec.bump, ['amplitude', 'strength'], 0));",
+        "    if (bumpScale > 0) {",
+        "      material.bumpMap = textures.height;",
+        "      material.bumpScale = bumpScale;",
+        "    }",
+        "    const displacementScale = Math.max(0, readLayerNumber(spec.displacement, ['amplitude', 'strength'], 0));",
+        "    if (displacementScale > 0) {",
+        "      material.displacementMap = textures.height;",
+        "      material.displacementScale = displacementScale;",
+        "      material.displacementBias = -displacementScale * 0.5;",
+        "    }",
+        "  }",
+        "  material.envMapIntensity = readLayerNumber(spec, ['envMapIntensity'], 0.8);",
+        "  material.userData.sculptMaterial = spec;",
+        "  material.userData.proceduralMapsIndependent = true;",
+        "  material.userData.pbrTextureSource = textures?.source ?? 'flat-fallback';",
+        "  material.userData.referencePbr = spec.referencePbr ?? null;",
+        "  material.needsUpdate = true;",
+        "  return material;",
+        "}",
+        "",
+        "type AttachmentEndpoint = {",
+        "  start: THREE.Vector3;",
+        "  midpoint: THREE.Vector3;",
+        "  quaternion: THREE.Quaternion;",
+        "  length: number;",
+        "  baseRadius: number;",
+        "  endRadius: number;",
+        "};",
+        "",
+        "function readVector3(value: unknown, fallback: [number, number, number]): THREE.Vector3 {",
+        "  if (Array.isArray(value) && value.length === 3 && value.every((item) => typeof item === 'number')) {",
+        "    return new THREE.Vector3(value[0], value[1], value[2]);",
+        "  }",
+        "  return new THREE.Vector3(fallback[0], fallback[1], fallback[2]);",
+        "}",
+        "",
+        "function readNumber(value: unknown, fallback: number): number {",
+        "  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;",
+        "}",
+        "",
+        "function makeAttachmentEndpoint(attachment: unknown): AttachmentEndpoint | null {",
+        "  if (!attachment || typeof attachment !== 'object') return null;",
+        "  const record = attachment as Record<string, unknown>;",
+        "  const start = readVector3(record.localStart, [0, 0, 0]);",
+        "  const end = readVector3(record.localEnd, [0, 1, 0]);",
+        "  const delta = end.clone().sub(start);",
+        "  const length = delta.length();",
+        "  if (length <= 0.0001) return null;",
+        "  const direction = delta.clone().normalize();",
+        "  const quaternion = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), direction);",
+        "  const baseRadius = Math.max(0.005, readNumber(record.baseRadius, 0.06));",
+        "  const endRadius = Math.max(0.003, readNumber(record.endRadius, baseRadius * 0.55));",
+        "  return {",
+        "    start,",
+        "    midpoint: delta.multiplyScalar(0.5),",
+        "    quaternion,",
+        "    length,",
+        "    baseRadius,",
+        "    endRadius,",
+        "  };",
+        "}",
+        "",
+        f"// Generated from ObjectSculptSpec target: {target}",
+        f"// Sculpt build pass: {pass_id}",
+        (
+            "// Compile-only hosted preview: unreviewed; no upstream pass approval is claimed."
+            if pass_id == "hosted-preview"
+            else "// Pass-gated output. Finish browser screenshot review before unlocking deeper passes."
+        ),
+        f"export function {function_name}(options: ProceduralModelOptions = {{}}): THREE.Group {{",
+        "  const root = new THREE.Group();",
+        f"  root.name = {json.dumps(target)};",
+        "",
+        "  const materialMap: Record<string, THREE.Material> = {};",
+    ]
+    for material_id, material in materials.items():
+        lines.extend(
+            [
+                f"  materialMap[{json.dumps(material_id)}] = createSculptMaterial(",
+                f"    {json.dumps(material_id)},",
+                f"    {json_literal(material)},",
+                "    options",
+                "  );",
+            ]
+        )
+    lines.extend(
+        [
+            "",
+            "  const nodes: Record<string, THREE.Object3D> = { root };",
+            "  const meshes: Record<string, THREE.Mesh> = {};",
+            "  const sockets: Record<string, THREE.Object3D> = {};",
+            "  const colliders: Record<string, unknown> = {};",
+            "  const destructionGroups: Record<string, THREE.Object3D[]> = {};",
+        ]
+    )
+
+    for index, component in enumerate(components):
+        component_id = str(component.get("id") or f"component-{index}")
+        component_var = local_var("mesh", component_id, index)
+        node_var = local_var("node", component_id, index)
+        primitive = str(component.get("primitive") or "box")
+        if primitive not in VALID_PRIMITIVES:
+            primitive = "box"
+        transform = component.get("transform", {}) if isinstance(component.get("transform"), dict) else {}
+        action_profile = component.get("actionProfile") if isinstance(component.get("actionProfile"), dict) else {}
+        sockets_spec = action_profile.get("sockets", []) if isinstance(action_profile.get("sockets"), list) else []
+        destruction = action_profile.get("destruction") if isinstance(action_profile.get("destruction"), dict) else {}
+        fracture_group = destruction.get("fractureGroup") if isinstance(destruction, dict) else None
+        attachment = attachment_for_geometry(component, primitive)
+        attachment_var = local_var("attachment", component_id, index)
+        endpoint_var = local_var("endpoint", component_id, index)
+        material_id = str(component.get("material") or next(iter(materials.keys()), "base"))
+        parent = component.get("parent") or "root"
+        name = str(component.get("name") or component_id)
+        lines.extend(
+            [
+                "",
+                f"  const {attachment_var} = {json.dumps(attachment, ensure_ascii=False)};",
+                f"  const {endpoint_var} = makeAttachmentEndpoint({attachment_var});",
+                f"  const {node_var} = new THREE.Group();",
+                f"  {node_var}.name = {json.dumps(name + '__pivot')};",
+                f"  if ({endpoint_var}) {{",
+                f"    {node_var}.position.copy({endpoint_var}.start);",
+                f"    {node_var}.rotation.set(0, 0, 0);",
+                f"    {node_var}.scale.set(1, 1, 1);",
+                "  } else {",
+                f"    {node_var}.position.set({vector(transform.get('position'), [0, 0, 0])});",
+                f"    {node_var}.rotation.set({vector(transform.get('rotation'), [0, 0, 0])});",
+                f"    {node_var}.scale.set({vector(transform.get('scale'), [1, 1, 1])});",
+                "  }",
+                f"  {node_var}.userData.sculptComponent = {json.dumps(component, ensure_ascii=False)};",
+                f"  {node_var}.userData.actionProfile = {json.dumps(action_profile, ensure_ascii=False)};",
+                f"  (nodes[{json.dumps(str(parent))}] ?? root).add({node_var});",
+                f"  nodes[{json.dumps(component_id)}] = {node_var};",
+            ]
+        )
+        if primitive in AXIS_ATTACHMENT_PRIMITIVES:
+            lines.extend(
+                [
+                    f"  const {component_var}Geometry = {endpoint_var}",
+                    f"    ? {attachment_geometry_for(primitive, endpoint_var)}",
+                    f"    : {geometry_for(primitive)};",
+                ]
+            )
+        else:
+            lines.append(f"  const {component_var}Geometry = {geometry_for(primitive)};")
+        lines.extend(
+            [
+                f"  const {component_var} = new THREE.Mesh(",
+                f"    {component_var}Geometry,",
+                f"    materialMap[{json.dumps(material_id)}] ?? new THREE.MeshStandardMaterial({{ color: 0x888888 }})",
+                "  );",
+                f"  {component_var}.name = {json.dumps(name)};",
+                f"  if ({endpoint_var}) {{",
+                f"    {component_var}.position.copy({endpoint_var}.midpoint);",
+                f"    {component_var}.quaternion.copy({endpoint_var}.quaternion);",
+                "  } else {",
+                f"    {component_var}.scale.set({dimension_scale_vector(component, primitive)});",
+                "  }",
+                f"  {component_var}.castShadow = options.castShadow ?? true;",
+                f"  {component_var}.receiveShadow = options.receiveShadow ?? true;",
+                f"  {component_var}.userData.sculptComponent = {json.dumps(component, ensure_ascii=False)};",
+                f"  {node_var}.add({component_var});",
+                f"  meshes[{json.dumps(component_id)}] = {component_var};",
+                f"  colliders[{json.dumps(component_id)}] = {json.dumps(action_profile.get('collider', {}), ensure_ascii=False)};",
+            ]
+        )
+        if isinstance(fracture_group, str) and fracture_group:
+            lines.extend(
+                [
+                    f"  destructionGroups[{json.dumps(fracture_group)}] ??= [];",
+                    f"  destructionGroups[{json.dumps(fracture_group)}].push({node_var});",
+                ]
+            )
+        for socket_index, socket in enumerate(sockets_spec):
+            if not isinstance(socket, dict):
+                continue
+            socket_id = str(socket.get("id") or f"socket-{socket_index}")
+            socket_var = local_var("socket", f"{component_id}_{socket_id}", socket_index)
+            local_position = socket.get("localPosition", socket.get("position"))
+            local_rotation = socket.get("localRotation", socket.get("rotation"))
+            socket_key = f"{component_id}:{socket_id}"
+            lines.extend(
+                [
+                    f"  const {socket_var} = new THREE.Object3D();",
+                    f"  {socket_var}.name = {json.dumps(socket_id)};",
+                    f"  {socket_var}.position.set({vector(local_position, [0, 0, 0])});",
+                    f"  {socket_var}.rotation.set({vector(local_rotation, [0, 0, 0])});",
+                    f"  {socket_var}.userData.socket = {json.dumps(socket, ensure_ascii=False)};",
+                    f"  {node_var}.add({socket_var});",
+                    f"  sockets[{json.dumps(socket_key)}] = {socket_var};",
+                ]
+            )
+    look_dev_targets = spec.get("lookDevTargets", {})
+    lighting_from_photo = spec.get("lightingFromPhoto", [])
+    lines.extend(
+        [
+            "",
+            "  root.userData.sculptRuntime = { nodes, meshes, sockets, colliders, destructionGroups } satisfies ProceduralModelRuntime;",
+            f"  root.userData.lookDevTargets = {json_literal(look_dev_targets)};",
+            "  root.userData.actionReadiness = {",
+            "    note: 'Use root.userData.sculptRuntime.nodes for transforms, sockets for attachments, colliders for physics proxies, and destructionGroups for breakable sets.',",
+            "  };",
+            "  return root;",
+            "}",
+            "",
+            f"export function create{type_name}LookDevLights(",
+            "  mode: 'neutral' | 'grazing' | 'reference' = 'neutral',",
+            "): THREE.Group {",
+            "  const lights = new THREE.Group();",
+            f"  lights.name = {json.dumps(target + ' look-dev lights')};",
+            "  const hemi = new THREE.HemisphereLight(",
+            "    mode === 'reference' ? 0xfff0d6 : 0xf2f4ff,",
+            "    0x363b42,",
+            "    mode === 'grazing' ? 0.28 : mode === 'reference' ? 0.72 : 0.85,",
+            "  );",
+            "  lights.add(hemi);",
+            "  const key = new THREE.DirectionalLight(",
+            "    mode === 'reference' ? 0xffcf8a : 0xfff4e8,",
+            "    mode === 'grazing' ? 4.2 : mode === 'reference' ? 2.6 : 2.15,",
+            "  );",
+            "  if (mode === 'grazing') key.position.set(7.5, 1.1, 4.0);",
+            "  else if (mode === 'reference') key.position.set(-4.5, 7.5, 5.0);",
+            "  else key.position.set(-4.0, 6.0, 5.5);",
+            "  key.castShadow = true;",
+            "  key.shadow.mapSize.set(4096, 4096);",
+            "  key.shadow.bias = -0.00025;",
+            "  key.shadow.normalBias = 0.018;",
+            "  lights.add(key);",
+            "  const fill = new THREE.DirectionalLight(0xa8c4ff, mode === 'grazing' ? 0.12 : 0.42);",
+            "  fill.position.set(4.0, 3.0, 3.5);",
+            "  lights.add(fill);",
+            "  const rim = new THREE.DirectionalLight(0xfff1c4, mode === 'grazing' ? 0.28 : 0.85);",
+            "  rim.position.set(0.5, 4.5, -6.0);",
+            "  lights.add(rim);",
+            "  lights.userData.reviewMode = mode;",
+            f"  lights.userData.lightingFromPhoto = {json_literal(lighting_from_photo)};",
+            f"  lights.userData.lookDevTargets = {json_literal(look_dev_targets)};",
+            "  return lights;",
+            "}",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("spec", type=Path)
+    parser.add_argument("--out", type=Path, required=True)
+    parser.add_argument(
+        "--pass-id",
+        help="Build pass to generate. Defaults to the current unlocked sculptPipeline pass.",
+    )
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args(argv)
+
+    spec = load_spec(args.spec.expanduser().resolve())
+    pass_id = args.pass_id or unlocked_pass(spec)
+    try:
+        assert_pass_unlocked(spec, pass_id)
+    except ValueError as exc:
+        parser.error(str(exc))
+    gaps = pass_specific_gaps(spec, pass_id)
+    if gaps:
+        parser.error(f"build pass {pass_id!r} needs spec refinement: {'; '.join(gaps)}")
+    output = args.out.expanduser().resolve()
+    if output.exists() and not args.force:
+        parser.error(f"{output} already exists; use --force to overwrite")
+    output.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        source = generate(spec, pass_id)
+    except ValueError as exc:
+        parser.error(str(exc))
+    output.write_text(source, encoding="utf-8")
+    print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage3_build/orchestrate_passes.py

@@ -0,0 +1,543 @@
+#!/usr/bin/env python3
+"""Gate procedural sculpt generation through ordered build passes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_shared"))
+from feature_acceptance_policy import feature_gate_failures
+
+
+DEFAULT_PASS_ORDER = [
+    "blockout",
+    "structural-pass",
+    "form-refinement",
+    "material-pass",
+    "surface-pass",
+    "lighting-pass",
+    "interaction-pass",
+    "optimization-pass",
+]
+VISUAL_PASS_IDS = set(DEFAULT_PASS_ORDER) - {"optimization-pass"}
+ATTACHMENT_ROLES = {
+    "appendage",
+    "branch",
+    "limb",
+    "arm",
+    "leg",
+    "handle",
+    "connector",
+    "tube",
+    "cable",
+    "horn",
+    "wing",
+    "tail",
+    "root",
+    "fork",
+    "rib",
+    "support",
+    "hinge",
+    "socket",
+    "pipe",
+}
+ATTACHMENT_PRIMITIVES = {"cylinder", "cone", "capsule", "tube", "curve-sweep"}
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("spec must be a JSON object")
+    return payload
+
+
+def write_spec(path: Path, spec: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(spec, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def pass_order(spec: dict[str, Any]) -> list[str]:
+    ids: list[str] = []
+    for item in spec.get("buildPasses", []):
+        if isinstance(item, dict) and isinstance(item.get("id"), str) and item["id"].strip():
+            ids.append(item["id"])
+    return ids or DEFAULT_PASS_ORDER.copy()
+
+
+def pass_acceptance(spec: dict[str, Any], pass_id: str) -> list[str]:
+    for item in spec.get("buildPasses", []):
+        if isinstance(item, dict) and item.get("id") == pass_id:
+            acceptance = item.get("acceptance", [])
+            if isinstance(acceptance, list):
+                return [str(value) for value in acceptance if str(value).strip()]
+    return []
+
+
+def visual_evidence(entry: dict[str, Any]) -> dict[str, Any]:
+    visual = entry.get("visualEvidence")
+    return visual if isinstance(visual, dict) else {}
+
+
+def review_completes_pass(spec: dict[str, Any], entry: dict[str, Any], pass_id: str) -> bool:
+    if entry.get("passId") != pass_id or entry.get("action") != "continue":
+        return False
+    if pass_id in VISUAL_PASS_IDS:
+        visual = visual_evidence(entry)
+        if not visual.get("renderScreenshot") or not visual.get("comparisonImage"):
+            return False
+        score = entry.get("aiVisionScore")
+        threshold = entry.get("visualAcceptanceThreshold", 0.7)
+        if not has_number(score) or not has_number(threshold) or float(score) < float(threshold):
+            return False
+        if feature_gate_failures(spec, entry, pass_id):
+            return False
+    return True
+
+
+def completed_passes(spec: dict[str, Any], ids: list[str]) -> list[str]:
+    history = spec.get("reviewHistory", [])
+    if not isinstance(history, list):
+        return []
+    completed: list[str] = []
+    for pass_id in ids:
+        if any(
+            isinstance(entry, dict) and review_completes_pass(spec, entry, pass_id)
+            for entry in history
+        ):
+            completed.append(pass_id)
+        else:
+            break
+    return completed
+
+
+def current_pass(ids: list[str], completed: list[str]) -> str:
+    if len(completed) >= len(ids):
+        return "complete"
+    return ids[len(completed)]
+
+
+def next_required_evidence(spec: dict[str, Any], pass_id: str) -> list[str]:
+    if pass_id == "complete":
+        return []
+    evidence = pass_acceptance(spec, pass_id)
+    evidence.extend(pass_specific_evidence(pass_id))
+    if pass_id in VISUAL_PASS_IDS:
+        evidence.append("browser render screenshot from your agent's browser/screenshot tool")
+        evidence.append("side-by-side reference/render comparison sheet for AI vision review")
+        evidence.append("AI vision score at or above the visual acceptance threshold")
+        evidence.append("all critical semantic feature scores from the shared image pair at or above their thresholds")
+        evidence.append("self-correction review appended with action=continue before the next pass")
+    return evidence
+
+
+def has_non_empty(value: Any) -> bool:
+    if isinstance(value, str):
+        return bool(value.strip()) and value.strip().lower() not in {"none", "unassessed", "n/a"}
+    if isinstance(value, list):
+        return any(has_non_empty(item) for item in value)
+    if isinstance(value, dict):
+        return any(has_non_empty(item) for item in value.values())
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return abs(float(value)) > 0
+    return False
+
+
+def number_from_layer(value: Any, keys: tuple[str, ...]) -> float:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    if isinstance(value, dict):
+        for key in keys:
+            item = value.get(key)
+            if isinstance(item, (int, float)) and not isinstance(item, bool):
+                return float(item)
+    return 0.0
+
+
+def is_vector3(value: Any) -> bool:
+    return (
+        isinstance(value, list)
+        and len(value) == 3
+        and all(isinstance(item, (int, float)) and not isinstance(item, bool) for item in value)
+    )
+
+
+def has_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def component_requires_attachment(component: dict[str, Any]) -> bool:
+    if not component.get("parent"):
+        return False
+    role = str(component.get("role") or "").lower()
+    name = str(component.get("name") or component.get("id") or "").lower()
+    primitive = str(component.get("primitive") or "").lower()
+    action = component.get("actionProfile") if isinstance(component.get("actionProfile"), dict) else {}
+    animation_role = str(action.get("animationRole") or "").lower()
+    tokens = {role, animation_role} | set(re.findall(r"[a-z0-9]+", name))
+    return bool(tokens & ATTACHMENT_ROLES) or primitive in ATTACHMENT_PRIMITIVES
+
+
+def attachment_complete(component: dict[str, Any]) -> bool:
+    attachment = component.get("attachment")
+    if not isinstance(attachment, dict):
+        return False
+    has_endpoint = is_vector3(attachment.get("localStart")) and is_vector3(attachment.get("localEnd"))
+    has_socket = has_non_empty(attachment.get("parentSocket")) or has_non_empty(attachment.get("parentId"))
+    has_contact = has_non_empty(attachment.get("contactType"))
+    has_overlap = (
+        number_from_layer(attachment.get("embedDepth"), ("base", "amount", "value")) > 0
+        or number_from_layer(attachment.get("overlap"), ("base", "amount", "value")) > 0
+    )
+    has_tolerance = has_number(attachment.get("gapTolerance"))
+    return has_endpoint and has_socket and has_contact and has_overlap and has_tolerance
+
+
+def attachment_gaps(spec: dict[str, Any]) -> list[str]:
+    gaps: list[str] = []
+    for component in spec.get("componentTree", []):
+        if not isinstance(component, dict) or not component_requires_attachment(component):
+            continue
+        if attachment_complete(component):
+            continue
+        component_id = str(component.get("id") or component.get("name") or "(unnamed)")
+        gaps.append(
+            f"component {component_id!r} requires attachment.parentSocket/localStart/localEnd/"
+            "contactType/embedDepth(or overlap)/gapTolerance"
+        )
+    return gaps
+
+
+def material_has_palette(material: dict[str, Any]) -> bool:
+    color_variation = material.get("colorVariation")
+    if isinstance(color_variation, dict) and len(color_variation.get("palette", [])) >= 2:
+        return True
+    albedo = material.get("albedo")
+    if isinstance(albedo, dict) and has_non_empty(albedo.get("secondary")):
+        return True
+    return has_non_empty(material.get("baseColor") or material.get("color"))
+
+
+def material_has_response(material: dict[str, Any]) -> bool:
+    if number_from_layer(material.get("roughness"), ("variation", "base")) > 0:
+        return True
+    if number_from_layer(material.get("normal"), ("strength", "amplitude")) > 0:
+        return True
+    if number_from_layer(material.get("bump"), ("amplitude", "strength")) > 0:
+        return True
+    if number_from_layer(material.get("displacement"), ("amplitude", "strength")) > 0:
+        return True
+    return False
+
+
+def material_has_locality(material: dict[str, Any]) -> bool:
+    if has_non_empty(material.get("localOverrides")):
+        return True
+    wear = material.get("wear")
+    if isinstance(wear, dict) and (
+        number_from_layer(wear.get("edgeWear"), ("base", "amount")) > 0
+        or has_non_empty(wear.get("scratches"))
+        or has_non_empty(wear.get("chips"))
+    ):
+        return True
+    dirt = material.get("dirt")
+    if isinstance(dirt, dict) and (
+        number_from_layer(dirt.get("amount"), ("base", "amount")) > 0
+        or number_from_layer(dirt.get("cavityBias"), ("base", "amount")) > 0
+    ):
+        return True
+    for field in ("moss", "stains", "scratches", "chips", "wetness", "patina", "soot"):
+        if has_non_empty(material.get(field)):
+            return True
+    return False
+
+
+def quality_first_enabled(spec: dict[str, Any]) -> bool:
+    targets = spec.get("lookDevTargets")
+    return isinstance(targets, dict) and targets.get("qualityPriority") == "reference-fidelity"
+
+
+def reference_pbr_usable(material: dict[str, Any], threshold: float) -> tuple[bool, str]:
+    material_id = str(material.get("id") or "(unnamed)")
+    reference = material.get("referencePbr")
+    if not isinstance(reference, dict):
+        return False, f"material {material_id!r} needs usable referencePbr extracted from source pixels"
+    if reference.get("usable") is not True:
+        return False, f"material {material_id!r} referencePbr.usable must be true"
+    confidence = reference.get("confidence", reference.get("estimatedFidelity"))
+    if not has_number(confidence) or float(confidence) < threshold:
+        return False, f"material {material_id!r} referencePbr confidence must be >= {threshold}"
+    maps = reference.get("maps")
+    if not isinstance(maps, dict):
+        return False, f"material {material_id!r} referencePbr needs maps"
+    for channel in ("albedo", "roughness", "height", "normal", "ao"):
+        entry = maps.get(channel)
+        if not isinstance(entry, dict) or not has_non_empty(entry.get("url") or entry.get("path")):
+            return False, f"material {material_id!r} referencePbr missing {channel} map path/url"
+    return True, ""
+
+
+def quality_first_material_gaps(spec: dict[str, Any], material: dict[str, Any]) -> list[str]:
+    material_id = str(material.get("id") or "(unnamed)")
+    gaps: list[str] = []
+    targets = spec.get("lookDevTargets")
+    material_targets = targets.get("materialPass", {}) if isinstance(targets, dict) else {}
+    minimum_resolution = material_targets.get("minimumTextureResolution", 1024)
+    if not isinstance(minimum_resolution, int) or isinstance(minimum_resolution, bool):
+        minimum_resolution = 1024
+    extraction_targets = material_targets.get("referencePbrExtraction", {})
+    if not isinstance(extraction_targets, dict):
+        extraction_targets = {}
+    pbr_required = (
+        extraction_targets.get("requiredWhenSourceImagePresent") is True
+        and has_non_empty(spec.get("sourceImage"))
+    )
+    pbr_threshold = extraction_targets.get("targetThreshold", 0.7)
+    if not has_number(pbr_threshold):
+        pbr_threshold = 0.7
+    resolution = material.get("textureResolution")
+    if not isinstance(resolution, int) or isinstance(resolution, bool) or resolution < minimum_resolution:
+        gaps.append(f"material {material_id!r} textureResolution must be >= {minimum_resolution}")
+
+    projection = material.get("textureProjection")
+    if not isinstance(projection, dict) or not has_non_empty(projection.get("mode")):
+        gaps.append(f"material {material_id!r} needs textureProjection.mode and texel-density intent")
+
+    bands = material.get("surfaceFrequencyBands")
+    band_ids = {
+        str(item.get("id")).lower()
+        for item in bands
+        if isinstance(item, dict) and has_non_empty(item.get("id"))
+    } if isinstance(bands, list) else set()
+    missing_bands = {"macro", "meso", "micro"} - band_ids
+    if missing_bands:
+        gaps.append(
+            f"material {material_id!r} missing surface frequency bands: "
+            + ", ".join(sorted(missing_bands))
+        )
+
+    roughness = material.get("roughness")
+    roughness_map = roughness.get("map") if isinstance(roughness, dict) else None
+    if not has_non_empty(roughness_map) or "albedo" in str(roughness_map).lower():
+        gaps.append(f"material {material_id!r} needs an independent roughness map")
+    if not has_non_empty(material.get("normal")) and not has_non_empty(material.get("bump")):
+        gaps.append(f"material {material_id!r} needs an independent height/normal response")
+    if not has_non_empty(material.get("ambientOcclusion")):
+        gaps.append(f"material {material_id!r} needs an independent ambient-occlusion response")
+    if pbr_required:
+        ok, message = reference_pbr_usable(material, float(pbr_threshold))
+        if not ok:
+            gaps.append(message)
+    return gaps
+
+
+def material_pass_gaps(spec: dict[str, Any]) -> list[str]:
+    materials = [item for item in spec.get("materials", []) if isinstance(item, dict)]
+    if not materials:
+        return ["materials array is empty"]
+    if not any(material_has_palette(item) for item in materials):
+        return ["no material has a reference-derived albedo palette or secondary color zones"]
+    gaps: list[str] = []
+    if not any(material_has_response(item) for item in materials):
+        gaps.append("no material defines roughness variation or normal/bump/displacement response")
+    if not any(material_has_locality(item) for item in materials):
+        gaps.append("no material defines local overrides, AO, dirt, wear, stains, moss, chips, or scratches")
+    if quality_first_enabled(spec):
+        for material in materials:
+            if material.get("qualityTier") == "utility":
+                continue
+            gaps.extend(quality_first_material_gaps(spec, material))
+    return gaps
+
+
+def surface_pass_gaps(spec: dict[str, Any]) -> list[str]:
+    components = [item for item in spec.get("componentTree", []) if isinstance(item, dict)]
+    has_surface_detail = any(has_non_empty(item.get("surfaceDetail")) for item in components)
+    if not has_surface_detail:
+        return ["componentTree has no meaningful surfaceDetail for normal/bump/displacement/AO locality"]
+    return []
+
+
+def lighting_pass_gaps(spec: dict[str, Any]) -> list[str]:
+    lighting = spec.get("lightingFromPhoto", [])
+    if not isinstance(lighting, list) or len([item for item in lighting if has_non_empty(item)]) < 3:
+        return ["lightingFromPhoto needs at least three concrete entries for key/fill/rim or environment lighting"]
+    text = " ".join(str(item).lower() for item in lighting)
+    required_groups = {
+        "key light": ("key", "sun", "main light"),
+        "fill light": ("fill", "ambient", "hemisphere"),
+        "rim/environment light": ("rim", "back light", "environment", "hdr", "reflection"),
+        "exposure/tone mapping": ("exposure", "tone", "aces", "filmic"),
+        "contact shadow": ("contact shadow", "ground shadow", "ambient occlusion", "ao"),
+    }
+    gaps = [
+        f"lightingFromPhoto missing {label}"
+        for label, terms in required_groups.items()
+        if not any(term in text for term in terms)
+    ]
+    return gaps
+
+
+def pass_specific_evidence(pass_id: str) -> list[str]:
+    if pass_id in {"structural-pass", "form-refinement"}:
+        return [
+            "attachment contracts for child appendages/connectors",
+            "no floating child roots/joints in the browser screenshot",
+        ]
+    if pass_id == "material-pass":
+        return [
+            "reference-derived albedo palette with dominant, secondary, and accent colors",
+            "independent albedo, roughness, height/normal, and AO maps",
+            "macro, meso, and micro surface-frequency response at 1024px or higher",
+            "local material masks: AO, dirt, wear, stains, moss, chips, scratches, wetness, or equivalent",
+            "neutral, grazing-light close-up, and reference-matched browser screenshots",
+            "AI vision comparison sheet score meeting the visual acceptance threshold",
+        ]
+    if pass_id == "surface-pass":
+        return [
+            "component surfaceDetail for tactile normal/bump/displacement and locality",
+        ]
+    if pass_id == "lighting-pass":
+        return [
+            "lightingFromPhoto with key/fill/rim or environment light",
+            "exposure, tone mapping, background, shadow softness, and contact shadow behavior",
+        ]
+    return []
+
+
+def pass_specific_gaps(spec: dict[str, Any], pass_id: str) -> list[str]:
+    if pass_id in {"structural-pass", "form-refinement"}:
+        return attachment_gaps(spec)
+    if pass_id == "material-pass":
+        return material_pass_gaps(spec)
+    if pass_id == "surface-pass":
+        return surface_pass_gaps(spec)
+    if pass_id == "lighting-pass":
+        return lighting_pass_gaps(spec)
+    return []
+
+
+def sync_pipeline(spec: dict[str, Any]) -> dict[str, Any]:
+    ids = pass_order(spec)
+    completed = completed_passes(spec, ids)
+    current = current_pass(ids, completed)
+    pipeline = spec.setdefault("sculptPipeline", {})
+    if not isinstance(pipeline, dict):
+        pipeline = {}
+        spec["sculptPipeline"] = pipeline
+    pipeline.update(
+        {
+            "passGateMode": "locked-sequential",
+            "passOrder": ids,
+            "currentPass": current,
+            "completedPasses": completed,
+            "lastCompletedPass": completed[-1] if completed else "",
+            "blockedReason": "" if current != "complete" else "all build passes completed",
+            "nextRequiredEvidence": next_required_evidence(spec, current),
+        }
+    )
+    return pipeline
+
+
+def check_pass(spec: dict[str, Any], requested_pass: str) -> tuple[bool, str, dict[str, Any]]:
+    pipeline = sync_pipeline(spec)
+    ids = list(pipeline["passOrder"])
+    if requested_pass not in ids:
+        return False, f"unknown build pass {requested_pass!r}", pipeline
+    current = str(pipeline["currentPass"])
+    completed = list(pipeline.get("completedPasses", []))
+    if requested_pass in completed or current == "complete":
+        gaps = pass_specific_gaps(spec, requested_pass)
+        if gaps:
+            return False, f"pass {requested_pass!r} needs spec refinement: {'; '.join(gaps)}", pipeline
+        return True, f"pass {requested_pass!r} is already completed and can be regenerated", pipeline
+    if requested_pass == current:
+        gaps = pass_specific_gaps(spec, requested_pass)
+        if gaps:
+            return False, f"pass {requested_pass!r} needs spec refinement: {'; '.join(gaps)}", pipeline
+        return True, f"pass {requested_pass!r} is the current unlocked pass", pipeline
+    previous_index = ids.index(requested_pass) - 1
+    previous = ids[previous_index] if previous_index >= 0 else ""
+    return (
+        False,
+        f"pass {requested_pass!r} is locked; complete {previous!r} with reviewHistory.action=continue and screenshot evidence first",
+        pipeline,
+    )
+
+
+def status_payload(spec: dict[str, Any]) -> dict[str, Any]:
+    pipeline = sync_pipeline(spec)
+    return {
+        "targetName": spec.get("targetName"),
+        "passGateMode": pipeline.get("passGateMode"),
+        "currentPass": pipeline.get("currentPass"),
+        "completedPasses": pipeline.get("completedPasses", []),
+        "nextRequiredEvidence": pipeline.get("nextRequiredEvidence", []),
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    status_parser = subparsers.add_parser("status", help="Print current sculpt pipeline state")
+    status_parser.add_argument("spec", type=Path)
+    status_parser.add_argument("--json", action="store_true")
+
+    check_parser = subparsers.add_parser("check", help="Fail unless a build pass is unlocked")
+    check_parser.add_argument("spec", type=Path)
+    check_parser.add_argument("--pass-id", required=True)
+    check_parser.add_argument("--json", action="store_true")
+
+    sync_parser = subparsers.add_parser("sync", help="Refresh sculptPipeline from reviewHistory")
+    sync_parser.add_argument("spec", type=Path)
+    sync_parser.add_argument("--in-place", action="store_true")
+    sync_parser.add_argument("--out", type=Path)
+    sync_parser.add_argument("--json", action="store_true")
+
+    args = parser.parse_args(argv)
+    spec_path = args.spec.expanduser().resolve()
+    spec = load_spec(spec_path)
+
+    if args.command == "status":
+        payload = status_payload(spec)
+        if args.json:
+            print(json.dumps(payload, indent=2, ensure_ascii=False))
+        else:
+            print(f"currentPass: {payload['currentPass']}")
+            print(f"completedPasses: {', '.join(payload['completedPasses']) or '(none)'}")
+            for item in payload["nextRequiredEvidence"]:
+                print(f"required: {item}")
+        return 0
+
+    if args.command == "check":
+        ok, message, pipeline = check_pass(spec, args.pass_id)
+        payload = {"ok": ok, "message": message, "pipeline": pipeline}
+        if args.json:
+            print(json.dumps(payload, indent=2, ensure_ascii=False))
+        else:
+            print("PASS" if ok else "FAIL")
+            print(message)
+        return 0 if ok else 1
+
+    if args.command == "sync":
+        payload = status_payload(spec)
+        output = spec_path if args.in_place else (args.out.expanduser().resolve() if args.out else None)
+        if output:
+            write_spec(output, spec)
+        if args.json:
+            print(json.dumps(payload, indent=2, ensure_ascii=False))
+        else:
+            print(output or json.dumps(spec, indent=2, ensure_ascii=False))
+        return 0
+
+    parser.error("unreachable command")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage4_review/append_review.py

@@ -0,0 +1,384 @@
+#!/usr/bin/env python3
+"""Append a self-correction review entry to an ObjectSculptSpec JSON file."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_shared"))
+from feature_acceptance_policy import feature_gate_failures
+
+
+VALID_ACTIONS = {"continue", "refine-spec", "refine-code", "request-input", "stop"}
+VISUAL_PASS_IDS = {
+    "blockout",
+    "structural-pass",
+    "form-refinement",
+    "material-pass",
+    "surface-pass",
+    "lighting-pass",
+    "interaction-pass",
+}
+DEFAULT_PASS_ORDER = [
+    "blockout",
+    "structural-pass",
+    "form-refinement",
+    "material-pass",
+    "surface-pass",
+    "lighting-pass",
+    "interaction-pass",
+    "optimization-pass",
+]
+
+
+def split_items(value: str | None) -> list[str]:
+    if not value:
+        return []
+    return [item.strip() for item in value.split(";") if item.strip()]
+
+
+def load_spec(path: Path) -> dict:
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("spec must be a JSON object")
+    return payload
+
+
+def load_json_argument(value: str | None, label: str) -> object | None:
+    if not value:
+        return None
+    candidate = Path(value).expanduser()
+    text = candidate.read_text(encoding="utf-8") if candidate.is_file() else value
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{label} must be valid inline JSON or a JSON file path") from exc
+
+
+def clamp_score(value: float) -> float:
+    return max(0.0, min(1.0, float(value)))
+
+
+def is_remote_or_virtual_path(value: str) -> bool:
+    return "://" in value or value.startswith("data:") or value.startswith("blob:")
+
+
+def validate_optional_file(value: str | None, label: str) -> None:
+    if not value or is_remote_or_virtual_path(value):
+        return
+    if not Path(value).expanduser().exists():
+        raise FileNotFoundError(f"{label} does not exist: {value}")
+
+
+def visual_acceptance_threshold(spec: dict) -> float:
+    loop = spec.get("selfCorrectLoop")
+    if isinstance(loop, dict):
+        acceptance = loop.get("visualAcceptance")
+        if isinstance(acceptance, dict) and isinstance(acceptance.get("threshold"), (int, float)):
+            return clamp_score(float(acceptance["threshold"]))
+    targets = spec.get("qualityTargets")
+    if isinstance(targets, dict) and isinstance(targets.get("targetFidelity"), (int, float)):
+        return clamp_score(float(targets["targetFidelity"]))
+    return 0.7
+
+
+def visual_acceptance_config(spec: dict) -> dict:
+    loop = spec.get("selfCorrectLoop")
+    if not isinstance(loop, dict):
+        return {}
+    acceptance = loop.get("visualAcceptance")
+    return acceptance if isinstance(acceptance, dict) else {}
+
+
+def pass_order(spec: dict) -> list[str]:
+    ids: list[str] = []
+    for item in spec.get("buildPasses", []):
+        if isinstance(item, dict) and isinstance(item.get("id"), str) and item["id"].strip():
+            ids.append(item["id"])
+    return ids or DEFAULT_PASS_ORDER.copy()
+
+
+def pass_acceptance(spec: dict, pass_id: str) -> list[str]:
+    for item in spec.get("buildPasses", []):
+        if isinstance(item, dict) and item.get("id") == pass_id:
+            acceptance = item.get("acceptance", [])
+            if isinstance(acceptance, list):
+                return [str(value) for value in acceptance if str(value).strip()]
+    return []
+
+
+def pass_specific_evidence(pass_id: str) -> list[str]:
+    if pass_id in {"structural-pass", "form-refinement"}:
+        return [
+            "attachment contracts for child appendages/connectors",
+            "no floating child roots/joints in the browser screenshot",
+        ]
+    if pass_id == "material-pass":
+        return [
+            "reference-derived albedo palette with dominant, secondary, and accent colors",
+            "independent albedo, roughness, height/normal, and AO maps",
+            "macro, meso, and micro surface-frequency response at 1024px or higher",
+            "local material masks: AO, dirt, wear, stains, moss, chips, scratches, wetness, or equivalent",
+            "neutral, grazing-light close-up, and reference-matched browser screenshots",
+        ]
+    if pass_id == "surface-pass":
+        return [
+            "component surfaceDetail for tactile normal/bump/displacement and locality",
+        ]
+    if pass_id == "lighting-pass":
+        return [
+            "lightingFromPhoto with key/fill/rim or environment light",
+            "exposure, tone mapping, background, shadow softness, and contact shadow behavior",
+        ]
+    return []
+
+
+def review_completes_pass(spec: dict, entry: dict, pass_id: str) -> bool:
+    if entry.get("passId") != pass_id or entry.get("action") != "continue":
+        return False
+    visual = entry.get("visualEvidence")
+    if pass_id in VISUAL_PASS_IDS and not (isinstance(visual, dict) and visual.get("renderScreenshot")):
+        return False
+    if pass_id in VISUAL_PASS_IDS:
+        score = entry.get("aiVisionScore")
+        threshold = entry.get("visualAcceptanceThreshold", 0.7)
+        if not isinstance(score, (int, float)) or not isinstance(threshold, (int, float)):
+            return False
+        if float(score) < float(threshold):
+            return False
+        if not (isinstance(visual, dict) and visual.get("comparisonImage")):
+            return False
+        if feature_gate_failures(spec, entry, pass_id):
+            return False
+    return True
+
+
+def sync_pipeline(spec: dict) -> None:
+    ids = pass_order(spec)
+    history = spec.get("reviewHistory", [])
+    completed: list[str] = []
+    if isinstance(history, list):
+        for pass_id in ids:
+            if any(
+                isinstance(entry, dict) and review_completes_pass(spec, entry, pass_id)
+                for entry in history
+            ):
+                completed.append(pass_id)
+            else:
+                break
+    current = "complete" if len(completed) >= len(ids) else ids[len(completed)]
+    required = [] if current == "complete" else pass_acceptance(spec, current)
+    required.extend(pass_specific_evidence(current))
+    if current in VISUAL_PASS_IDS:
+        required.extend(
+            [
+                "browser render screenshot from your agent's browser/screenshot tool",
+                "single side-by-side full reference/render comparison sheet",
+                "all critical semantic feature scores at or above their thresholds",
+                "self-correction review appended with action=continue before the next pass",
+            ]
+        )
+    pipeline = spec.setdefault("sculptPipeline", {})
+    if not isinstance(pipeline, dict):
+        pipeline = {}
+        spec["sculptPipeline"] = pipeline
+    pipeline.update(
+        {
+            "passGateMode": "locked-sequential",
+            "passOrder": ids,
+            "currentPass": current,
+            "completedPasses": completed,
+            "lastCompletedPass": completed[-1] if completed else "",
+            "blockedReason": "" if current != "complete" else "all build passes completed",
+            "nextRequiredEvidence": required,
+        }
+    )
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("spec", type=Path)
+    parser.add_argument("--pass-id", required=True, help="Build pass being reviewed")
+    parser.add_argument("--fidelity", type=float, required=True, help="Estimated match score from 0 to 1")
+    parser.add_argument("--action", choices=sorted(VALID_ACTIONS), required=True)
+    parser.add_argument("--summary", required=True, help="Short review summary")
+    parser.add_argument("--matched", help="Semicolon-separated matched criteria")
+    parser.add_argument("--mismatches", help="Semicolon-separated mismatches")
+    parser.add_argument("--spec-fixes", help="Semicolon-separated spec refinement tasks")
+    parser.add_argument("--code-fixes", help="Semicolon-separated code refinement tasks")
+    parser.add_argument("--evidence", help="Semicolon-separated screenshot/image/render paths or notes")
+    parser.add_argument("--reference-screenshot", help="Reference image/screenshot path or URL used for visual comparison")
+    parser.add_argument("--render-screenshot", help="Rendered browser screenshot path or URL for this pass")
+    parser.add_argument("--comparison-image", help="Side-by-side reference/render contact sheet reviewed by AI vision")
+    parser.add_argument("--ai-vision-score", type=float, help="AI vision visual match score from 0 to 1")
+    parser.add_argument("--layer-scores-json", help="JSON object with AI vision layer scores, e.g. silhouette/material/lighting")
+    parser.add_argument("--feature-reviews-json", help="JSON array or file path containing per-feature scores from the same full image pair")
+    parser.add_argument("--ai-vision-notes", help="AI vision critique explaining the score and mismatch root causes")
+    parser.add_argument("--visual-threshold", type=float, help="Override visual acceptance threshold for this review")
+    parser.add_argument("--camera-view", help="Camera/viewpoint label, e.g. front, three-quarter, side, close-up")
+    parser.add_argument("--visual-notes", help="Short notes from screenshot comparison")
+    parser.add_argument(
+        "--require-screenshot-files",
+        action="store_true",
+        help="Require local screenshot paths to exist before writing the review",
+    )
+    parser.add_argument("--in-place", action="store_true", help="Write back to the input spec")
+    parser.add_argument("--out", type=Path, help="Output JSON path when not using --in-place")
+    args = parser.parse_args(argv)
+
+    if args.require_screenshot_files:
+        validate_optional_file(args.reference_screenshot, "--reference-screenshot")
+        validate_optional_file(args.render_screenshot, "--render-screenshot")
+        validate_optional_file(args.comparison_image, "--comparison-image")
+    if args.pass_id in VISUAL_PASS_IDS and args.action == "continue" and not args.render_screenshot:
+        raise ValueError(
+            "visual pass cannot use action=continue without --render-screenshot; "
+            "capture a browser screenshot or choose refine-code/request-input"
+        )
+
+    spec_path = args.spec.expanduser().resolve()
+    spec = load_spec(spec_path)
+    history = spec.setdefault("reviewHistory", [])
+    if not isinstance(history, list):
+        raise ValueError("reviewHistory must be an array")
+    threshold = clamp_score(args.visual_threshold) if args.visual_threshold is not None else visual_acceptance_threshold(spec)
+    layer_scores = None
+    if args.layer_scores_json:
+        layer_scores = load_json_argument(args.layer_scores_json, "--layer-scores-json")
+        if not isinstance(layer_scores, dict):
+            raise ValueError("--layer-scores-json must be a JSON object")
+        for key, value in layer_scores.items():
+            if not isinstance(key, str) or not isinstance(value, (int, float)):
+                raise ValueError("--layer-scores-json values must be numeric scores")
+            if not 0 <= float(value) <= 1:
+                raise ValueError("--layer-scores-json values must be from 0 to 1")
+    if args.ai_vision_score is not None and not 0 <= args.ai_vision_score <= 1:
+        raise ValueError("--ai-vision-score must be from 0 to 1")
+    if args.visual_threshold is not None and not 0 <= args.visual_threshold <= 1:
+        raise ValueError("--visual-threshold must be from 0 to 1")
+    feature_reviews = load_json_argument(args.feature_reviews_json, "--feature-reviews-json")
+    if feature_reviews is None:
+        feature_reviews = []
+    if not isinstance(feature_reviews, list):
+        raise ValueError("--feature-reviews-json must be a JSON array")
+    for index, review in enumerate(feature_reviews):
+        if not isinstance(review, dict):
+            raise ValueError(f"feature review {index} must be an object")
+        if not isinstance(review.get("id"), str) or not review["id"].strip():
+            raise ValueError(f"feature review {index}.id is required")
+        score = review.get("score")
+        if score is not None and (
+            not isinstance(score, (int, float)) or not 0 <= float(score) <= 1
+        ):
+            raise ValueError(f"feature review {index}.score must be from 0 to 1")
+    if args.pass_id in VISUAL_PASS_IDS and args.action == "continue":
+        if not args.comparison_image:
+            raise ValueError(
+                "visual pass cannot use action=continue without --comparison-image; "
+                "create one with stage4_review/make_comparison_sheet.py"
+            )
+        if args.ai_vision_score is None:
+            raise ValueError(
+                "visual pass cannot use action=continue without --ai-vision-score; "
+                "AI vision must review the comparison sheet"
+            )
+        if clamp_score(args.ai_vision_score) < threshold:
+            raise ValueError(
+                f"AI vision score {clamp_score(args.ai_vision_score):.3f} is below threshold "
+                f"{threshold:.3f}; choose refine-spec/refine-code/request-input instead of continue"
+            )
+        acceptance = visual_acceptance_config(spec)
+        if acceptance.get("layerScoresRequired") is True and not layer_scores:
+            raise ValueError("visual pass cannot use action=continue without --layer-scores-json")
+        required_layers = acceptance.get("requiredLayerScores", [])
+        if isinstance(required_layers, list) and layer_scores:
+            missing_layers = [
+                layer
+                for layer in required_layers
+                if isinstance(layer, str) and layer not in layer_scores
+            ]
+            if missing_layers:
+                raise ValueError(
+                    "--layer-scores-json is missing required layers: "
+                    + ", ".join(missing_layers)
+                )
+
+    entry = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "passId": args.pass_id,
+        "estimatedFidelity": clamp_score(args.fidelity),
+        "aiVisionScore": clamp_score(args.ai_vision_score) if args.ai_vision_score is not None else None,
+        "visualAcceptanceThreshold": threshold,
+        "layerScores": layer_scores or {},
+        "featureReviews": feature_reviews,
+        "action": args.action,
+        "summary": args.summary,
+        "matched": split_items(args.matched),
+        "mismatches": split_items(args.mismatches),
+        "specFixes": split_items(args.spec_fixes),
+        "codeFixes": split_items(args.code_fixes),
+        "evidence": split_items(args.evidence),
+    }
+    if args.pass_id in VISUAL_PASS_IDS and args.action == "continue":
+        feature_failures = feature_gate_failures(spec, entry, args.pass_id)
+        if feature_failures:
+            raise ValueError(
+                "feature-level AI vision gate failed: " + "; ".join(feature_failures)
+            )
+
+    has_visual_evidence = any(
+        [
+            args.reference_screenshot,
+            args.render_screenshot,
+            args.comparison_image,
+            args.camera_view,
+            args.visual_notes,
+            args.ai_vision_notes,
+        ]
+    )
+    if has_visual_evidence:
+        visual_evidence = {
+            "referenceScreenshot": args.reference_screenshot or spec.get("sourceImage", ""),
+            "renderScreenshot": args.render_screenshot or "",
+            "comparisonImage": args.comparison_image or "",
+            "cameraView": args.camera_view or "",
+            "notes": args.visual_notes or "",
+            "aiVisionNotes": args.ai_vision_notes or "",
+        }
+        entry["visualEvidence"] = visual_evidence
+
+        visual_history = spec.setdefault("visualEvidence", [])
+        if not isinstance(visual_history, list):
+            raise ValueError("visualEvidence must be an array")
+        visual_history.append(
+            {
+                "timestamp": entry["timestamp"],
+                "passId": args.pass_id,
+                "estimatedFidelity": entry["estimatedFidelity"],
+                "aiVisionScore": entry["aiVisionScore"],
+                "visualAcceptanceThreshold": entry["visualAcceptanceThreshold"],
+                "layerScores": entry["layerScores"],
+                "featureReviews": entry["featureReviews"],
+                **visual_evidence,
+            }
+        )
+    history.append(entry)
+    sync_pipeline(spec)
+
+    output = spec_path if args.in_place else (args.out.expanduser().resolve() if args.out else None)
+    payload = json.dumps(spec, indent=2, ensure_ascii=False) + "\n"
+    if output:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(payload, encoding="utf-8")
+        print(output)
+    else:
+        print(payload, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/stage4_review/make_comparison_sheet.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""Create a side-by-side visual acceptance sheet for AI vision review.
+
+The sheet is only evidence packaging. It does not score the images. the agent or
+another AI vision reviewer should inspect the generated sheet and write the
+score back with stage4_review/append_review.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import struct
+import subprocess
+import sys
+import tempfile
+import zlib
+from pathlib import Path
+
+
+PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+
+def paeth_predictor(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa = abs(p - a)
+    pb = abs(p - b)
+    pc = abs(p - c)
+    if pa <= pb and pa <= pc:
+        return a
+    if pb <= pc:
+        return b
+    return c
+
+
+def read_png(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    data = path.read_bytes()
+    if not data.startswith(PNG_SIGNATURE):
+        raise ValueError("not a PNG file")
+    cursor = len(PNG_SIGNATURE)
+    width = height = bit_depth = color_type = interlace = None
+    idat = bytearray()
+    while cursor + 8 <= len(data):
+        length = struct.unpack(">I", data[cursor : cursor + 4])[0]
+        chunk_type = data[cursor + 4 : cursor + 8]
+        chunk_data = data[cursor + 8 : cursor + 8 + length]
+        cursor += 12 + length
+        if chunk_type == b"IHDR":
+            width, height, bit_depth, color_type, _, _, interlace = struct.unpack(">IIBBBBB", chunk_data)
+        elif chunk_type == b"IDAT":
+            idat.extend(chunk_data)
+        elif chunk_type == b"IEND":
+            break
+    if width is None or height is None or bit_depth != 8 or interlace != 0:
+        raise ValueError("unsupported PNG; expected 8-bit non-interlaced image")
+    channels_by_type = {0: 1, 2: 3, 4: 2, 6: 4}
+    if color_type not in channels_by_type:
+        raise ValueError("unsupported PNG color type; convert to RGB/RGBA first")
+    channels = channels_by_type[color_type]
+    row_bytes = width * channels
+    raw = zlib.decompress(bytes(idat))
+    rows: list[bytearray] = []
+    offset = 0
+    previous = bytearray(row_bytes)
+    for _ in range(height):
+        filter_type = raw[offset]
+        offset += 1
+        row = bytearray(raw[offset : offset + row_bytes])
+        offset += row_bytes
+        for index in range(row_bytes):
+            left = row[index - channels] if index >= channels else 0
+            up = previous[index]
+            up_left = previous[index - channels] if index >= channels else 0
+            if filter_type == 1:
+                row[index] = (row[index] + left) & 0xFF
+            elif filter_type == 2:
+                row[index] = (row[index] + up) & 0xFF
+            elif filter_type == 3:
+                row[index] = (row[index] + ((left + up) // 2)) & 0xFF
+            elif filter_type == 4:
+                row[index] = (row[index] + paeth_predictor(left, up, up_left)) & 0xFF
+            elif filter_type != 0:
+                raise ValueError(f"unsupported PNG filter {filter_type}")
+        rows.append(row)
+        previous = row
+    pixels: list[tuple[int, int, int, int]] = []
+    for row in rows:
+        for x in range(width):
+            base = x * channels
+            if color_type == 0:
+                gray = row[base]
+                pixels.append((gray, gray, gray, 255))
+            elif color_type == 2:
+                pixels.append((row[base], row[base + 1], row[base + 2], 255))
+            elif color_type == 4:
+                gray = row[base]
+                pixels.append((gray, gray, gray, row[base + 1]))
+            elif color_type == 6:
+                pixels.append((row[base], row[base + 1], row[base + 2], row[base + 3]))
+    return width, height, pixels
+
+
+def write_png_rgb(path: Path, width: int, height: int, pixels: list[tuple[int, int, int]]) -> None:
+    if len(pixels) != width * height:
+        raise ValueError("pixel payload has the wrong size")
+
+    def chunk(kind: bytes, payload: bytes) -> bytes:
+        checksum = zlib.crc32(kind)
+        checksum = zlib.crc32(payload, checksum) & 0xFFFFFFFF
+        return struct.pack(">I", len(payload)) + kind + payload + struct.pack(">I", checksum)
+
+    scanlines = bytearray()
+    for y in range(height):
+        scanlines.append(0)
+        for red, green, blue in pixels[y * width : (y + 1) * width]:
+            scanlines.extend((red, green, blue))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(
+        PNG_SIGNATURE
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(bytes(scanlines), level=6))
+        + chunk(b"IEND", b"")
+    )
+
+
+def load_image(path: Path) -> tuple[int, int, list[tuple[int, int, int, int]]]:
+    try:
+        return read_png(path)
+    except Exception as direct_error:
+        sips = shutil.which("sips")
+        if not sips:
+            raise ValueError(f"could not decode {path.name} as PNG and sips is unavailable: {direct_error}") from direct_error
+        with tempfile.TemporaryDirectory() as tmpdir:
+            converted = Path(tmpdir) / "converted.png"
+            result = subprocess.run(
+                [sips, "-s", "format", "png", str(path), "--out", str(converted)],
+                capture_output=True,
+                text=True,
+                check=False,
+            )
+            if result.returncode != 0:
+                raise ValueError(result.stderr.strip() or result.stdout.strip() or "sips conversion failed")
+            return read_png(converted)
+
+
+def composite_over_checker(pixel: tuple[int, int, int, int], x: int, y: int) -> tuple[int, int, int]:
+    red, green, blue, alpha = pixel
+    background = 238 if ((x // 12 + y // 12) % 2 == 0) else 210
+    mix = alpha / 255.0
+    return (
+        round(red * mix + background * (1 - mix)),
+        round(green * mix + background * (1 - mix)),
+        round(blue * mix + background * (1 - mix)),
+    )
+
+
+def resize_cover(
+    width: int,
+    height: int,
+    pixels: list[tuple[int, int, int, int]],
+    target_w: int,
+    target_h: int,
+) -> list[tuple[int, int, int]]:
+    scale = max(target_w / width, target_h / height)
+    scaled_w = max(1, round(width * scale))
+    scaled_h = max(1, round(height * scale))
+    offset_x = max(0, (scaled_w - target_w) // 2)
+    offset_y = max(0, (scaled_h - target_h) // 2)
+    output: list[tuple[int, int, int]] = []
+    for y in range(target_h):
+        source_y = min(height - 1, max(0, int((y + offset_y) / scale)))
+        for x in range(target_w):
+            source_x = min(width - 1, max(0, int((x + offset_x) / scale)))
+            output.append(composite_over_checker(pixels[source_y * width + source_x], x, y))
+    return output
+
+
+def fill_rect(
+    canvas: list[tuple[int, int, int]],
+    width: int,
+    x0: int,
+    y0: int,
+    rect_w: int,
+    rect_h: int,
+    color: tuple[int, int, int],
+) -> None:
+    height = len(canvas) // width
+    for y in range(max(0, y0), min(height, y0 + rect_h)):
+        row = y * width
+        for x in range(max(0, x0), min(width, x0 + rect_w)):
+            canvas[row + x] = color
+
+
+def blit(
+    canvas: list[tuple[int, int, int]],
+    width: int,
+    image: list[tuple[int, int, int]],
+    image_w: int,
+    x0: int,
+    y0: int,
+) -> None:
+    image_h = len(image) // image_w
+    height = len(canvas) // width
+    for y in range(image_h):
+        target_y = y0 + y
+        if target_y < 0 or target_y >= height:
+            continue
+        for x in range(image_w):
+            target_x = x0 + x
+            if 0 <= target_x < width:
+                canvas[target_y * width + target_x] = image[y * image_w + x]
+
+
+def create_sheet(
+    reference: Path,
+    render: Path,
+    out: Path,
+    width: int,
+    height: int,
+    gutter: int,
+) -> dict:
+    ref_w, ref_h, ref_pixels = load_image(reference)
+    ren_w, ren_h, ren_pixels = load_image(render)
+    panel_w = width
+    panel_h = height
+    canvas_w = panel_w * 2 + gutter * 3
+    header_h = 28
+    canvas_h = panel_h + gutter * 2 + header_h
+    canvas = [(246, 242, 236)] * (canvas_w * canvas_h)
+    fill_rect(canvas, canvas_w, gutter, gutter, panel_w, header_h, (40, 45, 48))
+    fill_rect(canvas, canvas_w, gutter * 2 + panel_w, gutter, panel_w, header_h, (40, 45, 48))
+    fill_rect(canvas, canvas_w, gutter, gutter + header_h, panel_w, panel_h, (230, 230, 230))
+    fill_rect(canvas, canvas_w, gutter * 2 + panel_w, gutter + header_h, panel_w, panel_h, (230, 230, 230))
+    ref_panel = resize_cover(ref_w, ref_h, ref_pixels, panel_w, panel_h)
+    ren_panel = resize_cover(ren_w, ren_h, ren_pixels, panel_w, panel_h)
+    blit(canvas, canvas_w, ref_panel, panel_w, gutter, gutter + header_h)
+    blit(canvas, canvas_w, ren_panel, panel_w, gutter * 2 + panel_w, gutter + header_h)
+    fill_rect(canvas, canvas_w, panel_w + gutter + gutter // 2, gutter, max(2, gutter // 5), canvas_h - gutter * 2, (170, 146, 92))
+    write_png_rgb(out, canvas_w, canvas_h, canvas)
+    return {
+        "comparisonImage": str(out.resolve()),
+        "referenceImage": str(reference.resolve()),
+        "renderScreenshot": str(render.resolve()),
+        "layout": "left=reference,right=render",
+        "panelWidth": panel_w,
+        "panelHeight": panel_h,
+        "note": "Send this image to AI vision for global, layer, and semantic feature scores; this script does not score.",
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--reference", type=Path, required=True)
+    parser.add_argument("--render", type=Path, required=True)
+    parser.add_argument("--out", type=Path, required=True)
+    parser.add_argument("--panel-width", type=int, default=720)
+    parser.add_argument("--panel-height", type=int, default=720)
+    parser.add_argument("--gutter", type=int, default=24)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        payload = create_sheet(
+            args.reference.expanduser().resolve(),
+            args.render.expanduser().resolve(),
+            args.out.expanduser().resolve(),
+            max(128, args.panel_width),
+            max(128, args.panel_height),
+            max(6, args.gutter),
+        )
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(payload, indent=2, ensure_ascii=False) if args.json else payload["comparisonImage"])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

forge/tests/test_pipeline.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""End-to-end integration tests for the Three.js Object Sculptor pipeline.
+
+Pure stdlib. Runs each CLI script as a subprocess and asserts the gate behavior
+described in SKILL.md / references. Also generates a tiny real PNG (struct+zlib)
+to exercise the image-consuming scripts without any third-party deps.
+
+Run: python3 forge/tests/test_pipeline.py   (from skill root)
+  or: python3 -m unittest discover -s forge/tests
+"""
+import json
+import struct
+import subprocess
+import sys
+import tempfile
+import unittest
+import zlib
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parents[2]
+SCRIPTS = SKILL / "forge"
+
+
+def run(script, *args):
+    return subprocess.run(
+        [sys.executable, str(SCRIPTS / script), *map(str, args)],
+        capture_output=True, text=True,
+    )
+
+
+def write_png(path, w=64, h=64):
+    """Write a minimal valid RGB PNG with a simple gradient (no PIL)."""
+    raw = bytearray()
+    for y in range(h):
+        raw.append(0)  # filter type 0 per scanline
+        for x in range(w):
+            raw += bytes(((x * 4) % 256, (y * 4) % 256, ((x + y) * 2) % 256))
+
+    def chunk(tag, data):
+        c = struct.pack(">I", len(data)) + tag + data
+        return c + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)
+
+    ihdr = struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0)
+    png = (b"\x89PNG\r\n\x1a\n"
+           + chunk(b"IHDR", ihdr)
+           + chunk(b"IDAT", zlib.compress(bytes(raw), 9))
+           + chunk(b"IEND", b""))
+    Path(path).write_bytes(png)
+
+
+class PipelineTest(unittest.TestCase):
+    def setUp(self):
+        self.dir = Path(tempfile.mkdtemp())
+        self.assessment = self.dir / "assessment.json"
+        self.spec = self.dir / "object-sculpt-spec.json"
+        self.ref = self.dir / "ref.png"
+        self.render = self.dir / "render.png"
+        write_png(self.ref)
+        write_png(self.render)
+
+    def test_probe_image(self):
+        r = run("stage1_intake/probe_image.py", self.ref)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertIn("64", r.stdout)  # reports dimensions
+
+    def test_assessment_and_spec(self):
+        r = run("stage2_spec/new_pre_spec_assessment.py", "Oak", "--complexity", "complex",
+                "--out", self.assessment)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertTrue(self.assessment.exists())
+        self.assertIn("qualityContract", json.loads(self.assessment.read_text()))
+
+        r = run("stage2_spec/new_sculpt_spec.py", "Oak", "--assessment", self.assessment,
+                "--out", self.spec)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        spec = json.loads(self.spec.read_text())
+        self.assertEqual(spec["schemaVersion"], "2.0")
+        self.assertEqual(spec["targetName"], "Oak")
+
+    def test_normal_validate_passes_strict_fails_on_shallow(self):
+        run("stage2_spec/new_pre_spec_assessment.py", "Oak", "--complexity", "complex",
+            "--out", self.assessment)
+        run("stage2_spec/new_sculpt_spec.py", "Oak", "--assessment", self.assessment,
+            "--out", self.spec)
+        # normal validation of a structurally-sound starter succeeds
+        self.assertEqual(run("stage2_spec/validate_sculpt_spec.py", self.spec).returncode, 0)
+        # strict quality gate must BLOCK a shallow starter spec
+        strict = run("stage2_spec/validate_sculpt_spec.py", self.spec, "--strict-quality")
+        self.assertNotEqual(strict.returncode, 0)
+        self.assertIn("strict quality failure", strict.stdout + strict.stderr)
+
+    def test_orchestrator_starts_at_blockout(self):
+        run("stage2_spec/new_sculpt_spec.py", "Oak", "--out", self.spec)
+        r = run("stage3_build/orchestrate_passes.py", "status", self.spec)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertIn("blockout", r.stdout)
+        # a future pass must be locked
+        locked = run("stage3_build/orchestrate_passes.py", "check", self.spec,
+                     "--pass-id", "material-pass")
+        self.assertNotEqual(locked.returncode, 0)
+
+    def test_generate_factory_emits_typescript(self):
+        run("stage2_spec/new_sculpt_spec.py", "Oak", "--out", self.spec)
+        out = self.dir / "createObjectModel.ts"
+        r = run("stage3_build/generate_threejs_factory.py", self.spec, "--out", out)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        ts = out.read_text()
+        self.assertIn("import * as THREE from 'three'", ts)
+        self.assertIn("sculptRuntime", ts)
+        # generating a locked future pass must fail
+        locked = run("stage3_build/generate_threejs_factory.py", self.spec, "--out", out,
+                     "--pass-id", "lighting-pass")
+        self.assertNotEqual(locked.returncode, 0)
+
+    def test_comparison_sheet_packages_without_scoring(self):
+        cmp = self.dir / "cmp.png"
+        r = run("stage4_review/make_comparison_sheet.py", "--reference", self.ref,
+                "--render", self.render, "--out", cmp, "--json")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertTrue(cmp.exists() and cmp.stat().st_size > 0)
+
+    def test_append_review_gate_and_record(self):
+        run("stage2_spec/new_sculpt_spec.py", "Oak", "--out", self.spec)
+        # GATE: continue on a visual pass WITHOUT screenshot evidence must be refused.
+        no_evidence = run("stage4_review/append_review.py", self.spec, "--pass-id", "blockout",
+                          "--fidelity", "0.8", "--action", "continue",
+                          "--summary", "no evidence", "--ai-vision-score", "0.8",
+                          "--in-place")
+        self.assertNotEqual(no_evidence.returncode, 0)
+        self.assertIn("render-screenshot", no_evidence.stdout + no_evidence.stderr)
+        # WITH evidence: the review is recorded.
+        cmp = self.dir / "cmp.png"
+        run("stage4_review/make_comparison_sheet.py", "--reference", self.ref,
+            "--render", self.render, "--out", cmp)
+        layers = json.dumps({
+            "silhouetteProportion": 0.82, "componentStructure": 0.78,
+            "formDetail": 0.75, "materialSurface": 0.7, "lightingCamera": 0.8,
+        })
+        # every critical feature target of this pass needs an AI-vision review entry
+        spec = json.loads(self.spec.read_text())
+        targets = spec.get("selfCorrectLoop", {}).get("featureReviewTargets", [])
+        reviews = [
+            {"id": t.get("id"), "score": 0.8, "visible": True, "notes": "acceptable"}
+            for t in targets if t.get("tier") == "critical"
+        ] or [{"id": "overall-silhouette", "score": 0.8, "visible": True, "notes": "ok"}]
+        freviews = self.dir / "features.json"
+        freviews.write_text(json.dumps(reviews))
+        r = run("stage4_review/append_review.py", self.spec, "--pass-id", "blockout",
+                "--fidelity", "0.8", "--action", "continue",
+                "--summary", "Blockout silhouette acceptable.",
+                "--render-screenshot", self.render, "--comparison-image", cmp,
+                "--ai-vision-score", "0.8", "--layer-scores-json", layers,
+                "--feature-reviews-json", freviews,
+                "--camera-view", "front", "--in-place")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        spec = json.loads(self.spec.read_text())
+        self.assertTrue(len(spec.get("reviewHistory", [])) >= 1)
+
+    def test_pbr_extraction_runs(self):
+        # low-detail synthetic image: either passes or refuses (non-zero) — both are valid,
+        # but it must not crash and must respect the confidence gate.
+        r = run("stage1_intake/extract_pbr_evidence.py", self.ref, "--out-dir", self.dir / "pbr",
+                "--material-id", "bark", "--target-threshold", "0.7",
+                "--report", self.dir / "pbr-report.json")
+        self.assertIn(r.returncode, (0, 1), r.stderr)
+        self.assertTrue((self.dir / "pbr-report.json").exists() or r.returncode == 1)
+
+    # ---- Track A / Track B upgrade coverage ----
+
+    def _fresh_spec(self, complexity="moderate"):
+        run("stage2_spec/new_pre_spec_assessment.py", "Widget", "--complexity", complexity,
+            "--out", self.assessment)
+        run("stage2_spec/new_sculpt_spec.py", "Widget", "--assessment", self.assessment,
+            "--out", self.spec)
+        return json.loads(self.spec.read_text())
+
+    def test_new_schema_fields_present(self):
+        spec = self._fresh_spec("complex")
+        pre = spec["preSpecAssessment"]
+        self.assertIn("detailInventory", pre)
+        self.assertIn("anatomy", pre)
+        self.assertIn("primaryDomain", pre["objectClass"])
+        self.assertIn("referenceCamera", spec)
+        # targetMinDetails scales with complexity
+        self.assertEqual(pre["detailInventory"]["targetMinDetails"], 10)
+
+    def test_detail_inventory_gate_fires_on_empty(self):
+        self._fresh_spec("moderate")
+        strict = run("stage2_spec/validate_sculpt_spec.py", self.spec, "--strict-quality")
+        self.assertNotEqual(strict.returncode, 0)
+        self.assertIn("detailInventory has 0 details", strict.stdout + strict.stderr)
+
+    def test_detail_inventory_backward_compatible(self):
+        # A spec with NO detailInventory (pre-upgrade shape) must not trigger the detail gate.
+        spec = self._fresh_spec("moderate")
+        spec["preSpecAssessment"].pop("detailInventory", None)
+        self.spec.write_text(json.dumps(spec))
+        strict = run("stage2_spec/validate_sculpt_spec.py", self.spec, "--strict-quality")
+        self.assertNotIn("detailInventory", strict.stdout + strict.stderr)
+
+    def test_character_gate_requires_anatomy(self):
+        spec = self._fresh_spec("moderate")
+        spec["preSpecAssessment"]["objectClass"]["primaryDomain"] = "character"
+        self.spec.write_text(json.dumps(spec))
+        strict = run("stage2_spec/validate_sculpt_spec.py", self.spec, "--strict-quality")
+        self.assertIn("anatomy.applies is not true", strict.stdout + strict.stderr)
+
+    def test_character_track_skipped_for_objects(self):
+        # primaryDomain unassessed/object must not trigger character warnings.
+        self._fresh_spec("moderate")
+        strict = run("stage2_spec/validate_sculpt_spec.py", self.spec, "--strict-quality")
+        self.assertNotIn("anatomy.applies", strict.stdout + strict.stderr)
+
+    def test_new_upgrade_scripts_help(self):
+        for script in ("stage1_intake/build_detail_inventory.py", "stage1_intake/extract_landmarks.py",
+                       "stage1_intake/solve_camera_pose.py", "stage1_intake/delight_albedo.py",
+                       "stage3_build/bake_projected_texture.py"):
+            r = run(script, "--help")
+            self.assertEqual(r.returncode, 0, f"{script}: {r.stderr}")
+
+    def test_build_detail_inventory_slices_zones(self):
+        out = self.dir / "di.json"
+        zones = self.dir / "zones"
+        r = run("stage1_intake/build_detail_inventory.py", self.ref, "--mode", "grid-3x3",
+                "--out-dir", zones, "--out", out)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertTrue(out.exists())
+        crops = list(zones.glob("*.png")) if zones.exists() else []
+        self.assertGreaterEqual(len(crops), 1)
+
+    def test_delight_reference_writes_png(self):
+        out = self.dir / "albedo.png"
+        r = run("stage1_intake/delight_albedo.py", self.ref, "--out", out)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertTrue(out.exists() and out.stat().st_size > 0)
+
+    # ---- v1.2 character generator ----
+
+    def test_character_flag_builds_humanoid_tree(self):
+        run("stage2_spec/new_sculpt_spec.py", "Person", "--character", "--out", self.spec)
+        spec = json.loads(self.spec.read_text())
+        ids = {c["id"] for c in spec["componentTree"]}
+        for part in ("root", "head", "torso", "neck", "hair", "glasses-frame-l", "arm-l"):
+            self.assertIn(part, ids)
+        # all parts flattened to root (no cascading non-uniform parent scale)
+        for c in spec["componentTree"]:
+            if c["id"] != "root":
+                self.assertEqual(c["parent"], "root")
+        # distinct per-part colors (skin vs hair vs shirt), not a single fallback
+        colors = {m["id"]: m.get("color") for m in spec["materials"] if m["id"] in ("skin", "hair", "shirt")}
+        self.assertEqual(len({colors["skin"], colors["hair"], colors["shirt"]}), 3)
+        # palette has >= 2 entries so the generator does not fall back to beige
+        for m in spec["materials"]:
+            if m["id"] in ("skin", "hair", "shirt"):
+                self.assertGreaterEqual(len(m.get("colorVariation", {}).get("palette", [])), 2)
+
+    def test_character_autodetect_from_domain(self):
+        run("stage2_spec/new_pre_spec_assessment.py", "Person", "--complexity", "complex", "--out", self.assessment)
+        a = json.loads(self.assessment.read_text())
+        a["preSpecAssessment"]["objectClass"]["primaryDomain"] = "character"
+        self.assessment.write_text(json.dumps(a))
+        run("stage2_spec/new_sculpt_spec.py", "Person", "--assessment", self.assessment, "--out", self.spec)
+        spec = json.loads(self.spec.read_text())
+        self.assertIn("head", {c["id"] for c in spec["componentTree"]})
+
+    def test_character_factory_generates(self):
+        run("stage2_spec/new_sculpt_spec.py", "Person", "--character", "--out", self.spec)
+        out = self.dir / "createCharacterModel.ts"
+        r = run("stage3_build/generate_threejs_factory.py", self.spec, "--out", out)
+        self.assertEqual(r.returncode, 0, r.stderr)
+        ts = out.read_text()
+        self.assertIn("createPersonModel", ts)
+        self.assertIn('meshes["head"]', ts)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)

grimoire/build/geometry_patterns.md

@@ -0,0 +1,120 @@
+# Procedural Three.js Object Patterns
+
+Use this reference only when implementing a model.
+
+## Geometry Choices
+
+- box: flat machinery, furniture, panels, blockout masses
+- sphere/ellipsoid: fruit, knobs, organic joints, rounded stones
+- cylinder/cone/capsule: trunks, pipes, limbs, handles, bottles, rockets
+- torus: rings, tires, loops, trim, cable coils
+- shape extrude: logos, flat ornamental plates, blades, keys, leaves
+- lathe: vases, bottles, bowls, lamps, wheels
+- tube along curve: cables, roots, branches, straps, hoses
+- instanced mesh: screws, rivets, leaves, needles, scales, pebbles, repeated ornaments
+- plane cards: thin leaves, feathers, labels, cloth strips, decals
+
+## Material Recipes
+
+- wood: brown base, vertical grain normal, roughness variation, darker creases, lighter worn edges
+- stone: mottled albedo, high roughness, bump/normal noise, lichen/dirt patches
+- metal: lower roughness, metalness, edge scratches, anisotropic-looking streaks via texture
+- plastic: controlled roughness, subtle color variation, bevels to catch highlights
+- leaf/plant: alpha cards or thin shape geometry, green hue variation, central vein, translucent-ish bright rim
+- water/glass: transparent material only if needed; add environment/reflection cues or it reads as a flat sheet
+
+## Material Layer Fields
+
+For each material, prefer a layered description:
+
+- `baseColor`: dominant sampled color.
+- `colorVariation`: palette, mottling pattern, amplitude, regional masks.
+- `roughness`: base value, variation amount, map/pattern source.
+- `metalness`: base value and local changes.
+- `normal`: procedural pattern, strength, scale.
+- `bump`: amplitude and scale for small tactile relief.
+- `displacement`: only for silhouette-visible or close-up relief.
+- `wear`: edge wear, scratches, chips, polish, exposed underlayer.
+- `dirt`: amount, cavity bias, color, vertical streaking, contact staining.
+- `localOverrides`: named regions where color/roughness/bump differs from the base.
+
+Local overrides should answer: where, what changes, how strong, and which image evidence supports it.
+
+## Local Feature Types
+
+Use `component.localFeatures` for details that matter to recognizability:
+
+- raised ridge
+- recessed groove
+- seam line
+- screw or rivet
+- chip or dent
+- scratch cluster
+- stain or dirt patch
+- decal or label area
+- hole or socket
+- bevel highlight
+- fabric stitch
+- leaf vein or serrated edge
+
+Each feature should include placement, approximate size, orientation, material effect, geometry effect, and confidence.
+
+## Detail Recipes
+
+Concrete Three.js material/geometry approach per `detailInventory` kind. Cross-reference
+`grimoire/intake/detail_inventory.md` for the full taxonomy and the evidence/mapping rule.
+
+- gloss: `MeshPhysicalMaterial` with a low-`roughness` localOverride (0.05-0.2) sized to the
+  hotspot region; use `clearcoat`/`clearcoatRoughness` for a lacquer layer over a rougher
+  base, `anisotropy`/`anisotropyRotation` for brushed/streaked highlights.
+- bevel: real geometry, not a normal map - `edgeTreatment.type = chamfer`, `bevelRadius`
+  object-relative (0.02-0.08), `segments` 2-4 for a soft catch-light rim, 1 for a hard edge.
+- fastener: `InstancedMesh` for the repeated part; `count` + spacing pattern (linear, radial,
+  grid) + head shape (hemisphere/flat/hex) + recess (raised vs countersunk); low-roughness
+  metal material on the head crown.
+- linework: pick engraved groove (real recessed geometry along a path, catches shadow),
+  painted line/decal (canvas-texture localOverride, color contrast only, no relief), or
+  panel-line (thin dark AO/roughness localOverride along a seam, no depth) - match whichever
+  the reference evidence shows; do not default to decal for something that casts a shadow.
+- stain: `material.localOverrides` region with `dirtAmount`, `cavityBias` (concentrate in
+  crevices), `streak` (directional, usually gravity-down), `patinaColor` for oxidation hue
+  shift, or a `fadedMask` (lighter, desaturated) for sun-bleaching - the inverse of dirt.
+
+## Character Geometry And Material Recipes
+
+Use these when `objectClass.primaryDomain` is `character` or `hybrid`. Pair with
+`grimoire/character/reconstruction.md` for proportion/landmark data.
+
+- head: sphere or ellipsoid scaled to the measured head-unit, then displaced/tapered toward
+  the reference face shape (jaw width, chin point, cheek fullness) rather than left spherical.
+- limbs: capsule or tapered cylinder per segment (upper arm, forearm, thigh, shin); taper
+  ratio and length come from `anatomy.proportions`; capsules keep joints visually continuous.
+- hands: simplified capsule-cluster (palm block + finger capsules) at low segment count;
+  do not attempt per-knuckle detail unless the reference is close-up and complexity is ultra.
+- hair: hair cards (alpha-mapped planes layered in clumps) for stylized/low-complexity, or a
+  tube-along-curve per lock for wavy/flowing hair with visible strand structure; prefer cards
+  by default - hair is the classic single-image failure mode, so favor legible clumps over
+  many thin strands that swim or alias.
+- face feature placement: position eyes, brows, nose, mouth using `anatomy.faceLandmarks`
+  normalized coordinates (eyeLine, eyeSpacing, noseBase, mouthLine, hairline); never eyeball
+  placement freehand once landmarks exist.
+- eyes: glossy sphere (low roughness, slight clearcoat) plus an iris decal/texture; a correct
+  catchlight (small bright localOverride matching the key light) sells more realism than
+  extra geometry.
+- clothing: extrude or plane panels per garment piece, with fold normals (a normal-map or
+  displacement pattern following expected gravity/pose creases) rather than a flat shell;
+  reuse Track A detail machinery (seam, stitch, decal, stain) for prints, buttons, wear.
+- skin: approximate subsurface scattering, not true SSS - warm base albedo, soft/lower
+  roughness variation (skin is not uniformly matte), and a rim or backlight to fake light
+  passing through thin tissue (ears, nose edge). Avoid pure-Lambertian flat skin.
+
+## Verification Cues
+
+A procedural object is usually failing when:
+
+- silhouette reads wrong even before material
+- every edge is perfectly sharp or perfectly smooth
+- material has one flat color and no roughness variation
+- lighting hides the form instead of explaining it
+- repeated details are too evenly spaced
+- close-up details add triangles but not recognizability

grimoire/character/likeness_maximization.md

@@ -0,0 +1,74 @@
+# Likeness Maximization (Projection-First Pipeline)
+
+Use this reference when the goal is maximum resemblance to a specific person or character in a single reference image, not a generic stylized character. This is the default high-likeness path for the `character` domain; `character/reconstruction.md` covers the fallback stylized/freehand path when the input is weak or the user accepts approximation.
+
+Read section 5.8-5.10 of `docs/UPGRADE_PLAN.md` for the full spec this reference implements.
+
+## Why Freehand Sculpting Cannot Reach High Likeness
+
+Hand-authored primitives (capsules, spheres, blend shapes tuned by eye) can approximate proportions but cannot reproduce the exact geometry and surface information encoded in a photo. The two levers that actually move likeness are: (1) getting the mesh's shape and camera to align precisely with the photo, and (2) putting the photo's own pixels onto that mesh as texture. Everything else is secondary.
+
+## Pipeline
+
+### (a) Fit a parametric template to landmarks
+
+Ship a lightweight, code-generated parametric humanoid/face template — a head-unit-parameterized body plus a morphable face, conceptually mirroring SMPL-X (body + hands + face, jaw/eye joints, linear blend skinning with corrective blendshapes) and FLAME (face-from-scans). This stays procedural: the template is code-generated and parameter-driven, never a downloaded art asset.
+
+Fit template parameters (shape, pose, expression) by minimizing reprojection error between template landmarks and the observed 2D landmarks from `stage1_intake/extract_landmarks.py` — the SMPLify-X idea. Do not hand-place vertices; solve for parameters that make the template's projected landmarks match the image landmarks.
+
+### (b) Camera match
+
+Estimate and store focal length, FOV, and orientation for the reference photo (`forge/stage1_intake/solve_camera_pose.py`, emits a `referenceCamera` spec block). The render camera must match this so:
+
+- the review screenshot can be pixel-overlaid against the source photo
+- the texture projection in step (d) lands correctly
+
+Without a matched camera, projected texture will misalign the moment the model is viewed from any angle other than the accidental one it was authored at.
+
+### (c) De-light before treating the photo as albedo
+
+A raw photo bakes in shadows, highlights, and ambient occlusion from whatever light was present when it was taken. Using it directly as albedo means the projected texture fights the new scene's lights. Run a de-lighting pass (`forge/stage1_intake/delight_albedo.py`) — high-pass/overlay neutralization at minimum, an AI delighter equivalent if available — to recover a neutral base color, then derive roughness/normal/AO independently. Treat "album must be free of baked lighting" as a hard requirement, not a nice-to-have.
+
+### (d) Project and bake
+
+Solve projective/camera-projection texturing from the matched camera (Three.js `ShaderMaterial`, or the `three-projected-material` approach) to map the de-lit reference onto the fitted mesh, then bake the result into the mesh's UVs (`forge/stage3_build/bake_projected_texture.py`, stdlib PNG) for the visible (front) side.
+
+### (e) Infer unseen regions, flag confidence
+
+Back/sides are not observed. Options, in order of preference:
+
+1. request an additional view (`request-input`: front/side/back) — always try this first for a real person
+2. mirror the front texture across the body's symmetry plane where anatomically valid (works reasonably for faces, poorly for asymmetric hair/clothing)
+3. palette-continue from the nearest observed edge as a last resort
+
+Every inferred region gets its own confidence score and a note of which strategy produced it. Never silently present an inferred back as if it were observed.
+
+### (f) Rig for deformation
+
+Emit a `SkinnedMesh` with a joint skeleton for the body plus morph targets/blend shapes for facial expression, exportable as glTF. Keep topology predictable (retopologized, evenly quaded around the face) so blendshapes deform cleanly. Expose skeleton and morph channels through `root.userData.sculptRuntime`.
+
+## Part-Specific Notes (stylized-to-realistic dial)
+
+Same recipes as `character/reconstruction.md`, dialed toward realism: skin keeps the warm-base/soft-roughness/rim-light approximation (true SSS is out of scope); hair still prefers stylized clumps over strand geometry — a single image cannot supply real hair microstructure, so do not oversell hair likeness; eyes get the glossy-sphere-plus-iris-decal treatment with a correct catchlight, which reads as more "alive" than raw geometric accuracy.
+
+## Honesty Note
+
+State plainly, every time this pipeline runs: a single image cannot yield a guaranteed 100 percent likeness. Back/sides, occluded geometry, and true skin/hair microstructure are not observable from one photo. This pipeline maximizes likeness through parametric fit + photo projection + de-lighting + camera match, reports per-region confidence, and requests additional views whenever the subject is a real person and fidelity matters. Never claim "100 percent match" as an output — report confidence per region instead.
+
+An optional, explicitly-flagged `generativeAssist` mode (importing an external image-to-3D base mesh, e.g. TRELLIS/Tripo/Hunyuan3D/Rodin) sets the realistic ceiling higher (~80-95 percent front-face shape accuracy per current generators) but is non-procedural and never the silent default — see UPGRADE_PLAN.md section 5.9.
+
+## Sources
+
+- [Expressive Body Capture: SMPL-X / SMPLify-X (arXiv 1904.05866)](https://arxiv.org/pdf/1904.05866)
+- [SMPLify-X overview (EmergentMind)](https://www.emergentmind.com/topics/smplify-x)
+- [Playing with Texture Projection in Three.js (Codrops)](https://tympanus.net/codrops/2020/01/07/playing-with-texture-projection-in-three-js/)
+- [three-projected-material (GitHub)](https://github.com/marcofugaro/three-projected-material)
+- [three.js morph targets - face example](https://threejs.org/examples/webgl_morphtargets_face.html)
+- [TexDreamer: high-fidelity 3D human texture (arXiv 2403.12906)](https://arxiv.org/pdf/2403.12906)
+- [Delight AI - Adobe Substance 3D Sampler](https://helpx.adobe.com/substance-3d-sampler/filters/tools/delight-ai-powered.html)
+- [De-Lighting 3D Scans (Sketchfab community)](https://sketchfab.com/blogs/community/de-lighting-3d-scans-in-unity-by-pete-mcnally/)
+- [Character Turnaround Guide (spines.com)](https://spines.com/character-turnaround/)
+- [How to Create a 3D Character Model Reference (Coohom)](https://www.coohom.com/article/how-to-create-a-3d-character-model-reference)
+- [Best AI 3D Model Generators 2026 (TRELLIS vs Meshy vs Tripo vs Hitem3D)](https://trellis2.app/blog/best-ai-3d-model-generator)
+- [7 Image-to-3D AI Generators, July 2026 (Vitalify)](https://www.vitalify.asia/en/blog/generative-ai/ai-image-to-3d-generators-comparison)
+- [How To Deploy Image-To-3D Models In Three.js (Threedium)](https://threedium.io/create/3d-models/platform/threejs)

grimoire/character/reconstruction.md

@@ -0,0 +1,63 @@
+# Character Reconstruction
+
+Use this reference when `objectClass.primaryDomain` is `character` or `hybrid`. It replaces guesswork proportions with a measured system so a generated humanoid actually resembles the reference pose and build.
+
+## Proportion System (head-units)
+
+Measure everything in head-units (HU): total body height divided by head height. Pick the style axis from the image, do not assume realistic by default:
+
+- realistic: ~7.5 HU (adult human)
+- stylized / anime-adjacent: ~5-6 HU
+- chibi / figurine: ~2-3 HU
+
+Record measured ratios, not assumed ones:
+
+- `headUnit`: head height as a fraction of total image height
+- `torso`: crown-to-hip distance in HU
+- `legs`: hip-to-floor distance in HU
+- `shoulderWidth`: in HU (roughly 1.5-2 HU realistic, wider for stylized heroic builds)
+- `hipWidth`: in HU
+
+If the image crops the legs or feet, mark `legs` and `hipWidth` as inferred and lower confidence rather than guessing a stock adult ratio.
+
+## Facial Landmark Layout
+
+Store landmarks as normalized coordinates (0-1) relative to head bounding box, not the full image, so they survive scale changes:
+
+- `hairline`: ~0.0-0.15 from crown depending on hairstyle bulk
+- `eyeLine`: ~0.45-0.55 (near vertical mid-head; lower for chibi, higher forehead for stylized)
+- `eyeSpacing`: horizontal gap between inner eye corners, ~0.2-0.35 of head width (wider spacing reads as more stylized/cute)
+- `noseBase`: ~0.6-0.7
+- `mouthLine`: ~0.75-0.85
+- `earTop` / `earBottom`: roughly bracket `eyeLine` to `noseBase`
+
+Pull these from the actual image via `forge/stage1_intake/extract_landmarks.py` overlay, not from a generic face chart. A stylized face with huge eyes will violate realistic ratios on purpose — match what is observed.
+
+## Pose / Skeleton
+
+Define joints as a minimal skeleton, matched to the reference silhouette and limb angles, not a default T-pose:
+
+- root -> neck -> head
+- neck -> left/right shoulder -> elbow -> wrist
+- root -> left/right hip -> knee -> ankle
+
+For each joint record an approximate angle (degrees, relative to rest pose) read off the silhouette. Prioritize matching:
+
+1. overall stance (weight distribution, contrapposto vs symmetric)
+2. limb angles at shoulders/hips (these dominate perceived pose match)
+3. hand/foot orientation only if clearly visible
+
+If a joint is occluded, do not invent an angle — mark `confidence` low and default to a neutral rest angle for that joint only.
+
+## Character Materials (stylized default)
+
+Reuse Track A detail machinery (`grimoire/intake/detail_inventory.md`) for accessories and trims. Base recipes:
+
+- **Skin**: warm base albedo sampled from the image, low-to-mid roughness, no true subsurface scattering — approximate with a soft rim/backlight term and a slightly desaturated shadow tint. Avoid `MeshPhysicalMaterial.transmission` unless the reference clearly shows translucency (ears, fingers backlit).
+- **Hair**: the single most common failure point for single-image reconstruction. Do NOT attempt strand-level geometry from one photo. Prefer stylized clumps — hair cards or short tube-along-curve locks grouped into 5-15 major masses matching the silhouette's hair shape, layered front-to-back with alpha or hard edges. Match the read silhouette (fringe, part line, volume) over any attempt at individual strands.
+- **Eyes**: a glossy sphere (high specular, low roughness) plus a separate iris disc/decal with darker outline and a small bright catchlight quad or emissive dot offset toward the key light direction. The catchlight is disproportionately important for "looks alive."
+- **Cloth**: extrude or plane panels following the silhouette's fold lines; add normal-map or geometry creasing at obvious fold zones (elbow, waist cinch, knee) rather than a flat plane. Local material overrides handle prints, seams, buttons via the Track A detail inventory.
+
+## Gate Notes
+
+Proportion and landmark values feed `anatomy` block validation (section 5.3/5.6 of the upgrade plan) — every measured value needs an `evidenceRef` back to the source image region, same discipline as object detail inventory.

grimoire/feedback/render_capture.md

@@ -0,0 +1,81 @@
+# Browser Screenshot Feedback
+
+Use this reference when a procedural Three.js reconstruction has a browser-renderable preview.
+
+## Capture Rule
+
+Each visual build pass should produce at least one rendered screenshot from a named review viewpoint. Use your agent's browser/screenshot tool (Claude Code browser MCP, your agent's in-app browser/preview, or the project's own preview) first. Do not install or download Playwright/Chromium just for this skill; use Playwright or another browser automation path only when the user explicitly allows it or the project already depends on it. If the in-app Browser is unavailable, ask for a screenshot path or use browser tooling that is already present in the target project.
+
+Create a side-by-side review image after capture:
+
+```bash
+../../forge/stage4_review/make_comparison_sheet.py \
+  --reference reference.png \
+  --render render.png \
+  --out comparison.png \
+  --json
+```
+
+The script only aligns and packages evidence. It must not calculate the acceptance score. your agent's vision must inspect `comparison.png`.
+
+Use the same full image pair to score at most five critical semantic features per pass. A feature is a subsystem such as a hull, cabin system, roof system, limb assembly, face, control panel, or sail-and-rigging system. It is not an individual mesh and does not need a separate crop. Score up to three uncertain important features only when adaptive escalation is useful.
+
+The starter spec contains generic review targets only as placeholders. Replace them with object-specific systems discovered during pre-spec assessment; otherwise strict quality validation should not pass a moderate or complex object.
+
+## Compare By Layer
+
+Review screenshot evidence in this order:
+
+1. Silhouette and proportions: bounding shape, width/height/depth cues, taper, symmetry, negative space.
+2. Component structure: parent/child placement, joints, contact points, repeated systems, floating or detached parts.
+3. Form detail: bevels, chamfers, curvature, bends, dents, seams, raised ridges, holes, deformation scale.
+4. Surface response: albedo zones, roughness variation, metalness, clearcoat, transmission, normal/bump/displacement, ambient occlusion.
+5. Local features: scratches, chips, dirt accumulation, moss, stains, color patches, edge wear, contact wear.
+6. Lighting/camera: exposure, shadow softness, contact shadows, color temperature, rim light, reflection readability.
+7. Performance tradeoff: whether missing detail is intentional because of triangle, draw call, texture, or FPS budgets.
+
+## Decision Matrix
+
+- If the screenshot reveals a missing or wrong component, choose `refine-spec`.
+- If the spec describes the component but the render does not match it, choose `refine-code`.
+- If the screenshot is too dark, too close, too far, or from the wrong viewpoint, choose `refine-code` for camera/lighting before judging model fidelity.
+- If the source image does not reveal enough geometry or material information, choose `request-input`.
+- If the screenshot matches the pass acceptance criteria and does not hide future risk, choose `continue`.
+
+`continue` is allowed only when the global AI vision score meets `selfCorrectLoop.visualAcceptance.threshold`, normally `0.7`, and every critical semantic feature meets its own threshold. A numeric or pixel-difference script may help diagnose alignment, but it cannot approve the pass.
+
+## AI Vision Scorecard
+
+Score each applicable layer from `0` to `1`, then assign one overall score based on the pass goal:
+
+- `silhouetteProportion`: outer contour, mass distribution, negative space, camera-normalized proportions.
+- `componentStructure`: hierarchy, placement, attachment, repeated systems, floating or disconnected parts.
+- `formDetail`: taper, bend, bevel, deformation, secondary forms, local geometry.
+- `materialSurface`: albedo, roughness, reflectance, normal/displacement, AO, local wear, tactile frequency.
+- `lightingCamera`: camera match, exposure, key/fill/rim balance, shadow/contact response, background.
+
+Do not hide a critical failed layer inside a high average. If a layer is essential to the current pass and remains visibly wrong, choose `refine-spec` or `refine-code` even when the arithmetic mean is above threshold.
+
+## Feature Tiers
+
+- `critical`: identity-defining, user-prioritized, visually salient, or high-risk subsystem. Must be visible in the full pair and pass independently.
+- `important`: useful secondary subsystem. Review only suspicious items; the reviewed average must meet the configured threshold.
+- `detail`: micro detail. Record mismatch notes and defer to refinement unless the user promotes it.
+
+Repeated parts should be one target when they form one recognizable system. For example, review three cabins as `cabin-system`, not three separate cabin targets.
+
+## Evidence Format
+
+Record screenshot evidence with:
+
+- `referenceScreenshot`: source image, crop, or marked-up reference path.
+- `renderScreenshot`: browser-rendered screenshot path.
+- `comparisonImage`: side-by-side evidence image reviewed by AI vision.
+- `cameraView`: named viewpoint such as `front`, `three-quarter`, `side`, `top`, or `close-up-material`.
+- `notes`: concise mismatch summary using 3D graphics terms.
+- `aiVisionScore`: overall score from `0` to `1`.
+- `layerScores`: per-layer scores from the scorecard.
+- `aiVisionNotes`: concrete matched features, mismatches, root causes, and next correction.
+- `featureReviews`: feature ID, score, visibility in the shared pair, and focused notes.
+
+Never use screenshots as decoration only. They are the ground truth for the self-correction loop.

grimoire/feedback/shading_realism.md

@@ -0,0 +1,80 @@
+# Material And Lighting Realism
+
+Use this reference whenever the model silhouette is acceptable but the render still looks unlike the source image.
+
+## Common Failure Pattern
+
+A procedural object often fails after the shape pass because the render has:
+
+- one flat albedo color per material
+- no roughness variation or cavity response
+- no normal/bump/displacement response on surfaces that should be tactile
+- missing local overrides such as moss, stains, edge wear, dirt, sap, rust, dust, scorch, or faded zones
+- lighting that is only ambient or too evenly exposed
+- weak contact shadows, no rim separation, and no tone mapping/exposure target
+
+Treat this as a `LookDev Reset`, not a geometry problem.
+
+## Material-Pass Requirements
+
+Before implementing or accepting `material-pass`, the spec must contain:
+
+- `albedo` palette: dominant, secondary, accent colors, and where they appear on the object.
+- `roughness` response: base value, variation, and local response such as smoother worn edges or rougher cavities.
+- tactile response: at least one of `normal`, `bump`, or `displacement` with scale/amplitude/strength.
+- locality: `localOverrides`, dirt, wear, scratches, chips, stains, moss, patina, wetness, soot, or cavity masks tied to `viewEvidence`.
+- material-specific behavior: alpha/transmission/translucency for thin or transparent parts, metalness/clearcoat for reflective parts, cloth/fiber grain for fabric-like parts.
+- independent PBR channels: albedo, roughness, height/normal, and AO must be generated or authored separately; never reuse albedo as a roughness, height, normal, or AO map.
+- reference-derived PBR extraction: when a source image is available and fidelity matters, run `../../forge/stage1_intake/extract_pbr_evidence.py` for each important material or crop before accepting material-pass. The default target threshold is `0.7`; below that, stop or request better references unless the user explicitly accepts a lower-fidelity approximation.
+- scale hierarchy: close-up materials must describe macro, meso, and micro surface-frequency bands with object-relative frequency and amplitude.
+- projection/UV intent: state UV, triplanar, cylindrical, planar, or another projection strategy, plus repeat/texel-density intent so detail does not stretch across scaled components.
+- quality-first resolution: use at least 1024px procedural maps for important close-up materials and prefer 2048px when reference fidelity is the priority.
+- geometric relief: if a ridge, crack, seam, chip, bark plate, fold, or dent affects the visible silhouette, represent it with geometry or displacement-capable topology instead of texture alone.
+
+Do not accept "brown bark", "gold leaves", "dark metal", or "rough stone" as sufficient. Translate it into PBR terms: albedo palette, roughness, normal/bump, AO, dirt/wear, and local masks.
+
+Do not claim exact PBR recovery from a single image. Pixels include baked lighting, exposure, shadow, view angle, and camera response. Treat extracted maps as reference-derived material evidence that still needs neutral/grazing/reference screenshot review.
+
+Do not accept a material merely because all required fields are present. The browser render must prove that:
+
+- roughness breaks highlights independently from albedo color
+- normal/height detail remains readable under grazing light
+- cavities and contacts have coherent AO rather than uniformly dark noise
+- referencePbr maps, when present, are loaded by the generated Three.js material and have confidence at or above the configured threshold
+- micro detail does not visibly tile or swim when the object is scaled
+- local overrides appear in the same regions supported by `viewEvidence`
+
+## Lighting-Pass Requirements
+
+Before accepting `lighting-pass`, the spec must contain:
+
+- key light direction, color temperature, intensity, and shadow softness
+- fill light color/intensity, or explicit reason for no fill
+- rim/back light or environment reflection cue when the silhouette needs separation
+- ambient/hemisphere/environment color
+- exposure and tone-mapping intent
+- background color or gradient
+- contact shadow / ground shadow behavior
+
+Separate object material from photo lighting: a material should still read correctly in neutral turntable lighting, then a reference-matching lighting setup can be added.
+
+## Screenshot Review
+
+For material and lighting screenshots, compare in this order:
+
+1. Albedo palette: are dominant and accent colors close to the reference?
+2. Value range: are dark cavities and bright highlights in the right places?
+3. Surface response: does roughness/normal/bump catch light?
+4. Locality: are moss, stains, dirt, wear, chips, or color patches placed where the reference shows them?
+5. Light structure: can you identify key, fill, rim/environment, contact shadow, and exposure?
+6. Material-vs-light split: if the scene is relit neutrally, does the object still have believable material detail?
+
+For quality-first work, capture three deliberate look-dev views before choosing `continue`:
+
+1. `neutral`: broad soft key/fill lighting for honest albedo and form reading.
+2. `grazing`: a low-angle hard or semi-hard key close-up that exposes smooth-plastic highlights, weak normals, uniform roughness, and texture tiling.
+3. `reference-match`: the source camera and lighting direction as closely as the available evidence allows.
+
+A material that only looks convincing in the reference-matched light has not passed. Fix its PBR response first, then tune the reference lighting.
+
+If the mismatch is mostly color/texture/lighting, choose `refine-code` only when the spec already has the above details. Otherwise choose `refine-spec` first.

grimoire/glossary/3d_vocabulary.md

@@ -0,0 +1,84 @@
+# 3D Graphics Terminology For Object Sculpt Specs
+
+Use this reference when writing or reviewing an `ObjectSculptSpec`. The goal is to describe what the agent should build in terms a Three.js/technical-artist workflow can act on.
+
+## Geometry And Topology
+
+- `silhouette`: the outer read of the object from a given camera angle.
+- `primitive family`: box, sphere, ellipsoid, cylinder, cone, capsule, torus, lathe, extrusion, tube, plane card, instanced cluster.
+- `topology intent`: hard-surface blockout, subdivision-ready surface, low-poly prop, organic deformed mesh, alpha-card cluster.
+- `bevel radius`: size of rounded edge transition in object-relative units.
+- `bevel segments`: number of edge-rounding subdivisions.
+- `chamfer`: flat angled edge cut, usually cheaper than a rounded bevel.
+- `taper`: gradual scale change along an axis.
+- `bend`: curvature deformation along an axis or spline.
+- `twist`: rotational deformation along an axis.
+- `boolean cut`: subtractive shape such as hole, notch, slot, recess, or carved opening.
+- `edge loop`: repeated ring/path of vertices used to support shape or deformation.
+- `local deformation`: localized dent, swelling, pinch, warp, sag, or buckle.
+- `displacement`: geometry-level height movement that can affect silhouette.
+- `normal strategy`: vertex normals, weighted normals, flat shading, generated tangent-space normal.
+- `UV strategy`: generated procedural coordinates, cylindrical projection, triplanar-like mapping, atlas-ready unwrapped regions.
+
+## Material And PBR
+
+- `albedo` / `baseColor`: diffuse color independent of lighting.
+- `roughness`: microfacet scatter; high roughness is matte, low roughness is glossy.
+- `metalness`: whether material behaves as conductive metal in PBR.
+- `normal map`: tangent-space normal detail that changes lighting without changing silhouette.
+- `bump map`: height-derived normal detail, usually procedural and cheaper than displacement.
+- `displacement map`: geometry displacement; use only when relief should affect silhouette or close-up shape.
+- `ambient occlusion`: darkening in creases, contact zones, and cavities.
+- `cavity dirt`: localized dark/dusty buildup in recessed areas.
+- `edge wear`: exposed lighter/polished/damaged material on protruding edges.
+- `clearcoat`: secondary glossy layer over base material.
+- `transmission`: light passing through transparent/translucent material.
+- `alpha`: opacity or cutout transparency.
+- `anisotropy`: directional highlight stretch, useful for brushed metal or fibers.
+- `procedural noise scale`: spatial frequency of generated variation.
+- `local mask`: region-specific control for color, roughness, dirt, wear, or bump.
+
+## Surface Local Features
+
+- `raised ridge`: geometry or normal detail protruding from surface.
+- `recessed groove`: carved or shadowed line cut into the surface.
+- `seam line`: boundary between joined pieces or material panels.
+- `scratch cluster`: group of thin directional marks affecting albedo/roughness/normal.
+- `chip`: broken missing piece, often with exposed underlayer.
+- `dent`: inward local deformation.
+- `stain`: local albedo/roughness color change without strong geometry change.
+- `contact wear`: abrasion where object touches ground, hands, joints, or other parts.
+- `decal region`: image/text/logo-like area; approximate with colored planes or generated texture unless exact fidelity is required.
+
+## Lighting And Rendering
+
+- `key light`: dominant light source.
+- `fill light`: softer light used to lift shadows.
+- `rim light`: back/side light that outlines silhouette.
+- `environment reflection`: skybox/HDRI-like reflection source.
+- `contact shadow`: near-surface shadow grounding the object.
+- `shadow softness`: blur/spread of shadow edge.
+- `color temperature`: warm/cool light tint.
+- `exposure`: scene brightness scale.
+- `tone mapping`: output transform affecting contrast and highlights.
+
+## Animation, Physics, And Destruction
+
+- `pivot`: local rotation origin.
+- `hinge`: constrained rotation joint.
+- `socket`: attachment point for a child part.
+- `collider`: simplified physics shape.
+- `rigid body`: simulated physical body.
+- `fracture seam`: planned break line.
+- `detachable fragment`: piece that can separate during destruction.
+- `impulse direction`: force vector used to trigger movement or breakage.
+
+## Writing Rule
+
+Bad: `the surface is ugly and too smooth`.
+
+Better: `increase microRoughness to 0.45, add tangent-space fine-noise normal with strength 0.2 and scale 32, add low-frequency albedo mottling at amplitude 0.12, and add cavity dirt local masks in recessed grooves`.
+
+Bad: `make the edges realistic`.
+
+Better: `add 0.025 relative bevel radius with 3 segments on exposed hard-surface edges, add edge-wear local overrides on bevel crests, and keep internal seams sharper with 1-segment chamfers`.

grimoire/intake/detail_inventory.md

@@ -0,0 +1,131 @@
+# Detail Inventory
+
+Use this reference during analysis, before the spec is authored. It exists because small
+identity-defining marks (a bevel highlight, a row of rivets, a stain) get skipped when the
+agent only eyeballs the whole image once. Scan zone by zone and record every mark as a
+structured `detail`, not as prose.
+
+## The Rule
+
+Every `detail` entry records: where (`region`, normalized), what changes (`kind` + `affects`),
+how strong (`scale`, intensity implied by the recipe below), evidence region (`evidenceRef`),
+and confidence. It MUST set `mapsTo` a real `component.localFeatures[]` entry or
+`material.localOverrides[]` entry. A detail described only in prose is a gate failure - if it
+does not map to a field the generator reads, it will not reach the render.
+
+## Taxonomy - kind to graphics terms
+
+### gloss (do bong)
+Localized low-roughness zone or specular hotspot, not a global material change.
+- `material.localOverrides`: `roughness` low value (0.05-0.2) over the region, or
+  `clearcoat` + `clearcoatRoughness` on `MeshPhysicalMaterial` for a lacquer/wet look.
+- Streaked highlights (brushed metal, hair) -> `anisotropy` + `anisotropyRotation`.
+- Record hotspot position relative to the key light direction; a gloss detail with no
+  matching light direction will not render visibly.
+
+### bevel (bo goc)
+Edge treatment, not a texture trick - light catches a real chamfer.
+- `component.localFeatures` geometry effect: `edgeTreatment.type = chamfer`,
+  `bevelRadius` (object-relative, e.g. 0.02-0.08), `segments` (2-4 for a soft rim, 1 for hard).
+- Note whether it reads as a bright rim highlight under grazing light; if the reference
+  shows a crisp bright line along an edge, the bevel must be real geometry, not a normal map.
+
+### fastener (screw / rivet / bolt)
+Repeated small parts - always an instanced system, never one-off meshes.
+- `InstancedMesh`, `count`, spacing/distribution (linear, radial, grid), head shape
+  (hemisphere, flat, hex), recess (raised vs countersunk), material (usually metal, low
+  roughness at the head crown).
+- Confidence should reflect whether every instance is visible or only a legible subset
+  (partial rows behind occlusion still count if spacing is inferable).
+
+### linework (engraving / painted line / panel-line)
+Three distinct techniques - pick the one the evidence supports, they read differently:
+- Engraved groove: geometry effect, a recessed `groove` (see below) following a path;
+  catches shadow, no geometry it will look flat under any light.
+- Painted line / decal: `material.localOverrides` with a canvas-texture decal region;
+  color contrast only, no relief.
+- Panel-line: dark AO seam - a thin `localOverride` darkening roughness/AO along a seam
+  without true depth; use when the reference shows a soft dark line, not a hard groove.
+- State a legibility target: line must remain readable at the review's grazing-light shot.
+
+### contour (edge outline / toon rim)
+Stylized outline, usually a rim-light or a backface-outline technique.
+- `material.localOverrides` or a dedicated outline pass (inverted-hull or shader rim).
+- Record which silhouette edges carry it; partial outlines (only the top edge) are common.
+
+### seam
+Construction line where two surfaces meet (molded parts, fabric panels, armor plates).
+- Geometry effect: a thin recessed `groove` or a raised `ridge` (whichever the reference
+  shows) plus a slightly darker AO localOverride in the crevice.
+
+### stitch (fabric stitch)
+- `component.localFeatures`: small repeated bumps or a dashed groove along a seam path;
+  usually paired with a `linework: painted line` for the thread color contrast.
+- Instance or repeat along a curve like a fastener row, but finer spacing.
+
+### stain (dirt / patina / discolour / faded)
+Always a `material.localOverrides` region, described with these sub-fields:
+- `dirtAmount`: 0-1, how much darker/desaturated.
+- `cavityBias`: whether it concentrates in crevices/cavities (usually yes for dirt/grime).
+- `streak`: vertical/directional streaking flag + direction (gravity-fed dirt runs down).
+- `patinaColor`: hex or named hue shift for oxidation/verdigris/rust bloom.
+- `fadedMask`: a lighter, desaturated region for sun-bleaching - opposite of dirt, still a
+  localOverride.
+- `region`: where on the object, tied to `evidenceRef`.
+
+### scratch
+Thin localized roughness/normal perturbation, optionally exposing an underlayer color.
+- `material.localOverrides`: scratch cluster with orientation (usually radial or directional
+  from handling), width, and whether it exposes a different base color underneath.
+
+### chip
+Small area of missing surface material, usually at an edge or corner.
+- Geometry effect if it changes silhouette (a notch); otherwise a localOverride exposing
+  an underlayer color/roughness at a corner/edge component.
+
+### decal
+Printed/applied graphic or label, flat against the surface.
+- `material.localOverrides` with a canvas-texture region; record placement, approximate
+  size, and rotation. Decals do not add geometry unless they have physical thickness
+  (a sticker edge) - if so, add a thin raised `component.localFeatures` plate.
+
+### emissive
+Self-lit region (LED, glow, screen, ember).
+- `material.localOverrides`: `emissive` color + `emissiveIntensity`, and whether it should
+  bloom under the renderer's tone mapping. Record whether it is constant or should read as
+  a light source affecting nearby surfaces (may need a matching point/area light).
+
+### hole
+Actual opening or socket, changes silhouette/topology.
+- `component.localFeatures` geometry effect: a real cut or socket, not a dark texture patch.
+  Record depth and whether the interior needs its own material (visible cavity).
+
+### groove
+Recessed linear or curved channel.
+- Geometry effect: negative relief along a path, width/depth object-relative, plus AO
+  darkening in the channel. Shares mechanics with engraved linework and seams.
+
+### ridge
+Raised linear or curved feature, the geometric inverse of a groove.
+- Geometry effect: positive relief along a path, width/height object-relative, catches
+  highlight along its top edge (pair with a gloss or bevel note if the reference shows a
+  highlight line on the ridge crest).
+
+## Scan Method
+
+Pick one and record it as `scanMethod`:
+- `component-zones`: walk each planned component's bounding region; best when component
+  boundaries are already known.
+- `grid-3x3` / `grid-4x4`: divide the image into a uniform grid and inspect every cell;
+  use when components are not yet decided or the object has no obvious part boundaries.
+
+Set `targetMinDetails` from complexity tier: simple 3, moderate 6, complex 10, ultra 16
+(starting values, tune after runs). Scanning zone by zone against a minimum count is what
+prevents a single-glance miss of small marks.
+
+## Confidence
+
+Score 0-1 per detail. Lower confidence for: partially occluded regions, marks inferred by
+symmetry rather than seen, or ambiguous kind classification (e.g. scratch vs. panel-line).
+Do not inflate confidence to pad `targetMinDetails` - an unlinked or low-confidence detail
+that fails the `mapsTo` check still blocks the gate.

grimoire/intake/quality_contract.md

@@ -0,0 +1,68 @@
+# Pre-Spec Assessment And Quality Contract
+
+Use this reference before authoring an `ObjectSculptSpec`. The purpose is to prevent shallow specs that are technically valid but too vague to recreate the reference object.
+
+Do not use fixed domain profiles. Assess the object from observed traits, complexity, and target fidelity.
+
+## Soft Object Classification
+
+Describe the object using multiple axes:
+
+- form language: organic, hard-surface, mechanical, architectural, botanical-like, character-like, amorphous, sculptural, fabric-like, transparent-like
+- structure kind: single body, compound object, branching hierarchy, repeated modules, layered shell, articulated assembly, deformable surface
+- motion potential: static prop, whole-object transform, articulated, bendable, detachable, destructible, effect-emitter
+- material families: wood, bark, leaf, metal, stone, ceramic, plastic, rubber, cloth, glass-like, liquid-like, skin-like, mixed
+
+These are descriptors, not domain templates. Use only what the image supports.
+
+## Complexity Scoring
+
+Score each axis from 0 to 3:
+
+- silhouette complexity: simple outline to heavily interrupted/organic silhouette
+- component count: one piece to many visible subparts
+- hierarchy depth: flat object to deep parent-child structure
+- repetition density: none to thousands of repeated marks/leaves/scales/rivets
+- material layer count: one material to many layered local material responses
+- local detail density: plain surface to dense scratches, bumps, moss, seams, chips, pores, or grain
+- occlusion risk: fully visible to many hidden/inferred parts
+- action readiness need: static to many pivots/sockets/colliders/destruction seams
+
+Map total judgment to:
+
+- `simple`: few parts, low detail, one or two materials
+- `moderate`: several parts, visible local detail, shallow hierarchy
+- `complex`: many parts, repeated systems, multiple materials, several hierarchy levels
+- `ultra-complex`: dense organic/mechanical/architectural structure where fidelity depends on deep hierarchy and repeated microstructure
+
+## Quality Contract
+
+Before generating code, define exactly what makes the model good enough:
+
+- definition of done for this object
+- minimum macro, meso, and micro feature counts
+- required repeated systems and their distribution rules
+- required material layers and local overrides
+- screenshot viewpoints required for visual comparison
+- failure modes that should block `continue`
+
+Good feature groups are specific to the image:
+
+- weak: `make leaves look good`
+- strong: `leaf clusters must form irregular overlapping canopy masses, with varied card size/orientation/color and gaps exposing secondary branches`
+
+- weak: `add bark texture`
+- strong: `trunk and primary branches need vertical ridges, cavity-darkened cracks, moss/lichen patches near roots and inner forks, roughness variation, and nonuniform displacement/bump`
+
+## Strict Quality Gate
+
+Run `../../forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality` before code generation. The script path is relative to the skill folder.
+
+If strict validation fails:
+
+- refine `preSpecAssessment` if complexity was underestimated
+- refine `qualityContract` if definition of done is too generic
+- add missing components, material layers, repetition systems, evidence refs, or local features
+- only lower the quality bar if the user explicitly accepts a simpler approximation
+
+The gate should block code generation when the spec could describe many different objects instead of the provided reference.

grimoire/intake/validation_rubric.md

@@ -0,0 +1,66 @@
+# Object Image Validation Rubric
+
+Use this reference when the suitability decision is unclear.
+
+## Pass
+
+- one obvious target object
+- object occupies enough of the frame
+- at least one strong silhouette
+- major materials are visible
+- hidden side can be reasonably inferred
+- target can be approximated with procedural primitives
+
+## Conditional
+
+- one view only but object has rotational symmetry
+- some occlusion but macro shape is clear
+- fine surface detail can be represented with procedural texture
+- target is organic but user accepts stylization
+- exact brand/logo/text fidelity is not required
+
+## Reject
+
+- target object is ambiguous
+- photo is a scene, not an object reference
+- important shape is hidden, cropped, blurred, or transparent
+- request demands exact mesh extraction or manufacturing-grade dimensions
+- object relies primarily on smoke, liquid, glass caustics, or lace (no reconstruction path exists for these)
+
+## Character / Human Suitability
+
+Do not blanket-reject a subject for being hair- or cloth-fold-dominant. If the form language is character-like (humanoid silhouette, skin/cloth/hair materials), classify it `character-conditional -> stylized` instead of `reject`. Route through `grimoire/character/reconstruction.md` (proportions, landmarks, pose, stylized materials) by default.
+
+- **character-conditional -> stylized**: humanoid subject, at least one clear frontal view, pose readable, hair/cloth is present but the user accepts the stylized-clump/fold-normal treatment rather than photoreal strands or drape simulation. Proceed with the standard character pipeline.
+- **character-conditional -> maximum likeness**: user explicitly wants the closest possible match to a specific person/character. Confirm this intent before starting, then route through `grimoire/character/likeness_maximization.md` (projection-first: template fit, camera match, de-lighting, texture projection). State up front that a single image cannot guarantee 100 percent likeness; report per-region confidence instead of claiming an exact match.
+- **still reject**: no humanoid silhouette is discernible at all, the figure is fully occluded/cropped below usable proportions, or the request demands photoreal skin/hair microstructure from a single low-resolution image with no willingness to provide more views or accept stylization.
+
+Before committing to a character spec:
+
+- confirm which stylization level the user accepts (realistic ~7.5 heads / stylized 5-6 / chibi 2-3) — do not assume realistic by default
+- request front, side, and back (or full-body) views whenever the visible view cannot support pose, proportion, or back-of-head/body inference
+- if maximum likeness is requested but only one low-quality view is available, say so explicitly and offer the stylized fallback as the practical alternative
+
+## Ask For Better Input
+
+Ask for:
+
+- front, side, and back views
+- a neutral background
+- higher resolution
+- close-ups of material/detail
+- desired style: realistic, stylized, low-poly, game prop, hero render
+
+## Complex Object Detail Standard
+
+For objects with many details, require:
+
+- macro components for the overall mass
+- meso components for visible sub-assemblies
+- micro components or local features for repeated/tiny details
+- material layer stack for every visually distinct surface
+- local overrides for stains, scratches, dirt, color changes, wear, bumps, and roughness shifts
+- confidence per component or feature
+- evidence refs to image regions
+
+If these cannot be inferred from the image, mark the spec `conditional` and list missing views or close-ups.

grimoire/readiness/action_rigging.md

@@ -0,0 +1,53 @@
+# Action-Ready Procedural Models
+
+Use this reference when a procedural Three.js model may later need animation, transformation, physics, or destruction.
+
+## Design Goal
+
+The generated model should be a runtime-ready hierarchy, not a single decorative mesh. Future actions should be added by targeting named nodes, sockets, colliders, and destruction groups instead of rewriting the reconstruction.
+
+## Hierarchy Pattern
+
+Use this structure:
+
+- `root`: whole-object motion, visibility, global scale, runtime metadata.
+- `component pivot Group`: stable transform node for each macro/meso component.
+- `visual mesh`: child of the component pivot; holds geometry and material.
+- `socket Object3D`: child of the relevant pivot; marks attachment, effect, grip, or joint positions.
+- collider metadata/proxy: simplified runtime shape, not necessarily a visible mesh.
+- destruction group metadata: semantic grouping for detach/break logic.
+
+## Pivot Rules
+
+- Use center pivots only when the object rotates around its center of mass.
+- Use base pivots for trees, signs, bottles, poles, legs, and upright props.
+- Use hinge pivots for lids, doors, handles, flaps, jaws, levers, and wings.
+- Use branch/root pivots for organic appendages that bend from one end.
+- Use custom pivots when the reference clearly implies a mechanical joint or socket.
+
+## Collider Rules
+
+- Use primitive proxies first: box, sphere, capsule, cylinder.
+- Use compound proxies for complex silhouettes.
+- Avoid visual mesh colliders unless the user explicitly asks for high-precision collision.
+- Mark triggers separately from solid colliders.
+- Store collider intent even when no physics engine is installed.
+
+## Destruction Rules
+
+- Break along existing seams, joints, material boundaries, weak points, or branch roots.
+- Use detachable component groups for large fragments.
+- Use procedural small fragments only where they improve readability.
+- Attach impact, spark, dust, liquid, or debris effect sockets when destruction is expected.
+- Preserve material continuity on exposed fracture faces where possible.
+
+## Acceptance Criteria
+
+An action-ready model passes when:
+
+- Every major part has a stable ID and pivot node.
+- Movable or breakable parts are not merged into unrelated geometry.
+- Sockets are named and placed in local coordinates.
+- Collider proxies exist for physics-relevant parts.
+- Destruction groups and fracture seams are explicit.
+- `root.userData.sculptRuntime` exposes maps that later code can target.