commoncurriculum · Copilot · Oct 13, 2025 · Oct 13, 2025 · Oct 13, 2025 · Oct 13, 2025
diff --git a/DEBUG_REPORT.md b/DEBUG_REPORT.md
@@ -0,0 +1,164 @@
+# Debug Report: Release Job Failure
+
+**Date**: October 13, 2025  
+**Issue**: Release workflow failing with 404 error when publishing to NPM  
+**Status**: ✅ Diagnosed and documented with comprehensive fix guide
+
+---
+
+## Executive Summary
+
+Your release job is failing because NPM cannot access the `@supergrain` organization to publish packages. This is a configuration issue, not a code issue. The workflow, package setup, and code are all correct.
+
+## Error Details
+
+**Workflow Run**: https://github.com/commoncurriculum/supergrain/actions/runs/18472079034
+
+**Error Message**:
+```
+npm error 404 Not Found - PUT https://registry.npmjs.org/@supergrain%2fcore
+npm error 404 The requested resource '@supergrain/[email protected]' could not be found 
+             or you do not have permission to access it.
+```
+
+## Root Cause Analysis
+
+The 404 error indicates one of three problems:
+
+1. **NPM Organization Missing** (Most likely)
+   - The `@supergrain` organization doesn't exist on npmjs.com
+   - Solution: Create it at https://www.npmjs.com/org/create
+
+2. **NPM Token Issues**
+   - Token is wrong type (needs to be "Automation", not "Publish")
+   - Token doesn't have access to `@supergrain` organization
+   - Token has expired
+   - Solution: Create new automation token with correct permissions
+
+3. **GitHub Secret Issues**
+   - `NPM_TOKEN` secret is missing or incorrect
+   - Solution: Update the secret with a valid automation token
+
+## What's Correct
+
+✅ **Workflow Configuration**: The `.github/workflows/publish.yml` is properly configured  
+✅ **Package Configuration**: All packages have correct `publishConfig.access: "public"`  
+✅ **Changesets Setup**: The `.changeset/config.json` is properly configured  
+✅ **Build Process**: All packages build successfully  
+✅ **Package Scope**: All packages correctly use `@supergrain/` scope
+
+## What You Need to Fix
+
+The issue is entirely with NPM organization and token setup. No code changes are needed.
+
+## Documentation Created
+
+I've created comprehensive documentation to help you fix this:
+
+### 🎯 Quick Start
+**[QUICK_FIX_SUMMARY.md](QUICK_FIX_SUMMARY.md)** (2.6 KB)
+- Fastest path to fixing the issue
+- Step-by-step instructions
+- 5-minute fix guide
+
+### 📖 Comprehensive Guide
+**[TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md)** (5.5 KB)
+- Detailed diagnosis steps
+- Solutions for every scenario
+- Local testing commands
+- FAQ and common issues
+
+### 📚 Updated Documentation
+- **README.md**: Added link to troubleshooting guide
+- **NPM_SETUP.md**: Added 404 error section with link to guide
+- **NPM_PUBLISHING_CHECKLIST.md**: Added troubleshooting section
+- **RELEASING.md**: Updated with prominent link to troubleshooting
+
+## Recommended Action Plan
+
+### Step 1: Check Organization (2 minutes)
+1. Visit https://www.npmjs.com/org/supergrain
+2. If you see 404: The organization doesn't exist
+3. If you see the org page: The organization exists, token is the issue
+
+### Step 2: Create/Fix Organization (3 minutes)
+**If organization doesn't exist:**
+1. Go to https://www.npmjs.com/org/create
+2. Enter `supergrain` as organization name
+3. Complete the creation process
+
+### Step 3: Create Automation Token (3 minutes)
+1. Go to https://www.npmjs.com/settings/[YOUR_USERNAME]/tokens
+2. Click "Generate New Token"
+3. **Critical**: Select "Automation" (not "Publish")
+4. Ensure "Read and Write" permissions
+5. Ensure access to `@supergrain` organization
+6. Copy the token
+
+### Step 4: Update GitHub Secret (2 minutes)
+1. Go to https://github.com/commoncurriculum/supergrain/settings/secrets/actions
+2. Find or create `NPM_TOKEN`
+3. Paste your new automation token
+4. Save
+
+### Step 5: Test (2 minutes)
+1. Go to https://github.com/commoncurriculum/supergrain/actions/workflows/publish.yml
+2. Click "Run workflow"
+3. Select branch: `main`
+4. Click "Run workflow"
+5. Verify it succeeds
+
+**Total Time**: ~12 minutes
+
+## Common Mistakes to Avoid
+
+❌ Using "Publish" token instead of "Automation"  
+❌ Token without "Read and Write" permissions  
+❌ Token without access to the organization  
+❌ Not creating the organization first  
+❌ Expired token  
+
+## Testing Your Setup Locally
+
+You can verify your token works before updating the GitHub secret:
+
+```bash
+# Set up your token locally (replace YOUR_TOKEN)
+echo "//registry.npmjs.org/:_authToken=YOUR_TOKEN" > ~/.npmrc
+
+# Test organization access
+npm access ls-packages @supergrain
+
+# Test publishing (dry run)
+cd packages/core
+npm publish --dry-run
+```
+
+If these commands work, your token is correct and will work in GitHub Actions.
+
+## Next Steps
+
+1. **Start with**: [QUICK_FIX_SUMMARY.md](QUICK_FIX_SUMMARY.md)
+2. **If you need more details**: [TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md)
+3. **After fixing**: Test the workflow to ensure it works
+4. **For future releases**: Follow [RELEASING.md](RELEASING.md)
+
+## Support
+
+If you're still having issues after following the guides:
+
+1. Check the full error logs in GitHub Actions
+2. Try the local testing commands above
+3. Verify each step in [TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md)
+4. Check that your token hasn't expired
+5. Ensure you're an admin/owner of the `@supergrain` organization
+
+## Summary
+
+**Problem**: NPM cannot access `@supergrain` organization  
+**Cause**: Missing organization or incorrect token setup  
+**Fix Time**: ~12 minutes  
+**Fix Complexity**: Easy (no code changes needed)  
+**Success Rate**: High (clear steps with verification)
+
+The release workflow itself is correct and will work once the NPM setup is fixed.
diff --git a/NPM_PUBLISHING_CHECKLIST.md b/NPM_PUBLISHING_CHECKLIST.md
@@ -74,6 +74,11 @@ If something goes wrong, check:
 3. **Token expiration** - Check if your NPM token is still valid
 4. **NPM_SETUP.md** - Review the troubleshooting section
 
+### 🔴 Release Job Failing?
+
+If you're seeing **404 errors** or other NPM publish failures, see:
+📖 **[TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md)** - Comprehensive debugging guide
+
 Common issues and solutions are documented in [NPM_SETUP.md](NPM_SETUP.md#troubleshooting).
 
 ## 🎉 Success!

diff --git a/NPM_SETUP.md b/NPM_SETUP.md
@@ -133,6 +133,11 @@ Once the token is added, the publishing workflow is ready! To test:
 
 ## Troubleshooting
 
+### Release Job Failing with 404 Error?
+
+**If you're seeing NPM publish failures**, see the comprehensive debugging guide:
+📖 **[TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md)** - Step-by-step diagnosis and fixes
+
 ### "402 Payment Required" Error
 
 This means you're trying to publish a scoped package without the proper NPM organization setup or token permissions. Make sure:
@@ -148,6 +153,16 @@ This means authentication failed or you don't have permission. Check:
 - The token has "Read and Write" permissions
 - You're an admin of the `@supergrain` organization
 
+### "404 Not Found" Error When Publishing
+
+This means NPM cannot access the `@supergrain` organization. Common causes:
+- The NPM organization `@supergrain` doesn't exist (create it at https://www.npmjs.com/org/create)
+- Your NPM token doesn't have access to the organization
+- Your token is the wrong type (must be "Automation", not "Publish")
+- Your token has expired
+
+**See [TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md) for detailed steps to fix this.**
+
 ### "404 Not Found" When Installing
 
 If users get 404 errors when trying to install, the packages might not be public. Verify:

diff --git a/QUICK_FIX_SUMMARY.md b/QUICK_FIX_SUMMARY.md
@@ -0,0 +1,79 @@
+# Quick Fix Summary - Release Job Failure
+
+## What's Wrong?
+
+Your release job is failing with this error:
+```
+npm error 404 Not Found - PUT https://registry.npmjs.org/@supergrain%2fcore
+```
+
+## What This Means
+
+NPM cannot access the `@supergrain` organization to publish packages. This is **not a code issue** - it's a configuration issue with your NPM setup.
+
+## What You Need to Do
+
+### Option 1: Quick Check (5 minutes)
+
+1. **Visit**: https://www.npmjs.com/org/supergrain
+   - If you see 404: The organization doesn't exist → Go to Option 2
+   - If you see the org: The token is wrong → Go to Option 3
+
+### Option 2: Create the NPM Organization (if it doesn't exist)
+
+1. Go to https://www.npmjs.com/org/create
+2. Enter `supergrain` as the organization name
+3. Complete the creation
+4. Then proceed to Option 3 to set up your token
+
+### Option 3: Fix Your NPM Token
+
+The issue is likely that your NPM token is missing, wrong type, or doesn't have access.
+
+**Quick fix:**
+
+1. **Create a NEW token**:
+   - Go to https://www.npmjs.com/settings/[YOUR_USERNAME]/tokens
+   - Click "Generate New Token"
+   - Select **"Automation"** (this is critical!)
+   - Ensure it has **Read and Write** permissions
+   - Ensure it has access to the `@supergrain` organization
+   - Copy the token (you won't see it again!)
+
+2. **Update GitHub Secret**:
+   - Go to https://github.com/commoncurriculum/supergrain/settings/secrets/actions
+   - Find `NPM_TOKEN` and click "Update" (or create new if it doesn't exist)
+   - Paste your new token
+   - Click "Update secret"
+
+3. **Test it**:
+   - Go to https://github.com/commoncurriculum/supergrain/actions/workflows/publish.yml
+   - Click "Run workflow"
+   - Select branch: `main`
+   - Click "Run workflow"
+   - It should now succeed!
+
+## Need More Help?
+
+See the comprehensive troubleshooting guide:
+📖 **[TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md)**
+
+This guide includes:
+- Detailed diagnosis steps
+- How to verify each part of your setup
+- Commands to test your token locally
+- Solutions for every possible issue
+
+## Common Mistakes
+
+❌ **Wrong token type**: Must be "Automation", not "Publish"
+❌ **Wrong permissions**: Must have "Read and Write"
+❌ **No org access**: Token must have access to `@supergrain`
+❌ **Expired token**: Check the expiration date
+
+## Still Stuck?
+
+If you've followed these steps and it's still not working:
+1. Check the full error logs in the GitHub Actions tab
+2. Review [TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md) for detailed steps
+3. Try the local testing commands in the troubleshooting guide
diff --git a/README.md b/README.md
@@ -906,8 +906,9 @@ This project uses [Changesets](https://github.com/changesets/changesets) for aut
 GitHub Actions automatically handles versioning, changelogs, and publishing to NPM.
 
 **Documentation:**
-- [NPM_SETUP.md](NPM_SETUP.md) - Complete guide for setting up NPM publishing (tokens, scoped packages, troubleshooting)
 - [RELEASING.md](RELEASING.md) - Step-by-step instructions for creating releases
+- [NPM_SETUP.md](NPM_SETUP.md) - Complete guide for setting up NPM publishing (tokens, scoped packages)
+- [TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md) - 🔴 **Release failing? Start here for diagnosis and fixes**
 
 ## License
 

diff --git a/RELEASING.md b/RELEASING.md
@@ -161,9 +161,16 @@ All changesets will be combined into a single release PR.
 
 ## Troubleshooting
 
+### 🔴 Release Job Failing with 404 Error?
+
+If your release workflow is failing with NPM publish errors, see the comprehensive debugging guide:
+📖 **[TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md)** - Step-by-step diagnosis and fixes
+
+### Quick Fixes
+
 **"No changeset files found"**: You need to run `pnpm changeset` first to describe your changes.
 
-**NPM publish fails**: Check that `NPM_TOKEN` secret is set correctly in GitHub settings.
+**NPM publish fails**: Check that `NPM_TOKEN` secret is set correctly in GitHub settings. See [TROUBLESHOOTING_RELEASE.md](TROUBLESHOOTING_RELEASE.md) for detailed steps.
 
 **Wrong version bump**: Edit or delete the changeset file in `.changeset/` and create a new one.