ci: restructure release branches into main, beta, and alpha

.github/dependabot.yml

@@ -2,7 +2,7 @@ version: 2
 updates:
   # SDK core packages and workspace tooling
   - package-ecosystem: npm
-    target-branch: prerelease
+    target-branch: beta
     directories:
       - /
       - /packages/sdk
@@ -25,7 +25,7 @@ updates:
 
   # Test apps
   - package-ecosystem: npm
-    target-branch: prerelease
+    target-branch: beta
     directories:
       - /test/test-nextjs
       - /test/test-vite
@@ -49,7 +49,7 @@ updates:
 
   # Example apps
   - package-ecosystem: npm
-    target-branch: prerelease
+    target-branch: beta
     directories:
       - /examples/example-bnb
       - /examples/example-hoodi
@@ -78,7 +78,7 @@ updates:
           - version-update:semver-patch
 
   - package-ecosystem: github-actions
-    target-branch: prerelease
+    target-branch: beta
     directory: /
     schedule:
       interval: weekly

.github/workflows/abi.yml

@@ -2,7 +2,7 @@ name: ABI Check
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     paths:
       - "contracts/src/**"
       - "contracts/foundry.toml"

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
   workflow_call:
 
 concurrency:

.github/workflows/codemod.yml

@@ -2,7 +2,7 @@ name: Codemod
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     paths:
       - "codemods/**"
       - ".github/workflows/codemod.yml"

.github/workflows/contracts-test.yml

@@ -2,7 +2,7 @@ name: Contracts Test
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     paths:
       - "contracts/src/**"
       - "contracts/test/**"

.github/workflows/docs.yml

@@ -2,7 +2,7 @@ name: Docs
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     paths: &doc-paths
       - "docs/**"
       - "examples/**/README.md"
@@ -17,11 +17,10 @@ on:
       - "package.json"
       - "pnpm-lock.yaml"
       - ".github/workflows/docs.yml"
-  # semantic-release forces branch-to-branch merges (prerelease→main) with the
-  # docs:retarget fix committed directly on top, so doc changes routinely reach
-  # main/prerelease via direct push, never a PR. Run the checks there too.
+  # Promotions are branch-to-branch merges (beta→main; alpha→beta→main for breaking work)
+  # with docs:retarget committed on top, so docs reach main/beta/alpha by direct push, not a PR.
   push:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     paths: *doc-paths
   workflow_call:
 
@@ -67,17 +66,15 @@ jobs:
       - name: Verify LLM corpus artifacts are up to date
         run: pnpm exec turbo run llm:check
 
-      # Doc URLs are branch-specific (raw.githubusercontent .../main|prerelease, and
-      # docs.zama.org .../stable|alpha). `github.base_ref` is the branch this PR lands
-      # on — reliable here even though the PR is checked out detached. If the committed
-      # URLs target the wrong branch (e.g. a promotion that forgot `pnpm docs:retarget`),
-      # this fails. `ref_name` covers the direct-push and workflow_call (release) paths.
+      # Doc URLs are branch-specific (raw.githubusercontent .../main|beta, docs.zama.org
+      # .../stable|beta). `base_ref` is the PR's target branch; `ref_name` covers direct-push
+      # and workflow_call (release). Fails if committed URLs target the wrong branch.
       - name: Verify doc URLs target the right branch
         run: pnpm docs:check-target "${{ github.base_ref || github.ref_name }}"
 
   # External link liveness for the published docs + READMEs. Internal links and
   # anchors are checked above by `pnpm docs:check-links`; this job covers `https://`
-  # targets. Runs for PRs and direct pushes to main/prerelease, but NOT when this
+  # targets. Runs for PRs and direct pushes to main/beta/alpha, but NOT when this
   # workflow is reused by release.yml: there `github.workflow` is the caller's name
   # ("Release"), so external flakiness still can't block a release. If it flakes on
   # PRs, move to a scheduled (cron) workflow.

.github/workflows/examples.yml

@@ -8,7 +8,7 @@ name: Examples CI
 # import, a type error — against the SDK release it actually targets.
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     paths:
       - "examples/**"
       - ".github/workflows/examples.yml"

.github/workflows/integration.yml

@@ -7,7 +7,7 @@ name: Integration
 # blip should never block an unrelated merge.
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     paths:
       - "packages/sdk/**"
       - "pnpm-lock.yaml"

.github/workflows/license-compat.yml

@@ -2,9 +2,9 @@ name: License Compatibility
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
   push:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}

.github/workflows/playwright.yml

@@ -2,7 +2,7 @@ name: Playwright
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
   workflow_call:
 
 concurrency:

.github/workflows/pr-title-lint.yml

@@ -2,7 +2,7 @@ name: PR Title Lint
 
 on:
   pull_request:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
     types: [opened, edited, synchronize, reopened]
 
 concurrency:

.github/workflows/release-preview.yml

@@ -29,8 +29,8 @@ jobs:
     steps:
       - name: Validate target branch
         run: |
-          if [[ "${GITHUB_REF_NAME}" != "main" && "${GITHUB_REF_NAME}" != "prerelease" ]]; then
-            echo "Release preview is only allowed from main or prerelease (got: ${GITHUB_REF_NAME})."
+          if [[ "${GITHUB_REF_NAME}" != "main" && "${GITHUB_REF_NAME}" != "beta" && "${GITHUB_REF_NAME}" != "alpha" ]]; then
+            echo "Release preview is only allowed from main, beta, or alpha (got: ${GITHUB_REF_NAME})."
             exit 1
           fi
 

.github/workflows/release.yml

@@ -2,7 +2,7 @@ name: Release
 
 on:
   push:
-    branches: [main, prerelease]
+    branches: [main, beta, alpha]
   workflow_dispatch:
     inputs:
       publish-tag:
@@ -163,8 +163,8 @@ jobs:
     steps:
       - name: Validate target branch
         run: |
-          if [[ "${GITHUB_REF_NAME}" != "main" && "${GITHUB_REF_NAME}" != "prerelease" ]]; then
-            echo "::error::Releases are only allowed from main or prerelease (got: ${GITHUB_REF_NAME})."
+          if [[ "${GITHUB_REF_NAME}" != "main" && "${GITHUB_REF_NAME}" != "beta" && "${GITHUB_REF_NAME}" != "alpha" ]]; then
+            echo "::error::Releases are only allowed from main, beta, or alpha (got: ${GITHUB_REF_NAME})."
             exit 1
           fi
 

.releaserc.cjs

@@ -26,7 +26,11 @@ const mainTemplate = extract("mainTemplate").replace(/^\* /gm, "- ");
 const commitPartial = extract("commitPartial").replace(/^\*/, "-");
 
 module.exports = {
-  branches: ["main", { name: "prerelease", channel: "alpha", prerelease: "alpha" }],
+  branches: [
+    "main",
+    { name: "beta", channel: "beta", prerelease: "beta" },
+    { name: "alpha", channel: "alpha", prerelease: "alpha" },
+  ],
   tagFormat: "v${version}",
   plugins: [
     [

AGENTS.md

@@ -32,7 +32,7 @@ Load these on demand during planning — they are not preloaded:
 - [`docs/agents/architecture.md`](docs/agents/architecture.md) — repo layout, how operations flow through the system (balance, transfer, shield, unshield, routing)
 - [`docs/agents/conventions.md`](docs/agents/conventions.md) — shared naming rules and design decisions (contracts-vs-tokens, Solidity-mirror params, pure contract call builders, stage-gate docs language, …)
 - [`docs/agents/gotchas.md`](docs/agents/gotchas.md) — shared footguns: address normalization in query keys, PR base branch, shared-branch safety
-- [`docs/agents/changelog.md`](docs/agents/changelog.md) — the GitBook changelog convention: mainline-only pages, the Alpha unreleased tip, per-minor vs. frozen-major pagination, nav wiring, and the `docs:changelog` automation
+- [`docs/agents/changelog.md`](docs/agents/changelog.md) — the GitBook changelog convention: mainline-only pages, the Beta unreleased tip, per-minor vs. frozen-major pagination, nav wiring, and the `docs:changelog` automation
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — dev commands (build, test, E2E, typecheck, lint, format), LLM artifact generation (`pnpm llm:build` / `llm:check`), API reports (`pnpm api-report*`), and the PR/release workflow
 
 Some packages add their own AGENTS.md with package-specific rules — they merge with this root file when you're working in that subtree:

CONTRIBUTING.md

@@ -63,7 +63,7 @@ Use descriptive branch names:
 
 ### Making Changes
 
-1. Create a feature branch from `prerelease` (the default PR base; `main` is reserved for release/CI-infra PRs)
+1. Create a feature branch from `beta` (the default PR base; `main` is reserved for release/CI-infra PRs). `alpha` is not a feature-PR target — it's a protected branch used only for testing changes incompatible with the current protocol on mainnet/testnet (e.g. a new FHEVM SDK major version), synced from `beta` and merged back only once stable enough.
 2. Make your changes
 3. Ensure all checks pass:
 
@@ -79,7 +79,7 @@ pnpm build        # Build output
 
 ### GitBook Documentation
 
-The docs in `docs/gitbook/src/` are published to GitBook (both `main` and `prerelease` ship as separate spaces). **Links between doc pages must be relative `.md` paths** — e.g. `[Token](../reference/sdk/Token.md)`, never host-absolute (`/reference/sdk/Token`). GitBook serves each space under a sub-path (`docs.zama.org/protocol/sdk/…`), so a leading-slash link resolves against the site root and breaks (it only surfaces on the live site — use GitBook's per-PR preview to check rendering). Anchors must match a heading in the target page.
+The docs in `docs/gitbook/src/` are published to GitBook (both `main` and `beta` ship as separate spaces, labeled "Stable" and "Beta" in the docs site version switcher; `alpha` is a protocol-testing branch only and has no separate docs space). **Links between doc pages must be relative `.md` paths** — e.g. `[Token](../reference/sdk/Token.md)`, never host-absolute (`/reference/sdk/Token`). GitBook serves each space under a sub-path (`docs.zama.org/protocol/sdk/…`), so a leading-slash link resolves against the site root and breaks (it only surfaces on the live site — use GitBook's per-PR preview to check rendering). Anchors must match a heading in the target page.
 
 `pnpm docs:check-links` validates this (no host-absolute links, every relative target and `#anchor` resolves) and runs in CI on any docs change. Run it locally before pushing doc edits.
 
@@ -100,10 +100,10 @@ pnpm llm:check
 
 The pre-commit hook regenerates and stages the LLM artifacts automatically when relevant staged sources change. If a corpus source is partially staged, stage or discard the remaining changes before committing so the generated files match the committed source state.
 
-Doc URLs are branch-specific: the corpus and the migration-guide prompt link to `raw.githubusercontent.com/zama-ai/sdk/<branch>/…` and `docs.zama.org/protocol/sdk/<space>/…` — `main`/`stable` on the release branch, `prerelease`/`alpha` on the prerelease branch. They can't be derived at build time (CI checks out PRs detached, and the committed artifacts must match the rebuild), so the branch is committed and flipped at promotion with one idempotent command:
+Doc URLs are branch-specific: the corpus and the migration-guide prompt link to `raw.githubusercontent.com/zama-ai/sdk/<branch>/…` and `docs.zama.org/protocol/sdk/<space>/…` — `main`/`stable` on the release branch, `beta`/`beta` on the beta branch (`alpha` has no docs space of its own). They can't be derived at build time (CI checks out PRs detached, and the committed artifacts must match the rebuild), so the branch is committed and flipped at promotion with one idempotent command:
 
 ```bash
-pnpm docs:retarget main        # or: prerelease
+pnpm docs:retarget main        # or: beta
 ```
 
 CI (`pnpm docs:check-target`, driven by the PR's base branch) fails any PR whose committed URLs target the wrong branch and points you at the command above.
@@ -160,28 +160,29 @@ We use [semantic-release](https://semantic-release.gitbook.io/semantic-release/)
 Release behavior:
 
 1. PR titles are validated against Conventional Commits.
-2. Squash-merging into a release branch (`main` or `prerelease`) preserves that title as the release signal.
+2. Squash-merging into a release branch (`main`, `beta`, or `alpha`) preserves that title as the release signal.
 3. semantic-release computes the next version (`patch`/`minor`/`major`) from merged commits. Breaking changes must be signaled with `!` in the PR title (e.g. `feat!: drop deprecated API`); `BREAKING CHANGE:` text in commit bodies is preserved in the changelog but does not affect the version bump.
 4. `@zama-fhe/sdk` and `@zama-fhe/react-sdk` are versioned and published together in lockstep.
-5. `main` publishes stable versions to npm `latest`, while `prerelease` publishes prerelease versions to npm `alpha`.
+5. `main` publishes stable versions to npm `latest`, `beta` publishes prerelease versions to npm `beta`, and `alpha` publishes prerelease versions to npm `alpha`.
 6. GitHub release notes and tags are generated automatically.
 
 Release workflows:
 
-- `Release` (`.github/workflows/release.yml`): automatic publish on push to `main` and `prerelease`, gated by `Vitest` and `Playwright`.
-- `Release (Manual)` (`.github/workflows/release-manual.yml`): manual publish restricted to `main` and `prerelease`, with the same `Vitest` + `Playwright` gates before publishing. Shares a concurrency group with `Release` to prevent simultaneous publishes on the same ref.
-- `Release Preview` (`.github/workflows/release-preview.yml`): manual dry-run restricted to `main` and `prerelease` (`pnpm release:dry-run`), no publish side effects.
+- `Release` (`.github/workflows/release.yml`): automatic publish on push to `main`, `beta`, and `alpha`, gated by `Vitest` and `Playwright`.
+- Manual publish: the same `Release` workflow (`release.yml`) also runs on `workflow_dispatch` (same `main`/`beta`/`alpha` restriction and `Vitest` + `Playwright` gates). Use it to recover when semantic-release created the tag but the npm publish step failed — a `publish-tag` input republishes from an existing tag, and a `dry-run` input is available.
+- `Release Preview` (`.github/workflows/release-preview.yml`): manual dry-run restricted to `main`, `beta`, and `alpha` (`pnpm release:dry-run`), no publish side effects.
 
 Install channels:
 
 - Stable: `npm i @zama-fhe/sdk`
-- Prerelease: `npm i @zama-fhe/sdk@alpha`
+- Beta: `npm i @zama-fhe/sdk@beta`
+- Alpha: `npm i @zama-fhe/sdk@alpha`
 
 Maintainer requirements:
 
 - Configure branch protection on `main` to require both `Vitest` and `Playwright` checks before merge.
-- Configure branch protection on `prerelease` with the same required checks.
-- Configure npm trusted publishers for `@zama-fhe/sdk` and `@zama-fhe/react-sdk` pointing to this repository's `release.yml` and `release-manual.yml` workflows.
+- Configure branch protection on `beta` and `alpha` with the same required checks.
+- Configure npm trusted publishers for `@zama-fhe/sdk` and `@zama-fhe/react-sdk` pointing to this repository's `release.yml` workflow.
 
 ## Architecture Guidelines
 

README.md

@@ -25,9 +25,9 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@zama-fhe/sdk">
-    <img src="https://img.shields.io/npm/v/%40zama-fhe%2Fsdk/alpha?label=dev%20release&style=flat-square" alt="Dev release"></a>
+    <img src="https://img.shields.io/npm/v/%40zama-fhe%2Fsdk/beta?label=dev%20release&style=flat-square" alt="Dev release"></a>
   <a href="https://www.npmjs.com/package/@zama-fhe/sdk">
-    <img src="https://img.shields.io/npm/last-update/%40zama-fhe%2Fsdk/alpha?style=flat-square" alt="Dev release last updated"></a>
+    <img src="https://img.shields.io/npm/last-update/%40zama-fhe%2Fsdk/beta?style=flat-square" alt="Dev release last updated"></a>
   <a href="https://github.com/zama-ai/sdk/actions/workflows/ci.yml">
     <img src="https://img.shields.io/github/actions/workflow/status/zama-ai/sdk/ci.yml?style=flat-square&label=CI" alt="CI"></a>
   <a href="https://github.com/zama-ai/sdk/actions/workflows/playwright.yml">

docs/agents/changelog.md

@@ -7,16 +7,17 @@ The repo has **two** changelog surfaces — keep them distinct:
 
 ## Conventions
 
-- **Mainline releases only** — no per-prerelease pages. The unreleased tip accumulates on a single **Alpha page** under an "Unreleased" hint; on release its content is promoted into a version section and the Alpha page resets.
+- **Mainline releases only** — no per-prerelease pages. The unreleased tip accumulates on a single **Beta page** under an "Unreleased" hint; on release its content is promoted into a version section and the Beta page resets.
+- **`alpha` is off the changelog** — the protocol-testing `alpha` branch has no GitBook space or doc URLs, so its `-alpha.N` builds never get a page or section here; only `beta`/stable work is written up.
 - **Active major line → one page per minor**, behind a collapsible parent index. Page title and H1 are both `{minor}.x`. Inside, one `## {version}` section per release, **newest-first**, each opening with a `_Released YYYY-MM-DD._` dateline and grouping changes under `###` topic headings (not raw commit types).
 - **Superseded majors → one page per major**, grouped under a collapsible "Legacy versions" parent, same newest-first sections.
 - **Legacy pages are historical record** — write them in the API vocabulary of their era (don't modernize names) and don't link into the current-API `guides/`/`reference/` trees, the migration guide excepted.
-- **Nav is newest-to-oldest** (Alpha → active line → Legacy) and nests with **2-space indent** — the SUMMARY-driven LLM corpus derives page depth from indentation, so an off-indent entry miscategorizes the page.
+- **Nav is newest-to-oldest** (Beta → active line → Legacy) and nests with **2-space indent** — the SUMMARY-driven LLM corpus derives page depth from indentation, so an off-indent entry miscategorizes the page.
 - **Release datelines are real dates by design.** The no-calendar-dates rule is about forward-looking promises, not the historical record of when a version shipped.
 
 ## Automation
 
-- **`pnpm docs:changelog`** does the mechanical half — scaffolds missing `## {version}` stubs, new `{minor}.x` pages and their nav entries, and the Alpha "raw material" list. Deterministic, idempotent, no-op-safe; it writes stubs, never prose.
+- **`pnpm docs:changelog`** does the mechanical half — scaffolds missing `## {version}` stubs, new `{minor}.x` pages and their nav entries, and the Beta "raw material" list. Deterministic, idempotent, no-op-safe; it writes stubs, never prose.
 - **The `sdk-changelog` skill** does the editorial half — drafting the plain-language prose from those stubs.
 - **Promotion is automatic**, inside `pnpm docs:retarget main` at the release merge, with the version derived from the newest mainline entry in `CHANGELOG.md` — so pull the release commit before retargeting, or promotion silently no-ops.
 - **Enforcement:** `pnpm docs:check-links` (links, anchors, orphans) and the SUMMARY-driven corpus (`pnpm llm:build`).

docs/agents/fhevm-sdk-1x-migration.md

@@ -16,7 +16,7 @@
 > **This doc is now a historical record** of two migrations that have both landed. Keep it for the
 > rationale and the rename mapping (still an accurate reference for the current API); it no longer
 > describes pending work. For the user-facing description of the current backend, see
-> [`changelog/alpha.md`](../gitbook/src/changelog/alpha.md) and
+> [`changelog/beta.md`](../gitbook/src/changelog/beta.md) and
 > [`concepts/architecture.md`](../gitbook/src/concepts/architecture.md).
 
 Internal feedback that originally set this split (track 1 was deferred first, then completed):