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
docs: clarify base skill and plugin quickstart
hoainhod508b596cb22
diff --git a/README.md b/README.mdindex 556ada6..fe2416b 100644--- a/README.md+++ b/README.md@@ -110,97 +110,198 @@ A staged sculpting pipeline turns the reference image into a spec, then generate## Quick start-1. **Install** — place this folder in your skills directory:-- ```bash- git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs- ```-- If you use more than one host, keep a single checkout and point each entrypoint at it as a- symlink, so they cannot drift apart:-- ```text- ~/.claude/skills/img2threejs -> <your checkout>- ~/.codex/skills/img2threejs -> <your checkout>- ```-- **CLI installer (Node.js >= 18 and Git):** available as- [`img2threejs` on npm](https://www.npmjs.com/package/img2threejs):-- ```bash- npx img2threejs install --dry-run- npx img2threejs install # all detected hosts- npx img2threejs install --host claude # only this host- npx img2threejs update --ref v2.0.0- npx img2threejs doctor- ```-- Or install the CLI globally, then install the skill:-- ```bash- npm install -g img2threejs- img2threejs install- ```-- Supported host directories are `~/.hermes`, `~/.claude`, `~/.codex`, and- `$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`). The CLI fetches the- base skill directly from GitHub at `v2.0.0` by default; `--ref` accepts a- semantic tag (including prereleases) or full 40-character commit SHA, not a branch.- Checkouts live under `~/.img2threejs/releases/<sha>/img2threejs`; hosts installing- the same commit share that checkout. `update` refuses lower skill versions, including- prerelease downgrades. The CLI does not overwrite manual installs or unrelated links.- Move those entries yourself to switch to CLI-managed installs. `--dry-run` is offline- and writes nothing; it does not verify that a remote ref exists or check downgrades.- The base skill is not a plugin: `img2 add` is only for the optional plugins below.-- To test the CLI directly from this checkout, run- `node bin/img2threejs.mjs install --dry-run`. See [CONTRIBUTING.md](CONTRIBUTING.md)- for tarball and publication checks.--2. **Add domain plugins (optional)** — domain knowledge (CS2 skins today) lives in installed- plugins, not in this checkout. Install the [img2 harness](https://github.com/img2threejs/img2)- once, then add plugins to it:-- ```bash- npx github:img2threejs/img2 install # ~/.img2, the plugin registry, and an `img2` launcher- img2 add img2threejs/plugin-cs2 # clone @ newest tag, pin SHA, link host skills- img2 doctor # fail-loud static audit of every installed plugin- ```-- An installed domain plugin contributes its own checklist steps, evidence collection, spec- augmentation (quality floors merge raise-only), and a blocking review gate — and registers its- profile with `forge/state.py init --profile <id>`. With no plugins installed, `generic`,- and `character` are available; a profile whose plugin is missing (`cs2`, `animated-character`) fails- loud naming what is installed, never silently downgrades. `img2 remove <id>` reverses cleanly.-- **Official plugins:**-- | Plugin | Adds | Install |- |---|---|---|- | [plugin-cs2](https://github.com/img2threejs/plugin-cs2) | `cs2` profile — CS2 weapon-skin reconstruction: family adapters, finish rules, domain review gate | `img2 add img2threejs/plugin-cs2` |- | [plugin-character](https://github.com/img2threejs/plugin-character) | `animated-character` profile — everything `character` has plus the Stage R rigging/animation gates | `img2 add img2threejs/plugin-character` |- | [plugin-img2glb](https://github.com/img2threejs/plugin-img2glb) | `image → glb` emission target via the hosted TRELLIS space | `img2 add img2threejs/plugin-img2glb` |- | [plugin-hello-cube](https://github.com/img2threejs/plugin-hello-cube) | minimal reference plugin — copy it to write your own | `img2 add img2threejs/plugin-hello-cube` |-- Writing your own: the harness repo's- [docs/WRITING_A_PLUGIN.md](https://github.com/img2threejs/img2/blob/main/docs/WRITING_A_PLUGIN.md).--3. **Invoke** — in Claude Code, attach or point to an object image and run:-- ```- /img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.- ```-- That is enough: the skill classifies the subject, runs the detail inventory, and gates every pass on its own.--4. **Follow the pipeline** — the skill validates the image, writes an assessment and spec, generates the factory pass by pass, and shows you a side-by-side comparison at each step until the render matches.-- For a multi-session reconstruction, create a local state index first:-- ```bash- python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json- python3 forge/next.py --state .img2threejs/state.json- ```+### Which project and CLI do I need?++| Project | Role | CLI |+|---|---|---|+| **[img2threejs](https://github.com/img2threejs/img2threejs)** — this repository | Base reconstruction skill, procedural Three.js pipeline, scripts and quality gates | `npx --yes img2threejs@latest <command>` |+| **[img2](https://github.com/img2threejs/img2)** | Optional plugin harness: catalog, registry, host links and capability lookup | `npx --yes @img2threejs/img2@latest <command>` |+| **Domain and output plugins** — linked below | Additional workflows, domain rules or explicitly selected output routes | Install through `img2 add <plugin-id>` |++The two CLIs are separate packages with independent versions. Installing the harness does+**not** install this base skill; adding a plugin does **not** generate a model.+Start with the base skill. Add the harness only when you need plugins.++### 1. Install the base skill++The CLI needs **Node.js ≥ 18 and Git**; the reconstruction scripts need **Python ≥ 3.10**.+Configure your agent host first. The base installer detects Hermes, Claude Code, Codex and+OpenCode; the plugin harness currently integrates with Claude Code, Codex and OpenCode.++Preview, install into all detected hosts, then inspect their base-skill links:++```bash+npx --yes img2threejs@latest install --dry-run+npx --yes img2threejs@latest install+npx --yes img2threejs@latest doctor+```++To install into just one detected host instead, use:++```bash+npx --yes img2threejs@latest install --host claude+```++The `--yes` above belongs to **npx**, allowing the CLI package download. It is not an+overwrite flag for the base installer.++Supported host directories are `~/.hermes`, `~/.claude`, `~/.codex`, and+`$XDG_CONFIG_HOME/opencode` (default `~/.config/opencode`). The CLI fetches the base skill+from GitHub at `v2.0.0` by default. Its `--ref` accepts a semantic tag (including prereleases)+or a full 40-character commit SHA, **not a branch**:++```bash+npx --yes img2threejs@latest update --ref v2.0.0+```++Checkouts live under `~/.img2threejs/releases/<sha>/img2threejs`; hosts installing the same+commit share that checkout. `update` refuses lower skill versions, including prerelease+downgrades. The installer refuses manual installs and unrelated links rather than+overwriting them. Keep those installations, or deliberately move their entries yourself+before switching to CLI-managed installs. `--dry-run` is offline and writes nothing; it+does not verify remote ref availability or downgrades.++**Manual alternative — choose this or the CLI, not both at the same skill path:**++```bash+git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs+```++For multiple hosts, keep one checkout and point each host's `img2threejs` skill entry at+it with a symlink so copies cannot drift apart. A manual clone follows the repository's+default branch rather than the CLI's pinned release.++You can also install the CLI globally with `npm install -g img2threejs`, then run+`img2threejs install`. To test it from this checkout, run+`node bin/img2threejs.mjs install --dry-run`; see [CONTRIBUTING.md](CONTRIBUTING.md)+for packaging and publication checks.++### 2. Install the plugin harness, if needed++Use harness CLI **0.4.0 or newer** for short plugin IDs:++```bash+npx --yes @img2threejs/img2@latest install --yes+npx --yes @img2threejs/img2@latest plugins+```++The harness uses `~/.img2` and tries to link an `img2` launcher onto your `PATH`. Read+the install output for its location. `plugins` lists the official live catalog; `list`+shows registrations on your machine.++For short commands that use the latest published harness, set this bash/zsh alias:++```bash+alias img2='npx --yes @img2threejs/img2@latest'+```++It lasts for this shell session. Add it to `~/.zshrc` and run `source ~/.zshrc` to keep+it in future zsh sessions. Every `img2 ...` command below also works with the explicit+`npx --yes @img2threejs/img2@latest ...` prefix. An existing harness checkout and its+older launcher are not automatically upgraded by running `install` again.++The first `--yes` in the harness install command belongs to npx; the final one skips+the harness consent prompt. Neither permits replacing an existing plugin.++### 3. Choose plugins — do not install everything by default++| Plugin / source README | Adds | Access | Install after harness setup |+|---|---|---|---|+| [cs2](https://github.com/img2threejs/plugin-cs2) | `cs2` profile — CS2 weapon/glove skin reconstruction, family adapters, finish rules and blocking domain review gates | Public | `img2 add cs2 --yes` |+| [character](https://github.com/img2threejs/plugin-character) | `animated-character` profile — character workflow plus Stage R rigging/animation gates | Public | `img2 add character --yes` |+| [environment](https://github.com/img2threejs/plugin-environment) | The environment plugin, distributed from a private repository | **Private — authorized Git access required** | `img2 add environment --yes` |+| [img2glb](https://github.com/img2threejs/plugin-img2glb) | Explicit `image → glb` route through the hosted TRELLIS space; generated mesh output, not the default code-only route | Public | `img2 add img2glb --yes` |+| [hello-cube](https://github.com/img2threejs/plugin-hello-cube) | Small deterministic image-to-Three.js cube example and plugin contract exerciser | Public | `img2 add hello-cube --yes` |++These are announced plugins; use `img2 plugins` for the current catalog. Open each+plugin's linked README for its input requirements, dependencies and tool setup.+For CS2 and character workflows:++```bash+img2 add cs2 --yes+img2 add character --yes+img2 list+img2 doctor+img2 sync --check+```++An installed domain plugin contributes its checklist steps, evidence collection, spec+augmentation (quality floors merge raise-only), and blocking review gates. With no plugins+installed, the base has `generic` and `character` profiles. A profile whose plugin is+missing (`cs2`, `animated-character`) fails loud naming what is installed; it never silently+downgrades. The base skill is not a plugin: **do not use `img2 add` to install this repository.**++**Private environment source:** GitHub access and working Git credentials are required.+The link may return 404 when you are signed out or lack permission. The public+[`img2-environment` npm installer](https://www.npmjs.com/package/img2-environment) can+bootstrap the harness, but does not grant access to the private source:++```bash+npx --yes img2-environment install --dry-run+npx --yes img2-environment install --yes+```++That installer has its own SDK pin and may retain older CLI presentation.+For lifecycle and trust details, read the [harness usage guide](https://github.com/img2threejs/img2#quickstart).+To write a plugin, follow [WRITING_A_PLUGIN.md](https://github.com/img2threejs/img2/blob/main/docs/WRITING_A_PLUGIN.md).++### 4. Run a reconstruction in your agent++Start a new agent session or restart the current one after installing skills.+In Claude Code, attach an image or give its path and invoke:++```text+/img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.+Keep its proportions, silhouette and colours. Follow the quality gates.+Report the output files, render-review evidence and any inferred regions.+```++In another host, ask the agent to use the installed `img2threejs` skill with that image.+For a plugin workflow, name the profile explicitly, for example:++```text+Use img2threejs with the installed cs2 domain and ./reference.png.+Follow the cs2 profile and its family-specific reconstruction and review gates.+```++```text+Use img2threejs with the installed character plugin and ./reference.png.+Follow the animated-character profile. Do not claim animation readiness until its rig gates pass.+```++The agent validates the image, writes an assessment and spec, generates the factory pass+by pass, and reviews rendered comparisons. Installation alone does none of that.+For a multi-session reconstruction, run these from the skill root:++```bash+python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json+python3 forge/next.py --state .img2threejs/state.json+```++### 5. Audit and maintain the installation++```bash+npx --yes img2threejs@latest doctor # base-skill host/link report+img2 doctor # static audit of registered plugins+img2 update cs2 --check # read-only check for a newer plugin version+img2 update cs2 # install a newer available plugin version+img2 remove cs2 # unlink owned links and back up the managed checkout+```++Neither doctor command proves visual likeness or animation quality; those require the+reconstruction's render and domain gates. `img2 update --check` exits 1 when an update is+pending, not only on errors. Local `--link` checkouts are live and are not fetched by update.++| Finding / refusal | Meaning and next action |+|---|---|+| `WARN ... multi-capability provider` | The plugin declares multiple capabilities; each edge resolves independently. This warning alone does not fail `img2 doctor`. Do not delete capabilities or reinstall just to remove it. |+| `FAIL ... opencode link missing` | The reported OpenCode skill link is missing. Inspect the reported path and registered checkout; it is not proof that the reconstruction code is broken. `sync` regenerates harness data, not host links. |+| Plugin already registered | Use `img2 list` and `img2 update <id>`, not another ordinary `add`. Use `add --force` only when deliberately replacing a registration; it backs up and reinstalls rather than merely repairing a link. |+| Unmanaged base skill | Keep the manual checkout, or deliberately move its host entry before using the base installer. The base CLI does not overwrite it. |+| Private source returns 404 / access denied | Sign in with a GitHub account authorized for that repository and configure Git credentials. A public npm installer cannot bypass source permissions. |++For plugin audit exit codes, replacement behavior and additional troubleshooting, see+the [img2 README](https://github.com/img2threejs/img2#refs-replacement-and-common-refusals).### Driving it harder