@holokai/neuron-sdk 0.1.1 → 0.2.0

package/README.md

@@ -778,3 +778,83 @@ Heartbeats aren't reaching the gateway, so the reaper hasn't reclaimed them. Che
 ### Auth 401 on every request
 
 The `auth` callback isn't returning a valid token. If using a refresh flow, ensure the callback fetches a fresh token on each call (the SDK caches nothing — it's your callback's job).
+
+---
+
+## Releasing (maintainers)
+
+`@holokai/neuron-sdk` is published to public npm. Releases are cut from a
+monorepo-scoped git tag, and CI does the publish — there is no npm token on
+anyone's laptop and none stored in the repo.
+
+### Cut a release
+
+1. **Bump the version** in `packages/neuron-sdk/package.json`
+   (`version`). Follow semver:
+   - Pilot phase, we are in **`0.x`**. Because the protocol is still absorbing
+     pilot-developer feedback, a **breaking** change bumps the **minor**
+     (`0.2.0` → `0.3.0`); a backward-compatible change or fix bumps the
+     **patch** (`0.2.0` → `0.2.1`). This is the standard `0.x` convention and
+     is what buys us room to break things on feedback without a major bump.
+   - Hold **`1.0.0`** until the public API has survived pilot feedback and we're
+     ready to commit to "breaking changes bump the major." Jumping to `1.0.0`
+     is a stability promise, not a milestone — don't spend it early.
+2. **Commit** the bump (reference the Linear ticket) and merge to `main`.
+3. **Tag and push** from `main`:
+   ```sh
+   git tag neuron-sdk-v0.2.0        # must equal the package.json version
+   git push origin neuron-sdk-v0.2.0
+   ```
+   The tag is prefixed `neuron-sdk-v` (the Python SDK uses
+   `neuron-sdk-python-v`) so the two never collide.
+4. **`publish-neuron-sdk.yml`** fires on the tag: it asserts the tag version
+   matches `package.json`, runs the `prepublish` gate (`build` + `test`), and
+   publishes to npm. The `npm` GitHub Environment gates the publish behind a
+   **required-reviewer approval** — approve the run under Actions, and on success
+   the new version is live at
+   [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk).
+
+   > No `--provenance`: bigbrain is a private repo, so npm's provenance
+   > attestation (a public transparency-log link back to the source) adds little
+   > and has historically errored from private repos. Trusted-publishing auth is
+   > unaffected. Add the flag back if bigbrain ever goes public.
+
+The tag→`package.json` assertion means a mismatched tag fails **before** the
+registry is touched — npm refuses to re-upload an existing version, so there's
+no half-published state to clean up.
+
+### Publish auth: npm Trusted Publishing (one-time setup)
+
+CI authenticates to npm via **OIDC trusted publishing** — GitHub Actions
+exchanges a short-lived OIDC token for publish rights, so no long-lived
+`NPM_TOKEN` exists to leak. This mirrors the Python SDK's PyPI trusted
+publishing. It requires two one-time setups:
+
+1. **On npmjs.com** (a package admin, once): open the
+   [`@holokai/neuron-sdk`](https://www.npmjs.com/package/@holokai/neuron-sdk)
+   package → **Settings → Trusted Publisher → GitHub Actions**, and register:
+   - Organization / repository: `holok-ai/bigbrain`
+   - Workflow filename: `publish-neuron-sdk.yml`
+   - Environment: `npm`
+2. **In this repo** (once): create the **`npm`** GitHub Environment
+   (Settings → Environments). Add reviewers/branch protection here if you want a
+   manual approval gate before each publish.
+
+Until the trusted publisher is registered, the `npm publish` step fails with an
+auth error — that's the expected "not set up yet" signal, not a code bug.
+
+### Manual publish (fallback / first bootstrap)
+
+The tag flow is the norm. If you ever need to publish by hand (e.g. to bootstrap
+the very first version before trusted publishing is configured):
+
+```sh
+cd packages/neuron-sdk
+pnpm run publish:npm:dry   # inspect the tarball + files list
+pnpm run publish:npm       # runs the prepublishOnly build+test gate, then publishes
+```
+
+This uses your own `npm login` credentials and skips the CI approval gate —
+prefer the tag flow for anything a developer will consume.
+
+<!-- ci: force full build on the self-hosted runner (HOL-2028 verify); safe to remove -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holokai/neuron-sdk",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "SDK for building Holokai neurons — connect to a BigBrain gateway over HTTP+SSE or Electron IPC and execute capability-typed tasks.",
   "license": "MIT",
   "author": "Holokai",