diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..c39bf8b
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,22 @@
+name: ci
+on:
+  pull_request:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  test:
+    # ci-workflows python-ci @ main
+    uses: img2threejs/ci-workflows/.github/workflows/python-ci.yml@4b7a0612d2c52815792124a18ae3f9032a4f0a88
+    with:
+      python-version: '3.12'
+      test-command: |
+        pkg="$(node -p 'require("./package.json").version')"
+        plg="$(node -p 'require("./plugin.json").version')"
+        if [ "$pkg" != "$plg" ]; then
+          echo "version mismatch: package.json=$pkg plugin.json=$plg"
+          exit 1
+        fi
+        git clone --depth 1 https://github.com/img2threejs/img2 ../img2-harness
+        python3 -m unittest discover -s tests
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
new file mode 100644
index 0000000..07399eb
--- /dev/null
+++ b/.github/workflows/publish.yml
@@ -0,0 +1,23 @@
+name: publish
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: read
+jobs:
+  publish:
+    # ci-workflows npm-publish (feat/reusable-npm-publish); re-pin to the merged main SHA once img2threejs/ci-workflows#2 lands
+    uses: img2threejs/ci-workflows/.github/workflows/npm-publish.yml@27da7a68505591492cb4ef7358968890c6e39844
+    permissions:
+      contents: read
+      id-token: write
+    with:
+      tag: ${{ github.ref_name }}
+      version-file: plugin.json
+      node-version: '24'
+      python-version: '3.12'
+      test-command: |
+        git clone --depth 1 https://github.com/img2threejs/img2 ../img2-harness
+        python3 -m unittest discover -s tests
+    secrets:
+      npm-token: ${{ secrets.NPM_TOKEN }}
diff --git a/README.md b/README.md
index bf97449..2ae9dd3 100644
--- a/README.md
+++ b/README.md
@@ -21,3 +21,14 @@ python3 -m unittest discover -s tests       # test (needs a sibling/linked harne
 ```
 
 Full walkthrough: `docs/WRITING_A_PLUGIN.md` in the [img2 harness](https://github.com/img2threejs/img2).
+
+## Publishing to npm
+
+CI and publishing run through the org's shared [`img2threejs/ci-workflows`](https://github.com/img2threejs/ci-workflows) reusable workflows; this repo owns only its triggers and its test command.
+
+1. Bump the version in **both** `plugin.json` and `package.json` — the `ci` workflow's version-sync check fails the build if they disagree.
+2. Update `CHANGELOG.md` if the repo has one.
+3. Commit the bump.
+4. Tag the commit `vX.Y.Z` (matching the new version) and push the tag. A prerelease tag (`v1.2.3-beta.1`) publishes under the matching npm dist-tag (`beta`); a stable tag publishes under `latest`.
+5. The shared `npm-publish.yml` workflow re-validates the tag against `package.json` and `plugin.json`, runs this repo's tests in a job with no access to the publish credential, and runs `npm publish --provenance` using the org's `NPM_TOKEN` secret (a granular npm automation token with publish rights on the `@img2threejs` scope, configured once at the org or repo level — no per-repo trusted-publisher setup needed). Re-pushing a tag whose version is already on the registry is a no-op, not a failure.
+6. Workflow references in `.github/workflows/` are pinned to a specific `ci-workflows` commit SHA, per that repo's pinning policy.
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..3ced4ce
--- /dev/null
+++ b/package.json
@@ -0,0 +1,20 @@
+{
+  "name": "@img2threejs/plugin-hello-cube",
+  "version": "0.1.2",
+  "description": "Turn an image into a deterministic Three.js cube (contract exerciser)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/img2threejs/plugin-hello-cube.git"
+  },
+  "files": [
+    "SKILL.md",
+    "gates.json",
+    "plugin.json",
+    "steps.json",
+    "tools"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}