Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
Python 3dai-agentsclaude-codecomputer-graphicsgenerativeimage-to-3dprocedural-generationthreejstypescriptwebgl
refactor: restructure project layout ahead of the full harness rebuild
hoainhoc42abe5424b1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 9e93cb0..e8e2f6a 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -5,10 +5,10 @@ quality-gated Three.js model. Contributions that keep that identity sharp are ve## Good first areas-- New procedural material or geometry recipes in `references/procedural-patterns.md`.+- New procedural material or geometry recipes in `grimoire/build/geometry_patterns.md`.- Object-domain templates and detail-inventory taxonomy improvements.-- Generator primitives, bevels, instancing, and surface-band tuning in `scripts/generate_threejs_factory.py`.-- More pipeline tests in `scripts/tests/test_pipeline.py`.+- Generator primitives, bevels, instancing, and surface-band tuning in `forge/stage3_build/generate_threejs_factory.py`.+- More pipeline tests in `forge/tests/test_pipeline.py`.- Documentation and worked examples.## Where the project is strong vs honest limits@@ -26,8 +26,8 @@ explicit, flagged, opt-in mode.## Development- Scripts are pure Python 3.10+ standard library. No pip dependencies.-- Run the test suite from the skill root: `python3 scripts/tests/test_pipeline.py`.-- Validate a spec before generation: `python3 scripts/validate_sculpt_spec.py spec.json --strict-quality`.+- Run the test suite from the skill root: `python3 forge/tests/test_pipeline.py`.+- Validate a spec before generation: `python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality`.- Keep changes backward compatible: existing object specs must continue to validate.- No emojis in source, docs, or generated output.diff --git a/README.md b/README.mdindex 5d23ed3..6037f86 100644--- a/README.md+++ b/README.md@@ -51,9 +51,9 @@ It runs under Claude Code, Codex, or OpenCode. It is agent-agnostic: wherever th### Subjects and detail accuracy-- **Objects and characters.** Each subject is classified `object`, `character`, or `hybrid`. Objects follow the hard-surface pipeline; characters route through an anatomy-aware track (head-unit proportions, facial landmarks, pose) documented in `references/character-reconstruction.md`.-- **Detail-first analysis.** Before code generation the pipeline enumerates a `detailInventory` of identity-defining small details (gloss, bevel/rounding, screws/rivets, engraved or painted linework, contours, stains and wear). Every detail must map to a real component or material entry, and a strict-quality gate blocks generation until the inventory is complete. Taxonomy: `references/detail-inventory.md`.-- **Maximum likeness for a specific person or character.** An opt-in projection-first path fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. A single image cannot guarantee 100 percent likeness, so the pipeline reports per-region confidence and asks for more views when it matters. Details: `references/likeness-maximization.md`.+- **Objects and characters.** Each subject is classified `object`, `character`, or `hybrid`. Objects follow the hard-surface pipeline; characters route through an anatomy-aware track (head-unit proportions, facial landmarks, pose) documented in `grimoire/character/reconstruction.md`.+- **Detail-first analysis.** Before code generation the pipeline enumerates a `detailInventory` of identity-defining small details (gloss, bevel/rounding, screws/rivets, engraved or painted linework, contours, stains and wear). Every detail must map to a real component or material entry, and a strict-quality gate blocks generation until the inventory is complete. Taxonomy: `grimoire/intake/detail_inventory.md`.+- **Maximum likeness for a specific person or character.** An opt-in projection-first path fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. A single image cannot guarantee 100 percent likeness, so the pipeline reports per-region confidence and asks for more views when it matters. Details: `grimoire/character/likeness_maximization.md`.---@@ -122,11 +122,11 @@ After every pass the agent chooses exactly one action: `continue`, `refine-spec`The scripts run from the skill root and need only Python 3.10+ — nothing to install.```bash-python3 scripts/probe_reference_image.py <image>-python3 scripts/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json-python3 scripts/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json-python3 scripts/validate_sculpt_spec.py spec.json --strict-quality-python3 scripts/generate_threejs_factory.py spec.json --out src/createObjectModel.ts+python3 forge/stage1_intake/probe_image.py <image>+python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json+python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json+python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality+python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts```---@@ -150,23 +150,23 @@ The net effect: you still get a faithful 3D model from an image, but the expensi| Script | Role || --- | --- |-| `probe_reference_image.py` | Image metadata and obvious technical issues (not a visual check). |-| `new_pre_spec_assessment.py` | Classify the object, score complexity, emit a quality contract. |-| `new_sculpt_spec.py` | Author the ObjectSculptSpec from the assessment. |-| `validate_sculpt_spec.py` | Validate the spec; `--strict-quality` blocks shallow specs before codegen. |-| `extract_reference_pbr.py` | Reference-derived PBR evidence per crop (inference, not inverse rendering). |-| `sculpt_pass_orchestrator.py` | Locked pass state: status, check, sync. |-| `generate_threejs_factory.py` | Emit the Three.js `Group` factory for the current unlocked pass. |-| `make_visual_comparison_sheet.py` | Package one reference-vs-render sheet for review. |-| `append_sculpt_review.py` | Record a per-pass review: scores, decision, evidence. |-| `visual_feature_gate.py` | Internal helper enforcing per-feature score thresholds. |-| `build_detail_inventory.py` | Slice the reference into zones and scaffold a detail inventory. |-| `extract_reference_landmarks.py` | Overlay a landmark grid and scaffold an anatomy block for characters. |-| `solve_reference_camera.py` | Emit a reference-camera block so the render can be camera-matched. |-| `delight_reference.py` | Approximate a neutral albedo from the photo before texture projection. |-| `bake_projected_texture.py` | Emit a projection/UV-bake descriptor for photo-texture projection. |--The `references/` folder holds the detailed rubrics each gate applies (validation, pre-spec assessment, procedural patterns, material and lighting realism, attachment correctness, action-ready models, self-correction).+| `stage1_intake/probe_image.py` | Image metadata and obvious technical issues (not a visual check). |+| `stage2_spec/new_pre_spec_assessment.py` | Classify the object, score complexity, emit a quality contract. |+| `stage2_spec/new_sculpt_spec.py` | Author the ObjectSculptSpec from the assessment. |+| `stage2_spec/validate_sculpt_spec.py` | Validate the spec; `--strict-quality` blocks shallow specs before codegen. |+| `stage1_intake/extract_pbr_evidence.py` | Reference-derived PBR evidence per crop (inference, not inverse rendering). |+| `stage3_build/orchestrate_passes.py` | Locked pass state: status, check, sync. |+| `stage3_build/generate_threejs_factory.py` | Emit the Three.js `Group` factory for the current unlocked pass. |+| `stage4_review/make_comparison_sheet.py` | Package one reference-vs-render sheet for review. |+| `stage4_review/append_review.py` | Record a per-pass review: scores, decision, evidence. |+| `_shared/feature_acceptance_policy.py` | Internal helper enforcing per-feature score thresholds. |+| `stage1_intake/build_detail_inventory.py` | Slice the reference into zones and scaffold a detail inventory. |+| `stage1_intake/extract_landmarks.py` | Overlay a landmark grid and scaffold an anatomy block for characters. |+| `stage1_intake/solve_camera_pose.py` | Emit a reference-camera block so the render can be camera-matched. |+| `stage1_intake/delight_albedo.py` | Approximate a neutral albedo from the photo before texture projection. |+| `stage3_build/bake_projected_texture.py` | Emit a projection/UV-bake descriptor for photo-texture projection. |++The `grimoire/` folder holds the detailed rubrics each gate applies (validation, pre-spec assessment, procedural patterns, material and lighting realism, attachment correctness, action-ready models, self-correction).---diff --git a/SKILL.md b/SKILL.mdindex 2484794..bd5c349 100644--- a/SKILL.md+++ b/SKILL.md@@ -24,7 +24,7 @@ action-ready props, game objects, botanical/mechanical parts, and stylized recon## Core PromiseSculpt from a photo, in order — never one-shot a mesh:-1. **Validate** the image is a suitable 3D target (`references/validation-rubric.md`).+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.@@ -41,65 +41,65 @@ hidden sides or guarantee exact geometry — say so instead of faking confidence## The Loop (scripts do enforcement; agent vision does judgment)-Run scripts from the skill root (`scripts/...`). Pure Python 3.10+ stdlib, no pip installs.-Full flags: `references/scripts.md`. Never let a script *score* visuals — that is the agent's job.+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: `scripts/probe_reference_image.py <image>` (metadata only, not a visual check).+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:- `scripts/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json`. Rules: `references/pre-spec-assessment.md`.+ `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 everyidentity-defining small detail (gloss, bevel, fasteners, linework, contours, stains):- `scripts/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json`.+ `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: `references/detail-inventory.md`.+ prose only. Taxonomy + 3D-term recipes: `grimoire/intake/detail_inventory.md`.2c. **Character/hybrid subjects** — capture head-unit proportions + facial/body landmarks:- `scripts/extract_reference_landmarks.py <image> --out anatomy.json --overlay overlay.png`, then- fill `preSpecAssessment.anatomy`. Route: `references/character-reconstruction.md`. For maximum- likeness use the projection-first path (`references/likeness-maximization.md`): solve the camera- (`solve_reference_camera.py`), de-light the photo (`delight_reference.py`), and project it onto- the fitted mesh (`bake_projected_texture.py`). A single image cannot guarantee 100% likeness —+ `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:- `scripts/new_sculpt_spec.py "Name" --image <img> --assessment assessment.json --out object-sculpt-spec.json`.+ `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-definingsystems (≤5 critical, ≤3 important per pass); for characters add `anatomy-proportion`,`face-landmark-placement`, `pose-silhouette`, `outfit-and-palette`. Use 3D-graphics terms only- (`references/3d-graphics-terminology.md`), never "nice/smooth/shiny".+ (`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:- `scripts/extract_reference_pbr.py <crop> --out-dir <dir> --material-id <id> --target-threshold 0.7`.+ `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:- `scripts/validate_sculpt_spec.py object-sculpt-spec.json` then `--strict-quality`.+ `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, nolocal overrides, no micro groups is NOT implementation-ready even if JSON validates).6. **Locked build passes** — only touch the currently unlocked pass:- `scripts/sculpt_pass_orchestrator.py status object-sculpt-spec.json`- `scripts/sculpt_pass_orchestrator.py check object-sculpt-spec.json --pass-id <pass>`- `scripts/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts`+ `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:- `scripts/make_visual_comparison_sheet.py --reference <img> --render <shot> --out cmp.png --json`.+ `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):- `scripts/append_sculpt_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`.+ `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:- `scripts/sculpt_pass_orchestrator.py sync object-sculpt-spec.json --in-place`.+ `forge/stage3_build/orchestrate_passes.py sync object-sculpt-spec.json --in-place`.## Gates (do not skip)-- **Suitability**: pass / conditional / reject before any planning. `references/validation-rubric.md`.+- **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 + globalAI-vision score ≥ threshold (default 0.7) AND every critical feature ≥ its own threshold.- Details + per-layer scorecard: `references/browser-screenshot-feedback.md`.+ 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`. `references/action-ready-models.md`.+ 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.- `references/attachment-joint-correctness.md`.-- **Material/lighting**: `references/material-lighting-realism.md` — independent PBR channels+ `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@@ -109,7 +109,7 @@ Full flags: `references/scripts.md`. Never let a script *score* visuals — thatheadphones, face features), flattened to world space under a hidden root, with per-partcharacter 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: `references/validation-rubric.md`+ 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@@ -117,7 +117,7 @@ Full flags: `references/scripts.md`. Never let a script *score* visuals — thatAfter 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: `references/self-correction-loop.md`.+guide + fidelity scale: `grimoire/review/self_correction.md`.## Implementation Rules (brief)@@ -125,7 +125,7 @@ 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: `references/procedural-patterns.md`.+material recipes + hard-won failure patterns: `grimoire/build/geometry_patterns.md`.## Outputdiff --git a/docs/PROMOTION.md b/docs/PROMOTION.mddeleted file mode 100644index 835b1ec..0000000--- a/docs/PROMOTION.md+++ /dev/null@@ -1,124 +0,0 @@-# Promotion playbook (attract stars and contributors, without spamming)--This is copy you post from your own accounts. It is deliberately honest about scope so the-project earns trust instead of a spam label. Repo: https://github.com/hoainho/img2threejs--## Ground rules (read first)--- Do NOT open issues or pull requests on three.js, react-three-fiber, or other libraries just to- advertise this project. That is spam, gets closed, and damages your reputation.-- DO post in venues that exist for showing work, and DO submit to curated lists that accept- entries. Post once per venue, respond to comments, do not cross-post aggressively.-- Lead with an honest scope line every time: strong for objects, stylized-only for characters.- The demo GIF is a chest (its strongest result), not a person.--## Submitted PRs (log)--- awesome-threejs (AxiomeCG, active): https://github.com/AxiomeCG/awesome-threejs/pull/24 (Tools > 3D modeling)-- awesome-webgl (sjfricke, active): https://github.com/sjfricke/awesome-webgl/pull/36 (Libraries > Others)--Deliberately NOT submitted (dead/stale repos - PRs there get zero visibility and read as spam-blasting):-- we-list/awesome-threejs (last push 2016)-- crubier/awesome-three-js (last push 2019)-- Fasani/three-js-resources (last push 2021)--## 1. three.js Discourse — Showcase category--Venue: https://discourse.threejs.org/ (category: Showcase)--Anti-spam / correctness rules for this forum (important):-- Post in the "Showcase" category only. Do NOT use Help/Questions or unrelated threads.-- New Discourse accounts start at trust level 0 and often CANNOT post links or images until they- reach TL1. Reach TL1 first: read several topics, spend a few minutes in the forum, enter a few- topics. Then your post with the repo link/GIF will not be auto-flagged.-- One topic only. Do not create duplicates, do not bump, do not paste the same link into other- people's threads.-- Disclose it is your own project, give an honest scope line, and ask a real question or invite- feedback/contributors — a pure "star my repo" post gets flagged.-- Reply to every comment; engagement is what separates a showcase from spam.-- Use an accurate, non-clickbait title and correct tags.--Title: img2threejs - rebuild an object photo as a code-only procedural Three.js model--Body:-> I built a skill/toolkit that reconstructs the object in a single reference image as a-> code-only, procedural Three.js model - primitives, procedural shaders, and generated geometry,-> no downloaded meshes or art packs. It runs a staged pipeline (blockout, structure, form,-> material, lighting) with a screenshot-vs-reference review loop at each step.->-> Honest scope: it is strong for hard-surface objects and stylized/low-poly assets. Characters-> currently read as game/figurine avatars, not photoreal likeness - that is a documented limit.->-> Repo (MIT, pure-Python stdlib tooling + generated TypeScript): https://github.com/hoainho/img2threejs-> Feedback and contributors welcome, especially on procedural material recipes.--## 2. Reddit - r/threejs and r/webgl--Title: img2threejs: turn an object photo into a procedural, code-only Three.js model (MIT)--Body:-> Open-source toolkit that rebuilds the object in one reference image as procedural Three.js code-> (no mesh downloads), gated by a staged pipeline with a render-vs-reference review loop. Strong-> for hard-surface objects; characters are stylized-only for now (documented). Would love feedback-> and contributors. Repo: https://github.com/hoainho/img2threejs--Flair: Showcase / Project. Post to r/threejs first; wait a day before r/webgl.--## 3. Hacker News - Show HN--Title: Show HN: img2threejs - rebuild an object photo as procedural Three.js code--Text:-> It reconstructs the object in a single image as a code-only procedural Three.js model, gated by-> a staged pipeline (blockout to material to lighting) with a screenshot-vs-reference review loop.-> Pure-Python stdlib tooling emits diffable TypeScript; no downloaded meshes. Honest about limits:-> great for hard-surface objects, stylized-only for people. MIT. Feedback welcome.-> https://github.com/hoainho/img2threejs--Post during US morning (weekday) for visibility. Reply to every comment.--## 4. Short social post (X / Bluesky / Mastodon)--> img2threejs: give it one photo of an object, get back a code-only procedural Three.js model --> no mesh downloads, quality-gated by a render-vs-reference loop. MIT, contributors welcome.-> https://github.com/hoainho/img2threejs--Attach the demo GIF (assets/demo.gif).--## 5. Awesome-list submission (the welcomed "contribute to a known repo" path)--Candidate lists (verified real + active; read each repo's CONTRIBUTING and format before a PR):-- awesome-threejs: https://github.com/AxiomeCG/awesome-threejs (most active, well-categorized)-- awesome-threejs (alt): https://github.com/we-list/awesome-threejs-- awesome-three-js (alt): https://github.com/crubier/awesome-three-js-- three-js-resources: https://github.com/Fasani/three-js-resources-- awesome-webgl: https://github.com/sjfricke/awesome-webgl (see CONTRIBUTING.md at /blob/master/CONTRIBUTING.md)--Timing note: most awesome lists expect some notability/traction. Submitting a days-old repo with-~1 star can get a PR rejected or read as premature self-promotion. Do the showcase posts first,-gather a bit of traction, then submit. Pick the ONE list that best fits (AxiomeCG/awesome-threejs-under a tools/generators section), follow its exact entry format, and open a single clean PR from-your own account.--Entry line to add (match the list's existing format):-> - [img2threejs](https://github.com/hoainho/img2threejs) - Rebuild the object in a reference image as a code-only, procedural, quality-gated Three.js model.--PR description:-> Adds img2threejs, an MIT-licensed toolkit that reconstructs an object photo as procedural-> Three.js code (no downloaded assets), with a staged review pipeline. Placed under the-> tools/generators section. Happy to adjust wording or placement.--Submit from your own GitHub account, one list at a time, and follow each list's CONTRIBUTING rules.--## 6. Make the repo itself convert visitors--- Topics set: threejs, webgl, 3d, procedural-generation, image-to-3d, generative, typescript, computer-graphics, ai-agents, claude-code.-- README opens with the demo GIF and an honest scope line. Done.-- LICENSE and CONTRIBUTING present. Done.-- Consider a hosted live demo later (the chest project) and link it as the repo homepage - a- clickable demo converts far better than a GIF.--## Metrics to watch--- Where stars come from (GitHub traffic - referrers). Double down on the venue that converts.-- Issues/PRs opened - reply within a day to keep momentum and turn visitors into contributors.diff --git a/docs/UPGRADE_PLAN.md b/docs/UPGRADE_PLAN.mdindex c860637..506d12b 100644--- a/docs/UPGRADE_PLAN.md+++ b/docs/UPGRADE_PLAN.md@@ -10,15 +10,15 @@ v1.2.0 implementation notes:Shipped in 1.1.0:- Schema: preSpecAssessment.detailInventory (+ targetMinDetails by complexity), objectClass.primaryDomain, preSpecAssessment.anatomy, top-level referenceCamera.-- Gates: validate_sculpt_spec.py detail-inventory gate (count + component/material linkage + gloss/fastener checks) and character track gate (anatomy + character feature targets); both backward compatible.-- References: detail-inventory.md, character-reconstruction.md, likeness-maximization.md; procedural-patterns.md detail + character recipes; validation-rubric.md character suitability branch.-- Scripts: build_detail_inventory.py, extract_reference_landmarks.py, solve_reference_camera.py, delight_reference.py, bake_projected_texture.py.+- Gates: stage2_spec/validate_sculpt_spec.py detail-inventory gate (count + component/material linkage + gloss/fastener checks) and character track gate (anatomy + character feature targets); both backward compatible.+- References: intake/detail_inventory.md, character/reconstruction.md, character/likeness_maximization.md; build/geometry_patterns.md detail + character recipes; intake/validation_rubric.md character suitability branch.+- Scripts: 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.- Tests: 16 pass (8 new covering the schema, gates, backward compat, and new scripts). SKILL.md + README updated; version bumped to 1.1.0.Not yet implemented (follow-up, do not assume present):-- generate_threejs_factory.py humanoid rig + face-landmark placement + detail-emission hooks.-- new_sculpt_spec.py character componentTree template.-- sculpt_pass_orchestrator.py proportion-lock / feature-placement passes.+- stage3_build/generate_threejs_factory.py humanoid rig + face-landmark placement + detail-emission hooks.+- stage2_spec/new_sculpt_spec.py character componentTree template.+- stage3_build/orchestrate_passes.py proportion-lock / feature-placement passes.- delight/camera/projection scripts are documented approximations/descriptors, not GPU-accurate implementations.Scope decisions locked with maintainer:- Primary goal for human/character subjects: maximize likeness to the reference image, aiming as close to 100 percent as the input allows.@@ -38,11 +38,11 @@ Two weaknesses in the current 1.0 pipeline:| Symptom | Root cause | Location || --- | --- | --- |-| Humans look nothing like the image | No anatomy/landmark/pose model; object-only geometry recipes | `references/procedural-patterns.md`, `scripts/new_pre_spec_assessment.py`, `scripts/new_sculpt_spec.py` |-| Humans get rejected early | Rubric rejects hair/cloth-fold-dominant subjects | `references/validation-rubric.md` |-| Whole-image score hides face/proportion errors | Feature gate has no anatomy features | `scripts/visual_feature_gate.py`, spec `featureReviewTargets` |-| Small details missed | Detail density is one score; no inventory artifact or gate | `references/pre-spec-assessment.md`, `scripts/new_pre_spec_assessment.py`, `scripts/validate_sculpt_spec.py` |-| No help inspecting detail zones | Probe returns metadata only | `scripts/probe_reference_image.py` |+| Humans look nothing like the image | No anatomy/landmark/pose model; object-only geometry recipes | `grimoire/build/geometry_patterns.md`, `forge/stage2_spec/new_pre_spec_assessment.py`, `forge/stage2_spec/new_sculpt_spec.py` |+| Humans get rejected early | Rubric rejects hair/cloth-fold-dominant subjects | `grimoire/intake/validation_rubric.md` |+| Whole-image score hides face/proportion errors | Feature gate has no anatomy features | `forge/_shared/feature_acceptance_policy.py`, spec `featureReviewTargets` |+| Small details missed | Detail density is one score; no inventory artifact or gate | `grimoire/intake/quality_contract.md`, `forge/stage2_spec/new_pre_spec_assessment.py`, `forge/stage2_spec/validate_sculpt_spec.py` |+| No help inspecting detail zones | Probe returns metadata only | `forge/stage1_intake/probe_image.py` |## 3. Design principles (must hold across the upgrade)@@ -88,7 +88,7 @@ Supported `kind` values (the detail taxonomy): `gloss`, `bevel`, `fastener` (scrRule: every `detail` must set `affects` (geometry or material or both) and `mapsTo` a real `component.localFeatures[]` entry or `material.localOverrides[]` entry. A detail described only in prose is a gate failure.-### 4.2 New reference: `references/detail-inventory.md`+### 4.2 New reference: `grimoire/intake/detail_inventory.md`Taxonomy plus how to express each detail in 3D-graphics terms:- gloss / do bong -> roughness low zone, clearcoat, specular hotspot location, anisotropy if streaked.@@ -100,23 +100,23 @@ Taxonomy plus how to express each detail in 3D-graphics terms:Each entry states: where, what changes, how strong, which evidence supports it.-### 4.3 New script: `scripts/build_detail_inventory.py`+### 4.3 New script: `forge/stage1_intake/build_detail_inventory.py`- Input: reference image (+ optional component regions).- Output: crops of each zone (grid or per-component) into a directory + a `detailInventory` skeleton JSON to fill.- Purpose: force systematic zone-by-zone inspection so the agent does not eyeball the whole image once and miss small marks.-- Pure stdlib PNG slicing (struct/zlib), consistent with `make_visual_comparison_sheet.py`.+- Pure stdlib PNG slicing (struct/zlib), consistent with `stage4_review/make_comparison_sheet.py`.### 4.4 Schema and gate changes-- `scripts/new_pre_spec_assessment.py`: emit `detailInventory` skeleton; set `targetMinDetails` from complexity tier (simple 3, moderate 6, complex 10, ultra 16 as starting values, tunable).-- `scripts/new_sculpt_spec.py`: carry `detailInventory` into the spec; wire a helper so each detail links to a component/material.-- `scripts/validate_sculpt_spec.py` (`--strict-quality`): new checks+- `forge/stage2_spec/new_pre_spec_assessment.py`: emit `detailInventory` skeleton; set `targetMinDetails` from complexity tier (simple 3, moderate 6, complex 10, ultra 16 as starting values, tunable).+- `forge/stage2_spec/new_sculpt_spec.py`: carry `detailInventory` into the spec; wire a helper so each detail links to a component/material.+- `forge/stage2_spec/validate_sculpt_spec.py` (`--strict-quality`): new checks- detail count >= `targetMinDetails` for the tier.- every detail `mapsTo` an existing component localFeature or material localOverride (no orphan prose).- a "detailed" object must carry material roughness variation + at least one bevel/edgeTreatment when the inventory lists gloss/bevel details.- gloss details require a low-roughness localOverride or clearcoat; fastener details require an instanced/repetition system or explicit small-count meso parts.-- `references/browser-screenshot-feedback.md`: add a mandatory detail close-up review - grazing-light shot that must show bevel highlights, countable fasteners, legible linework, and stains in the correct regions. Add a per-detail checklist to the review sheet.+- `grimoire/feedback/render_capture.md`: add a mandatory detail close-up review - grazing-light shot that must show bevel highlights, countable fasteners, legible linework, and stains in the correct regions. Add a per-detail checklist to the review sheet.### 4.5 Track A acceptance criteria@@ -132,10 +132,10 @@ Goal: add a first-class character track that reconstructs a humanoid matching th### 5.1 Domain detection-- `scripts/new_pre_spec_assessment.py`: add `objectClass.primaryDomain = object | character | hybrid` inferred from the agent's classification (character-like form language + skin/cloth/hair materials + humanoid silhouette).+- `forge/stage2_spec/new_pre_spec_assessment.py`: add `objectClass.primaryDomain = object | character | hybrid` inferred from the agent's classification (character-like form language + skin/cloth/hair materials + humanoid silhouette).- When `character` or `hybrid`, the assessment additionally emits an `anatomy` block and character feature targets.-### 5.2 New reference: `references/character-reconstruction.md`+### 5.2 New reference: `grimoire/character/reconstruction.md`- Proportion system in head-units, with a style axis: realistic ~7.5 heads, stylized ~5-6, figurine/chibi 2-3. Record measured ratios from the image (head : torso : legs, shoulder width, hip width).- Facial landmark layout: eye line near vertical mid-head, eye spacing, nose base, mouth line, hairline, ear top/bottom. Store normalized coordinates.@@ -159,7 +159,7 @@ Goal: add a first-class character track that reconstructs a humanoid matching th}```-### 5.4 New script: `scripts/extract_reference_landmarks.py`+### 5.4 New script: `forge/stage1_intake/extract_landmarks.py`- Overlays a labelled grid / guide on the reference so the agent's vision can fill in landmark coordinates (eyes, shoulders, hips, joints).- Outputs an `anatomy` skeleton with normalized coordinates + an overlay image for review.@@ -167,16 +167,16 @@ Goal: add a first-class character track that reconstructs a humanoid matching th### 5.5 Generator and pipeline-- `scripts/new_sculpt_spec.py`: humanoid component template - `rig` root with joint pivot nodes; head, face-feature group, hair group, torso, arms, legs as capsule/tapered primitives; outfit parts as separate components with Track A detail hooks.-- `scripts/generate_threejs_factory.py`: emit the humanoid rig (named joint pivots, action-ready sockets), capsule limbs, face-feature placement from landmarks, hair cards; expose everything via `root.userData.sculptRuntime`.+- `forge/stage2_spec/new_sculpt_spec.py`: humanoid component template - `rig` root with joint pivot nodes; head, face-feature group, hair group, torso, arms, legs as capsule/tapered primitives; outfit parts as separate components with Track A detail hooks.+- `forge/stage3_build/generate_threejs_factory.py`: emit the humanoid rig (named joint pivots, action-ready sockets), capsule limbs, face-feature placement from landmarks, hair cards; expose everything via `root.userData.sculptRuntime`.- Two new build sub-passes inserted for the character domain, before `material-pass`:- `proportion-lock`: block out the humanoid at the measured head-unit proportions and pose; gate on silhouette + proportion match.- `feature-placement`: place facial features and hair to the landmark coordinates; gate on face landmark alignment.-- `references/validation-rubric.md`: add a character suitability branch - classify humans as `character-conditional -> stylized` rather than reject; specify when to request more views (front, side, full-body) and confirm accepted stylization level.+- `grimoire/intake/validation_rubric.md`: add a character suitability branch - classify humans as `character-conditional -> stylized` rather than reject; specify when to request more views (front, side, full-body) and confirm accepted stylization level.### 5.6 Character feature gates-`scripts/visual_feature_gate.py` + spec `featureReviewTargets`: add critical character features with their own thresholds:+`forge/_shared/feature_acceptance_policy.py` + spec `featureReviewTargets`: add critical character features with their own thresholds:- anatomy-proportion (head-unit ratios, limb lengths)- face-landmark-placement (eye line, feature spacing)- pose-silhouette (limb angles, stance)@@ -197,7 +197,7 @@ The single largest likeness win, per section 13, is to stop hand-sculpting faces1. Parametric template fit (the industry standard for likeness):- Ship a lightweight, code-generated parametric humanoid template (head-unit-parameterized body plus a morphable face), conceptually mirroring SMPL-X (body + face + hands, jaw and eye joints) and FLAME (face-from-scans). This is still procedural: the template is generated by code and driven by parameters, not a downloaded art pack.- - Fit template parameters (shape, pose, expression) to the 2D landmarks and proportions extracted from the image, following the SMPLify-X idea: minimize the reprojection error between template landmarks and observed image landmarks. Landmarks come from `extract_reference_landmarks.py` (agent-vision assisted).+ - Fit template parameters (shape, pose, expression) to the 2D landmarks and proportions extracted from the image, following the SMPLify-X idea: minimize the reprojection error between template landmarks and observed image landmarks. Landmarks come from `stage1_intake/extract_landmarks.py` (agent-vision assisted).- Rationale: proportions + landmark alignment are where "looks like the person" lives; freehand primitives cannot hit this reliably.2. Photo texture projection (biggest single-image likeness gain):@@ -238,39 +238,39 @@ State plainly in outputs: a single image cannot yield a guaranteed 100 percent l## 6. Cross-cutting: feedback loop upgrades-- `make_visual_comparison_sheet.py`: optional overlay mode (landmark lines for characters; region boxes for detail review).+- `stage4_review/make_comparison_sheet.py`: optional overlay mode (landmark lines for characters; region boxes for detail review).- Reviews record per-detail and per-landmark scores, not only the five existing layer scores.- Keep one packaged sheet per review to preserve token efficiency.## 7. File-by-file change summaryNew files:-- `references/detail-inventory.md`-- `references/character-reconstruction.md`-- `references/likeness-maximization.md` (projection-first pipeline: template fit, photo projection, de-lighting, camera match, turnaround)-- `scripts/build_detail_inventory.py`-- `scripts/extract_reference_landmarks.py`-- `scripts/solve_reference_camera.py` (estimate focal/FOV/orientation; emit `referenceCamera` block)-- `scripts/bake_projected_texture.py` (project the de-lit reference onto the fitted mesh view and bake to UV; stdlib PNG)-- `scripts/delight_reference.py` (recover neutral albedo from the photo before projection)+- `grimoire/intake/detail_inventory.md`+- `grimoire/character/reconstruction.md`+- `grimoire/character/likeness_maximization.md` (projection-first pipeline: template fit, photo projection, de-lighting, camera match, turnaround)+- `forge/stage1_intake/build_detail_inventory.py`+- `forge/stage1_intake/extract_landmarks.py`+- `forge/stage1_intake/solve_camera_pose.py` (estimate focal/FOV/orientation; emit `referenceCamera` block)+- `forge/stage3_build/bake_projected_texture.py` (project the de-lit reference onto the fitted mesh view and bake to UV; stdlib PNG)+- `forge/stage1_intake/delight_albedo.py` (recover neutral albedo from the photo before projection)- a code-generated parametric humanoid/face template module (head-unit body + morphable face), inline in the generator or as `assets/humanoid_template` data- demo assets for one detailed object close-up and one high-likeness character (projection-based)Modified files:-- `references/pre-spec-assessment.md` (detail inventory + domain + anatomy)-- `references/procedural-patterns.md` (character recipes + detail recipes)-- `references/validation-rubric.md` (character suitability branch)-- `references/material-lighting-realism.md` (skin/hair/cloth notes)-- `references/browser-screenshot-feedback.md` (detail close-up + landmark overlay review)-- `references/self-correction-loop.md` (character sub-pass guidance)-- `scripts/new_pre_spec_assessment.py`-- `scripts/new_sculpt_spec.py`-- `scripts/validate_sculpt_spec.py`-- `scripts/generate_threejs_factory.py`-- `scripts/visual_feature_gate.py`-- `scripts/sculpt_pass_orchestrator.py` (register proportion-lock / feature-placement passes for character domain)-- `scripts/probe_reference_image.py` (hint detail-scan when complexity high)-- `scripts/tests/test_pipeline.py` (new coverage)+- `grimoire/intake/quality_contract.md` (detail inventory + domain + anatomy)+- `grimoire/build/geometry_patterns.md` (character recipes + detail recipes)+- `grimoire/intake/validation_rubric.md` (character suitability branch)+- `grimoire/feedback/shading_realism.md` (skin/hair/cloth notes)+- `grimoire/feedback/render_capture.md` (detail close-up + landmark overlay review)+- `grimoire/review/self_correction.md` (character sub-pass guidance)+- `forge/stage2_spec/new_pre_spec_assessment.py`+- `forge/stage2_spec/new_sculpt_spec.py`+- `forge/stage2_spec/validate_sculpt_spec.py`+- `forge/stage3_build/generate_threejs_factory.py`+- `forge/_shared/feature_acceptance_policy.py`+- `forge/stage3_build/orchestrate_passes.py` (register proportion-lock / feature-placement passes for character domain)+- `forge/stage1_intake/probe_image.py` (hint detail-scan when complexity high)+- `forge/tests/test_pipeline.py` (new coverage)- `SKILL.md`, `README.md` (document both tracks, bump version)## 8. Phased roadmap@@ -282,13 +282,13 @@ Modified files:| P3 | 1.2.0 | character reference + rubric branch + domain/anatomy in assessment | human image -> character-stylized + anatomy block || P4 | 1.2.0 | character spec template + landmark script + humanoid generator | test character at correct head-units + pose + landmarks || P5 | 1.2.0 | character feature gates + proportion-lock/feature-placement passes | face/proportion/pose scored; one case passes stylized bar |-| P6 | 1.3.0 | likeness-max: `solve_reference_camera.py` + `delight_reference.py` + `bake_projected_texture.py` + parametric template fit | render camera-matches the photo; de-lit reference projected onto the fitted mesh; front-face likeness visibly higher than stylized baseline |+| P6 | 1.3.0 | likeness-max: `stage1_intake/solve_camera_pose.py` + `stage1_intake/delight_albedo.py` + `stage3_build/bake_projected_texture.py` + parametric template fit | render camera-matches the photo; de-lit reference projected onto the fitted mesh; front-face likeness visibly higher than stylized baseline || P7 | 1.3.0 | optional `generativeAssist` mode (flagged, non-default) + confidence reporting for unseen regions | import-and-refine path works end-to-end and is clearly labelled non-procedural || P8 | 1.3.0 | docs + demos + version bump | SKILL.md/README updated, high-likeness character demo, no emoji |## 9. Testing strategy-- Extend `scripts/tests/test_pipeline.py`: detail-inventory validation (pass/fail cases), domain detection, anatomy validation, character feature-gate thresholds, backward-compat (a 1.0 object spec still validates).+- Extend `forge/tests/test_pipeline.py`: detail-inventory validation (pass/fail cases), domain detection, anatomy validation, character feature-gate thresholds, backward-compat (a 1.0 object spec still validates).- End-to-end smoke: rebuild the loot-chest with the detail gate on; reconstruct one stylized character end-to-end.## 10. Backward compatibilitydiff --git a/scripts/visual_feature_gate.py b/forge/_shared/feature_acceptance_policy.pysimilarity index 100%rename from scripts/visual_feature_gate.pyrename to forge/_shared/feature_acceptance_policy.pydiff --git a/scripts/requirements.txt b/forge/requirements.txtsimilarity index 100%rename from scripts/requirements.txtrename to forge/requirements.txtdiff --git a/scripts/build_detail_inventory.py b/forge/stage1_intake/build_detail_inventory.pysimilarity index 99%rename from scripts/build_detail_inventory.pyrename to forge/stage1_intake/build_detail_inventory.pyindex 02ca54b..b2cb01b 100644--- a/scripts/build_detail_inventory.py+++ b/forge/stage1_intake/build_detail_inventory.py@@ -4,7 +4,7 @@Scans the reference zone by zone (a uniform grid, or named component regions) so smallidentity-defining marks are not missed by a single glance at the whole image. Writes onecrop PNG per zone plus a detailInventory skeleton JSON (see docs/UPGRADE_PLAN.md 4.1 and-references/detail-inventory.md) with one detail stub per zone for the agent to classify,+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 andcrops; it does not judge what is in them."""diff --git a/scripts/delight_reference.py b/forge/stage1_intake/delight_albedo.pysimilarity index 100%rename from scripts/delight_reference.pyrename to forge/stage1_intake/delight_albedo.pydiff --git a/scripts/extract_reference_landmarks.py b/forge/stage1_intake/extract_landmarks.pysimilarity index 99%rename from scripts/extract_reference_landmarks.pyrename to forge/stage1_intake/extract_landmarks.pyindex 50cea8e..c6def80 100644--- a/scripts/extract_reference_landmarks.py+++ b/forge/stage1_intake/extract_landmarks.py@@ -3,7 +3,7 @@Draws head-unit ticks, a rule-of-thirds grid, a center symmetry axis, default face-lineguides (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 references/character-reconstruction.md),+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 visionsupplies the actual proportions, pose, and landmark coordinates.diff --git a/scripts/extract_reference_pbr.py b/forge/stage1_intake/extract_pbr_evidence.pysimilarity index 99%rename from scripts/extract_reference_pbr.pyrename to forge/stage1_intake/extract_pbr_evidence.pyindex f97fbad..c4e41ee 100755--- a/scripts/extract_reference_pbr.py+++ b/forge/stage1_intake/extract_pbr_evidence.py@@ -615,7 +615,7 @@ def material_patch("referencePbr": {"version": "1.0","sourceImage": str(image.resolve()),- "extractor": "extract_reference_pbr.py",+ "extractor": "stage1_intake/extract_pbr_evidence.py","method": "single-image pixel evidence with de-lighting estimate; not photogrammetry","usable": usable,"verdict": verdict,diff --git a/scripts/probe_reference_image.py b/forge/stage1_intake/probe_image.pysimilarity index 100%rename from scripts/probe_reference_image.pyrename to forge/stage1_intake/probe_image.pydiff --git a/scripts/solve_reference_camera.py b/forge/stage1_intake/solve_camera_pose.pysimilarity index 99%rename from scripts/solve_reference_camera.pyrename to forge/stage1_intake/solve_camera_pose.pyindex 6d49df8..5b6cc11 100755--- a/scripts/solve_reference_camera.py+++ b/forge/stage1_intake/solve_camera_pose.py@@ -125,7 +125,7 @@ def build_camera(image: Path, args: argparse.Namespace) -> dict[str, Any]:camera: dict[str, Any] = {"version": "1.0","sourceImage": str(image),- "solver": "solve_reference_camera.py",+ "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"diff --git a/scripts/new_pre_spec_assessment.py b/forge/stage2_spec/new_pre_spec_assessment.pysimilarity index 100%rename from scripts/new_pre_spec_assessment.pyrename to forge/stage2_spec/new_pre_spec_assessment.pydiff --git a/scripts/new_sculpt_spec.py b/forge/stage2_spec/new_sculpt_spec.pysimilarity index 99%rename from scripts/new_sculpt_spec.pyrename to forge/stage2_spec/new_sculpt_spec.pyindex 0d5a783..a9aa19c 100755--- a/scripts/new_sculpt_spec.py+++ b/forge/stage2_spec/new_sculpt_spec.py@@ -65,7 +65,7 @@ def make_pre_spec_assessment(target_name: str) -> dict:"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 scripts/build_detail_inventory.py to scan zones."+ "never prose only. Use forge/stage1_intake/build_detail_inventory.py to scan zones."),"details": [],},@@ -91,8 +91,8 @@ def make_pre_spec_assessment(target_name: str) -> dict:"confidence": 0.0,"note": ("Only meaningful when objectClass.primaryDomain is character or hybrid. "- "Set applies=true and fill from scripts/extract_reference_landmarks.py. "- "See references/character-reconstruction.md and references/likeness-maximization.md."+ "Set applies=true and fill from forge/stage1_intake/extract_landmarks.py. "+ "See grimoire/character/reconstruction.md and grimoire/character/likeness_maximization.md."),},}@@ -470,7 +470,7 @@ def make_spec(target_name: str, image: str | None, assessment_payload: dict | No"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 (scripts/solve_reference_camera.py) so the "+ "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."),},@@ -659,7 +659,7 @@ def make_spec(target_name: str, image: str | None, assessment_payload: dict | No"requiredWhenSourceImagePresent": True,"targetThreshold": 0.7,"stopOnLowConfidence": True,- "script": "scripts/extract_reference_pbr.py",+ "script": "forge/stage1_intake/extract_pbr_evidence.py","acceptedLimitation": "single-image extraction is reference-derived inference, not exact photogrammetry",},"mustAvoid": [@@ -1092,7 +1092,7 @@ 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 new_pre_spec_assessment.py")+ 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",diff --git a/scripts/validate_sculpt_spec.py b/forge/stage2_spec/validate_sculpt_spec.pysimilarity index 99%rename from scripts/validate_sculpt_spec.pyrename to forge/stage2_spec/validate_sculpt_spec.pyindex bea32ff..85a2ce5 100755--- a/scripts/validate_sculpt_spec.py+++ b/forge/stage2_spec/validate_sculpt_spec.py@@ -10,7 +10,8 @@ import sysfrom pathlib import Pathfrom typing import Any-from visual_feature_gate import feature_gate_failures, feature_review_policy+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_shared"))+from feature_acceptance_policy import feature_gate_failures, feature_review_policyREQUIRED_TOP_LEVEL = {@@ -1296,7 +1297,7 @@ def validate_sculpt_pipeline(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 sculpt_pass_orchestrator.py sync")+ 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}")diff --git a/scripts/bake_projected_texture.py b/forge/stage3_build/bake_projected_texture.pysimilarity index 97%rename from scripts/bake_projected_texture.pyrename to forge/stage3_build/bake_projected_texture.pyindex ecabcef..2b56e5e 100755--- a/scripts/bake_projected_texture.py+++ b/forge/stage3_build/bake_projected_texture.py@@ -86,7 +86,7 @@ def build_descriptor(args: argparse.Namespace) -> dict[str, Any]:return {"projectedTextureBake": {"version": "1.0",- "generator": "bake_projected_texture.py",+ "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,@@ -123,8 +123,8 @@ def build_descriptor(args: argparse.Namespace) -> dict[str, Any]: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 delight_reference.py, if available")- parser.add_argument("--camera", help="Path to a referenceCamera JSON produced by solve_reference_camera.py")+ 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",diff --git a/scripts/generate_threejs_factory.py b/forge/stage3_build/generate_threejs_factory.pysimilarity index 99%rename from scripts/generate_threejs_factory.pyrename to forge/stage3_build/generate_threejs_factory.pyindex 2ac9298..7eef01f 100755--- a/scripts/generate_threejs_factory.py+++ b/forge/stage3_build/generate_threejs_factory.py@@ -10,7 +10,7 @@ import sysfrom pathlib import Pathfrom typing import Any-from sculpt_pass_orchestrator import pass_specific_gaps+from orchestrate_passes import pass_specific_gapsVALID_PRIMITIVES = {@@ -112,7 +112,7 @@ def assert_pass_unlocked(spec: dict[str, Any], requested_pass: str) -> None:previous = ids[previous_index] if previous_index >= 0 else ""raise ValueError(f"build pass {requested_pass!r} is locked; complete {previous!r} first with "- "append_sculpt_review.py action=continue and browser screenshot evidence"+ "stage4_review/append_review.py action=continue and browser screenshot evidence")diff --git a/scripts/sculpt_pass_orchestrator.py b/forge/stage3_build/orchestrate_passes.pysimilarity index 99%rename from scripts/sculpt_pass_orchestrator.pyrename to forge/stage3_build/orchestrate_passes.pyindex 8f5298c..7b0e842 100755--- a/scripts/sculpt_pass_orchestrator.py+++ b/forge/stage3_build/orchestrate_passes.py@@ -10,7 +10,8 @@ import sysfrom pathlib import Pathfrom typing import Any-from visual_feature_gate import feature_gate_failures+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_shared"))+from feature_acceptance_policy import feature_gate_failuresDEFAULT_PASS_ORDER = [diff --git a/scripts/append_sculpt_review.py b/forge/stage4_review/append_review.pysimilarity index 98%rename from scripts/append_sculpt_review.pyrename to forge/stage4_review/append_review.pyindex 0365e6f..c011c7f 100755--- a/scripts/append_sculpt_review.py+++ b/forge/stage4_review/append_review.py@@ -9,7 +9,8 @@ import sysfrom datetime import datetime, timezonefrom pathlib import Path-from visual_feature_gate import feature_gate_failures+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "_shared"))+from feature_acceptance_policy import feature_gate_failuresVALID_ACTIONS = {"continue", "refine-spec", "refine-code", "request-input", "stop"}@@ -278,7 +279,7 @@ def main(argv: list[str]) -> int:if not args.comparison_image:raise ValueError("visual pass cannot use action=continue without --comparison-image; "- "create one with make_visual_comparison_sheet.py"+ "create one with stage4_review/make_comparison_sheet.py")if args.ai_vision_score is None:raise ValueError(diff --git a/scripts/make_visual_comparison_sheet.py b/forge/stage4_review/make_comparison_sheet.pysimilarity index 99%rename from scripts/make_visual_comparison_sheet.pyrename to forge/stage4_review/make_comparison_sheet.pyindex 5bee134..5843d98 100755--- a/scripts/make_visual_comparison_sheet.py+++ b/forge/stage4_review/make_comparison_sheet.py@@ -3,7 +3,7 @@The sheet is only evidence packaging. It does not score the images. the agent oranother AI vision reviewer should inspect the generated sheet and write the-score back with append_sculpt_review.py.+score back with stage4_review/append_review.py."""from __future__ import annotationsdiff --git a/scripts/tests/test_pipeline.py b/forge/tests/test_pipeline.pysimilarity index 76%rename from scripts/tests/test_pipeline.pyrename to forge/tests/test_pipeline.pyindex daad3df..474b0a1 100644--- a/scripts/tests/test_pipeline.py+++ b/forge/tests/test_pipeline.py@@ -5,8 +5,8 @@ Pure stdlib. Runs each CLI script as a subprocess and asserts the gate behaviordescribed 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 scripts/tests/test_pipeline.py (from skill root)- or: python3 -m unittest discover -s scripts/tests+Run: python3 forge/tests/test_pipeline.py (from skill root)+ or: python3 -m unittest discover -s forge/tests"""import jsonimport struct@@ -18,7 +18,7 @@ import zlibfrom pathlib import PathSKILL = Path(__file__).resolve().parents[2]-SCRIPTS = SKILL / "scripts"+SCRIPTS = SKILL / "forge"def run(script, *args):@@ -59,18 +59,18 @@ class PipelineTest(unittest.TestCase):write_png(self.render)def test_probe_image(self):- r = run("probe_reference_image.py", self.ref)+ r = run("stage1_intake/probe_image.py", self.ref)self.assertEqual(r.returncode, 0, r.stderr)self.assertIn("64", r.stdout) # reports dimensionsdef test_assessment_and_spec(self):- r = run("new_pre_spec_assessment.py", "Oak", "--complexity", "complex",+ 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("new_sculpt_spec.py", "Oak", "--assessment", self.assessment,+ 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())@@ -78,51 +78,51 @@ class PipelineTest(unittest.TestCase):self.assertEqual(spec["targetName"], "Oak")def test_normal_validate_passes_strict_fails_on_shallow(self):- run("new_pre_spec_assessment.py", "Oak", "--complexity", "complex",+ run("stage2_spec/new_pre_spec_assessment.py", "Oak", "--complexity", "complex","--out", self.assessment)- run("new_sculpt_spec.py", "Oak", "--assessment", 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("validate_sculpt_spec.py", self.spec).returncode, 0)+ self.assertEqual(run("stage2_spec/validate_sculpt_spec.py", self.spec).returncode, 0)# strict quality gate must BLOCK a shallow starter spec- strict = run("validate_sculpt_spec.py", self.spec, "--strict-quality")+ 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("new_sculpt_spec.py", "Oak", "--out", self.spec)- r = run("sculpt_pass_orchestrator.py", "status", self.spec)+ 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("sculpt_pass_orchestrator.py", "check", self.spec,+ 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("new_sculpt_spec.py", "Oak", "--out", self.spec)+ run("stage2_spec/new_sculpt_spec.py", "Oak", "--out", self.spec)out = self.dir / "createObjectModel.ts"- r = run("generate_threejs_factory.py", self.spec, "--out", out)+ 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("generate_threejs_factory.py", self.spec, "--out", out,+ 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("make_visual_comparison_sheet.py", "--reference", self.ref,+ 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("new_sculpt_spec.py", "Oak", "--out", self.spec)+ 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("append_sculpt_review.py", self.spec, "--pass-id", "blockout",+ 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")@@ -130,7 +130,7 @@ class PipelineTest(unittest.TestCase):self.assertIn("render-screenshot", no_evidence.stdout + no_evidence.stderr)# WITH evidence: the review is recorded.cmp = self.dir / "cmp.png"- run("make_visual_comparison_sheet.py", "--reference", self.ref,+ run("stage4_review/make_comparison_sheet.py", "--reference", self.ref,"--render", self.render, "--out", cmp)layers = json.dumps({"silhouetteProportion": 0.82, "componentStructure": 0.78,@@ -145,7 +145,7 @@ class PipelineTest(unittest.TestCase):] or [{"id": "overall-silhouette", "score": 0.8, "visible": True, "notes": "ok"}]freviews = self.dir / "features.json"freviews.write_text(json.dumps(reviews))- r = run("append_sculpt_review.py", self.spec, "--pass-id", "blockout",+ 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,@@ -159,7 +159,7 @@ class PipelineTest(unittest.TestCase):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("extract_reference_pbr.py", self.ref, "--out-dir", self.dir / "pbr",+ 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)@@ -168,9 +168,9 @@ class PipelineTest(unittest.TestCase):# ---- Track A / Track B upgrade coverage ----def _fresh_spec(self, complexity="moderate"):- run("new_pre_spec_assessment.py", "Widget", "--complexity", complexity,+ run("stage2_spec/new_pre_spec_assessment.py", "Widget", "--complexity", complexity,"--out", self.assessment)- run("new_sculpt_spec.py", "Widget", "--assessment", self.assessment,+ run("stage2_spec/new_sculpt_spec.py", "Widget", "--assessment", self.assessment,"--out", self.spec)return json.loads(self.spec.read_text())@@ -186,7 +186,7 @@ class PipelineTest(unittest.TestCase):def test_detail_inventory_gate_fires_on_empty(self):self._fresh_spec("moderate")- strict = run("validate_sculpt_spec.py", self.spec, "--strict-quality")+ 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)@@ -195,33 +195,33 @@ class PipelineTest(unittest.TestCase):spec = self._fresh_spec("moderate")spec["preSpecAssessment"].pop("detailInventory", None)self.spec.write_text(json.dumps(spec))- strict = run("validate_sculpt_spec.py", self.spec, "--strict-quality")+ 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("validate_sculpt_spec.py", self.spec, "--strict-quality")+ 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("validate_sculpt_spec.py", self.spec, "--strict-quality")+ 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 ("build_detail_inventory.py", "extract_reference_landmarks.py",- "solve_reference_camera.py", "delight_reference.py",- "bake_projected_texture.py"):+ 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("build_detail_inventory.py", self.ref, "--mode", "grid-3x3",+ 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())@@ -230,14 +230,14 @@ class PipelineTest(unittest.TestCase):def test_delight_reference_writes_png(self):out = self.dir / "albedo.png"- r = run("delight_reference.py", self.ref, "--out", out)+ 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("new_sculpt_spec.py", "Person", "--character", "--out", self.spec)+ 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"):@@ -255,18 +255,18 @@ class PipelineTest(unittest.TestCase):self.assertGreaterEqual(len(m.get("colorVariation", {}).get("palette", [])), 2)def test_character_autodetect_from_domain(self):- run("new_pre_spec_assessment.py", "Person", "--complexity", "complex", "--out", self.assessment)+ 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("new_sculpt_spec.py", "Person", "--assessment", self.assessment, "--out", self.spec)+ 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("new_sculpt_spec.py", "Person", "--character", "--out", self.spec)+ run("stage2_spec/new_sculpt_spec.py", "Person", "--character", "--out", self.spec)out = self.dir / "createCharacterModel.ts"- r = run("generate_threejs_factory.py", self.spec, "--out", out)+ 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)diff --git a/references/procedural-patterns.md b/grimoire/build/geometry_patterns.mdsimilarity index 97%rename from references/procedural-patterns.mdrename to grimoire/build/geometry_patterns.mdindex 2a453a8..5f11ed7 100644--- a/references/procedural-patterns.md+++ b/grimoire/build/geometry_patterns.md@@ -62,7 +62,7 @@ Each feature should include placement, approximate size, orientation, material e## Detail RecipesConcrete Three.js material/geometry approach per `detailInventory` kind. Cross-reference-`references/detail-inventory.md` for the full taxonomy and the evidence/mapping rule.+`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 thehotspot region; use `clearcoat`/`clearcoatRoughness` for a lacquer layer over a rougher@@ -83,7 +83,7 @@ Concrete Three.js material/geometry approach per `detailInventory` kind. Cross-r## Character Geometry And Material RecipesUse these when `objectClass.primaryDomain` is `character` or `hybrid`. Pair with-`references/character-reconstruction.md` for proportion/landmark data.+`grimoire/character/reconstruction.md` for proportion/landmark data.- head: sphere or ellipsoid scaled to the measured head-unit, then displaced/tapered towardthe reference face shape (jaw width, chin point, cheek fullness) rather than left spherical.diff --git a/references/likeness-maximization.md b/grimoire/character/likeness_maximization.mdsimilarity index 86%rename from references/likeness-maximization.mdrename to grimoire/character/likeness_maximization.mdindex d5e2a5f..271080b 100644--- a/references/likeness-maximization.md+++ b/grimoire/character/likeness_maximization.md@@ -1,6 +1,6 @@# 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.+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.@@ -14,11 +14,11 @@ Hand-authored primitives (capsules, spheres, blend shapes tuned by eye) can apprShip 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 `extract_reference_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.+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 (`scripts/solve_reference_camera.py`, emits a `referenceCamera` spec block). The render camera must match this so:+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@@ -27,11 +27,11 @@ Without a matched camera, projected texture will misalign the moment the model i### (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 (`scripts/delight_reference.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.+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 (`scripts/bake_projected_texture.py`, stdlib PNG) for the visible (front) side.+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@@ -49,7 +49,7 @@ Emit a `SkinnedMesh` with a joint skeleton for the body plus morph targets/blend## 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.+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 Notediff --git a/references/character-reconstruction.md b/grimoire/character/reconstruction.mdsimilarity index 91%rename from references/character-reconstruction.mdrename to grimoire/character/reconstruction.mdindex c6be73a..335c3d6 100644--- a/references/character-reconstruction.md+++ b/grimoire/character/reconstruction.md@@ -31,7 +31,7 @@ Store landmarks as normalized coordinates (0-1) relative to head bounding box, n- `mouthLine`: ~0.75-0.85- `earTop` / `earBottom`: roughly bracket `eyeLine` to `noseBase`-Pull these from the actual image via `scripts/extract_reference_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.+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@@ -51,7 +51,7 @@ If a joint is occluded, do not invent an angle — mark `confidence` low and def## Character Materials (stylized default)-Reuse Track A detail machinery (`references/detail-inventory.md`) for accessories and trims. Base recipes:+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.diff --git a/references/browser-screenshot-feedback.md b/grimoire/feedback/render_capture.mdsimilarity index 99%rename from references/browser-screenshot-feedback.mdrename to grimoire/feedback/render_capture.mdindex a99d8b8..159c254 100644--- a/references/browser-screenshot-feedback.md+++ b/grimoire/feedback/render_capture.md@@ -9,7 +9,7 @@ Each visual build pass should produce at least one rendered screenshot from a naCreate a side-by-side review image after capture:```bash-../../scripts/make_visual_comparison_sheet.py \+../../forge/stage4_review/make_comparison_sheet.py \--reference reference.png \--render render.png \--out comparison.png \diff --git a/references/material-lighting-realism.md b/grimoire/feedback/shading_realism.mdsimilarity index 94%rename from references/material-lighting-realism.mdrename to grimoire/feedback/shading_realism.mdindex 198e03d..9703544 100644--- a/references/material-lighting-realism.md+++ b/grimoire/feedback/shading_realism.md@@ -25,7 +25,7 @@ Before implementing or accepting `material-pass`, the spec must contain:- 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 `../../scripts/extract_reference_pbr.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.+- 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.diff --git a/references/3d-graphics-terminology.md b/grimoire/glossary/3d_vocabulary.mdsimilarity index 100%rename from references/3d-graphics-terminology.mdrename to grimoire/glossary/3d_vocabulary.mddiff --git a/references/detail-inventory.md b/grimoire/intake/detail_inventory.mdsimilarity index 100%rename from references/detail-inventory.mdrename to grimoire/intake/detail_inventory.mddiff --git a/references/pre-spec-assessment.md b/grimoire/intake/quality_contract.mdsimilarity index 95%rename from references/pre-spec-assessment.mdrename to grimoire/intake/quality_contract.mdindex 1a6378d..22e9951 100644--- a/references/pre-spec-assessment.md+++ b/grimoire/intake/quality_contract.md@@ -56,7 +56,7 @@ Good feature groups are specific to the image:## Strict Quality Gate-Run `../../scripts/validate_sculpt_spec.py spec.json --strict-quality` before code generation. The script path is relative to the skill folder.+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:diff --git a/references/validation-rubric.md b/grimoire/intake/validation_rubric.mdsimilarity index 86%rename from references/validation-rubric.mdrename to grimoire/intake/validation_rubric.mdindex d8649b5..64292a1 100644--- a/references/validation-rubric.md+++ b/grimoire/intake/validation_rubric.md@@ -29,10 +29,10 @@ Use this reference when the suitability decision is unclear.## 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 `references/character-reconstruction.md` (proportions, landmarks, pose, stylized materials) by default.+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 `references/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.+- **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:diff --git a/references/action-ready-models.md b/grimoire/readiness/action_rigging.mdsimilarity index 100%rename from references/action-ready-models.mdrename to grimoire/readiness/action_rigging.mddiff --git a/references/attachment-joint-correctness.md b/grimoire/readiness/joint_attachment.mdsimilarity index 100%rename from references/attachment-joint-correctness.mdrename to grimoire/readiness/joint_attachment.mddiff --git a/references/self-correction-loop.md b/grimoire/review/self_correction.mdsimilarity index 96%rename from references/self-correction-loop.mdrename to grimoire/review/self_correction.mdindex 412cc4a..e2f19d1 100644--- a/references/self-correction-loop.md+++ b/grimoire/review/self_correction.md@@ -6,7 +6,7 @@ Use this reference when a model construction pass has just finished.1. Capture or collect a rendered screenshot for the current browser view.2. Select at most five critical semantic systems for the current pass and only the suspicious important systems.-3. Create one full reference/render comparison sheet with `make_visual_comparison_sheet.py`.+3. Create one full reference/render comparison sheet with `stage4_review/make_comparison_sheet.py`.4. Inspect the sheet once with your agent's vision and score the global image, relevant visual layers, and each selected semantic feature visible in that pair.5. Compare the rendered result to current `ObjectSculptSpec`.6. Decide whether the mismatch is caused by the spec, the implementation, lighting/camera, missing evidence, or performance tradeoff.diff --git a/references/scripts.md b/grimoire/scripts.mdsimilarity index 65%rename from references/scripts.mdrename to grimoire/scripts.mdindex ba87ab6..745415c 100644--- a/references/scripts.md+++ b/grimoire/scripts.md@@ -2,34 +2,34 @@All scripts are pure Python 3.10+ **standard library** — no pip install, no PIL/numpy, noPlaywright/Chromium. PNG read/write is done via `struct`/`zlib`. Run from the skill root so-paths resolve as `scripts/<name>.py`. Non-zero exit = a gate failed; read the printed reasons.+paths resolve as `forge/<name>.py`. Non-zero exit = a gate failed; read the printed reasons.Division of labor: **scripts enforce structure and package evidence; they never score visuals.**The acceptance score always comes from the agent's own vision inspecting the comparison sheet.-## probe_reference_image.py-`probe_reference_image.py <image>` — image type, dimensions, aspect ratio, obvious technical+## stage1_intake/probe_image.py+`stage1_intake/probe_image.py <image>` — image type, dimensions, aspect ratio, obvious technicalissues. Metadata only; not a substitute for visual inspection.-## new_pre_spec_assessment.py-`new_pre_spec_assessment.py "Name" [--image IMG] [--complexity simple|moderate|complex|ultra-complex] --out assessment.json [--force]`+## stage2_spec/new_pre_spec_assessment.py+`stage2_spec/new_pre_spec_assessment.py "Name" [--image IMG] [--complexity simple|moderate|complex|ultra-complex] --out assessment.json [--force]`Emits a pre-spec assessment + `qualityContract` skeleton. Refine `--complexity` after looking at-the image. See `pre-spec-assessment.md` for the scoring axes and contract checklist.+the image. See `intake/quality_contract.md` for the scoring axes and contract checklist.-## new_sculpt_spec.py-`new_sculpt_spec.py "Name" [--image IMG] [--assessment assessment.json] --out object-sculpt-spec.json [--force]`+## stage2_spec/new_sculpt_spec.py+`stage2_spec/new_sculpt_spec.py "Name" [--image IMG] [--assessment assessment.json] --out object-sculpt-spec.json [--force]`Starter `ObjectSculptSpec` (schema 2.0). With `--assessment` it seeds from the completed gate.Always replace generic starter `featureReviewTargets` with real identity-defining systems.-## validate_sculpt_spec.py-`validate_sculpt_spec.py spec.json [--json] [--strict-quality]`+## stage2_spec/validate_sculpt_spec.py+`stage2_spec/validate_sculpt_spec.py spec.json [--json] [--strict-quality]`Normal: checks required fields, score ranges, material refs, component IDs, parent links,transforms, primitive names (warnings allowed). `--strict-quality`: promotes quality warnings toerrors — blocks code gen when the spec is too shallow for its contract (min macro/meso/microcounts, material layers, repetition systems, review viewpoints, non-generic feature targets,-material-pass locality, lighting-pass real lights). Fix per `pre-spec-assessment.md`.+material-pass locality, lighting-pass real lights). Fix per `intake/quality_contract.md`.-## sculpt_pass_orchestrator.py+## stage3_build/orchestrate_passes.py- `status spec.json` — current unlocked pass + required evidence.- `check spec.json --pass-id <pass>` — non-zero unless that pass is unlocked or already done.- `sync spec.json --in-place` — recompute `sculptPipeline` from `reviewHistory`.@@ -39,27 +39,27 @@ interaction-pass → optimization-pass`. A pass unlocks only after the prior pas`action=continue` backed by a render screenshot, a comparison sheet, a global AI-vision score ≥threshold (default 0.7), and every critical feature ≥ its own threshold.-## generate_threejs_factory.py-`generate_threejs_factory.py spec.json --out src/createObjectModel.ts [--pass-id PASS] [--force]`+## stage3_build/generate_threejs_factory.py+`stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts [--pass-id PASS] [--force]`Emits a TypeScript Three.js `Group` factory for the **current unlocked pass only**. Passing afuture `--pass-id` fails until earlier passes are reviewed `continue`. Output exposes`root.userData.sculptRuntime` (nodes/meshes/sockets/colliders/destructionGroups) — hand-refine it.-## make_visual_comparison_sheet.py-`make_visual_comparison_sheet.py --reference IMG --render SHOT --out cmp.png [--panel-width N] [--panel-height N] [--gutter N] [--json]`+## stage4_review/make_comparison_sheet.py+`stage4_review/make_comparison_sheet.py --reference IMG --render SHOT --out cmp.png [--panel-width N] [--panel-height N] [--gutter N] [--json]`Aligns + packages one side-by-side sheet. It does **not** compute an acceptance score — inspect-`cmp.png` with agent vision and write the score back via `append_sculpt_review.py`.+`cmp.png` with agent vision and write the score back via `stage4_review/append_review.py`.-## append_sculpt_review.py-`append_sculpt_review.py spec.json --pass-id PASS --fidelity 0-1 --action continue|refine-spec|refine-code|request-input|stop --summary "..." [evidence flags] --in-place`+## stage4_review/append_review.py+`stage4_review/append_review.py spec.json --pass-id PASS --fidelity 0-1 --action continue|refine-spec|refine-code|request-input|stop --summary "..." [evidence flags] --in-place`Evidence flags: `--matched --mismatches --spec-fixes --code-fixes --evidence --reference-screenshot--render-screenshot --comparison-image --ai-vision-score 0-1 --layer-scores-json '{...}'--feature-reviews-json f.json --ai-vision-notes "..." --visual-threshold 0-1 --camera-view NAME--require-screenshot-files`. Layer keys: `silhouetteProportion, componentStructure, formDetail,materialSurface, lightingCamera`. Records one self-correction entry into `reviewHistory`.-## extract_reference_pbr.py-`extract_reference_pbr.py <crop> --out-dir DIR --material-id ID [--target-threshold 0.7] [--size N]+## stage1_intake/extract_pbr_evidence.py+`stage1_intake/extract_pbr_evidence.py <crop> --out-dir DIR --material-id ID [--target-threshold 0.7] [--size N][--palette-size N] [--spec spec.json --in-place | --out-spec p.json] [--report r.json][--allow-low-confidence] [--multi-view-reference]`Extracts reference-derived evidence: albedo palette, de-lit albedo, roughness estimate, height,@@ -67,6 +67,6 @@ normal, AO. **Inference, not inverse rendering** — pixels include baked lightiand refuses to patch the spec when confidence < `--target-threshold` (default 0.7) unless`--allow-low-confidence`. Treat sub-threshold as `request-input`/`refine-spec`, not a pass.-## visual_feature_gate.py+## _shared/feature_acceptance_policy.pyInternal helper imported by the orchestrator/validator (`feature_gate_failures`,`feature_review_policy`). Enforces the ≤5 critical / ≤3 important feature-tier policy. Not a CLI.