Document npm package bootstrap publishing

.github/workflows/publish-codex-flows.yml

@@ -17,6 +17,8 @@ jobs:
     if: inputs.confirm_package == 'publish-codex-flow-packages'
     runs-on: ubuntu-latest
     environment: npm-publish
+    env:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -35,6 +37,10 @@ jobs:
       - name: Update npm
         run: npm install -g npm@^11.10.0
 
+      - name: Configure npm token
+        if: env.NPM_TOKEN != ''
+        run: npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"
+
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
@@ -48,7 +54,7 @@ jobs:
           if npm view "@peezy.tech/codex-flows@$version" version --json >/dev/null 2>&1; then
             echo "@peezy.tech/codex-flows@$version is already published"
           else
-            npm publish --access public
+            npm publish --access public --provenance
           fi
 
       - name: Publish @peezy.tech/flow-runtime
@@ -58,7 +64,7 @@ jobs:
           if npm view "@peezy.tech/flow-runtime@$version" version --json >/dev/null 2>&1; then
             echo "@peezy.tech/flow-runtime@$version is already published"
           else
-            npm publish --access public
+            npm publish --access public --provenance
           fi
 
       - name: Publish @peezy.tech/flow-backend-convex
@@ -68,5 +74,5 @@ jobs:
           if npm view "@peezy.tech/flow-backend-convex@$version" version --json >/dev/null 2>&1; then
             echo "@peezy.tech/flow-backend-convex@$version is already published"
           else
-            npm publish --access public
+            npm publish --access public --provenance
           fi

README.md

@@ -128,6 +128,12 @@ for package in packages/codex-client packages/flow-runtime packages/flow-backend
 done
 ```
 
+If first-publishing through GitHub Actions, add a short-lived `NPM_TOKEN` secret
+to the `npm-publish` environment before dispatching the workflow. The workflow
+uses that token when present and otherwise falls back to npm trusted publishing.
+After the first publish succeeds and package-level trusted publishing is
+configured, remove the bootstrap token.
+
 After the packages exist, configure npm trusted publishing for each public
 package:
 

docs/development-flow.md

@@ -100,8 +100,9 @@ To publish through GitHub trusted publishing:
 2. Commit and push to jojo.
 3. Confirm the Codeberg mirror has received the commit.
 4. Push the same commit to GitHub.
-5. Run `.github/workflows/publish-codex-flows.yml` on GitHub with confirmation input `publish-codex-flow-packages`.
-6. Verify npm:
+5. For a package name that has never existed on npm, either publish once with a human npm session or add a short-lived `NPM_TOKEN` secret to the `npm-publish` GitHub environment. Package-level trusted publishing can take over after the package exists.
+6. Run `.github/workflows/publish-codex-flows.yml` on GitHub with confirmation input `publish-codex-flow-packages`.
+7. Verify npm:
 
 ```bash
 npm dist-tag ls @peezy.tech/codex-flows