CONTRIBUTING.md

# Contributing to img2threejs

Thanks for your interest. img2threejs turns a reference image into a code-only, procedural,
quality-gated Three.js model. Contributions that keep that identity sharp are very welcome.

## Good first areas

- 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 `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

- Strong: hard-surface objects, props, stylized/low-poly assets.
- Stylized-only: characters and creatures read as game/figurine avatars, not photoreal likeness.
- Out of scope today: photoreal reconstruction of a specific person, animal, or landscape from a
  single image. That needs photo-texture projection or ML image-to-3D, which breaks the code-only
  promise. See `docs/UPGRADE_PLAN.md` for the analysis and the tiered roadmap.

Please do not add code that silently downloads meshes or art packs — the core promise is
reconstruction by code. If you want a projection or generative-assist path, propose it as an
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 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.

## Pull requests

- Keep PRs focused and describe the behavior change plus how you verified it.
- Add or update tests for new gates, schema fields, or templates.
- Update `docs/UPGRADE_PLAN.md` status when you land a roadmap item.

## Reporting issues

Include the reference image characteristics, the command you ran, the spec or generated output,
and what you expected versus what you got. Screenshots of the render help a lot.