From 828d2130d0bcc9e1d78fcec3956e048b9dca0acc Mon Sep 17 00:00:00 2001
From: Aegis <Aegis@stackbilt.dev>
Date: Tue, 2 Jun 2026 07:33:56 -0500
Subject: [PATCH] fix: restore release publish auth fallback

Keep npm trusted publishing as the preferred release path, but make the tag
workflow use NPM_TOKEN when the secret exists so publish does not depend on
npmjs.org trusted-publisher configuration being complete. Document both auth
paths for the next release.

Governed-By: aegis-oss#51
Resolves-Request: aegis-oss#51
---
 .github/workflows/release.yml | 14 +++++++++--
 README.md                     |  1 +
 docs/publishing.md            | 45 +++++++++++++++++++++++++++++++++++
 3 files changed, 58 insertions(+), 2 deletions(-)
 create mode 100644 docs/publishing.md

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a8d3730..1cb70e6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -19,8 +19,9 @@ jobs:
 
       - uses: actions/setup-node@v6
         with:
-          node-version: '22'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
+          package-manager-cache: false
 
       - name: Install dependencies
         working-directory: web
@@ -36,4 +37,13 @@ jobs:
 
       - name: Publish
         working-directory: web
-        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          if [ -n "${NODE_AUTH_TOKEN:-}" ]; then
+            echo "Publishing with NPM_TOKEN fallback and provenance."
+            npm publish --provenance --access public
+          else
+            echo "Publishing with npm trusted publishing (OIDC)."
+            npm publish --access public
+          fi
diff --git a/README.md b/README.md
index 03ed61a..5157d59 100644
--- a/README.md
+++ b/README.md
@@ -241,6 +241,7 @@ AEGIS pairs with other Stackbilt open-source tools:
 - [Configuration](docs/configuration.md) — Full operator config reference
 - [Memory System](docs/memory-system.md) — Memory tiers, consolidation, and dreaming cycle
 - [Connecting MCP Clients](docs/connecting-mcp-clients.md) — OpenClaw, Claude Desktop, Claude Code, Cursor, and any MCP client
+- [Publishing](docs/publishing.md) — Release workflow, npm trusted publishing, and token fallback
 
 ## Contributing
 
diff --git a/docs/publishing.md b/docs/publishing.md
new file mode 100644
index 0000000..be746ec
--- /dev/null
+++ b/docs/publishing.md
@@ -0,0 +1,45 @@
+# Publishing
+
+`@stackbilt/aegis-core` is published from `web/` by the tag-triggered GitHub Actions workflow in `.github/workflows/release.yml`.
+
+## Release trigger
+
+Push a semver tag from `main`:
+
+```bash
+git tag v0.6.6
+git push origin v0.6.6
+```
+
+The workflow installs dependencies, runs typecheck/tests, then publishes `web/package.json` to npm.
+
+## Authentication modes
+
+The workflow supports two publish paths.
+
+### Preferred: npm trusted publishing
+
+Configure npm trusted publishing for package `@stackbilt/aegis-core`:
+
+- Provider: GitHub Actions
+- Repository: `Stackbilt-dev/aegis-oss`
+- Workflow filename: `release.yml`
+- Environment: unset unless the workflow is updated to use a GitHub environment
+
+When trusted publishing is active, the workflow publishes with `npm publish --access public`. npm automatically emits provenance for public packages published from public GitHub-hosted runners.
+
+### Fallback: npm automation token
+
+Until trusted publishing is configured and verified, set the GitHub Actions secret `NPM_TOKEN` to a package-scoped npm automation token that can publish `@stackbilt/aegis-core`.
+
+When `NPM_TOKEN` is present, the workflow publishes with token auth:
+
+```bash
+npm publish --provenance --access public
+```
+
+Keep `id-token: write` in the workflow permissions so provenance can still be generated for the token-auth fallback.
+
+## Validation
+
+A release is considered healthy when the tag-triggered workflow completes green and npm shows the tagged `web/package.json` version for `@stackbilt/aegis-core`.