chore(release): prepare npm publishing switch

.changeset/README.md

@@ -108,10 +108,9 @@ because they change no publishable package.
   `rsc-markdown-stream: workspace:^` edge republishes it with the renderer's
   new caret. The scaffolder's two optional `workspace:*` peers patch-bump and
   republish it whenever either member of its exact release pair moves.
-- `access` stays `"restricted"` at the repository level until the release
-  owner decides the npm package names and access policy
-  (`docs/preview-packages.md`). `@agent-bundle/runtime` and
-  `create-agent-bundle` already override it with `publishConfig.access`.
+- `access` is `"public"` at the repository level, and every publishable
+  package uses `publishConfig.access: "public"`. The scoped
+  `@agent-bundle/runtime` package must keep that explicit override.
 
 ## Release flow
 
@@ -149,5 +148,25 @@ because they change no publishable package.
    npm provenance (`NPM_CONFIG_PROVENANCE=true`, `id-token: write`) and
    creates GitHub releases and tags.
 
+## Enabling npm publishing
+
+The `agent-bundle` name on npm belongs to an unrelated project. Complete a
+transfer or choose a different package name, and create or confirm control of
+the `@agent-bundle` npm scope, before enabling this workflow; otherwise
+`changeset publish` can leave a partial four-package release.
+
+1. Create an npm granular access token for CI with **Read and write (publish
+   and stage)**, **Bypass 2FA**, and the **All packages** grant so it can
+   publish `agent-bundle`, `create-agent-bundle`, `rsc-markdown-stream`, and
+   the `@agent-bundle` scope; set it as the repository secret `NPM_TOKEN`.
+2. Set the repository variable `AGENT_BUNDLE_NPM_PUBLISH=true`.
+3. Merge the Version Packages pull request.
+
+After step 2, keep `main` unchanged until step 3: any intervening push runs
+registry verification and is red while the versioned packages are absent.
+
+If publishing does not happen, **Verify published registry artifacts** fails
+on any package version that `npm view` cannot resolve.
+
 Until publishing is enabled, installable previews come from pkg.pr.new
 (`pnpm preview:publish`, `docs/preview-packages.md`).

.changeset/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/@changesets/config@4.0.0/schema.json",
-  "access": "restricted",
+  "access": "public",
   "baseBranch": "main",
   "bumpVersionsWithWorkspaceProtocolOnly": true,
   "changedFilePatterns": ["**", "!tests/**"],

.github/workflows/release.yml

@@ -30,8 +30,8 @@ jobs:
     timeout-minutes: 60
     env:
       # npm publishing is opt-in and off by default: previews ship through
-      # pkg.pr.new (docs/preview-packages.md) until the package-name and
-      # access decisions are made. Set the repository variable
+      # pkg.pr.new (docs/preview-packages.md) until npm ownership of the
+      # package names is resolved. Set the repository variable
       # AGENT_BUNDLE_NPM_PUBLISH=true *and* the NPM_TOKEN secret to let the
       # action run `pnpm release` (release gates + `changeset publish`) when
       # the Version Packages PR merges. While off, the action still opens and

docs/preview-packages.md

@@ -1,16 +1,14 @@
 # Preview packages (pkg.pr.new)
 
-Nothing is published to npm yet, deliberately: the current package names are
-placeholders, and npm publishing is deferred until the final name is chosen
-(it will then use [npm package provenance](https://docs.npmjs.com/generating-provenance-statements);
-the publish step exports `NPM_CONFIG_PROVENANCE=true` and runs the packed
-release gates before `changeset publish`, and only runs at all when the
+Automated npm publishing is not enabled. It will use
+[npm package provenance](https://docs.npmjs.com/generating-provenance-statements);
+the publish step exports `NPM_CONFIG_PROVENANCE=true`, runs the packed release
+gates before `changeset publish`, and only runs when the
 `AGENT_BUNDLE_NPM_PUBLISH` repository variable is `true` — see "How an npm
-release will flow" below). Before enabling that path, the
-release owner must resolve the repository-wide `"access": "restricted"`
-policy for `agent-bundle`, which does not currently override it with
-`publishConfig.access`. Until then
-pkg.pr.new is the release channel. Every CI package-preview run publishes real,
+release will flow" below. All publishable packages use public access, but the
+`agent-bundle` name on npm belongs to an unrelated project; complete a transfer
+or choose another name before enabling publication. Until then, pkg.pr.new is
+the release channel. Every CI package-preview run publishes real,
 installable tarballs of all four publishable workspace packages (`agent-bundle`,
 `@agent-bundle/runtime`, `rsc-markdown-stream`, `create-agent-bundle`) to
 [pkg.pr.new](https://pkg.pr.new)

packages/agent-bundle/README.md

@@ -1160,6 +1160,6 @@ Run the complete local delivery gate with `pnpm check && pnpm check:release`.
 `pnpm pack:dry-run`, `pnpm lint:release`, and `pnpm test:packed:release`, and it does not replace
 `pnpm check`. `pnpm release` runs that release gate before `changeset publish`.
 Native Claude/Codex smokes stay intentionally opt-in and skipped in ordinary CI.
-npm publishing is deferred until the release owner picks the final package name/scope;
-pkg.pr.new previews are the interim channel, and the first npm release will use npm
-package provenance (`publishConfig.provenance` is already set).
+Automated npm publishing is opt-in; pkg.pr.new previews remain the CI release channel until the
+repository owner resolves the unrelated package currently using the `agent-bundle` name and
+enables it. npm releases use public access and package provenance.

packages/agent-bundle/package.json

@@ -18,6 +18,7 @@
     "url": "git+https://github.com/ScriptedAlchemy/agent-bundle.git"
   },
   "publishConfig": {
+    "access": "public",
     "provenance": true
   },
   "type": "module",

website/docs/en/guide/distribution/preview-packages.mdx

@@ -1,14 +1,12 @@
 ---
-description: 'The pkg.pr.new preview channel that stands in for npm: how previews are published, how to pin them, and what changes at the first npm release.'
+description: 'The pkg.pr.new preview channel that stands in for npm: how previews are published, how to pin them, and how automated publishing is enabled.'
 ---
 
 # Preview packages
 
-Nothing is published to npm yet, deliberately. The current package names are placeholders, and
-npm publishing is deferred until the final name is chosen. Until then, **pkg.pr.new is the
-release channel**: every CI package-preview run publishes real, installable tarballs of all four
-publishable workspace packages to a free continuous-release registry keyed by commit SHA and pull
-request.
+Automated npm publishing is not enabled yet. Until it is, **pkg.pr.new is the CI release
+channel**: every package-preview run publishes real, installable tarballs of all four publishable
+workspace packages to a free continuous-release registry keyed by commit SHA and pull request.
 
 The install commands and the runtime pairing rule are in
 [Installation](../start/installation.mdx). This page is the channel itself: where previews come
@@ -59,16 +57,26 @@ npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha-or-
 A scaffolded project pins `agent-bundle` to the preview of the same commit the scaffolder came
 from, so both sides of the pairing rule hold automatically.
 
-## What changes at the first npm release
+## Enabling npm publishing
 
-The first npm release will use
+Automated npm releases use
 [npm package provenance](https://docs.npmjs.com/generating-provenance-statements): the publish
 step exports `NPM_CONFIG_PROVENANCE=true` and runs the packed release gates before
-`changeset publish`. `publishConfig.provenance` is already set.
+`changeset publish`. Every publishable package sets `publishConfig.provenance` and public access.
 
-Before that path is enabled, the release owner has to resolve two things: the final package name
-and license, and the repository-wide `"access": "restricted"` policy for `agent-bundle`, which is
-not currently overridden with `publishConfig.access`.
+The `agent-bundle` name on npm belongs to an unrelated project. Complete a transfer or choose a
+different package name, and create or confirm control of the `@agent-bundle` npm scope, before
+enabling this workflow; otherwise `changeset publish` can leave a partial four-package release.
+
+1. Create an npm granular access token for CI with **Read and write (publish and stage)** and
+   **Bypass 2FA** and the **All packages** grant so it can publish `agent-bundle`,
+   `create-agent-bundle`, `rsc-markdown-stream`, and the `@agent-bundle` scope; set it as the
+   repository secret `NPM_TOKEN`.
+2. Set the repository variable `AGENT_BUNDLE_NPM_PUBLISH=true`.
+3. Merge the Version Packages pull request.
+
+After step 2, keep `main` unchanged until step 3: any intervening push runs registry verification
+and is red while the versioned packages are absent.
 
 The `Release packages` workflow records one of `version-maintenance-only`,
 `published`, or `failed`, with executed and skipped stages. Qualification runs against the exact versioned candidate SHA, not the
@@ -77,7 +85,8 @@ refreshes that PR nor qualifies a versioned candidate — is
 `version-maintenance-only`. A Version Packages merge, and every `main` push while
 publishing is enabled, must end with each publishable `package.json` version resolving on
 npm (`scripts/verify-registry-versions.sh`); otherwise the run is `failed` and
-**NOT PUBLISHED**.
+**NOT PUBLISHED**. If publishing does not happen, **Verify published registry artifacts** fails
+on any package version that `npm view` cannot resolve.
 
 `pnpm release` runs the release gate — `pnpm pack:dry-run`, `pnpm lint:release`, and
 `pnpm test:packed:release` — before publishing. `lint:release` runs `attw` with the `esm-only`

website/docs/en/guide/start/installation.mdx

@@ -100,8 +100,9 @@ compiler may be `0.2.0` while its runtime is `0.1.0`. A runtime-bearing template
 Local compiler tarballs use the recorded runtime version in the sibling tarball name and verify
 both packed manifests before writing the project.
 
-The first npm release will use npm package provenance. Until the release owner picks the final
-package name and license, pkg.pr.new previews are the release channel.
+The first automated npm release will use package provenance. Until the release owner resolves the
+unrelated project that currently owns the `agent-bundle` name, pkg.pr.new previews are the release
+channel.
 
 ## Verify the install
 

website/docs/zh/guide/distribution/preview-packages.mdx

@@ -1,11 +1,10 @@
 ---
-description: '代替 npm 的 pkg.pr.new 预览通道：预览包如何发布、如何固定版本，以及首个 npm 版本发布后会发生什么变化。'
+description: '代替 npm 的 pkg.pr.new 预览通道：预览包如何发布、如何固定版本，以及如何启用自动发布。'
 ---
 
 # 预览包
 
-目前尚未向 npm 发布任何内容，这是刻意为之。现有的包名只是占位符，npm 发布被推迟到最终包名确定之后。
-在那之前，**pkg.pr.new 就是发布通道**：每次 CI 的 package-preview 运行都会把全部四个可发布的工作区包
+自动 npm 发布尚未启用。在启用之前，**pkg.pr.new 是 CI 发布通道**：每次 package-preview 运行都会把全部四个可发布的工作区包
 以真实、可安装的 tarball 形式发布到一个按 commit SHA 与 pull request 索引的免费持续发布注册表。
 
 安装命令与 runtime 配对规则在[安装](../start/installation.mdx)中。本页讲的是通道本身：预览包从哪里来、
@@ -50,22 +49,33 @@ npx https://pkg.pr.new/ScriptedAlchemy/agent-bundle/create-agent-bundle@<sha-or-
 脚手架生成的项目会把 `agent-bundle` 固定到脚手架自身所来自的那个提交的预览版本，因此上述配对规则的
 两侧会自动成立。
 
-## 首个 npm 版本发布后会发生什么变化
+## 启用 npm 发布
 
-首个 npm 版本将使用
+自动 npm 发布使用
 [npm package provenance](https://docs.npmjs.com/generating-provenance-statements)：发布步骤会导出
 `NPM_CONFIG_PROVENANCE=true`，并在 `changeset publish` 之前运行打包发布门禁。
-`publishConfig.provenance` 已经设置好了。
+每个可发布包都设置了 `publishConfig.provenance` 和公开访问权限。
 
-在启用这条路径之前，发布负责人必须解决两件事：最终的包名与许可证，以及 `agent-bundle` 仓库层面的
-`"access": "restricted"` 策略——目前它并没有被 `publishConfig.access` 覆盖。
+npm 上的 `agent-bundle` 名称属于一个无关项目。启用此工作流之前，必须完成名称转让或选择其他包名，
+并创建或确认对 `@agent-bundle` npm scope 的控制权；否则 `changeset publish` 可能只发布四个包中的一部分。
+
+1. 为 CI 创建一个 npm granular access token，并启用 **Read and write (publish and stage)**
+   与 **Bypass 2FA**，同时使用 **All packages** 授权，使其能够发布 `agent-bundle`、
+   `create-agent-bundle`、`rsc-markdown-stream` 和 `@agent-bundle` scope；将其设置为仓库
+   secret `NPM_TOKEN`。
+2. 设置仓库变量 `AGENT_BUNDLE_NPM_PUBLISH=true`。
+3. 合并 Version Packages pull request。
+
+完成第 2 步后，在第 3 步之前不要更改 `main`：只要版本化包还不在 npm 上，任何中间推送都会运行
+注册表验证并显示为红色。
 
 `Release packages` 工作流会记录 `version-maintenance-only`、`published` 或 `failed` 之一，
 并列出已执行与已跳过的阶段。资格认定针对精确的版本化候选
 SHA，而不是预版本的 main 提交。成功刷新 Version Packages PR，或既没有刷新该 PR 也没有对版本化候选做资格认定的
 `main` 推送，结果都是 `version-maintenance-only`。合并 Version Packages 之后，以及启用发布期间的每次 `main`
 推送，都必须以每个可发布包的 `package.json` 版本在 npm 上可解析结束（`scripts/verify-registry-versions.sh`）；
-否则该次运行为 `failed` 并写明 **NOT PUBLISHED**。
+否则该次运行为 `failed` 并写明 **NOT PUBLISHED**。如果发布没有发生，
+**Verify published registry artifacts** 会在任何无法通过 `npm view` 解析的包版本上失败。
 
 `pnpm release` 会在发布之前运行发布门禁 —— `pnpm pack:dry-run`、`pnpm lint:release` 与
 `pnpm test:packed:release`。`lint:release` 先对打包后的 `agent-bundle`、`@agent-bundle/runtime`、`rsc-markdown-stream` 与

website/docs/zh/guide/start/installation.mdx

@@ -88,8 +88,8 @@ peer。`npm create` 会分别固定这两个记录值，而不是把 compiler 
 `--framework-version`；此时应安装与 compiler 匹配的脚手架版本。本地 compiler tarball 会在相邻
 runtime tarball 的文件名中使用记录的 runtime 版本，并在写入项目之前校验两个包的清单。
 
-首个 npm 版本将使用 npm package provenance。在发布负责人确定最终包名与许可证之前，pkg.pr.new 预览
-就是发布通道。
+首个自动 npm 版本将使用 package provenance。在发布负责人解决当前占用 `agent-bundle` 名称的无关项目
+之前，pkg.pr.new 预览就是发布通道。
 
 ## 验证安装