fix: restore release publish auth fallback

.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

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
 

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`.