.github/workflows/manual-release.yaml

@@ -0,0 +1,193 @@
+name: Manual Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_bump:
+        description: Version bump type
+        required: true
+        default: beta
+        type: choice
+        options:
+          - beta
+          - alpha
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests and validation
+        run: |
+          npm run validate
+          npm run format:check
+          npm run lint
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        run: |
+          case "${{ github.event.inputs.version_bump }}" in
+            alpha|beta) npm version prerelease --no-git-tag-version --preid=${{ github.event.inputs.version_bump }} ;;
+            *)          npm version ${{ github.event.inputs.version_bump }} --no-git-tag-version ;;
+          esac
+
+      - name: Get new version and previous tag
+        id: version
+        run: |
+          echo "new_version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+          echo "previous_tag=$(git describe --tags --abbrev=0)" >> $GITHUB_OUTPUT
+
+      - name: Update installer package.json
+        run: |
+          sed -i 's/"version": ".*"/"version": "${{ steps.version.outputs.new_version }}"/' tools/installer/package.json
+
+      # TODO: Re-enable web bundles once tools/cli/bundlers/ is restored
+      # - name: Generate web bundles
+      #   run: npm run bundle
+
+      - name: Commit version bump
+        run: |
+          git add .
+          git commit -m "release: bump to v${{ steps.version.outputs.new_version }}"
+
+      - name: Generate release notes
+        id: release_notes
+        run: |
+          # Get commits since last tag
+          COMMITS=$(git log ${{ steps.version.outputs.previous_tag }}..HEAD --pretty=format:"- %s" --reverse)
+
+          # Categorize commits
+          FEATURES=$(echo "$COMMITS" | grep -E "^- (feat|Feature)" || true)
+          FIXES=$(echo "$COMMITS" | grep -E "^- (fix|Fix)" || true)  
+          CHORES=$(echo "$COMMITS" | grep -E "^- (chore|Chore)" || true)
+          OTHERS=$(echo "$COMMITS" | grep -v -E "^- (feat|Feature|fix|Fix|chore|Chore|release:|Release:)" || true)
+
+          # Build release notes
+          cat > release_notes.md << 'EOF'
+          ## 🚀 What's New in v${{ steps.version.outputs.new_version }}
+
+          EOF
+
+          if [ ! -z "$FEATURES" ]; then
+            echo "### ✨ New Features" >> release_notes.md
+            echo "$FEATURES" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          if [ ! -z "$FIXES" ]; then
+            echo "### 🐛 Bug Fixes" >> release_notes.md
+            echo "$FIXES" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          if [ ! -z "$OTHERS" ]; then
+            echo "### 📦 Other Changes" >> release_notes.md
+            echo "$OTHERS" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          if [ ! -z "$CHORES" ]; then
+            echo "### 🔧 Maintenance" >> release_notes.md
+            echo "$CHORES" >> release_notes.md
+            echo "" >> release_notes.md
+          fi
+
+          cat >> release_notes.md << 'EOF'
+
+          ## 📦 Installation
+
+          ```bash
+          npx bmad-method install
+          ```
+
+          **Full Changelog**: https://github.com/bmad-code-org/BMAD-METHOD/compare/${{ steps.version.outputs.previous_tag }}...v${{ steps.version.outputs.new_version }}
+          EOF
+
+          # Output for GitHub Actions
+          echo "RELEASE_NOTES<<EOF" >> $GITHUB_OUTPUT
+          cat release_notes.md >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Create and push tag
+        run: |
+          # Check if tag already exists
+          if git rev-parse "v${{ steps.version.outputs.new_version }}" >/dev/null 2>&1; then
+            echo "Tag v${{ steps.version.outputs.new_version }} already exists, skipping tag creation"
+          else
+            git tag -a "v${{ steps.version.outputs.new_version }}" -m "Release v${{ steps.version.outputs.new_version }}"
+            git push origin "v${{ steps.version.outputs.new_version }}"
+          fi
+
+      - name: Push changes to main
+        run: |
+          if git push origin HEAD:main 2>/dev/null; then
+            echo "✅ Successfully pushed to main branch"
+          else
+            echo "⚠️ Could not push to main (protected branch). This is expected."
+            echo "📝 Version bump and tag were created successfully."
+          fi
+
+      - name: Publish to NPM
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          VERSION="${{ steps.version.outputs.new_version }}"
+          if [[ "$VERSION" == *"alpha"* ]]; then
+            echo "Publishing alpha prerelease version with --tag alpha"
+            npm publish --tag alpha
+          elif [[ "$VERSION" == *"beta"* ]]; then
+            echo "Publishing beta prerelease version with --tag latest"
+            npm publish --tag latest
+          else
+            echo "Publishing stable version with --tag latest"
+            npm publish --tag latest
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.new_version }}
+          name: "BMad Method v${{ steps.version.outputs.new_version }}"
+          body: |
+            ${{ steps.release_notes.outputs.RELEASE_NOTES }}
+          draft: false
+          prerelease: ${{ contains(steps.version.outputs.new_version, 'alpha') || contains(steps.version.outputs.new_version, 'beta') }}
+
+      - name: Summary
+        run: |
+          echo "## 🎉 Successfully released v${{ steps.version.outputs.new_version }}!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 📦 Distribution" >> $GITHUB_STEP_SUMMARY
+          echo "- **NPM**: Published with @latest tag" >> $GITHUB_STEP_SUMMARY
+          echo "- **GitHub Release**: https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v${{ steps.version.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### ✅ Installation" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "npx bmad-method@${{ steps.version.outputs.new_version }} install" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

docs/downloads.md

@@ -0,0 +1,74 @@
+---
+title: Downloads
+---
+
+Download BMad Method resources for offline use, AI training, or integration.
+
+## Source Bundles
+
+Download these from the `downloads/` folder on the documentation site.
+
+| File               | Description                     |
+| ------------------ | ------------------------------- |
+| `bmad-sources.zip` | Complete BMad source files      |
+| `bmad-prompts.zip` | Agent and workflow prompts only |
+
+## LLM-Optimized Files
+
+These files are designed for AI consumption - perfect for loading into Claude, ChatGPT, or any LLM context window. See [API Access](#api-access) below for URLs.
+
+| File            | Description                         | Use Case                   |
+| --------------- | ----------------------------------- | -------------------------- |
+| `llms.txt`      | Documentation index with summaries  | Quick overview, navigation |
+| `llms-full.txt` | Complete documentation concatenated | Full context loading       |
+
+### Using with LLMs
+
+**Claude Projects:**
+```
+Upload llms-full.txt as project knowledge
+```
+
+**ChatGPT:**
+```
+Paste llms.txt for navigation, or sections from llms-full.txt as needed
+```
+
+**API Usage:**
+```python
+import requests
+docs = requests.get("https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt").text
+# Include in your system prompt or context
+```
+
+## Installation Options
+
+```bash
+npx bmad-method install
+```
+
+[More details](/docs/how-to/install-bmad.md)
+
+## Version Information
+
+- **Current Version:** See [CHANGELOG](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)
+- **Release Notes:** Available on [GitHub Releases](https://github.com/bmad-code-org/BMAD-METHOD/releases)
+
+## API Access
+
+For programmatic access to BMad documentation:
+
+```bash
+# Get documentation index
+curl https://bmad-code-org.github.io/BMAD-METHOD/llms.txt
+
+# Get full documentation
+curl https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
+```
+
+## Contributing
+
+Want to improve BMad Method? Check out:
+
+- [Contributing Guide](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)
+- [GitHub Repository](https://github.com/bmad-code-org/BMAD-METHOD)

docs/how-to/established-projects.md

@@ -3,7 +3,7 @@ title: "Established Projects"
 description: How to use BMad Method on existing codebases
 ---
 
-Use BMad Method effectively when working on existing projects and legacy codebases, sometimes also referred to as brownfield projects.
+Use BMad Method effectively when working on existing projects and legacy codebases.
 
 This guide covers the essential workflow for onboarding to existing projects with BMad Method.
 

docs/how-to/get-answers-about-bmad.md

@@ -42,6 +42,8 @@ Fetch `llms-full.txt` into your session:
 https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
 ```
 
+See the [Downloads page](/docs/downloads.md) for other downloadable resources.
+
 ### 3. Ask Your Question
 
 :::note[Example]

docs/how-to/install-bmad.md

@@ -5,8 +5,6 @@ description: Step-by-step guide to installing BMad in your project
 
 Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
 
-If you want to use a non interactive installer and provide all install options on the command line, [this guide](/docs/non-interactive-installation.md).
-
 ## When to Use This
 
 - Starting a new project with BMad

docs/how-to/shard-large-documents.md

@@ -2,17 +2,23 @@
 title: "Document Sharding Guide"
 ---
 
-Use the `shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management.
-
-This is no longer recommended, and soon with updated workflows and most major llms and tools supporting sub processes this will be unnecessary.
+Use the `shard-doc` tool to split large markdown files into smaller, organized files for better context management.
 
 ## When to Use This
 
-Only use this if you notice your chosen tool / model combination are failing to load and read all the documents as input when needed.
+- Very large complex PRDs
+- Architecture documents with multiple system layers
+- Epic files with 4+ epics (especially for Phase 4)
+- UX design specs covering multiple subsystems
 
 ## What is Document Sharding?
 
-Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`).
+Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). This enables:
+
+- **Selective Loading** - Workflows load only the sections they need
+- **Reduced Token Usage** - Massive efficiency gains for large projects
+- **Better Organization** - Logical section-based file structure
+- **Maintained Context** - Index file preserves document structure
 
 ### Architecture
 
@@ -55,6 +61,28 @@ Agent: Sharding PRD.md...
        ✓ Complete!
 ```
 
+## What You Get
+
+**index.md structure:**
+
+```markdown
+
+## Sections
+
+1. [Overview](./overview.md) - Project vision and objectives
+2. [User Requirements](./user-requirements.md) - Feature specifications
+3. [Epic 1: Authentication](./epic-1-authentication.md) - User auth system
+4. [Epic 2: Dashboard](./epic-2-dashboard.md) - Main dashboard UI
+   ...
+```
+
+**Individual section files:**
+
+- Named from heading text (kebab-case)
+- Contains complete section content
+- Preserves all markdown formatting
+- Can be read independently
+
 ## How Workflow Discovery Works
 
 BMad workflows use a **dual discovery system**:

docs/how-to/upgrade-to-v6.md

@@ -20,7 +20,14 @@ Use the BMad installer to upgrade from v4 to v6, which includes automatic detect
 
 ### 1. Run the Installer
 
-Follow the [Installer Instructions](/docs/how-to/install-bmad.md).
+```bash
+npx bmad-method install
+```
+
+The installer automatically detects:
+
+- **Legacy v4 folder**: `.bmad-method`
+- **IDE command artifacts**: Legacy bmad folders in `.claude/commands/`, `.cursor/commands/`, etc.
 
 ### 2. Handle Legacy Installation
 
@@ -28,16 +35,21 @@ When v4 is detected, you can:
 
 - Allow the installer to back up and remove `.bmad-method`
 - Exit and handle cleanup manually
-
-If you named your bmad method folder something else - you will need to manual remove the folder yourself.
+- Keep both (not recommended for same project)
 
 ### 3. Clean Up IDE Commands
 
-Manually remove legacy v4 IDE commands - for example if you have claude, look for any nested folders that start with bmad and remove them:
+Manually remove legacy v4 IDE commands:
 
 - `.claude/commands/BMad/agents`
 - `.claude/commands/BMad/tasks`
 
+New v6 commands will be at `.claude/commands/bmad/<module>/agents|workflows`.
+
+:::tip[Accidentally Deleted Commands?]
+If you delete the wrong commands, rerun the installer and choose "quick update" to restore them.
+:::
+
 ### 4. Migrate Planning Artifacts
 
 **If you have planning documents (Brief/PRD/UX/Architecture):**
@@ -59,6 +71,24 @@ If you have stories created or implemented:
 3. Run the Scrum Master's `sprint-planning` workflow
 4. Tell the SM which epics/stories are already complete
 
+### 6. Migrate Agent Customizations
+
+**v4:** Modified agent files directly in `_bmad-*` folders
+
+**v6:** All customizations go in `_bmad/_config/agents/` using customize files:
+
+```yaml
+# _bmad/_config/agents/bmm-pm.customize.yaml
+persona:
+  name: 'Captain Jack'
+  role: 'Swashbuckling Product Owner'
+  communication_style: |
+    - Talk like a pirate
+    - Use nautical metaphors
+```
+
+After modifying customization files, rerun the installer and choose "rebuild all agents" or "quick update".
+
 ## What You Get
 
 **v6 unified structure:**
@@ -78,18 +108,24 @@ your-project/
 ## Module Migration
 
 | v4 Module | v6 Status |
-| ----------------------------- | ----------------------------------------- |
-| `.bmad-2d-phaser-game-dev`    | Integrated into BMGD Module               |
-| `.bmad-2d-unity-game-dev`     | Integrated into BMGD Module               |
-| `.bmad-godot-game-dev`        | Integrated into BMGD Module               |
-| `.bmad-infrastructure-devops` | Deprecated — new DevOps agent coming soon |
-| `.bmad-creative-writing`      | Not adapted — new v6 module coming soon   |
+|-----------|-----------|
+| `_bmad-2d-phaser-game-dev` | Integrated into BMGD Module |
+| `_bmad-2d-unity-game-dev` | Integrated into BMGD Module |
+| `_bmad-godot-game-dev` | Integrated into BMGD Module |
+| `_bmad-infrastructure-devops` | Deprecated — new DevOps agent coming soon |
+| `_bmad-creative-writing` | Not adapted — new v6 module coming soon |
 
 ## Key Changes
 
 | Concept | v4 | v6 |
-| ------------- | ------------------------------------- | ------------------------------------ |
+|---------|----|----|
 | **Core** | `_bmad-core` was actually BMad Method | `_bmad/core/` is universal framework |
 | **Method** | `_bmad-method` | `_bmad/bmm/` |
 | **Config** | Modified files directly | `config.yaml` per module |
 | **Documents** | Sharded or unsharded required setup | Fully flexible, auto-scanned |
+
+## Tips
+
+- **Back up first** — Keep your v4 installation until you verify v6 works
+- **Use v6 workflows** — Even partial planning docs benefit from v6's improved discovery
+- **Rebuild after customizing** — Always run the installer after changing customize files

docs/index.md

@@ -2,7 +2,7 @@
 title: Welcome to the BMad Method
 ---
 
-The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform.
+The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework that helps you build software faster and smarter. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity—whether you're fixing a bug or building an enterprise platform.
 
 If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
 

package.json

@@ -41,6 +41,10 @@
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
+    "release:major": "gh workflow run \"Manual Release\" -f version_bump=major",
+    "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
+    "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
+    "release:watch": "gh run watch",
     "test": "npm run test:schemas && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
     "test:install": "node test/test-installation-components.js",
@@ -89,6 +93,7 @@
     "@astrojs/sitemap": "^3.6.0",
     "@astrojs/starlight": "^0.37.5",
     "@eslint/js": "^9.33.0",
+    "archiver": "^7.0.1",
     "astro": "^5.16.0",
     "c8": "^10.1.3",
     "eslint": "^9.33.0",

tools/build-docs.mjs

@@ -2,10 +2,10 @@
  * BMAD Documentation Build Pipeline
  *
  * Consolidates docs from multiple sources, generates LLM-friendly files,
- * and builds the Astro+Starlight site.
+ * creates downloadable bundles, and builds the Astro+Starlight site.
  *
  * Build outputs:
- *   build/artifacts/     - With llms.txt, llms-full.txt
+ *   build/artifacts/     - With llms.txt, llms-full.txt, ZIPs
  *   build/site/          - Final Astro output (deployable)
  */
 
@@ -13,6 +13,7 @@ import { execSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import archiver from 'archiver';
 import { getSiteUrl } from '../website/src/lib/site-url.mjs';
 
 // =============================================================================
@@ -34,6 +35,7 @@ const LLM_EXCLUDE_PATTERNS = [
   'changelog',
   'ide-info/',
   'v4-to-v6-upgrade',
+  'downloads/',
   'faq',
   'reference/glossary/',
   'explanation/game-dev/',
@@ -79,16 +81,17 @@ main().catch((error) => {
 // =============================================================================
 // Pipeline Stages
 /**
- * Generate LLM files for the documentation pipeline.
+ * Generate LLM files and downloadable bundles for the documentation pipeline.
  *
- * Creates the build/artifacts directory and writes `llms.txt` and `llms-full.txt` (sourced from the provided docs directory).
+ * Creates the build/artifacts directory, writes `llms.txt` and `llms-full.txt` (sourced from the provided docs directory),
+ * and produces download ZIP bundles.
  *
  * @param {string} docsDir - Path to the source docs directory containing Markdown files.
  * @returns {string} Path to the created artifacts directory.
  */
 
 async function generateArtifacts(docsDir) {
-  printHeader('Generating LLM files');
+  printHeader('Generating LLM files and download bundles');
 
   const outputDir = path.join(BUILD_DIR, 'artifacts');
   fs.mkdirSync(outputDir, { recursive: true });
@@ -96,6 +99,7 @@ async function generateArtifacts(docsDir) {
   // Generate LLM files reading from docs/, output to artifacts/
   generateLlmsTxt(outputDir);
   generateLlmsFullTxt(docsDir, outputDir);
+  await generateDownloadBundles(outputDir);
 
   console.log();
   console.log(`  \u001B[32m✓\u001B[0m Artifact generation complete`);
@@ -172,6 +176,8 @@ function generateLlmsTxt(outputDir) {
     '## Quick Links',
     '',
     `- [Full Documentation (llms-full.txt)](${siteUrl}/llms-full.txt) - Complete docs for AI context`,
+    `- [Source Bundle](${siteUrl}/downloads/bmad-sources.zip) - Complete source code`,
+    `- [Prompts Bundle](${siteUrl}/downloads/bmad-prompts.zip) - Agent prompts and workflows`,
     '',
   ].join('\n');
 
@@ -243,6 +249,7 @@ function compareLlmDocs(a, b) {
 
 function getLlmSortKey(filePath) {
   if (filePath === 'index.md') return 0;
+  if (filePath === 'downloads.md') return 1;
   if (filePath.startsWith(`tutorials${path.sep}`) || filePath.startsWith('tutorials/')) return 2;
   if (filePath.startsWith(`how-to${path.sep}`) || filePath.startsWith('how-to/')) return 3;
   if (filePath.startsWith(`explanation${path.sep}`) || filePath.startsWith('explanation/')) return 4;
@@ -315,6 +322,48 @@ function validateLlmSize(content) {
   }
 }
 
+// =============================================================================
+// Download Bundle Generation
+// =============================================================================
+
+async function generateDownloadBundles(outputDir) {
+  console.log('  → Generating download bundles...');
+
+  const downloadsDir = path.join(outputDir, 'downloads');
+  fs.mkdirSync(downloadsDir, { recursive: true });
+
+  await generateSourcesBundle(downloadsDir);
+  await generatePromptsBundle(downloadsDir);
+}
+
+async function generateSourcesBundle(downloadsDir) {
+  const srcDir = path.join(PROJECT_ROOT, 'src');
+  if (!fs.existsSync(srcDir)) return;
+
+  const zipPath = path.join(downloadsDir, 'bmad-sources.zip');
+  await createZipArchive(srcDir, zipPath, ['__pycache__', '.pyc', '.DS_Store', 'node_modules']);
+
+  const size = (fs.statSync(zipPath).size / 1024 / 1024).toFixed(1);
+  console.log(`    bmad-sources.zip (${size}M)`);
+}
+
+/**
+ * Create a zip archive of the project's prompts modules and place it in the downloads directory.
+ *
+ * Creates bmad-prompts.zip from src/modules, excluding common unwanted paths, writes it to the provided downloads directory, and logs the resulting file size. If the modules directory does not exist, the function returns without creating a bundle.
+ * @param {string} downloadsDir - Destination directory where bmad-prompts.zip will be written.
+ */
+async function generatePromptsBundle(downloadsDir) {
+  const modulesDir = path.join(PROJECT_ROOT, 'src', 'modules');
+  if (!fs.existsSync(modulesDir)) return;
+
+  const zipPath = path.join(downloadsDir, 'bmad-prompts.zip');
+  await createZipArchive(modulesDir, zipPath, ['docs', '.DS_Store', '__pycache__', 'node_modules']);
+
+  const size = Math.floor(fs.statSync(zipPath).size / 1024);
+  console.log(`    bmad-prompts.zip (${size}K)`);
+}
+
 // =============================================================================
 // Astro Build
 /**
@@ -335,6 +384,7 @@ function runAstroBuild() {
  * Copy generated artifact files into the built site directory.
  *
  * Copies llms.txt and llms-full.txt from the artifacts directory into the site directory.
+ * If a downloads subdirectory exists under artifacts, copies it into siteDir/downloads.
  *
  * @param {string} artifactsDir - Path to the build artifacts directory containing generated files.
  * @param {string} siteDir - Path to the target site directory where artifacts should be placed.
@@ -344,6 +394,11 @@ function copyArtifactsToSite(artifactsDir, siteDir) {
 
   fs.copyFileSync(path.join(artifactsDir, 'llms.txt'), path.join(siteDir, 'llms.txt'));
   fs.copyFileSync(path.join(artifactsDir, 'llms-full.txt'), path.join(siteDir, 'llms-full.txt'));
+
+  const downloadsDir = path.join(artifactsDir, 'downloads');
+  if (fs.existsSync(downloadsDir)) {
+    copyDirectory(downloadsDir, path.join(siteDir, 'downloads'));
+  }
 }
 
 // =============================================================================
@@ -352,7 +407,7 @@ function copyArtifactsToSite(artifactsDir, siteDir) {
  * Prints a concise end-of-build summary and displays a sample listing of the final site directory.
  *
  * @param {string} docsDir - Path to the source documentation directory used for the build.
- * @param {string} artifactsDir - Path to the directory containing generated artifacts (e.g., llms.txt).
+ * @param {string} artifactsDir - Path to the directory containing generated artifacts (e.g., llms.txt, downloads).
  * @param {string} siteDir - Path to the final built site directory whose contents will be listed.
  */
 
@@ -471,6 +526,35 @@ function copyDirectory(src, dest, exclude = []) {
   return true;
 }
 
+/**
+ * Create a ZIP archive of a directory, optionally excluding entries that match given substrings.
+ * @param {string} sourceDir - Path to the source directory to archive.
+ * @param {string} outputPath - Path to write the resulting ZIP file.
+ * @param {string[]} [exclude=[]] - Array of substrings; any entry whose path includes one of these substrings will be omitted.
+ * @returns {Promise<void>} Resolves when the archive has been fully written and closed, rejects on error.
+ */
+function createZipArchive(sourceDir, outputPath, exclude = []) {
+  return new Promise((resolve, reject) => {
+    const output = fs.createWriteStream(outputPath);
+    const archive = archiver('zip', { zlib: { level: 9 } });
+
+    output.on('close', resolve);
+    archive.on('error', reject);
+
+    archive.pipe(output);
+
+    const baseName = path.basename(sourceDir);
+    archive.directory(sourceDir, baseName, (entry) => {
+      for (const pattern of exclude) {
+        if (entry.name.includes(pattern)) return false;
+      }
+      return entry;
+    });
+
+    archive.finalize();
+  });
+}
+
 // =============================================================================
 // Console Output Formatting
 // =============================================================================

tools/docs/BUNDLE_DISTRIBUTION_SETUP.md

@@ -0,0 +1,95 @@
+# Bundle Distribution Setup (For Maintainers)
+
+**Audience:** BMAD maintainers setting up bundle auto-publishing
+
+---
+
+## One-Time Setup
+
+Run these commands once to enable auto-publishing:
+
+```bash
+# 1. Create bmad-bundles repo
+gh repo create bmad-code-org/bmad-bundles --public --description "BMAD Web Bundles"
+
+# 2. Ensure `main` exists (GitHub Pages API requires a source branch)
+git clone git@github.com:bmad-code-org/bmad-bundles.git
+cd bmad-bundles
+printf '# bmad-bundles\n\nStatic bundles published from BMAD-METHOD.\n' > README.md
+git add README.md
+git commit -m "Initial commit"
+git push origin main
+cd -
+
+# 3. Enable GitHub Pages (API replacement for removed --enable-pages flag)
+gh api repos/bmad-code-org/bmad-bundles/pages --method POST -f source[branch]=main -f source[path]=/
+# (Optional) confirm status
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source}'
+
+# 4. Create GitHub PAT and add as secret
+# Go to: https://github.com/settings/tokens/new
+# Scopes: repo (full control)
+# Name: bmad-bundles-ci
+# Then add as secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+# (paste PAT when prompted)
+```
+
+If the Pages POST returns `409`, the site already exists. If it returns `422` about `main` missing, redo step 2 to push the initial commit.
+
+**Done.** Bundles auto-publish on every main merge.
+
+---
+
+## How It Works
+
+**On main merge:**
+
+- `.github/workflows/bundle-latest.yaml` runs
+- Publishes to: `https://bmad-code-org.github.io/bmad-bundles/`
+
+**On release:**
+
+- `npm run release:patch` runs `.github/workflows/manual-release.yaml`
+- Attaches bundles to: `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+
+---
+
+## Testing
+
+```bash
+# Test latest channel
+git push origin main
+# Wait 2 min, then: curl https://bmad-code-org.github.io/bmad-bundles/
+
+# Test stable channel
+npm run release:patch
+# Check: gh release view
+```
+
+---
+
+## Troubleshooting
+
+**"Permission denied" or auth errors**
+
+```bash
+# Verify PAT secret exists
+gh secret list --repo bmad-code-org/BMAD-METHOD | grep BUNDLES_PAT
+
+# If missing, recreate PAT and add secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+```
+
+**GitHub Pages not updating / need to re-check config**
+
+```bash
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source,html_url}'
+```
+
+---
+
+## Distribution URLs
+
+**Stable:** `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+**Latest:** `https://bmad-code-org.github.io/bmad-bundles/`

website/README.md

@@ -73,3 +73,4 @@ Note: If copying, remember to keep the copy in sync with changes to `docs/`.
 The build pipeline (`npm run docs:build`) produces:
 - Static HTML site in `build/site/`
 - LLM-friendly files: `llms.txt`, `llms-full.txt`
+- Downloadable ZIP bundles in `downloads/`

website/src/components/Header.astro

@@ -26,6 +26,9 @@ const shouldRenderSearch =
 		{shouldRenderSearch && <Search {...Astro.props} />}
 	</div>
 	<div class="sl-hidden md:sl-flex print:hidden right-group">
+		<nav class="sl-flex nav-links">
+			<a href={`${import.meta.env.BASE_URL}downloads/`}>Downloads</a>
+		</nav>
 		<div class="sl-flex social-icons">
 			<SocialIcons {...Astro.props} />
 		</div>
@@ -52,11 +55,33 @@ const shouldRenderSearch =
 	}
 
 	.right-group,
-	.social-icons {
+	.social-icons,
+	.nav-links {
 		gap: 1rem;
 		align-items: center;
 	}
 
+	.nav-links a {
+		color: var(--sl-color-white);
+		text-decoration: none;
+		font-size: 0.875rem;
+		font-weight: 500;
+		padding: 0.25rem 0.5rem;
+		border-radius: 4px;
+		transition: color 0.15s ease, background-color 0.15s ease;
+	}
+
+	.nav-links a:hover {
+		color: var(--sl-color-accent);
+		background-color: rgba(140, 140, 255, 0.1);
+	}
+
+	.nav-links::after {
+		content: '';
+		height: 2rem;
+		border-inline-end: 1px solid var(--sl-color-gray-5);
+	}
+
 	.social-icons::after {
 		content: '';
 		height: 2rem;

website/src/components/MobileMenuFooter.astro

@@ -9,6 +9,9 @@ import type { Props } from '@astrojs/starlight/props';
 	<div class="sl-flex social-icons">
 		<SocialIcons {...Astro.props} />
 	</div>
+	<nav class="sl-flex nav-links">
+		<a href={`${import.meta.env.BASE_URL}downloads/`}>Downloads</a>
+	</nav>
 	<ThemeSelect {...Astro.props} />
 	<LanguageSelect {...Astro.props} />
 </div>
@@ -30,4 +33,21 @@ import type { Props } from '@astrojs/starlight/props';
 		padding: 0.5rem 0;
 		align-items: center;
 	}
+	.nav-links {
+		gap: 1rem;
+		align-items: center;
+	}
+	.nav-links a {
+		color: var(--sl-color-white);
+		text-decoration: none;
+		font-size: 0.875rem;
+		font-weight: 500;
+		padding: 0.5rem 0.75rem;
+		border-radius: 4px;
+		transition: color 0.15s ease, background-color 0.15s ease;
+	}
+	.nav-links a:hover {
+		color: var(--sl-color-accent);
+		background-color: rgba(140, 140, 255, 0.1);
+	}
 </style>

website/src/rehype-base-paths.js

@@ -3,6 +3,7 @@
  *
  * Transforms:
  *   /img/foo.png → /BMAD-METHOD/img/foo.png (when base is /BMAD-METHOD/)
+ *   /downloads/file.zip → /BMAD-METHOD/downloads/file.zip
  *   /llms.txt → /BMAD-METHOD/llms.txt
  *
  * Only affects absolute paths (/) - relative paths and external URLs are unchanged.