bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.21

package/CONTRIBUTING.md

@@ -86,25 +86,13 @@ Please propose small, granular changes! For large or significant changes, discus
 
 ### Which Branch?
 
-**Submit to `next` branch** (most contributions):
-
-- ✨ New features or agents
-- 🎨 Enhancements to existing features
-- 📚 Documentation updates
-- ♻️ Code refactoring
-- ⚡ Performance improvements
-- 🧪 New tests
-- 🎁 New bmad modules
-
-**Submit to `main` branch** (critical only):
+**Submit PR's to `main` branch** (critical only):
 
 - 🚨 Critical bug fixes that break basic functionality
 - 🔒 Security patches
 - 📚 Fixing dangerously incorrect documentation
 - 🐛 Bugs preventing installation or basic usage
 
-**When in doubt, submit to `next`**. We'd rather test changes thoroughly before they hit stable.
-
 ### PR Size Guidelines
 
 - **Ideal PR size**: 200-400 lines of code changes
@@ -248,10 +236,8 @@ Each commit should represent one logical change:
 3. **Don't paste code in issues** - create a proper PR instead
 4. **Don't submit your whole project** - contribute specific improvements
 
-## Code Style
+## Prompt & Agent Guidelines
 
-- Follow the existing code style and conventions
-- Write clear comments for complex logic
 - Keep dev agents lean - they need context for coding, not documentation
 - Web/planning agents can be larger with more complex tasks
 - Everything is natural language (markdown) - no code in core framework

package/LICENSE

@@ -21,6 +21,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 TRADEMARK NOTICE:
-BMAD™, BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. The use of these 
+BMad™ , BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. The use of these 
 trademarks in this software does not grant any rights to use the trademarks 
 for any other purpose.

package/README.md

@@ -1,263 +1,245 @@
-# BMad CORE + BMad Method
+# BMad Method & BMad Core
 
-[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
+[![Stable Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=stable)](https://www.npmjs.com/package/bmad-method)
+[![Alpha Version](https://img.shields.io/npm/v/bmad-method/alpha?color=orange&label=alpha)](https://www.npmjs.com/package/bmad-method)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
-> **🚨 ALPHA VERSION DOCUMENTATION**
->
-> This README documents **BMad v6 (Alpha)** - currently under active development.
->
-> **To install v6 Alpha:** `npx bmad-method@alpha install`
->
-> **Looking for stable v4 documentation?** [View v4 README](https://github.com/bmad-code-org/BMAD-METHOD/tree/v4-stable)
->
-> **Want the stable version?** `npx bmad-method install` (installs v4.x)
-
-## The Universal Human-AI Collaboration Platform
-
-BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) is a revolutionary framework that amplifies human potential through specialized AI agents. Unlike traditional AI tools that replace human thinking, BMad-CORE guides you through reflective workflows that bring out your best ideas and the AI's full capabilities.
-
-**🎯 Human Amplification, Not Replacement** • **🎨 Works in Any Domain** • **⚡ Powered by Specialized Agents**
-
----
-
-## 🔄 Upgrading from v4?
-
-**[→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Complete migration instructions for existing v4 users
-
 ---
 
-## What is BMad-CORE?
+<div align="center">
 
-BMad-CORE is the **universal foundation** that powers all BMad modules. It provides:
+## 🎉 NEW: BMAD V6 Installer - Create & Share Custom Content!
 
-- **Agent orchestration framework** for specialized AI personas
-- **Workflow execution engine** for guided processes
-- **Modular architecture** allowing domain-specific extensions
-- **IDE integrations** across multiple development environments
-- **Update-safe customization system** for all agents and workflows
+The completely revamped **BMAD V6 installer** now includes built-in support for creating, installing, and sharing custom modules, agents, workflows, templates, and tools! Build your own AI solutions or share them with your team - and real soon, with the whole BMad Community througha verified community sharing portal!
 
-### Core v6 Framework Enhancements
+**✨ What's New:**
 
-**All modules benefit from these new core capabilities:**
+- 📦 **Streamlined Custom Module Installation** - Package your custom content as installable modules
+- 🤖 **Agent & Workflow Sharing** - Distribute standalone agents and workflows
+- 🔄 **Unitary Module Support** - Install individual components without full modules
+- ⚙️ **Dependency Management** - Automatic handling of module dependencies
+- 🛡️ **Update-Safe Customization** - Your custom content persists through updates
 
-- **🎨 Full Agent Customization** - Modify any agent's name, role, personality, and behavior via `bmad/_cfg/agents/` customize files that survive all updates
-- **🌐 Multi-Language Support** - Choose your language for both agent communication and documentation output independently
-- **👤 User Personalization** - Agents address you by name and adapt to your technical level and preferences
-- **🔄 Update-Safe Configuration** - Your customizations persist through framework and module updates
-- **⚙️ Flexible Settings** - Configure communication style, technical depth, output formats, and more per module or globally
+**📚 Learn More:**
 
-### The C.O.R.E. Philosophy
+- [**Custom Content Overview**](./docs/custom-content.md) - Discover all supported content types
+- [**Installation Guide**](./docs/custom-content-installation.md) - Learn to create and install custom content
+- [**Detail Content Docs**](./src/modules/bmb/docs/index.md) - Reference details for agents, modules, workflows and the bmad builder
+- [**2 Very simple Custom Modules of questionable quality**](./samples/sample-custom-modules/README.md) - if you want to download and try to install a custom shared module, get an idea of how to bundle and share your own, or create your own personal agents, workflows and modules.
 
-- **C**ollaboration: Human-AI partnership where both contribute unique strengths
-- **O**ptimized: Refined processes for maximum effectiveness
-- **R**eflection: Guided thinking that unlocks better solutions
-- **E**ngine: Powerful framework orchestrating specialized agents and workflows
-
-Instead of giving you answers, BMad-CORE helps you **discover better solutions** through strategic questioning, expert guidance, and structured thinking.
+</div>
 
 ---
 
-## The BMad Method - Agile AI-Driven Development
+## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
 
-**The flagship module for software and game development excellence.**
+**Build More, Architect Dreams** (BMAD) with **21 specialized AI agents** across 4 official modules, and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms, and new step file workflows that allow for incredibly long workflows to stay on the rails longer than ever before!
 
-The BMad Method (BMM) is a complete AI-driven agile development framework that revolutionizes how you build software and games. Whether you're fixing a bug, building a feature, or architecting an enterprise system, BMM adapts to your needs.
+Additionally - when we say 'Build More, Architect Dreams' - we mean it! The BMad Builder has landed, and now as of Alpha.15 is fully supported in the installation flow via NPX - custom stand along agents, workflows and the modules of your dreams! The community forge will soon open, endless possibility awaits!
 
-### What's New in v6?
+> **🚀 v6 is a MASSIVE upgrade from v4!** Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. [See what's new →](#whats-new-in-v6)
 
-**🎯 Revolutionary Scale-Adaptive Workflows**
+> **📌 v6 Alpha Status:** Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to [BMadCode YouTube](https://www.youtube.com/@BMadCode).
 
-- **Levels 0-4**: Automatically adjusts from quick fixes to enterprise-scale projects
-- **Greenfield & Brownfield**: Full support for new projects and existing codebases
-- **Smart Context Engine**: New optimized brownfield documentation engine that understands your existing code
+## 🎯 Why BMad Method?
 
-**🏗️ Project-Adaptive Architecture**
+Unlike generic AI coding assistants, BMad Method provides **structured, battle-tested workflows** powered by specialized agents who understand agile development. Each agent has deep domain expertise—from product management to architecture to testing—working together seamlessly.
 
-- Architecture documents that adapt to YOUR project type (web, mobile, embedded, game, etc.)
-- No more "one-size-fits-all" templates
-- Specialized sections based on what you're actually building
-- Game development fully integrated with engine-specific guidance (Unity, Phaser, Godot, Unreal, and more)
+**✨ Key Benefits:**
 
-**⚡ From Simple to Complex - All in One System**
+- **Scale-Adaptive Intelligence** - Automatically adjusts planning depth from bug fixes to enterprise systems
+- **Complete Development Lifecycle** - Analysis → Planning → Architecture → Implementation
+- **Specialized Expertise** - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.)
+- **Proven Methodologies** - Built on agile best practices with AI amplification
+- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code
 
-- **Level 0-1**: Quick fixes and small features with minimal overhead
-- **Level 2**: Feature development with lightweight planning
-- **Level 3-4**: Full enterprise workflows with comprehensive documentation
-- Seamless workflow progression as complexity grows
+## 🏗️ The Power of BMad Core
 
-**💬 Highly Interactive & Guided**
+**BMad Method** is actually a sophisticated module built on top of **BMad Core** (**C**ollaboration **O**ptimized **R**eflection **E**ngine). This revolutionary architecture means:
 
-- Interactive workflows that ask the right questions
-- Agents guide you through discovery rather than giving generic answers
-- Context-aware recommendations based on your project state
-- Real-time validation and course correction
+- **BMad Core** provides the universal framework for human-AI collaboration
+- **BMad Method** leverages Core to deliver agile development workflows
+- **BMad Builder** lets YOU create custom modules as powerful as BMad Method itself
 
-**📋 Four-Phase Methodology**
+With **BMad Builder**, you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an **official community marketplace**. Imagine building and sharing your own specialized AI team!
 
-1. **Analysis** (Optional) - Brainstorming, research, product briefs
-2. **Planning** (Required) - Scale-adaptive PRD/GDD generation
-3. **Solutioning** (Level 3-4) - Adaptive architecture and tech specs
-4. **Implementation** (Iterative) - Story creation, context gathering, development, review
+## 📊 See It In Action
 
-### Specialized Agents
+<p align="center">
+  <img src="./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
+</p>
 
-- **PM** - Product planning and requirements
-- **Analyst** - Research and business analysis
-- **Architect** - Technical architecture and design
-- **Scrum Master** - Sprint planning and story management
-- **Developer** - Implementation with senior dev review
-- **Game Development** (Optional) - Game Designer, Game Developer, Game Architect
-- **And more** - UX, Test Architect, and other specialized roles
+<p align="center">
+  <em>Complete BMad Method workflow showing all phases, agents, and decision points</em>
+</p>
 
-### Documentation
+## 🚀 Get Started in 3 Steps
 
-- **[📚 Complete BMM Documentation](./src/modules/bmm/README.md)** - Full module reference
-- **[📖 BMM Workflows Guide](./src/modules/bmm/workflows/README.md)** - Essential reading for using BMM
+### 1. Install BMad Method
 
----
-
-## Additional Beta Modules
-
-### **[BMad Builder (BMB)](./src/modules/bmb/README.md)** - Create Custom Solutions
-
-Build your own agents, workflows, and modules using the BMad-CORE framework.
-
-- **Agent Creation**: Design specialized agents with custom roles and behaviors
-- **Workflow Design**: Build structured multi-step processes
-- **Module Development**: Package complete solutions for any domain
-- **Three Agent Types**: Full module, hybrid, and standalone agents
+```bash
+# Install v6 Alpha (recommended)
+npx bmad-method@alpha install
 
-**[📚 Complete BMB Documentation](./src/modules/bmb/README.md)** | **[🎯 Agent Creation Guide](./src/modules/bmb/workflows/create-agent/README.md)**
+# Or stable v4 for production
+npx bmad-method install
+```
 
----
+### 2. Initialize Your Project
 
-### **[Creative Intelligence Suite (CIS)](./src/modules/cis/readme.md)** - Innovation & Creativity
+Load any agent in your IDE and run:
 
-Transform creative and strategic thinking through AI-powered facilitation across five specialized domains.
+```
+*workflow-init
+```
 
-- **5 Interactive Workflows**: Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
-- **150+ Creative Techniques**: Proven frameworks and methodologies
-- **5 Specialized Agents**: Each with unique personas and facilitation styles
-- **Shared Resource**: Powers creative workflows in other modules (e.g., BMM brainstorming)
+This analyzes your project and recommends the right workflow track.
 
-**[📚 Complete CIS Documentation](./src/modules/cis/readme.md)** | **[📖 CIS Workflows](./src/modules/cis/workflows/README.md)**
+### 3. Choose Your Track
 
----
+BMad Method adapts to your needs with three intelligent tracks:
 
-## Quick Start
+| Track              | Use For                   | Planning                | Time to Start |
+| ------------------ | ------------------------- | ----------------------- | ------------- |
+| **⚡ Quick Flow**  | Bug fixes, small features | Tech spec only          | < 5 minutes   |
+| **📋 BMad Method** | Products, platforms       | PRD + Architecture + UX | < 15 minutes  |
+| **🏢 Enterprise**  | Compliance, scale         | Full governance suite   | < 30 minutes  |
 
-### Prerequisites
+> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal.
 
-- **Node.js v20+** ([Download](https://nodejs.org))
+## 🔄 How It Works: 4-Phase Methodology
 
-### Installation
+BMad Method guides you through a proven development lifecycle:
 
-Install BMad to your project using npx:
+1. **📊 Analysis** (Optional) - Brainstorm, research, and explore solutions
+2. **📝 Planning** - Create PRDs, tech specs, or game design documents
+3. **🏗️ Solutioning** - Design architecture, UX, and technical approach
+4. **⚡ Implementation** - Story-driven development with continuous validation
 
-```bash
-# Install v6 Alpha (this version)
-npx bmad-method@alpha install
+Each phase has specialized workflows and agents working together to deliver exceptional results.
 
-# Install stable v4 (production-ready)
-npx bmad-method install
-```
+## 🤖 Meet Your Team
 
-The interactive installer will guide you through:
+**12 Specialized Agents** working in concert:
 
-1. **Project location** - Where to install BMad
-2. **Module selection** - Choose which modules you need (BMM, BMB, CIS)
-3. **Configuration** - Set your name, language preferences, and module options
-   - **Game Development (Optional)**: When installing BMM, you can optionally include game development agents and workflow!
-4. **IDE integration** - Configure your development environment
+| Development | Architecture   | Product       | Leadership     |
+| ----------- | -------------- | ------------- | -------------- |
+| Developer   | Architect      | PM            | Scrum Master   |
+| UX Designer | Test Architect | Analyst       | BMad Master    |
+| Tech Writer | Game Architect | Game Designer | Game Developer |
 
-### What Gets Installed
+**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready fixture-based utilities.
 
-All modules install to a single `bmad/` folder in your project:
+Each agent brings deep expertise and can be customized to match your team's style.
 
-```
-your-project/
-└── bmad/
-    ├── core/         # Core framework (always installed)
-    ├── bmm/          # BMad Method (if selected)
-    ├── bmb/          # BMad Builder (if selected)
-    ├── cis/          # Creative Intelligence Suite (shared resources)
-    └── _cfg/         # Your customizations
-        └── agents/   # Agent customization files
-```
+## 📦 What's Included
 
-### Getting Started with BMM
+### Core Modules
 
-After installation, activate the Analyst agent in your IDE and run:
+- **BMad Method (BMM)** - Complete agile development framework
+  - 12 specialized agents
+  - 34 workflows across 4 phases
+  - Scale-adaptive planning
+  - [→ Documentation Hub](./src/modules/bmm/docs/index.md)
 
-```bash
-/workflow-init
-```
+- **BMad Builder (BMB)** - Create custom agents and workflows
+  - Build anything from simple agents to complex modules
+  - Create domain-specific solutions (legal, medical, finance, education)
+  - [→ Builder Guide](./src/modules/bmb/docs/index.md)
 
-Or run it directly as a command (command syntax varies by IDE - use slash commands in Claude Code, OpenCode, etc.).
+- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
+  - Brainstorming, design thinking, storytelling
+  - 5 creative facilitation workflows
+  - [→ Creative Workflows](./src/modules/cis/docs/index.md)
 
-This sets up the guided workflow system and helps you choose the right starting point for your project based on its complexity.
+### Key Features
 
----
+- **🎨 Customizable Agents** - Modify personalities, expertise, and communication styles
+- **🌐 Multi-Language Support** - Separate settings for communication and code output
+- **📄 Document Sharding** - 90% token savings for large projects
+- **🔄 Update-Safe** - Your customizations persist through updates
+- **🚀 Web Bundles** - Use in ChatGPT, Claude Projects, or Gemini Gems
 
-## Key Features
+## 📚 Documentation
 
-### 🎨 Update-Safe Customization
+### Quick Links
 
-- **Agent Customization**: Modify agents via `bmad/_cfg/agents/` customize files
-- **Persistent Settings**: Your customizations survive updates
-- **Multi-Language Support**: Agents communicate in your preferred language
-- **Flexible Configuration**: Adjust agent names, roles, communication styles, and more
+- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - 15-minute introduction
+- **[Complete BMM Documentation](./src/modules/bmm/docs/index.md)** - All guides and references
+- **[Agent Customization](./docs/agent-customization-guide.md)** - Personalize your agents
+- **[All Documentation](./docs/index.md)** - Complete documentation index
 
-### 🚀 Intelligent Installation
+### For v4 Users
 
-The installer automatically:
+- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
+- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
 
-- Detects and migrates v4 installations
-- Configures IDE integrations
-- Resolves module dependencies
-- Sets up agent customization templates
-- Creates unified agent manifests
+## 💬 Community & Support
 
-### 📁 Unified Architecture
+- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects
+- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features
+- **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and demos
+- **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles
+- **[Code of Conduct](.github/CODE_OF_CONDUCT.md)** - Community guidelines
 
-Everything in one place - no more scattered configuration folders. Clean, organized, maintainable.
+## 🛠️ Development
 
----
+For contributors working on the BMad codebase:
 
-## Additional Documentation
+```bash
+# Run all quality checks
+npm test
 
-- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions for v4 users
-- **[CLI Tool Guide](./tools/cli/README.md)** - Installer and bundler reference
-- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to BMad
+# Development commands
+npm run lint:fix      # Fix code style
+npm run format:fix    # Auto-format code
+npm run bundle        # Build web bundles
+```
 
----
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
 
-## Community & Support
+## What's New in v6
 
-- 💬 **[Discord](https://discord.gg/gk8jAdXWmj)** - Get help, share ideas, and collaborate
-- 🐛 **[Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs and request features
-- 🎥 **[YouTube](https://www.youtube.com/@BMadCode)** - Tutorials and updates
-- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Get notified of updates
+**v6 represents a complete architectural revolution from v4:**
 
----
+### 🚀 Major Upgrades
 
-## Contributing
+- **BMad Core Framework** - Modular architecture enabling custom domain solutions
+- **Scale-Adaptive Intelligence** - Automatic adjustment from bug fixes to enterprise
+- **Visual Workflows** - Beautiful SVG diagrams showing complete methodology
+- **BMad Builder Module** - Create and share your own AI agent teams
+- **50+ Workflows** - Up from 20 in v4, covering every development scenario
+- **19 Specialized Agents** - Enhanced with customizable personalities and expertise
+- **Update-Safe Customization** - Your configs persist through all updates
+- **Web Bundles** - Use agents in ChatGPT, Claude, and Gemini
+- **Multi-Language Support** - Separate settings for communication and code
+- **Document Sharding** - 90% token savings for large projects
 
-We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
+### 🔄 For v4 Users
 
----
+- **[Comprehensive Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Step-by-step migration
+- **[v4 Documentation Archive](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)** - Legacy reference
+- Backwards compatibility where possible
+- Smooth migration path with installer detection
 
-## License
+## 📄 License
 
 MIT License - See [LICENSE](LICENSE) for details.
 
-**Trademark Notice**: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved.
+**Trademarks:** BMad™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
+
+Supported by:&nbsp;&nbsp;<a href="https://m.do.co/c/00f11bd932bb"><img src="https://opensource.nyc3.cdn.digitaloceanspaces.com/attribution/assets/SVG/DO_Logo_horizontal_blue.svg" height="24" alt="DigitalOcean" style="vertical-align: middle;"></a>
 
 ---
 
-[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
+<p align="center">
+  <a href="https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD" alt="Contributors">
+  </a>
+</p>
 
-<sub>Built with ❤️ for the human-AI collaboration community</sub>
+<p align="center">
+  <sub>Built with ❤️ for the human-AI collaboration community</sub>
+</p>

package/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/`