@holokai/neuron-sdk 0.5.0 → 0.5.1

package/README.md

@@ -843,69 +843,75 @@ The `auth` callback isn't returning a valid token. If using a refresh flow, ensu
 
 ## 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.
+`@holokai/neuron-sdk` is published to public npm by BigBrain's Release
+workflow (`.github/workflows/release.yml`). There is no npm token on anyone's
+laptop and none stored in the repo, and pushing a tag publishes nothing.
+
+### Pick the 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` to `0.3.0`); a backward-compatible change or fix bumps the
+  **patch** (`0.2.0` to `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.
 
 ### 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
+1. Open **Actions, Release, Run workflow** on branch `main`.
+2. Fill **neuron-sdk** with the new version (`X.Y.Z`). Leave the other lines
+   (base, embedded, synapse) empty unless they are being released too; an
+   empty line is not touched. Tick **plan only** to read the plan without
+   cutting anything.
+3. The plan job checks the version (shaped `X.Y.Z`, not older than
+   `packages/neuron-sdk/package.json`, tag `neuron-sdk-vX.Y.Z` not taken) and
+   writes the plan to the run summary.
+4. A reviewer of the `release` environment approves the run. That is the only
+   approval.
+5. The cut writes the version into `packages/neuron-sdk/package.json`,
+   commits it to `main`, tags `neuron-sdk-vX.Y.Z` and pushes both. If the file
+   already carries the version (a bump merged by pull request), it only tags.
+6. From the commit the cut pushed, the run builds and tests the SDK (the
+   `prepublish` turbo task), packs it, and publishes the tarball to npm from a
+   GitHub-hosted runner. 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 is prefixed `neuron-sdk-v` (the Python SDK uses `neuron-sdk-python-v`)
+so the two never collide. The workflow file's header comments describe every
+job and how to recover a failed run.
 
-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.
+> 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.
 
 ### Publish auth: npm Trusted Publishing (one-time setup)
 
-CI authenticates to npm via **OIDC trusted publishing** — GitHub Actions
+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:
+`NPM_TOKEN` exists to leak. 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:
+   package, **Settings, Trusted Publisher, GitHub Actions**, and register:
    - Organization / repository: `holok-ai/bigbrain`
-   - Workflow filename: `publish-neuron-sdk.yml`
+   - Workflow filename: `release.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.
+2. **In this repo** (once): the **`npm`** GitHub Environment (Settings,
+   Environments) with no required reviewer, because the Release run's one
+   approval is on its cut, and a deployment branch rule of `main` only, so a
+   copy of `release.yml` on another branch cannot publish to npm.
 
 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.
+auth error. That is 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 Release workflow 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
@@ -915,6 +921,6 @@ pnpm run publish:npm       # runs the prepublishOnly build+test gate, then publi
 ```
 
 This uses your own `npm login` credentials and skips the CI approval gate —
-prefer the tag flow for anything a developer will consume.
+prefer the Release workflow 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.5.0",
+  "version": "0.5.1",
   "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",