Production interior authoring and interactive Three.js delivery plugin for img2.
docs: clarify private-source npm distribution and release plan
hoainho2dceef978d2f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f1591f8..5cebbbd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,6 +5,7 @@### Documentation- Rewrite the README around project scope, deliverables, installation, usage, contributor checks, support, security, and licensing. Keep detailed production instructions in the reference guides and clarify private-source access and publication status.+- Document private GitHub hosting with planned npm installer distribution, distinguish installer-only and payload access models, and add the official wrapper release checklist with tarball review, trusted publishing, and private-source provenance limits.## 0.2.0 — 2026-10-18diff --git a/README.md b/README.mdindex ba40d17..2d798f8 100644--- a/README.md+++ b/README.md@@ -6,7 +6,7 @@ img2 Interior is a plugin for the [img2 harness](https://github.com/img2threejs/This is an agent-guided authoring toolkit, not a pretrained image-to-mesh model. A reference image is the starting point; visual fidelity still depends on scene authoring and review.-[Quickstart](#quickstart) · [Documentation](#documentation) · [Contributing](#contributing) · [License](#license)+[Distribution](#distribution) · [Quickstart](#quickstart) · [Documentation](#documentation) · [Contributing](#contributing) · [License](#license)## What it does@@ -25,6 +25,16 @@ This is an agent-guided authoring toolkit, not a pretrained image-to-mesh model.Generated scenes, downloaded assets, renders, and local environments belong in the project workspace, not in the plugin checkout. They are not bundled with this repository.+## Distribution++The GitHub repository remains **private**. npm is the planned installer distribution channel; this repository currently supports source-checkout and source-archive installation. An npm installer has not been added or published for this plugin.++For private-source distribution, the recommended model is a **public, installer-only npm package** generated by the official img2 tooling. It ships the CLI and public package documentation, not the plugin implementation or scene assets. Installation fetches the implementation from this private repository, so users still need authorized GitHub read access.++Repository privacy and npm package visibility are separate. Publishing the full skill in a public npm package would make the included code downloadable without GitHub access. Distributing the payload through a private npm package instead requires an eligible paid npm account and explicit package read access.++Until an installer release is available, use the source installation below. Maintainers can follow the [npm release plan](reference/installation.md#npm-release-plan) for packaging, access choices, and release checks.+## Quickstart### Requirements@@ -41,9 +51,9 @@ Generated scenes, downloaded assets, renders, and local environments belong in tThe harness does not install Blender/Python dependencies or build a viewer for you. Follow the [environment setup](reference/production-runbook.md#2-prepare-project-local-environments) before native authoring. Availability of compatible Blender wheels depends on the platform.-### 1. Install the skill+### 1. Install from source-Repository access is currently required: the source is hosted in a **private GitHub repository**. Installation is from a persistent checkout or an extracted source archive; there is no published npm package or catalog entry for this plugin.+Access to the private `img2threejs/img2interior` repository is required for this installation method. Keep the checkout in a persistent location. An extracted source archive can also be installed with `add --link` as described in the [installation guide](reference/installation.md).The commands below install the harness and register the skill with agent hosts. They change local harness/host configuration. If a compatible harness is already installed, skip the `install` command.@@ -78,7 +88,7 @@ Review gates track stage order and current evidence. They do not measure aesthet| Guide | Contents || --- | --- |-| [Installation](reference/installation.md) | Host integration, linked checkouts, updates, and removal |+| [Installation and npm release plan](reference/installation.md) | Source installation, access models, release preparation, updates, and removal || [Production runbook](reference/production-runbook.md) | Environment setup and end-to-end commands || [Agent instructions](SKILL.md) | Skill entry point and stage-specific guidance || [Scene contract](reference/scene-contract.md) | Scene specification and Python builder interface |@@ -140,4 +150,6 @@ Paid generation, private uploads, purchases, deployment, and redistribution of rThe code in this repository is licensed under [Apache License 2.0](LICENSE).+Private hosting and package access controls do not change this license or revoke the rights it grants for distributed code.+Third-party assets and reference images remain subject to their own licenses and permissions. Poly Haven's CC0 asset license is separate from its API terms and attribution requirements; see the [resource guide](reference/resources.md).diff --git a/reference/installation.md b/reference/installation.mdindex 93b3327..fad4cdc 100644--- a/reference/installation.md+++ b/reference/installation.md@@ -53,3 +53,32 @@ This runs the official CLI with a temporary HOME/IMG2_HOME and three temporary h## Release and catalog boundariesKeep the repository private unless its owner separately authorizes a visibility change. Repository hosting and source ZIPs do not create an npm package, semver-tagged release or catalog entry. Request those operations separately; if an npm convenience installer is authorized, use the harness's official `create-img2-plugin-cli`, not a parallel custom installer.++## npm release plan++The GitHub repository stays private. npm is the intended installer channel, but this plugin does not yet include a generated npm installer or a published npm release. The source installation above remains the available path.++### Choose the artifact and access model++| Model | What npm distributes | What users need |+|---|---|---|+| Public installer, private GitHub implementation | Only the CLI, package metadata, and public README/license | Authorized HTTPS Git access to this repository |+| Public payload package, private GitHub development | The plugin implementation itself | Public npm access; included code is no longer private |+| Private payload package, private GitHub development | The plugin implementation, restricted by npm permissions | A paid npm user/organization account, npm authentication, and package read access |++The recommended private-source model is the first row, using the official installer generator. A public installer does not grant access to a private Git repository. A private npm payload can avoid GitHub access for consumers, but package readers can still inspect downloaded code. These controls do not replace or change the existing Apache-2.0 license.++See npm's [private package requirements](https://docs.npmjs.com/about-private-packages). Decide on payload visibility and licensing before authorizing the first publish.++### Prepare an installer release++1. **Confirm ownership and versions.** Choose an available npm package name owned by the maintainer or organization. Keep the plugin ID `interior` and skill name `img2-interior`. Select a reviewed plugin semver tag or full commit SHA; do not make an installer silently track an unreviewed branch.+2. **Generate the official wrapper.** Use `create-img2-plugin-cli` from a reviewed img2 version with `--private-repo`, `--source img2threejs/img2interior`, an explicit `--ref`, and a reviewed full `--workflow-ref` SHA. The generator creates `cli/`, its tests/public README/license, a publish workflow, and `CLI_QUICKSTART.md`; none of these have been generated in this repository yet.+3. **Review the tarball, not just the repository.** Run the generated CLI tests and `npm pack --dry-run` from `cli/`; inspect the actual packed tarball and test that artifact in an isolated consumer. Allow only the intended installer files and required package metadata/documentation. Do not include the plugin payload, credentials, workspace state, references, scene assets, or environments. Do not publish from the plugin root.+4. **Authorize the first publish.** Use an npm account with package write access and 2FA. Follow the generated quickstart for the reviewed package name, explicit access setting, and first manual release. For this public-wrapper model, the access setting is `public`; publishing is a separate authorized operation, not part of installing or testing the skill.+5. **Configure tokenless CI releases.** After the package exists, configure npm trusted publishing for this repository's exact caller workflow filename and the required publish permission. Use a supported GitHub-hosted runner with `id-token: write`; do not store a long-lived npm write token. Trusted publishing requires Node ≥22.14.0 and npm ≥11.5.1; the SDK's current release-setup instructions require npm ≥11.15 for its trust-management command.+6. **Keep private-source provenance disabled.** Generate with `--private-repo` and retain `provenance=false`. npm trusted publishing supports authentication for this release flow, but npm provenance attestations are not supported for private source repositories, even when the npm installer is public.+7. **Verify and document consumer access.** Test dry-run/install/doctor/removal in isolated host directories with authorized HTTPS Git credentials; also check an unauthorized consumer fails without a partial plugin registration. npm authentication alone is not GitHub authorization. Keep credentials out of package contents, command URLs, logs, and public examples.+8. **Release immutable versions.** Plugin source tags use `vX.Y.Z`; generated installer release tags use `cli-vX.Y.Z`. Publish the exact tested tarball, record the installed source ref/integrity, and update public install instructions only after the package/version is available and verified. npm installation does not register a catalog entry.++Official references: [img2 wrapper contract](https://github.com/img2threejs/img2/blob/main/docs/WRITING_A_PLUGIN.md#10-plugin-cli-wrapper-optional), [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/), and [npm provenance requirements](https://docs.npmjs.com/generating-provenance-statements/).