build: align ZITADEL Preview release channel

.changeset/README.md

@@ -22,13 +22,15 @@ corepack pnpm changeset
 
 Pick the affected packages, the bump type (patch / minor / major), and write a one-line summary. A markdown file appears in this directory and gets committed with your PR.
 
-## Alpha prerelease mode
+## Alpha versions, preview channel
 
-The repo is currently in changesets **prerelease mode** with the `alpha` tag (see `.changeset/pre.json`). While in this mode:
+The repo is currently in changesets **prerelease mode** with the `alpha` tag
+(see `.changeset/pre.json`). The `alpha` tag controls the version suffix; the
+public npm channel for community testing is `preview`. While in this mode:
 
 - `changeset version` cuts versions like `0.1.0-alpha.0`, `0.1.0-alpha.1`, …
-- `changeset publish` publishes them under the **`alpha`** npm dist-tag, **not** `latest`. So `npm install @zitadel/cli` keeps resolving the last stable release; consumers opt into prereleases with `@zitadel/cli@alpha`.
-- A package that has never had a stable release is published to `latest` on its first publish (changesets behaviour), then to `alpha` thereafter until it has a stable release.
+- `scripts/publish-changesets.mjs` publishes them under the **`preview`** npm dist-tag, **not** `latest`, while `.changeset/pre.json` exists. So `npm install @zitadel/cli` keeps resolving the last stable release; consumers opt into preview bundles with `@zitadel/cli@preview`.
+- The public packages are configured as a fixed MVP preview group, so the Version Packages PR keeps their versions aligned.
 
 To leave alpha and cut a stable `latest` release:
 
@@ -39,25 +41,24 @@ corepack pnpm changeset version   # strips the -alpha suffix
 
 ## Publishing (npm trusted publishing / OIDC)
 
-The [`.github/workflows/release-npm.yml`](../.github/workflows/release-npm.yml) workflow runs the [changesets GitHub Action](https://github.com/changesets/action). Pushing changesets to `main` opens a "Version Packages" PR aggregating all pending changesets; merging that PR bumps versions, updates `CHANGELOG.md` files, and publishes to npm (under the `alpha` dist-tag while in prerelease mode).
+The [`.github/workflows/release-npm.yml`](../.github/workflows/release-npm.yml) workflow runs the [changesets GitHub Action](https://github.com/changesets/action). Pushing changesets to `main` opens a "Version Packages" PR aggregating all pending changesets; merging that PR bumps versions, updates `CHANGELOG.md` files, and publishes to npm. While `.changeset/pre.json` exists, the publish step uses the `preview` dist-tag; after `changeset pre exit`, it uses Changesets' default dist-tag (`latest`). Package-level GitHub Releases are disabled; GoReleaser owns the product-level `ZITADEL Preview` releases. For the full product release order, follow the operator runbook in [`docs/operations/releasing.md`](../docs/operations/releasing.md).
 
-Publishing authenticates with **npm trusted publishing (OIDC)** — there is **no `NPM_TOKEN`** secret. Before the first automated publish, a maintainer must, once per public package:
+Publishing authenticates with **npm trusted publishing (OIDC)** — there is **no `NPM_TOKEN`** secret. The current public packages already exist on npm. When adding a new public package, a maintainer must create it on npm and then configure trusted publishing for it:
 
-1. Ensure the package exists on npm (publish `0.0.x` manually the first time if needed, since a trusted publisher can only be attached to an existing package).
-2. On npmjs.com → the package → **Settings → Trusted Publishing**, add a publisher:
+1. On npmjs.com → the package → **Settings → Trusted Publishing**, add a publisher:
    - Provider: **GitHub Actions**
    - Organization/owner: `zitadel`
    - Repository: `nextgen`
    - Workflow filename: `release-npm.yml` (exact, case-sensitive)
-3. Optionally, under **Publishing access**, require 2FA and disallow tokens so only this workflow can publish.
+2. Optionally, under **Publishing access**, require 2FA and disallow tokens so only this workflow can publish.
 
 While this repository is private, the workflow keeps npm provenance disabled
 with `NPM_CONFIG_PROVENANCE=false`. Trusted publishing still authenticates with
 short-lived OIDC credentials, but npm only accepts public provenance
 attestations from public source repositories. Re-enable provenance when
 `zitadel/nextgen` is public.
 
-The Go server binary is **not** managed by changesets — it is released with `goreleaser` through the manual [`release.yml`](../.github/workflows/release.yml) workflow while the repo is pre-release. See [docs/adrs/002-multi-package-release-strategy.md](../docs/adrs/002-multi-package-release-strategy.md).
+The Go server binary is **not** managed by changesets — it is released with `goreleaser` through the manual [`release.yml`](../.github/workflows/release.yml) workflow while the repo is pre-release. See [docs/adrs/002-multi-package-release-strategy.md](../docs/adrs/002-multi-package-release-strategy.md) for the rationale and [`docs/operations/releasing.md`](../docs/operations/releasing.md) for the release checklist.
 
 ## Licensing reminder
 

.changeset/better-goats-fry.md

@@ -0,0 +1,2 @@
+---
+---

.changeset/config.json

@@ -2,7 +2,19 @@
   "$schema": "https://unpkg.com/@changesets/config@latest/schema.json",
   "changelog": ["@changesets/changelog-github", { "repo": "zitadel/nextgen" }],
   "commit": false,
-  "fixed": [],
+  "fixed": [
+    [
+      "@zitadel/cli",
+      "@zitadel/api",
+      "@zitadel/components",
+      "@zitadel/sdk-core",
+      "@zitadel/sdk-next",
+      "@zitadel/sdk-nuxt",
+      "@zitadel/sdk-react",
+      "@zitadel/sdk-vue",
+      "@zitadel/sdk-angular"
+    ]
+  ],
   "linked": [],
   "access": "public",
   "baseBranch": "main",

.changeset/preview-bundle-channel.md

@@ -0,0 +1,13 @@
+---
+"@zitadel/cli": patch
+"@zitadel/api": patch
+"@zitadel/components": patch
+"@zitadel/sdk-core": patch
+"@zitadel/sdk-next": patch
+"@zitadel/sdk-nuxt": patch
+"@zitadel/sdk-react": patch
+"@zitadel/sdk-vue": patch
+"@zitadel/sdk-angular": patch
+---
+
+Publish the MVP preview bundle through the `preview` channel and align CLI, SDK, component, and local runtime image naming.

.github/instructions/consumer-journey.instructions.md

@@ -12,10 +12,10 @@ demo-app e2e suite.
 - Produce package artifacts with `corepack pnpm --dir <package> pack` and keep
   tarball verification for required package presence plus unresolved
   `catalog:` or `workspace:` dependency specs.
-- Pack only the six public Zitadel packages. Private support packages such as
-  design tokens must not be uploaded or published to Verdaccio.
+- Pack only the public preview Zitadel packages. Private support packages such
+  as design tokens must not be uploaded or published to Verdaccio.
 - Keep Verdaccio proxying npmjs for third-party dependencies while publishing
-  Zitadel tarballs under both `alpha` and `latest`.
+  Zitadel tarballs under the `preview` dist-tag.
 - Keep generated Next.js apps outside the repo and use `npm` inside the
   generated app to match the documented consumer path.
 - Preserve the CLI setup JSON contract: `--non-interactive --json` must parse

.github/instructions/release-docs.instructions.md

@@ -13,9 +13,14 @@ state of the repo.
 - Local-runtime image changes should preserve the zero-config Docker smoke:
   mounted `nextgen-data`, generated `server-encryption-key`, embedded Postgres,
   and no required `NEXTGEN_SERVER_ENCRYPTION_KEY`.
-- The release workflow is manual and draft-oriented while the repo is
-  pre-release. Do not imply official npm publishing is enabled.
+- The product release workflow is manual and draft-oriented while the repo is
+  pre-release. npm package publishing uses Changesets trusted publishing; keep
+  the full release sequence in `docs/operations/releasing.md` in sync with any
+  release workflow, Changesets, GoReleaser, or helper-script change.
 - npm package changes use changesets; Go server releases use GoReleaser.
+- Public preview docs should use `@zitadel/cli@preview` and
+  `ghcr.io/zitadel/zitadel-preview`; keep `nextgen` only for repo-internal or
+  temporary compatibility alias contexts.
 - Keep licensing text aligned with `LICENSING.md`: AGPL-3.0-only by default,
   MIT exceptions for CLI, SDKs, API contracts, and docs.
 - Docs that mention repo behavior should point to `AGENTS.md`; docs that mention

.github/workflows/ci.yml

@@ -148,7 +148,7 @@ jobs:
           # for ubuntu-latest smoke jobs (see quickstart-smoke).
           IMAGE_ID=""
           IMAGE_REF=""
-          for id in $(docker images ghcr.io/zitadel/nextgen --format '{{.ID}}' | sort -u); do
+          for id in $(docker images ghcr.io/zitadel/zitadel-preview --format '{{.ID}}' | sort -u); do
             arch=$(docker image inspect -f '{{.Architecture}}' "$id")
             ref=$(docker image inspect -f '{{index .RepoTags 0}}' "$id")
             case "$ref" in *snapshot*) ;; *) continue ;; esac
@@ -159,12 +159,12 @@ jobs:
             fi
           done
           if [ -z "$IMAGE_ID" ]; then
-            echo "::error::no linux/amd64 snapshot image found for ghcr.io/zitadel/nextgen"
-            docker images ghcr.io/zitadel/nextgen
+            echo "::error::no linux/amd64 snapshot image found for ghcr.io/zitadel/zitadel-preview"
+            docker images ghcr.io/zitadel/zitadel-preview
             exit 1
           fi
           # Save by a stable local tag: docker save by ID drops repo tags from the tarball.
-          CI_IMAGE="ghcr.io/zitadel/nextgen:ci-snapshot-smoke-amd64"
+          CI_IMAGE="ghcr.io/zitadel/zitadel-preview:ci-snapshot-smoke-amd64"
           docker tag "$IMAGE_ID" "$CI_IMAGE"
           echo "$CI_IMAGE" > dist/nextgen-image.tag
           docker save "$CI_IMAGE" -o dist/nextgen-image.tar
@@ -201,7 +201,7 @@ jobs:
           key: embedded-postgres-${{ runner.os }}-${{ hashFiles('go.sum') }}
       - name: Extract linux/amd64 server binary
         run: |
-          TARBALL="$(find goreleaser-dist -name 'nextgen_*_linux_amd64.tar.gz' | head -1)"
+          TARBALL="$(find goreleaser-dist -name 'zitadel-preview_*_linux_amd64.tar.gz' | head -1)"
           test -n "$TARBALL"
           tar -xzf "$TARBALL" -C .
           test -x ./nextgen
@@ -541,14 +541,14 @@ jobs:
 
       - name: Dry-run npm packs
         run: |
-          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt; do
+          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt packages/sdk-react packages/sdk-vue packages/sdk-angular; do
             corepack pnpm --dir "$dir" pack --dry-run
           done
 
       - name: Create npm package artifacts
         run: |
           mkdir -p "$RUNNER_TEMP/zitadel-npm-packages"
-          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt; do
+          for dir in apps/cli packages/api packages/components packages/sdk-core packages/sdk-next packages/sdk-nuxt packages/sdk-react packages/sdk-vue packages/sdk-angular; do
             corepack pnpm --dir "$dir" pack --pack-destination "$RUNNER_TEMP/zitadel-npm-packages"
           done
           ls -lh "$RUNNER_TEMP/zitadel-npm-packages"

.github/workflows/release-npm.yml

@@ -7,10 +7,12 @@ name: release-npm
 # merging that PR publishes to npm.
 #
 # The repo is in changesets PRERELEASE mode (.changeset/pre.json, tag "alpha"),
-# so versions are cut as X.Y.Z-alpha.N and published under the `alpha` npm
+# so versions are cut as X.Y.Z-alpha.N and published under the `preview` npm
 # dist-tag — `npm install @zitadel/cli` keeps resolving the last stable
-# `latest`; consumers opt into prereleases with `@zitadel/cli@alpha`. Run
+# `latest`; consumers opt into preview bundles with `@zitadel/cli@preview`. Run
 # `pnpm changeset pre exit` to leave alpha and cut a stable `latest` release.
+# The publish wrapper checks .changeset/pre.json: prereleases publish with
+# `--tag preview`; stable releases use Changesets' default dist-tag.
 #
 # Authentication uses npm trusted publishing (OIDC) — there is no NPM_TOKEN.
 # A maintainer must configure the trusted publisher for each public package
@@ -88,12 +90,14 @@ jobs:
         run: corepack pnpm nx run-many -t build
 
       - name: Create release PR or publish to npm
+        id: changesets
         uses: changesets/action@v1
         with:
           version: corepack pnpm changeset version
-          publish: corepack pnpm changeset publish
+          publish: node scripts/publish-changesets.mjs
           title: "chore: version packages"
           commit: "chore: version packages"
+          createGithubReleases: false
         env:
           # App token (not GITHUB_TOKEN) so the Version Packages PR triggers CI.
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

.github/workflows/release.yml

@@ -59,6 +59,10 @@ jobs:
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 
+      - name: Verify preview bundle versions
+        if: ${{ ! inputs.snapshot }}
+        run: node scripts/verify-preview-release.mjs --tag "${{ inputs.ref }}"
+
       - name: Login to GHCR
         if: ${{ ! inputs.snapshot }}
         uses: docker/login-action@v4

.goreleaser.yaml

@@ -32,7 +32,7 @@ archives:
     format_overrides:
       - goos: windows
         formats: [zip]
-    name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}'
+    name_template: 'zitadel-preview_{{ .Version }}_{{ .Os }}_{{ .Arch }}'
     files:
       - LICENSE
       - README.md
@@ -41,11 +41,14 @@ dockers_v2:
   - id: nextgen
     ids: [nextgen]
     images:
+      - 'ghcr.io/zitadel/zitadel-preview'
+      # Temporary compatibility alias while the repository is still named nextgen.
       - 'ghcr.io/zitadel/nextgen'
     tags:
       - '{{ .Version }}'
-      # Skip `latest` for snapshots so they don't clobber the published tag.
-      - '{{ if not .IsSnapshot }}latest{{ end }}'
+      # The public moving prerelease channel is `preview`; never publish
+      # prerelease artifacts to Docker `latest`.
+      - '{{ if not .IsSnapshot }}preview{{ end }}'
     platforms:
       - linux/amd64
       - linux/arm64
@@ -69,4 +72,5 @@ changelog:
   use: github
 
 release:
+  name_template: 'ZITADEL Preview {{ .Version }}'
   draft: true

AGENTS.md

@@ -49,8 +49,9 @@ Secrets").
   Playwright project. It installs local package tarballs through a temporary
   registry and verifies CLI setup plus real registration/login flows.
 - `packages/components/` contains shared Lit components.
-- `packages/sdk-core/`, `packages/sdk-next/`, and `packages/sdk-nuxt/` contain
-  public TypeScript SDKs.
+- `packages/sdk-core/`, `packages/sdk-next/`, `packages/sdk-nuxt/`,
+  `packages/sdk-react/`, `packages/sdk-vue/`, and `packages/sdk-angular/`
+  contain public TypeScript SDKs.
 - `packages/api-mock/` contains the in-process MSW handlers and standalone
   mock auth server used by demos and e2e tests.
 - `packages/lint/` contains the local Nx plugin that infers Oxlint targets.
@@ -74,12 +75,12 @@ Secrets").
 
 | I want to...                      | Run                                                            |
 | --------------------------------- | -------------------------------------------------------------- |
-| Check local runtime prerequisites | `npx @zitadel/cli@alpha doctor`                                |
-| Start local Zitadel               | `npx @zitadel/cli@alpha start`                                 |
-| Add auth to Next.js               | `npx @zitadel/cli@alpha setup --framework next --server local` |
-| Check generated app files         | `npx @zitadel/cli@alpha doctor`                                |
-| Stop local Zitadel, keeping data  | `npx @zitadel/cli@alpha stop`                                  |
-| Delete local Zitadel data         | `npx @zitadel/cli@alpha reset --force`                         |
+| Check local runtime prerequisites | `npx @zitadel/cli@preview doctor`                              |
+| Start local Zitadel               | `npx @zitadel/cli@preview start`                               |
+| Add auth to Next.js               | `npx @zitadel/cli@preview setup --framework next --server local` |
+| Check generated app files         | `npx @zitadel/cli@preview doctor`                              |
+| Stop local Zitadel, keeping data  | `npx @zitadel/cli@preview stop`                                |
+| Delete local Zitadel data         | `npx @zitadel/cli@preview reset --force`                       |
 
 `corepack pnpm run server` is a repository contributor command that runs the Go
 server from source. `zitadel start` is a published product CLI command that
@@ -213,7 +214,8 @@ For customer-local runtime workflows, agents should prefer
 - User-visible changes to a public npm package need a changeset. The public
   packages are `@zitadel/cli` (`apps/cli/`), `@zitadel/api`,
   `@zitadel/components`, `@zitadel/sdk-core`, `@zitadel/sdk-next`, and
-  `@zitadel/sdk-nuxt`. CI fails a PR that touches them without one
+  `@zitadel/sdk-nuxt`, `@zitadel/sdk-react`, `@zitadel/sdk-vue`, and
+  `@zitadel/sdk-angular`. CI fails a PR that touches them without one
   (`changeset-check` in `.github/workflows/ci.yml`).
 - Add a changeset by writing the file directly — do not depend on the
   interactive `pnpm changeset` prompt. Create `.changeset/<short-slug>.md`:
@@ -227,9 +229,9 @@ For customer-local runtime workflows, agents should prefer
   ```
 
   List only public package names; pick `patch` (fixes), `minor` (features), or
-  `major` (breaking). The repo is in `alpha` prerelease mode
-  (`.changeset/pre.json`), so versions cut as `X.Y.Z-alpha.N` automatically — no
-  extra action needed.
+  `major` (breaking). The repo is in `alpha` prerelease mode for version
+  suffixes (`.changeset/pre.json`), while npm publishing uses the `preview`
+  dist-tag for the community-testable bundle.
 
 - For changes that release nothing (docs, tests, CI, chores), add an empty
   changeset: `corepack pnpm changeset --empty`.

CONTRIBUTING.md

@@ -24,11 +24,11 @@
 
 | I want to...                      | Run                                                            |
 | --------------------------------- | -------------------------------------------------------------- |
-| Check local runtime prerequisites | `npx @zitadel/cli@alpha doctor`                                |
-| Start local Zitadel               | `npx @zitadel/cli@alpha start`                                 |
-| Add auth to Next.js               | `npx @zitadel/cli@alpha setup --framework next --server local` |
-| Stop local Zitadel, keeping data  | `npx @zitadel/cli@alpha stop`                                  |
-| Delete local Zitadel data         | `npx @zitadel/cli@alpha reset --force`                         |
+| Check local runtime prerequisites | `npx @zitadel/cli@preview doctor`                              |
+| Start local Zitadel               | `npx @zitadel/cli@preview start`                               |
+| Add auth to Next.js               | `npx @zitadel/cli@preview setup --framework next --server local` |
+| Stop local Zitadel, keeping data  | `npx @zitadel/cli@preview stop`                                |
+| Delete local Zitadel data         | `npx @zitadel/cli@preview reset --force`                       |
 
 Nx manages TypeScript workspace targets. Go commands and long-running local
 orchestration run through repository scripts so server processes are signaled