aiwg 2026.1.3 → 2026.1.5

package/CLAUDE.md

@@ -157,3 +157,40 @@ npm exec markdownlint-cli2 "**/*.md"
 
 <!-- TEAM DIRECTIVES: Add project-specific guidance below this line -->
 
+## Release Documentation Requirements
+
+**CRITICAL**: Every release MUST be documented in ALL of these locations:
+
+| Location | Purpose | Format |
+|----------|---------|--------|
+| `CHANGELOG.md` | Technical changelog | Keep a Changelog format with highlights table |
+| `docs/releases/vX.X.X-announcement.md` | Release announcement | Full feature documentation with examples |
+| `package.json` | Version bump | CalVer: `YYYY.MM.PATCH` |
+| GitHub Release | Public release notes | Condensed highlights + install instructions |
+| Gitea Release | Internal release notes | Same as GitHub |
+
+### Release Checklist
+
+Before pushing a version tag:
+
+1. **Update `package.json`** - Bump version following CalVer
+2. **Update `CHANGELOG.md`** - Add new version section with:
+   - Highlights table (What changed | Why you care)
+   - Detailed Added/Changed/Fixed sections
+   - Link to previous version
+3. **Create `docs/releases/vX.X.X-announcement.md`** - Full release document with:
+   - Feature highlights
+   - Code examples
+   - Migration notes (if applicable)
+   - Links to relevant documentation
+4. **Commit and tag** - `git tag -m "vX.X.X" vX.X.X`
+5. **Push to both remotes** - `git push origin main --tags && git push github main --tags`
+6. **Update GitHub Release** - Add proper release notes via `gh release edit`
+7. **Create Gitea Release** - Via MCP tool or web UI
+
+### Version Format
+
+- **CalVer**: `YYYY.MM.PATCH` (e.g., `2026.01.3`)
+- PATCH resets each month
+- Tag format: `vYYYY.MM.PATCH` (e.g., `v2026.01.3`)
+

package/agentic/code/addons/ralph/README.md

@@ -143,11 +143,28 @@ See `docs/examples/` for detailed walkthroughs:
 
 Ralph inverts traditional AI optimization from "unpredictable success" to "predictable failure with automatic recovery."
 
+## Important: When to Use Ralph
+
+**Ralph is a power tool.** Used correctly, it delivers overnight. Used incorrectly, it burns tokens producing junk.
+
+| Situation | Use Ralph? | Instead |
+|-----------|------------|---------|
+| Greenfield with no docs | **NO** | Use AIWG intake/flows first |
+| Vague requirements | **NO** | Write use cases first |
+| Clear spec, need implementation | **YES** | - |
+| Tests failing, need fixes | **YES** | - |
+| Migration with clear rules | **YES** | - |
+
+**The key insight**: Ralph excels at HOW to build, but thrashes on WHAT to build. Define your requirements first, then let Ralph implement.
+
+See [When to Use Ralph](docs/when-to-use-ralph.md) for detailed guidance on avoiding the token-burning trap.
+
 ## Related
 
-- [Quickstart Guide](docs/quickstart.md)
-- [Best Practices](docs/best-practices.md)
-- [Troubleshooting](docs/troubleshooting.md)
+- [When to Use Ralph](docs/when-to-use-ralph.md) - **Start here** - Understanding Ralph's sweet spot
+- [Quickstart Guide](docs/quickstart.md) - Getting started
+- [Best Practices](docs/best-practices.md) - Writing effective tasks
+- [Troubleshooting](docs/troubleshooting.md) - Common issues
 
 ## Credits
 

package/agentic/code/addons/ralph/docs/quickstart.md

@@ -2,6 +2,23 @@
 
 Get started with iterative AI task execution in 5 minutes.
 
+## Before You Start: Is Ralph Right for This Task?
+
+**Ralph is a power tool.** Before invoking it, ask yourself:
+
+| Question | If NO |
+|----------|-------|
+| Is my task well-defined with clear requirements? | Document requirements first |
+| Can I write a command that verifies success? | Ralph can't help with subjective goals |
+| Do I have tests/linting to validate correctness? | Add verification first |
+| Is this implementation work, not exploration? | Use Discovery Track for research |
+
+**The token-burning trap**: Ralph excels at HOW to implement but thrashes on WHAT to build. If you don't have clear requirements, Ralph will hallucinate features, contradict itself, and burn tokens producing junk.
+
+**Safe to proceed?** Read on. **Unsure?** See [When to Use Ralph](when-to-use-ralph.md) first.
+
+---
+
 ## What is Ralph?
 
 Ralph (from the "Ralph Wiggum methodology") executes AI tasks in a loop until completion criteria are met:
@@ -183,6 +200,7 @@ Ralph stores state and reports in `.aiwg/ralph/`:
 
 ## Next Steps
 
+- Read [When to Use Ralph](when-to-use-ralph.md) to understand Ralph's sweet spot
 - Read [Best Practices](best-practices.md) for effective prompt engineering
 - See [Examples](examples/) for common patterns
 - Check [Troubleshooting](troubleshooting.md) if you get stuck

package/agentic/code/addons/ralph/docs/when-to-use-ralph.md

@@ -0,0 +1,348 @@
+# When to Use Ralph (And When Not To)
+
+Understanding Ralph's sweet spot and avoiding the token-burning trap.
+
+## The Controversy
+
+Ralph divides people. Some swear by it. Others have war stories about it running all night, burning tokens, producing junk. Both are right - Ralph is a power tool, and like any power tool, it can build or destroy depending on how you use it.
+
+**The truth**: Ralph's effectiveness is directly proportional to how well-defined your project is before you invoke it.
+
+## The Two Extremes
+
+### The Disaster Case: Greenfield + Vague Directive
+
+```bash
+# DON'T DO THIS
+/ralph "make me a baking app" --completion "app works"
+```
+
+What happens:
+
+1. AI has no context about what "baking app" means
+2. No architecture decisions have been made
+3. No requirements exist
+4. AI hallucinates features, changes direction, contradicts itself
+5. Each iteration builds on shaky foundations
+6. Thrashing intensifies as hallucinated components conflict
+7. Token usage explodes
+8. Result: A mess that barely runs, if at all
+
+**Why this fails**: The AI is trying to answer "WHAT to build" while simultaneously trying to figure out "HOW to build it." These are fundamentally different problems. Mixing them creates chaos.
+
+### The Success Case: Documented Project + Implementation Focus
+
+```bash
+# DO THIS
+/ralph "Implement UC-AUTH-001 user login per the architecture doc" \
+  --completion "npm test -- auth passes AND npx tsc --noEmit passes"
+```
+
+What happens:
+
+1. UC-AUTH-001 defines exactly what login should do
+2. Architecture doc specifies technology choices
+3. AI knows the patterns, conventions, dependencies
+4. Each iteration focuses purely on implementation details
+5. Failures are specific: wrong import, missing mock, edge case
+6. AI learns from specific failures and fixes them
+7. Convergence to working code is predictable
+
+**Why this works**: The "WHAT" is settled. Ralph focuses entirely on "HOW" - the implementation mechanics where iteration genuinely helps.
+
+## The AIWG + Ralph Synergy
+
+AIWG was designed with Ralph in mind. The entire SDLC framework exists to create a corpus so complete that an AI can't thrash on what to build - it can only focus on how.
+
+### What AIWG Provides
+
+| AIWG Artifact | Eliminates This Uncertainty |
+|---------------|----------------------------|
+| Project Intake | What problem are we solving? |
+| Requirements (UC-*, US-*) | What features do we need? |
+| Software Architecture Doc | What tech stack, patterns, structure? |
+| ADRs | What decisions were made, and why? |
+| NFR modules | What are the quality requirements? |
+| Pseudo-code / interface specs | What's the API shape? |
+
+### The Transformation
+
+```
+Without AIWG:
+┌─────────────────────────────────────────────────────────┐
+│  Ralph → "What to build?" → Hallucinate → Thrash → $$$  │
+└─────────────────────────────────────────────────────────┘
+
+With AIWG:
+┌─────────────────────────────────────────────────────────┐
+│  AIWG → Defines "What" → Ralph → "How to build" → Done  │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Documentation as Specification
+
+By the time you've completed AIWG's Discovery Track:
+
+- Every feature is defined in a use case
+- Every decision is recorded in an ADR
+- The architecture is documented with component diagrams
+- Non-functional requirements are explicit
+- Even pseudo-code or interface shapes may exist
+
+**The docs are one step away from code.** Ralph's job becomes mechanical: translate this specification into working code, iterate on the implementation details until tests pass.
+
+## When Ralph Excels
+
+### Implementation of Well-Defined Features
+
+```bash
+/ralph "Implement @.aiwg/requirements/UC-PAY-003.md" \
+  --completion "npm test -- payment passes"
+```
+
+The use case document tells Ralph exactly what to build. Ralph figures out the implementation.
+
+### Mechanical Transformations
+
+```bash
+/ralph "Convert src/utils/*.js to TypeScript per @.aiwg/architecture/adr-012-typescript.md" \
+  --completion "npx tsc --noEmit passes"
+```
+
+The ADR defines the transformation rules. Ralph applies them iteratively.
+
+### Test-Driven Fixes
+
+```bash
+/ralph "Fix all failing tests in src/auth/" \
+  --completion "npm test -- auth passes"
+```
+
+Tests define expected behavior. Ralph makes code match expectations.
+
+### Dependency Resolution
+
+```bash
+/ralph "Update to React 19 and fix all breaking changes" \
+  --completion "npm test passes AND npm run build succeeds"
+```
+
+Ralph excels at the tedious iteration of finding compatible versions and fixing API changes.
+
+### Code Quality Gates
+
+```bash
+/ralph "Achieve 80% test coverage in src/services/" \
+  --completion "coverage report shows src/services >80%"
+```
+
+Clear metric, well-defined scope. Ralph adds tests until the threshold is met.
+
+## When NOT to Use Ralph
+
+### Greenfield Without Documentation
+
+If you have no architecture doc, no requirements, no design - **stop**. Don't invoke Ralph. Use the AIWG intake process first.
+
+```bash
+# First: Define what you're building
+/intake-wizard
+/flow-concept-to-inception
+/flow-inception-to-elaboration
+
+# Then: Build it
+/ralph "Implement UC-001" --completion "tests pass"
+```
+
+### Vague or Subjective Goals
+
+```bash
+# BAD - cannot verify, no clear target
+/ralph "make the code better" --completion "code is good"
+/ralph "improve UX" --completion "users are happy"
+/ralph "optimize performance" --completion "app is fast"
+```
+
+If you can't write a command that verifies success, Ralph can't iterate toward it.
+
+### Research or Exploration
+
+```bash
+# BAD - this isn't an implementation task
+/ralph "figure out how authentication should work" --completion "auth design is done"
+```
+
+Use `/flow-discovery-track` or manual exploration for research. Ralph is for implementation.
+
+### Undefined Scope
+
+```bash
+# BAD - how many features is "complete"?
+/ralph "finish the app" --completion "app is complete"
+```
+
+Break this into specific, documented features first.
+
+## Ralph for Documentation (Carefully Scoped)
+
+Ralph can help with documentation itself - but only with specific, verifiable scope:
+
+```bash
+# GOOD - specific, verifiable
+/ralph "Generate ADRs for all undocumented technical decisions in src/" \
+  --completion ".aiwg/architecture/adr-*.md exists for each major pattern"
+
+# GOOD - specific output
+/ralph "Create use cases from the feature list in product-brief.md" \
+  --completion "Each feature in product-brief.md has a corresponding .aiwg/requirements/UC-*.md"
+```
+
+```bash
+# BAD - too vague
+/ralph "document the project" --completion "docs are complete"
+```
+
+## Warning Signs: Is Ralph Thrashing?
+
+Watch for these indicators:
+
+| Sign | What It Means |
+|------|---------------|
+| Same error repeating | Structural problem, not implementation detail |
+| Contradictory changes | No clear requirements to guide decisions |
+| Growing file count | Hallucinating features not in scope |
+| Unrelated files changing | Lost context, working on wrong problem |
+| "Refactoring" without tests | No verification, just churning |
+
+**If you see these**: Abort Ralph, create documentation, then resume.
+
+```bash
+/ralph-abort
+# Create/update requirements docs
+# Define architecture decisions
+/ralph "Implement [specific, documented feature]" --completion "tests pass"
+```
+
+## The Ralph Readiness Checklist
+
+Before invoking Ralph, ask:
+
+- [ ] Is the feature documented in a use case or user story?
+- [ ] Is the architecture defined (or simple enough to be implicit)?
+- [ ] Can I write a command that verifies success?
+- [ ] Is the scope specific enough to complete in <20 iterations?
+- [ ] Are tests available to validate correctness?
+
+**If any answer is "no"**: Document first, Ralph second.
+
+## Summary
+
+| Situation | Action |
+|-----------|--------|
+| Greenfield, no docs | Use AIWG intake/flows first |
+| Vague requirements | Write use cases first |
+| No architecture | Create SAD/ADRs first |
+| Clear spec, need implementation | **Use Ralph** |
+| Tests failing, need fixes | **Use Ralph** |
+| Migration with clear rules | **Use Ralph** |
+| Coverage gap with clear target | **Use Ralph** |
+
+**The formula**: AIWG defines WHAT. Ralph implements HOW. Together they work. Apart, Ralph thrashes.
+
+## Industry Perspectives and Research
+
+The debate around iterative AI execution isn't unique to Ralph. Here's what the broader industry has learned.
+
+### The Context Problem
+
+[Augment Code's research](https://www.augmentcode.com/learn/agentic-swarm-vs-spec-driven-coding) found that both agentic swarms and specification-driven development fail for the same reason: they assume the hard problem is coordination or planning, not context understanding.
+
+> "Context understanding trumps coordination strategy... Perfect coordination doesn't help when agents are coordinating around incomplete information. Comprehensive specifications don't help when you can't specify what you don't fully understand."
+
+**AIWG's answer**: Create comprehensive context *first* through documentation. Ralph then operates in a rich-context environment where iteration actually helps.
+
+### Loop Drift and Thrashing
+
+[Research into agent loops](https://www.fixbrokenaiapps.com/blog/ai-agents-infinite-loops) identified "Loop Drift" as a core failure mode - agents misinterpreting termination signals, generating repetitive actions, or suffering from inconsistent internal state.
+
+**Why this matters for Ralph**: Clear completion criteria with objective verification commands (exit codes, test results) prevent drift. Subjective criteria like "code is good" invite drift.
+
+### Context Window Degradation
+
+[Token cost research](https://agentsarcade.com/blog/reducing-token-costs-long-running-agent-workflows) confirms that context windows have a quality curve:
+
+> "Early in the window, Claude is sharp. As tokens accumulate, quality degrades. If you try to cram multiple features into one iteration, you're working in the degraded part of the curve."
+
+**Best practice**: Keep iterations focused on single changes. Ralph's git-based state persistence lets each iteration start with fresh context while inheriting the work from prior iterations.
+
+### The Double-Loop Alternative
+
+[Test Double's "double-loop model"](https://testdouble.com/insights/youre-holding-it-wrong-the-double-loop-model-for-agentic-coding) argues against prescriptive prompts entirely:
+
+> "If you have to be super prescriptive with the AI agent, I might as well write the damn code."
+
+Their approach: First loop for exploration (treat implementation as disposable), second loop for polish (traditional code review).
+
+**AIWG's response**: Both models can work. Double-loop suits exploratory greenfield work where you're discovering requirements. Ralph + AIWG suits implementation of known requirements. The key is recognizing which phase you're in.
+
+### Security Concerns
+
+[NVIDIA's security research](https://developer.nvidia.com/blog/how-code-execution-drives-key-risks-in-agentic-ai-systems/) warns:
+
+> "AI-generated code is inherently untrusted. Systems that execute LLM-generated code must treat that code with the same caution as user-supplied inputs."
+
+**Ralph's safeguards**: Auto-commit creates rollback points. Tests verify correctness. Iteration limits prevent runaway execution. But the warning is real - always review final output before production.
+
+### Success Stories
+
+The Ralph methodology has proven effective for:
+
+- **React v16 to v19 migration**: 14 hours autonomous, no human intervention ([source](https://sidbharath.com/blog/ralph-wiggum-claude-code/))
+- **Overnight multi-repo delivery**: "Ship 6 repos overnight. $50k contract for $297 in API costs" ([source](https://venturebeat.com/technology/how-ralph-wiggum-went-from-the-simpsons-to-the-biggest-name-in-ai-right-now))
+- **Test coverage improvement**: Iterative test addition until threshold met
+
+The common thread: objectively verifiable goals with clear completion criteria.
+
+### Expert Consensus
+
+Industry practitioners have converged on these principles:
+
+| Principle | Source |
+|-----------|--------|
+| Verification is mandatory | Anthropic research: "models tend to declare victory without proper verification" |
+| Context beats coordination | Augment Code: "context understanding as the prerequisite for everything else" |
+| Small iterations work better | Oreate AI: "context windows have a quality curve" |
+| Safety limits are non-negotiable | Multiple sources: cap iterations, monitor costs, use sandboxes |
+| Boring technologies work better | Oreate AI: stable APIs and mature toolchains outperform trendy alternatives |
+
+### Contrary Views
+
+Not everyone agrees Ralph is the answer:
+
+**The "double-loop" camp** argues iteration should be exploratory first, not implementation-focused. They embrace disposable code during discovery.
+
+**The "context-first" camp** argues that understanding existing systems matters more than any coordination strategy. They focus on codebase comprehension tools.
+
+**The "human-in-the-loop" camp** argues autonomous execution is inherently risky. They prefer checkpoints and approval gates.
+
+**AIWG's synthesis**: All three camps make valid points. AIWG addresses them by:
+1. Supporting exploration during Discovery Track (not Ralph)
+2. Building rich context through documentation before implementation
+3. Providing iteration limits, auto-commits, and clear abort paths
+
+Ralph isn't for every phase of development - it's for the implementation phase after discovery is complete.
+
+## Related
+
+- [Quickstart Guide](quickstart.md) - Getting started with Ralph
+- [Best Practices](best-practices.md) - Writing effective tasks and criteria
+- [AIWG SDLC Framework](../../frameworks/sdlc-complete/README.md) - Documentation-first development
+- [Discovery Track](../../frameworks/sdlc-complete/docs/phases/discovery-track.md) - How to document before you build
+
+## External Resources
+
+- [The Ralph Wiggum Breakdown](https://dev.to/ibrahimpima/the-ralf-wiggum-breakdown-3mko) - Original methodology explanation
+- [VentureBeat: Ralph Wiggum in AI](https://venturebeat.com/technology/how-ralph-wiggum-went-from-the-simpsons-to-the-biggest-name-in-ai-right-now) - Industry adoption
+- [Test Double: Double Loop Model](https://testdouble.com/insights/youre-holding-it-wrong-the-double-loop-model-for-agentic-coding) - Alternative approach
+- [Augment Code: Spec-Driven vs Agentic](https://www.augmentcode.com/learn/agentic-swarm-vs-spec-driven-coding) - Context-first perspective
+- [Reducing Token Costs](https://agentsarcade.com/blog/reducing-token-costs-long-running-agent-workflows) - Cost management strategies

package/docs/contributing/ci-cd-secrets.md

@@ -0,0 +1,188 @@
+# CI/CD Secrets Configuration
+
+**Version:** 1.0
+**Last Updated:** 2026-01-14
+**Target Audience:** Repository maintainers and administrators
+
+## Overview
+
+This document describes the secrets required for CI/CD workflows in the AIWG repository. Secrets are used for authentication with package registries and external services.
+
+## Required Secrets
+
+### NPM_TOKEN
+
+**Purpose:** Authenticate with Gitea's npm package registry for publishing.
+
+**Required Scopes:**
+- `package:write` - Required to publish packages
+- `package:read` - Required to verify published packages
+
+**Used In:**
+- `.gitea/workflows/npm-publish.yml` - Publishing to Gitea npm registry
+- Creating Gitea releases via API
+
+### Setting Up NPM_TOKEN
+
+#### Step 1: Create a Gitea Access Token
+
+1. Log in to [git.integrolabs.net](https://git.integrolabs.net)
+2. Navigate to **Settings** → **Applications** → **Access Tokens**
+   - Direct URL: https://git.integrolabs.net/user/settings/applications
+3. Create a new token with:
+   - **Token Name:** `ci-npm-publish` (or descriptive name)
+   - **Select Scopes:**
+     - ✅ `write:package` (includes read:package)
+     - ✅ `read:repository` (for checkout operations)
+   - **Expiration:** Set according to your security policy (recommend 1 year max)
+4. Click **Generate Token**
+5. **IMPORTANT:** Copy the token immediately - it won't be shown again
+
+#### Step 2: Add Secret to Gitea Repository
+
+1. Navigate to the repository: https://git.integrolabs.net/roctinam/ai-writing-guide
+2. Go to **Settings** → **Actions** → **Secrets**
+3. Click **Add Secret**
+4. Configure:
+   - **Name:** `NPM_TOKEN`
+   - **Value:** Paste the token from Step 1
+5. Click **Add Secret**
+
+#### Step 3: Verify Configuration
+
+Trigger a manual workflow run to verify:
+
+```bash
+# Push a test tag (can be deleted after)
+git tag v9999.99.99-test
+git push origin v9999.99.99-test
+
+# Watch the workflow at:
+# https://git.integrolabs.net/roctinam/ai-writing-guide/actions
+
+# Clean up test tag
+git tag -d v9999.99.99-test
+git push origin :refs/tags/v9999.99.99-test
+```
+
+Or use the workflow dispatch with dry_run enabled.
+
+## Troubleshooting
+
+### Error: 401 Unauthorized
+
+```
+npm error code E401
+npm error 401 Unauthorized - PUT https://git.integrolabs.net/api/packages/roctinam/npm/aiwg
+```
+
+**Causes:**
+1. **Token expired** - Create a new token and update the secret
+2. **Token missing** - Verify NPM_TOKEN secret exists in repository settings
+3. **Wrong scopes** - Token must have `write:package` scope
+4. **Token revoked** - Check if token still exists in user settings
+
+**Resolution:**
+1. Go to https://git.integrolabs.net/user/settings/applications
+2. Check if the token exists and hasn't expired
+3. If expired/missing, create a new token with `write:package` scope
+4. Update the repository secret with the new token
+
+### Error: 403 Forbidden
+
+**Causes:**
+1. Token belongs to user without package write permissions
+2. Repository doesn't allow package publishing
+
+**Resolution:**
+1. Ensure token owner has write access to the repository
+2. Check organization/repository package settings
+
+### Token Not Being Used
+
+If the workflow isn't picking up the secret:
+
+1. Verify secret name is exactly `NPM_TOKEN` (case-sensitive)
+2. Check workflow file references `${{ secrets.NPM_TOKEN }}`
+3. Ensure workflow has appropriate permissions in `permissions:` block
+
+## Security Best Practices
+
+### Token Management
+
+- **Rotation:** Rotate tokens annually or when team members leave
+- **Scope:** Use minimum required scopes (write:package, read:repository)
+- **Naming:** Use descriptive names like `ci-npm-publish-2026`
+- **Audit:** Periodically review active tokens
+
+### Secret Storage
+
+- Never commit tokens to the repository
+- Use repository/organization secrets, not environment variables in code
+- Don't echo or log token values in workflows
+
+### Workflow Security
+
+```yaml
+# Good: Token passed via secrets
+env:
+  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+# Bad: Token hardcoded or echoed
+run: echo ${{ secrets.NPM_TOKEN }}  # NEVER do this
+```
+
+## Workflow Architecture
+
+### npm-publish.yml Flow
+
+```
+[Tag Push v*] → [Checkout] → [Configure npm] → [Build] → [Publish to Gitea] → [Verify]
+                                   ↓
+                            Uses NPM_TOKEN for:
+                            - .npmrc authentication
+                            - npm publish command
+                            - Gitea release API
+```
+
+### Secret Usage in Workflow
+
+```yaml
+# .npmrc configuration (line 55-56)
+//git.integrolabs.net/api/packages/roctinam/npm/:_authToken=${{ secrets.NPM_TOKEN }}
+
+# Publish command (line 107-109)
+npm publish --registry=${{ env.GITEA_NPM_REGISTRY }}
+env:
+  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+# Release creation (line 137)
+-H "Authorization: token ${{ secrets.NPM_TOKEN }}"
+```
+
+## Additional Secrets (Optional)
+
+### NPMJS_TOKEN (for public npm)
+
+If publishing to public npmjs.org:
+
+1. Create token at https://www.npmjs.com/settings/tokens
+2. Select "Automation" token type
+3. Add as secret named `NPMJS_TOKEN`
+4. Update workflow to use separate token for public registry
+
+### GITHUB_TOKEN (for GitHub mirror)
+
+For GitHub Actions (`.github/workflows/`):
+
+- Automatically provided by GitHub Actions
+- No manual configuration needed
+- Used for GitHub Releases and npm publish to GitHub Packages
+
+## References
+
+- [Gitea Package Registry Documentation](https://docs.gitea.com/usage/packages/npm)
+- [Gitea Actions Secrets](https://docs.gitea.com/usage/actions/secrets)
+- [npm Authentication](https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow)
+- @.gitea/workflows/npm-publish.yml - Main publish workflow
+- @.claude/rules/token-security.md - Token security rules