docs: update publish docs to reflect OIDC auth instead of NPM_TOKEN

Address PR review comments:
- Replace NPM_TOKEN references with npm OIDC setup instructions
- Fix platform names (linux-arm-gnu not linux-armv7-gnu)
- Add OIDC-specific failure scenarios in stress test
- Update manual steps with trusted publisher setup

Author: subtleGradient

.specs/publish/first/PREP/03-CONSTANTS.md

@@ -15,7 +15,8 @@
 ### C3: GitHub Repository
 - `effect-native/ansilust` exists
 - GitHub Actions enabled
-- GitHub Actions must be configured for npm OIDC authentication (no NPM_TOKEN secret required)
+- npm OIDC authentication configured (no NPM_TOKEN secret required)
+- Workflow has `permissions: id-token: write` for OIDC
 
 ### C4: Binary Works
 - Native build produces working binaries
@@ -68,7 +69,7 @@
 ## Immutable Dependencies
 
 ### For npm Publish
-1. NPM_TOKEN secret in GitHub Actions
+1. npm OIDC configured for effect-native org (trusted publisher)
 2. All platform packages created and ready
 3. launcher.js implemented
 4. optionalDependencies point to npm packages (not local files)

.specs/publish/first/PREP/04-STRESS-TEST.md

@@ -2,11 +2,17 @@
 
 ## What-If Scenarios
 
-### WIF-1: NPM_TOKEN Secret Missing
-**What if**: GitHub Actions runs but NPM_TOKEN isn't configured?
-**Impact**: npm publish fails, CI workflow breaks
-**Mitigation**: Check secrets before first release
-**Test**: `gh secret list` should show NPM_TOKEN
+### WIF-1: npm OIDC Not Configured
+**What if**: GitHub Actions runs but npm org doesn't have OIDC configured?
+**Impact**: npm publish fails with "No token available" error
+**Mitigation**: Configure trusted publisher in npm org settings
+**Test**: Check npm package settings show GitHub repo as trusted publisher
+
+### WIF-1b: id-token Permission Missing
+**What if**: Workflow doesn't have `permissions: id-token: write`?
+**Impact**: GitHub can't issue OIDC token, npm publish fails
+**Mitigation**: Ensure permission is set in release.yml (already done)
+**Test**: Check workflow YAML for `id-token: write`
 
 ### WIF-2: Platform Package Names Wrong
 **What if**: npm package names don't match what launcher expects?
@@ -86,7 +92,7 @@
 
 1. **CRITICAL**: launcher.js must exist and work
 2. **CRITICAL**: Platform package names must match exactly
-3. **HIGH**: All 10 platform packages must publish before meta
-4. **HIGH**: NPM_TOKEN must be configured
+3. **HIGH**: All 8 platform packages must publish before meta
+4. **HIGH**: npm OIDC must be configured (trusted publisher)
 5. **MEDIUM**: Cross-compilation must succeed for all targets
 6. **LOW**: Help/version flags in binary (nice to have)

.specs/publish/first/PREP/06-IMPACT-ASSESSMENT.md

@@ -13,10 +13,10 @@
 **Impact**: Cannot test global installation locally
 **Resolution**: Symlink directly in node_modules (works for testing)
 
-### FP3: NPM_TOKEN Not Verified
-**Issue**: Unknown if secret is configured in GitHub Actions
-**Impact**: Could fail on publish
-**Resolution**: Check via `gh secret list` before release
+### FP3: npm OIDC Not Configured
+**Issue**: npm org needs trusted publisher setup for OIDC
+**Impact**: Could fail on publish with auth error
+**Resolution**: Configure trusted publisher in npm org settings (see MANUAL-STEPS.md)
 
 ## What Works
 
@@ -68,16 +68,17 @@
    - Replace std.posix.isatty with cross-platform check
    - Replace std.posix.getenv with std.process.getEnvVarOwned
 
-2. **Verify NPM_TOKEN secret exists**
-   - `gh secret list` to check
+2. **Configure npm OIDC**
+   - Set up trusted publisher in npm org settings
+   - See MANUAL-STEPS.md for detailed instructions
 
 3. **Test CI workflow**
    - Push test tag to see if workflow runs
    - Fix any issues before real release
 
-4. **Update release.yml**
-   - Remove Windows target from build matrix (or handle failure gracefully)
-   - Add linux-i386-musl back when tested
+4. **Update release.yml** (DONE)
+   - Windows target removed from build
+   - Single runner builds all targets via Zig cross-compile
 
 5. **Create changeset and release**
    - `npx changeset add` - major bump to 1.0.0

.specs/publish/first/SPEC/MANUAL-STEPS.md

@@ -1,21 +1,31 @@
 # Manual Steps Required Before First Release
 
-## 1. Add NPM_TOKEN Secret to GitHub
+## 1. Configure npm OIDC Authentication
 
-### Option A: Via GitHub Web UI
-1. Go to https://github.com/effect-native/ansilust/settings/secrets/actions
-2. Click "New repository secret"
-3. Name: `NPM_TOKEN`
-4. Value: Your npm access token (get from https://www.npmjs.com/settings/~/tokens)
-5. Click "Add secret"
+The workflow uses npm OIDC authentication for publishing, which is more secure and does **not** require an `NPM_TOKEN` secret. Instead, GitHub Actions exchanges an OIDC token directly with npm.
 
-### Option B: Via gh CLI
-```bash
-# First, get an npm token from https://www.npmjs.com/settings/~/tokens
-# Choose "Automation" token type for CI/CD
-gh secret set NPM_TOKEN -R effect-native/ansilust
-# Paste your token when prompted
-```
+### Steps to Enable OIDC:
+
+1. **Go to npm organization settings**:
+   https://www.npmjs.com/settings/effect-native/packages
+
+2. **For each package**, enable "Require two-factor authentication or an automation token, or a token generated by a trusted publisher" under Publishing access
+
+3. **Link GitHub repository as trusted publisher**:
+   - Go to each package settings
+   - Under "Publishing access" → "Configure trusted publishers"
+   - Add `effect-native/ansilust` repository
+   - Select the `release.yml` workflow
+
+4. **Verify workflow has OIDC permissions** (already configured):
+   ```yaml
+   permissions:
+     id-token: write  # Required for npm OIDC
+   ```
+
+### References:
+- [npm OIDC docs](https://docs.npmjs.com/generating-provenance-statements)
+- [GitHub OIDC for npm](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers)
 
 ## 2. (Optional) Add AUR_SSH_KEY Secret
 

.specs/publish/first/SPEC/README.md

@@ -16,17 +16,17 @@ Pushed to: https://github.com/effect-native/ansilust/tree/feat/publish-v1
 
 ### What's Broken/Missing
 1. **Windows build fails** - POSIX API usage in code (deferred to v1.1.0)
-2. **NPM_TOKEN secret not configured** - see MANUAL-STEPS.md
+2. **npm OIDC not configured** - see MANUAL-STEPS.md for setup
 3. **AUR_SSH_KEY secret not configured** - can skip for v1.0.0
 4. **Platform packages created by CI** - assembly script ready
-5. **No GitHub release yet** - waiting on NPM_TOKEN
+5. **No GitHub release yet** - pending OIDC setup
 
 ### Critical Path to v1.0.0
 
 ```
-1. [MANUAL] Add NPM_TOKEN secret to GitHub repo
+1. [MANUAL] Configure npm OIDC for effect-native org (see MANUAL-STEPS.md)
 2. [MANUAL] Add AUR_SSH_KEY secret (or skip AUR for v1.0.0)
-3. [CODE]   Update release.yml to skip Windows target
+3. [CODE]   Update release.yml to skip Windows target (DONE)
 4. [CODE]   Create changeset for v1.0.0
 5. [CI]     Push, let changesets create version PR
 6. [MANUAL] Merge version PR
@@ -42,8 +42,8 @@ Pushed to: https://github.com/effect-native/ansilust/tree/feat/publish-v1
 | linux-x64-musl | READY | Alpine/containers |
 | linux-arm64-gnu | READY | RPi 4, Apple Silicon VMs |
 | linux-arm64-musl | READY | Alpine ARM |
-| linux-armv7-gnu | READY | RPi 2/3 |
-| linux-armv7-musl | READY | Older embedded |
+| linux-arm-gnu | READY | RPi 2/3 |
+| linux-arm-musl | READY | Older embedded |
 | darwin-x64 | READY | Intel Macs |
 | darwin-arm64 | READY | Apple Silicon |
 | win32-x64 | BLOCKED | POSIX API usage |
@@ -66,11 +66,11 @@ Pushed to: https://github.com/effect-native/ansilust/tree/feat/publish-v1
 
 ### Immediate Next Steps
 
-1. **[MANUAL]** Add NPM_TOKEN to GitHub secrets (see MANUAL-STEPS.md)
+1. **[MANUAL]** Configure npm OIDC (see MANUAL-STEPS.md)
 2. **[OPTIONAL]** Test release with `v0.0.2-test.1` tag
 3. **[MANUAL]** Create PR and merge feat/publish-v1 to main
 4. **[MANUAL]** Create changeset for v1.0.0
-5. **[AUTO]** Release workflow builds and publishes
+5. **[AUTO]** Release workflow builds and publishes (using OIDC provenance)
 
 ### Later (v1.1.0)