refactor(docs): migrate from Docusaurus to Astro+Starlight

Replace Docusaurus with Astro and the Starlight documentation theme
for improved performance, better customization, and modern tooling.

Build pipeline changes:
- New build-docs.js orchestrates link checking, artifact generation,
  and Astro build in sequence
- Add check-doc-links.js for validating internal links and anchors
- Generate llms.txt and llms-full.txt for LLM-friendly documentation
- Create downloadable source bundles (bmad-sources.zip, bmad-prompts.zip)
- Suppress MODULE_TYPELESS_PACKAGE_JSON warning in Astro build
- Output directly to build/site for cleaner deployment

Website architecture:
- Add rehype-markdown-links.js plugin to transform .md links to routes
- Add site-url.js helper for GitHub Pages URL resolution with strict
  validation (throws on invalid GITHUB_REPOSITORY format)
- Custom Astro components: Banner, Header, MobileMenuFooter
- Symlink docs/ into website/src/content/docs for Starlight

Documentation cleanup:
- Remove Docusaurus _category_.json files (Starlight uses frontmatter)
- Convert all docs to use YAML frontmatter with title field
- Move downloads.md from website/src/pages to docs/
- Consolidate style guide and workflow diagram docs
- Add 404.md and tutorials/index.md

.github/workflows/docs.yaml

@@ -39,20 +39,11 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Determine site URL
-        id: site-url
-        run: |
-          if [ "${{ github.repository }}" = "bmad-code-org/BMAD-METHOD" ]; then
-            echo "url=https://bmad-code-org.github.io/BMAD-METHOD" >> $GITHUB_OUTPUT
-          else
-            OWNER="${{ github.repository_owner }}"
-            REPO="${{ github.event.repository.name }}"
-            echo "url=https://${OWNER}.github.io/${REPO}" >> $GITHUB_OUTPUT
-          fi
-
       - name: Build documentation
         env:
-          SITE_URL: ${{ steps.site-url.outputs.url }}
+          # Override site URL from GitHub repo variable if set
+          # Otherwise, astro.config.mjs will compute from GITHUB_REPOSITORY
+          SITE_URL: ${{ vars.SITE_URL }}
         run: npm run docs:build
 
       - name: Upload artifact

.gitignore

@@ -75,6 +75,7 @@ _bmad-output
 
 bmad-custom-src/
 
-# Docusaurus / Documentation Build
+# Astro / Documentation Build
-.docusaurus/
+website/.astro/
+website/dist/
 build/

docs/404.md

@@ -0,0 +1,9 @@
+---
+title: Page Not Found
+template: splash
+---
+
+
+The page you're looking for doesn't exist or has been moved.
+
+[Return to Home](/)

docs/_README_WORKFLOW_DIAGRAMS.md

@@ -1,4 +1,7 @@
-# Workflow Diagram Maintenance
+---
+title: "Workflow Diagram Maintenance"
+---
+
 
 ## Regenerating SVG from Excalidraw
 

docs/_STYLE_GUIDE.md

@@ -1,8 +1,15 @@
-# Tutorial Style Guide
+# Documentation Style Guide
 
-Standards for writing tutorials and getting-started guides in BMad documentation.
+Internal guidelines for maintaining consistent, high-quality documentation across the BMAD Method project. This document is not included in the Starlight sidebar — it's for contributors and maintainers, not end users.
 
-## Standard Structure
+## Quick Principles
+
+1. **Clarity over brevity** — Be concise, but never at the cost of understanding
+2. **Consistent structure** — Follow established patterns so readers know what to expect
+3. **Strategic visuals** — Use admonitions, tables, and diagrams purposefully
+4. **Scannable content** — Headers, lists, and callouts help readers find what they need
+
+## Tutorial Structure
 
 Every tutorial should follow this structure:
 
@@ -50,22 +57,18 @@ Not all sections are required for every tutorial, but this is the standard flow.
 
 ## Admonitions
 
-Use Docusaurus admonitions strategically:
+Use Starlight admonitions strategically:
 
 ```md
 :::tip[Title]
 Shortcuts, best practices, "pro tips"
 :::
 
-:::info[Title]
+:::note[Title]
 Context, definitions, examples, prerequisites
 :::
 
-:::note
+:::caution[Title]
-Supplementary information (can be collapsed)
-:::
-
-:::warning[Title]
 Caveats, potential issues, things to watch out for
 :::
 
@@ -78,10 +81,10 @@ Critical warnings only — data loss, security issues
 
 | Admonition | Standard Use in Tutorials |
 |------------|---------------------------|
-| `:::info[Prerequisites]` | What users need before starting |
+| `:::note[Prerequisites]` | What users need before starting |
 | `:::tip[Quick Path]` | TL;DR summary at top of tutorial |
-| `:::warning[Fresh Chats]` | Context limitation reminders |
+| `:::caution[Fresh Chats]` | Context limitation reminders |
-| `:::info[Example]` | Command/response examples |
+| `:::note[Example]` | Command/response examples |
 | `:::tip[Check Your Status]` | How to verify progress |
 | `:::tip[Remember These]` | Key takeaways at end |
 
@@ -128,7 +131,7 @@ Agent: [Response here]
 For command/response examples, use an admonition instead:
 
 ```md
-:::info[Example]
+:::note[Example]
 Run `workflow-status` and the agent will tell you the next recommended workflow.
 :::
 ```
@@ -278,7 +281,7 @@ your-project/
 
 Load the **Analyst agent** in your IDE, wait for the menu, then run `workflow-init`.
 
-:::info[What Happens]
+:::note[What Happens]
 You'll describe your project goals and complexity. The workflow then recommends a planning track.
 :::
 ```

docs/_contributing/index.md

@@ -1,18 +0,0 @@
-# Contributing to BMAD Documentation
-
-This directory contains internal guidelines for maintaining consistent, high-quality documentation across the BMAD Method project.
-
-## Style Guides
-
-- [Tutorial Style Guide](./tutorial-style.md) — Formatting standards for tutorials and getting-started guides
-
-## Quick Principles
-
-1. **Clarity over brevity** — Be concise, but never at the cost of understanding
-2. **Consistent structure** — Follow established patterns so readers know what to expect
-3. **Strategic visuals** — Use admonitions, tables, and diagrams purposefully
-4. **Scannable content** — Headers, lists, and callouts help readers find what they need
-
-## Directory Purpose
-
-This `_contributing/` directory is prefixed with underscore to exclude it from the Docusaurus sidebar. These documents are for contributors and maintainers, not end users.

docs/downloads.md

@@ -1,32 +1,38 @@
-# Downloads
+---
+title: Downloads
+---
 
 Download BMAD Method resources for offline use, AI training, or integration.
 
+## Source Bundles
+
+| File | Description |
+|------|-------------|
+| **[bmad-sources.zip](/downloads/bmad-sources.zip)** | Complete BMAD source files |
+| **[bmad-prompts.zip](/downloads/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.
 
-| File                                | Description                         | Use Case                   |
+| File | Description | Use Case |
-| ----------------------------------- | ----------------------------------- | -------------------------- |
+|------|-------------|----------|
-| **[llms.txt](/llms.txt)**           | Documentation index with summaries  | Quick overview, navigation |
+| **[llms.txt](/llms.txt)** | Documentation index with summaries | Quick overview, navigation |
-| **[llms-full.txt](/llms-full.txt)** | Complete documentation concatenated | Full context loading       |
+| **[llms-full.txt](/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

docs/explanation/agents/barry-quick-flow.md

@@ -1,4 +1,7 @@
-# Quick Flow Solo Dev Agent (Barry)
+---
+title: "Quick Flow Solo Dev Agent (Barry)"
+---
+
 
 **Agent ID:** `_bmad/bmm/agents/quick-flow-solo-dev.md`
 **Icon:** 🚀

docs/explanation/agents/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Agents
+title: "Understanding Agents"
 description: Understanding BMAD agents and their roles
 ---
 
-# Understanding Agents
 
 Comprehensive guides to BMAD's AI agents - their roles, capabilities, and how to work with them effectively.
 

docs/explanation/architecture/_category_.json

@@ -1 +0,0 @@
-{ "label": "Architecture", "position": 2 }

docs/explanation/architecture/four-phases.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Four Phases
+title: "The Four Phases of BMad Method"
 description: Understanding the four phases of the BMad Method
 ---
 
-# The Four Phases of BMad Method
 
 BMad Method uses a four-phase approach that adapts to project complexity while ensuring consistent quality.
 

docs/explanation/architecture/preventing-agent-conflicts.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Preventing Agent Conflicts
+title: "Preventing Agent Conflicts"
 description: How architecture prevents conflicts when multiple agents implement a system
 ---
 
-# Preventing Agent Conflicts
 
 When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
 

docs/explanation/architecture/why-solutioning-matters.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Why Solutioning Matters
+title: "Why Solutioning Matters"
 description: Understanding why the solutioning phase is critical for multi-epic projects
 ---
 
-# Why Solutioning Matters
 
 Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
 

docs/explanation/bmad-builder/_category_.json

@@ -1 +0,0 @@
-{ "label": "BMAD Builder", "position": 7 }

docs/explanation/bmad-builder/custom-content-types.md

@@ -1,4 +1,7 @@
-# Custom Content
+---
+title: "Custom Content"
+---
+
 
 BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agents provides workflows and expertise to plan and build any custom content you can imagine.
 
@@ -14,13 +17,13 @@ This flexibility transforms the platform beyond its current capabilities, enabli
 
 ## Categories
 
-- [Custom Stand Alone Modules](#custom-stand-alone-modules)
+- [Custom Stand-Alone Modules](#custom-stand-alone-modules)
-- [Custom Add On Modules](#custom-add-on-modules)
+- [Custom Add-On Modules](#custom-add-on-modules)
 - [Custom Global Modules](#custom-global-modules)
 - [Custom Agents](#custom-agents)
 - [Custom Workflows](#custom-workflows)
 
-## Custom Stand Alone Modules
+## Custom Stand-Alone Modules
 
 Custom modules range from simple collections of related agents, workflows, and tools designed to work independently, to complex, expansive systems like the BMad Method or even larger applications.
 
@@ -31,9 +34,9 @@ Custom modules are [installable](../../how-to/installation/install-custom-module
 - Custom installer functions with IDE-specific post-installation handling (custom hooks, subagents, or vendor-specific tools)
 - Ability to bundle specific tools such as MCP, skills, execution libraries, and code
 
-## Custom Add On Modules
+## Custom Add-On Modules
 
-Custom Add On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
+Custom Add-On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
 
 Examples include:
 
@@ -41,7 +44,7 @@ Examples include:
 - Framework-specific support for particular use cases
 - Game development expansions that add new genre-specific capabilities without reinventing existing functionality
 
-Add on modules can include:
+Add-on modules can include:
 
 - Custom agents with awareness of the target module
 - Access to existing module workflows
@@ -49,7 +52,7 @@ Add on modules can include:
 
 ## Custom Global Modules
 
-Similar to Custom Stand Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMAD ecosystem.
+Similar to Custom Stand-Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMAD ecosystem.
 
 Examples include:
 

docs/explanation/bmad-builder/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: BMad Builder
+title: "BMad Builder (BMB)"
 description: Create custom agents, workflows, and modules for BMAD
 ---
 
-# BMad Builder (BMB)
 
 Create custom agents, workflows, and modules for BMAD.
 

docs/explanation/bmm/index.md

@@ -1,4 +1,7 @@
-# BMM Documentation
+---
+title: "BMM Documentation"
+---
+
 
 Complete guides for the BMad Method Module (BMM) - AI-powered agile development workflows that adapt to your project's complexity.
 
@@ -26,10 +29,10 @@ The BMad Method is meant to be adapted and customized to your specific needs. In
 
 First know there is the full BMad Method Process and then there is a Quick Flow for those quicker smaller efforts.
 
-- **[Full Adaptive BMad Method](#-workflow-guides)** - Full planning and scope support through extensive development and testing.
+- **[Full Adaptive BMad Method](#workflow-guides)** - Full planning and scope support through extensive development and testing.
   - Broken down into 4 phases, all of which are comprised of both required and optional phases
     - Phases 1-3 are all about progressive idea development through planning and preparations to build your project.
-    - Phase 4 is the implementation cycle where you will Just In Time (JIT) produce the contextual stories needed for the dev agent based on the extensive planing completed
+    - Phase 4 is the implementation cycle where you will Just In Time (JIT) produce the contextual stories needed for the dev agent based on the extensive planning completed
     - All 4 phases have optional steps in them, depending on how rigorous you want to go with planning, research ideation, validation, testing and traceability.
   - While there is a lot here, know that even this can be distilled down to a simple PRD, Epic and Story list and then jump into the dev cycle. But if that is all you want, you might be better off with the BMad Quick Flow described next
 

docs/explanation/core-concepts/_category_.json

@@ -1 +0,0 @@
-{ "label": "Core Concepts", "position": 1 }

docs/explanation/core-concepts/agent-roles.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Agent Roles
+title: "Agent Roles in BMad Method"
 description: Understanding the different agent roles in BMad Method
 ---
 
-# Agent Roles in BMad Method
 
 BMad Method uses specialized AI agents, each with a distinct role, expertise, and personality. Understanding these roles helps you know which agent to use for each task.
 

docs/explanation/core-concepts/index.md

@@ -1,4 +1,7 @@
-# BMAD Core Concepts
+---
+title: "BMAD Core Concepts"
+---
+
 
 Understanding the fundamental building blocks of the BMAD Method.
 

docs/explanation/core-concepts/what-are-agents.md

@@ -1,4 +1,7 @@
-# Agents
+---
+title: "Agents"
+---
+
 
 Agents are AI assistants that help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu.
 

docs/explanation/core-concepts/what-are-modules.md

@@ -1,4 +1,7 @@
-# Modules
+---
+title: "Modules"
+---
+
 
 Modules are organized collections of agents and workflows that solve specific problems or address particular domains.
 

docs/explanation/core-concepts/what-are-workflows.md

@@ -1,4 +1,7 @@
-# Workflows
+---
+title: "Workflows"
+---
+
 
 Workflows are like prompts on steroids. They harness the untapped power and control of LLMs through progressive disclosure—breaking complex tasks into focused steps that execute sequentially. Instead of random AI slop where you hope for the best, workflows give you repeatable, reliable, high-quality outputs.
 

docs/explanation/core/index.md

@@ -1,4 +1,7 @@
-# Core Module
+---
+title: "Core Module"
+---
+
 
 The Core Module is installed with all installations of BMAD modules and provides common functionality that any module, workflow, or agent can take advantage of.
 

docs/explanation/creative-intelligence/_category_.json

@@ -1 +0,0 @@
-{ "label": "Creative Intelligence", "position": 5 }

docs/explanation/creative-intelligence/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Creative Intelligence
+title: "Creative Intelligence Suite (CIS)"
 description: AI-powered creative facilitation with the Creative Intelligence Suite
 ---
 
-# Creative Intelligence Suite (CIS)
 
 AI-powered creative facilitation transforming strategic thinking through expert coaching across five specialized domains.
 
@@ -71,20 +70,16 @@ Business model disruption:
 ### Direct Workflow
 
 ```bash
-# Start interactive session
 workflow brainstorming
 
-# With context document
 workflow design-thinking --data /path/to/context.md
 ```
 
 ### Agent-Facilitated
 
 ```bash
-# Load agent
 agent cis/brainstorming-coach
 
-# Start workflow
 > *brainstorm
 ```
 

docs/explanation/faq/brownfield-faq.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Brownfield
+title: "Brownfield Development FAQ"
 description: Common questions about brownfield development in the BMad Method
 ---
 
-# Brownfield Development FAQ
 
 Quick answers to common questions about brownfield (existing codebase) development in the BMad Method.
 

docs/explanation/faq/getting-started-faq.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Getting Started
+title: "Getting Started FAQ"
 description: Common questions about getting started with the BMad Method
 ---
 
-# Getting Started FAQ
 
 Quick answers to common questions about getting started with the BMad Method.
 

docs/explanation/faq/implementation-faq.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Implementation
+title: "Implementation FAQ"
 description: Common questions about implementation in the BMad Method
 ---
 
-# Implementation FAQ
 
 Quick answers to common questions about implementation in the BMad Method.
 

docs/explanation/faq/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: FAQ
+title: "Frequently Asked Questions"
 description: Frequently asked questions about the BMad Method
 ---
 
-# Frequently Asked Questions
 
 Quick answers to common questions about the BMad Method, organized by topic.
 

docs/explanation/faq/levels-and-tracks-faq.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Levels & Tracks
+title: "Levels and Tracks FAQ"
 description: Common questions about choosing the right level for your project
 ---
 
-# Levels and Tracks FAQ
 
 Quick answers to common questions about choosing the right level for your BMad Method project.
 
@@ -14,7 +13,7 @@ Quick answers to common questions about choosing the right level for your BMad M
 **A:** Use workflow-init for automatic detection, or self-assess using these keywords:
 
 - **Level 0:** "fix", "bug", "typo", "small change", "patch" → 1 story
-- **Level 1:** "simple", "basic", "small feature", "add" → 2-10 stories
+- **Level 1:** "simple", "basic", "small feature", "add" → 1-10 stories
 - **Level 2:** "dashboard", "several features", "admin panel" → 5-15 stories
 - **Level 3:** "platform", "integration", "complex", "system" → 12-40 stories
 - **Level 4:** "enterprise", "multi-tenant", "multiple products" → 40+ stories

docs/explanation/faq/planning-faq.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Planning
+title: "Planning Documents FAQ"
 description: Common questions about planning documents in the BMad Method
 ---
 
-# Planning Documents FAQ
 
 Quick answers to common questions about planning documents in the BMad Method.
 

docs/explanation/faq/tools-faq.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Tools & Advanced
+title: "Tools and Advanced FAQ"
 description: Common questions about tools, IDEs, and advanced topics in the BMad Method
 ---
 
-# Tools and Advanced FAQ
 
 Quick answers to common questions about tools, IDEs, and advanced topics in the BMad Method.
 

docs/explanation/faq/workflows-faq.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Workflows
+title: "Workflows FAQ"
 description: Common questions about BMad Method workflows and phases
 ---
 
-# Workflows FAQ
 
 Quick answers to common questions about BMad Method workflows and phases.
 

docs/explanation/features/_category_.json

@@ -1 +0,0 @@
-{ "label": "Features", "position": 4 }

docs/explanation/features/advanced-elicitation.md

@@ -1,4 +1,7 @@
-# Advanced Elicitation
+---
+title: "Advanced Elicitation"
+---
+
 
 **Push the LLM to rethink its work through 50+ reasoning methods—essentially, LLM brainstorming.**
 

docs/explanation/features/brainstorming-techniques.md

@@ -1,4 +1,7 @@
-# Brainstorming
+---
+title: "Brainstorming"
+---
+
 
 **Facilitate structured creative sessions using 60+ proven ideation techniques.**
 

docs/explanation/features/party-mode.md

@@ -1,4 +1,7 @@
-# Party Mode: Multi-Agent Collaboration
+---
+title: "Party Mode: Multi-Agent Collaboration"
+---
+
 
 **Get all your AI agents in one conversation**
 
@@ -36,20 +39,15 @@ Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent or at ke
 ## Quick Start
 
 ```bash
-# Trigger party mode
 /bmad:core:workflows:party-mode
 
-# OR from any agent context
 *party-mode
 
-# Super Hack
 
 /bmad:core:workflows:party-mode and include also in the party Santa Clause and Einstein 
 
-# During party
 Ask questions, respond to agents, direct the conversation
 
-# Exit
 Type: exit
 ```
 

docs/explanation/features/quick-flow.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Quick Flow
+title: "Quick Spec Flow"
 description: Understanding Quick Spec Flow for rapid development in BMad Method
 ---
 
-# Quick Spec Flow
 
 Quick Spec Flow is a streamlined alternative to the full BMad Method for Quick Flow track projects. Instead of going through Product Brief → PRD → Architecture, you go straight to a context-aware technical specification and start coding.
 

docs/explanation/features/tea-overview.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: TEA Overview
+title: "Test Architect (TEA) Overview"
 description: Understanding the Test Architect (TEA) agent and its role in BMad Method
 ---
 
-# Test Architect (TEA) Overview
 
 The Test Architect (TEA) is a specialized agent focused on quality strategy, test automation, and release gates in BMad Method projects.
 

docs/explanation/features/web-bundles.md

@@ -1,4 +1,7 @@
-# Web Bundles
+---
+title: "Web Bundles"
+---
+
 
 Use BMAD agents in Gemini Gems and Custom GPTs.
 

docs/explanation/game-dev/_category_.json

@@ -1 +0,0 @@
-{ "label": "Game Development", "position": 6 }

docs/explanation/game-dev/agents.md

@@ -1,4 +1,7 @@
-# BMGD Agents Guide
+---
+title: "BMGD Agents Guide"
+---
+
 
 Complete reference for BMGD's six specialized game development agents.
 

docs/explanation/game-dev/bmgd-vs-bmm.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: BMGD vs BMM
+title: "BMGD vs BMM"
 description: Understanding the differences between BMGD and BMM
 ---
 
-# BMGD vs BMM
 
 BMGD (BMad Game Development) extends BMM (BMad Method) with game-specific capabilities. This page explains the key differences.
 

docs/explanation/game-dev/game-types.md

@@ -1,4 +1,7 @@
-# BMGD Game Types Guide
+---
+title: "BMGD Game Types Guide"
+---
+
 
 Reference for selecting and using BMGD's 24 supported game type templates.
 

docs/explanation/game-dev/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Game Development
+title: "BMGD - Game Development Module"
 description: AI-powered workflows for game design and development with BMGD
 ---
 
-# BMGD - Game Development Module
 
 Complete guides for the BMad Game Development Module (BMGD) - AI-powered workflows for game design and development that adapt to your project's needs.
 

docs/explanation/index.md

@@ -1,4 +1,7 @@
-# Explanation
+---
+title: "Explanation"
+---
+
 
 Understanding-oriented content that explains concepts, architecture, and the reasoning behind BMAD's design.
 

docs/explanation/philosophy/_category_.json

@@ -1 +0,0 @@
-{ "label": "Philosophy", "position": 3 }

docs/explanation/philosophy/facilitation-over-generation.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Facilitation Over Generation
+title: "Facilitation Over Generation"
 description: Understanding CIS's facilitation-first approach to creative work
 ---
 
-# Facilitation Over Generation
 
 The Creative Intelligence Suite (CIS) takes a fundamentally different approach from typical AI tools. Instead of generating solutions directly, CIS agents act as master facilitators who guide you to discover insights yourself.
 

docs/how-to/brownfield/_category_.json

@@ -1 +0,0 @@
-{ "label": "Brownfield", "position": 5 }

docs/how-to/brownfield/add-feature-to-existing.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Add Feature
+title: "How to Add a Feature to an Existing Project"
 description: How to add new features to an existing brownfield project
 ---
 
-# How to Add a Feature to an Existing Project
 
 Add new functionality to your brownfield codebase while respecting existing patterns and architecture.
 

docs/how-to/brownfield/document-existing-project.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Document Existing Project
+title: "How to Document an Existing Project"
 description: How to document an existing brownfield codebase using BMad Method
 ---
 
-# How to Document an Existing Project
 
 Use the `document-project` workflow to scan your entire codebase and generate comprehensive documentation about its current state.
 

docs/how-to/brownfield/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Brownfield Development
+title: "Brownfield Development"
 description: How to use BMad Method on existing codebases
 ---
 
-# Brownfield Development
 
 How to effectively use BMad Method when working on existing projects and legacy codebases.
 

docs/how-to/brownfield/quick-fix-in-brownfield.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Quick Fixes
+title: "How to Make Quick Fixes in Brownfield Projects"
 description: How to make quick fixes and ad-hoc changes in brownfield projects
 ---
 
-# How to Make Quick Fixes in Brownfield Projects
 
 Not everything requires the full BMad method or even Quick Flow. For bug fixes, refactorings, or small targeted changes, you can work directly with the agent.
 

docs/how-to/customization/_category_.json

@@ -1 +0,0 @@
-{ "label": "Customization", "position": 3 }

docs/how-to/customization/customize-agents.md

@@ -1,4 +1,7 @@
-# Agent Customization Guide
+---
+title: "Agent Customization Guide"
+---
+
 
 Customize BMad agents without modifying core files. All customizations persist through updates.
 
@@ -26,10 +29,8 @@ After editing, IT IS CRITICAL to rebuild the agent to apply changes:
 
 ```bash
 npx bmad-method@alpha install # and then select option to compile all agents
-# OR for individual agent only
 npx bmad-method@alpha build <agent-name>
 
-# Examples:
 npx bmad-method@alpha build bmm-dev
 npx bmad-method@alpha build core-bmad-master
 npx bmad-method@alpha build bmm-pm
@@ -119,7 +120,6 @@ prompts:
 **Example 1: Customize Developer Agent for TDD**
 
 ```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
 agent:
   metadata:
     name: 'TDD Developer'
@@ -135,7 +135,6 @@ critical_actions:
 **Example 2: Add Custom Deployment Workflow**
 
 ```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
 menu:
   - trigger: deploy-staging
     workflow: '{project-root}/_bmad/deploy-staging.yaml'
@@ -148,7 +147,6 @@ menu:
 **Example 3: Multilingual Product Manager**
 
 ```yaml
-# _bmad/_config/agents/bmm-pm.customize.yaml
 persona:
   role: 'Bilingual Product Manager'
   identity: 'Expert in US and LATAM markets'

docs/how-to/customization/customize-workflows.md

@@ -1,4 +1,7 @@
-# Workflow Customization Guide
+---
+title: "Workflow Customization Guide"
+---
+
 
 Customize and optimize workflows with step replacement and hooks.
 

docs/how-to/customization/index.md

@@ -1,4 +1,7 @@
-# BMAD Customization
+---
+title: "BMAD Customization"
+---
+
 
 Personalize agents and workflows to match your needs.
 

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

@@ -1,4 +1,7 @@
-# Document Sharding Guide
+---
+title: "Document Sharding Guide"
+---
+
 
 Comprehensive guide to BMad Method's document sharding system for managing large planning and architecture documents.
 
@@ -93,7 +96,6 @@ Agent: Sharding PRD.md...
 **index.md structure:**
 
 ```markdown
-# PRD - Index
 
 ## Sections
 

docs/how-to/customization/vendor-workflows.md

@@ -1,4 +1,7 @@
-# Workflow Vendoring, Customization, and Inheritance (Official Support Coming Soon))
+---
+title: "Workflow Vendoring, Customization, and Inheritance (Official Support Coming Soon)"
+---
+
 
 Vendoring and Inheritance of workflows are 2 ways of sharing or reutilizing workflows - but with some key distinctions and use cases.
 

docs/how-to/ide-setup/_category_.json

@@ -1 +0,0 @@
-{ "label": "IDE Setup", "position": 2 }

docs/how-to/index.md

@@ -1,4 +1,7 @@
-# How-To Guides
+---
+title: "How-To Guides"
+---
+
 
 Task-oriented guides that show you how to accomplish specific goals. Each guide assumes you already understand the basics.
 

docs/how-to/installation/_category_.json

@@ -1 +0,0 @@
-{ "label": "Installation", "position": 1 }

docs/how-to/installation/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Installation
+title: "Installation Guides"
 description: How to install and upgrade BMad Method
 ---
 
-# Installation Guides
 
 How-to guides for installing and configuring the BMad Method.
 

docs/how-to/installation/install-bmad.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Install BMAD
+title: "How to Install BMAD"
 description: Step-by-step guide to installing BMAD in your project
 ---
 
-# How to Install BMAD
 
 Complete guide to installing BMAD in your project.
 
@@ -112,10 +111,8 @@ communication_language: english
 
 Install Node.js 20+:
 ```bash
-# macOS with Homebrew
 brew install node
 
-# Or download from nodejs.org
 ```
 
 ### "Permission denied"

docs/how-to/installation/install-custom-modules.md

@@ -1,4 +1,7 @@
-# Custom Content Installation
+---
+title: "Custom Content Installation"
+---
+
 
 This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content extends BMAD's functionality with specialized tools and workflows that can be shared across projects or teams.
 

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

@@ -1,4 +1,7 @@
-# BMad v4 to v6 Upgrade Guide
+---
+title: "BMad v4 to v6 Upgrade Guide"
+---
+
 
 ## Overview
 

docs/how-to/troubleshooting/_category_.json

@@ -1 +0,0 @@
-{ "label": "Troubleshooting", "position": 6 }

docs/how-to/troubleshooting/bmgd-troubleshooting.md

@@ -1,4 +1,7 @@
-# BMGD Troubleshooting
+---
+title: "BMGD Troubleshooting"
+---
+
 
 Common issues and solutions when using BMGD workflows.
 
@@ -26,7 +29,6 @@ Common issues and solutions when using BMGD workflows.
 Check for `_bmad/bmgd/config.yaml` in your project. If missing, create it:
 
 ```yaml
-# BMGD Configuration
 output_folder: '{project-root}/docs/game-design'
 user_name: 'Your Name'
 communication_language: 'English'

docs/how-to/workflows/_category_.json

@@ -1 +0,0 @@
-{ "label": "Workflows", "position": 4 }

docs/how-to/workflows/bmgd-quick-flow.md

@@ -1,4 +1,7 @@
-# BMGD Quick-Flow Guide
+---
+title: "BMGD Quick-Flow Guide"
+---
+
 
 Fast-track workflows for rapid game prototyping and flexible development.
 

docs/how-to/workflows/conduct-research.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Conduct Research
+title: "How to Conduct Research"
 description: How to conduct market, technical, and competitive research using BMad Method
 ---
 
-# How to Conduct Research
 
 Use the `research` workflow to perform comprehensive multi-type research for validating ideas, understanding markets, and making informed decisions.
 

docs/how-to/workflows/create-architecture.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Create Architecture
+title: "How to Create Architecture"
 description: How to create system architecture using the BMad Method
 ---
 
-# How to Create Architecture
 
 Use the `architecture` workflow to make technical decisions explicit and prevent agent conflicts during implementation.
 

docs/how-to/workflows/create-epics-and-stories.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Create Epics & Stories
+title: "How to Create Epics and Stories"
 description: How to break PRD requirements into epics and stories using BMad Method
 ---
 
-# How to Create Epics and Stories
 
 Use the `create-epics-and-stories` workflow to transform PRD requirements into bite-sized stories organized into deliverable epics.
 

docs/how-to/workflows/create-prd.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Create PRD
+title: "How to Create a PRD"
 description: How to create a Product Requirements Document using the BMad Method
 ---
 
-# How to Create a PRD
 
 Use the `prd` workflow to create a strategic Product Requirements Document with Functional Requirements (FRs) and Non-Functional Requirements (NFRs).
 

docs/how-to/workflows/create-product-brief.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Create Product Brief
+title: "How to Create a Product Brief"
 description: How to create a product brief using the BMad Method
 ---
 
-# How to Create a Product Brief
 
 Use the `product-brief` workflow to define product vision and strategy through an interactive process.
 

docs/how-to/workflows/create-story.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Create Story
+title: "How to Create a Story"
 description: How to create implementation-ready stories from epic backlog
 ---
 
-# How to Create a Story
 
 Use the `create-story` workflow to prepare the next story from the epic backlog for implementation.
 
@@ -78,7 +77,6 @@ The create-story workflow pulls from:
 ## Example Output
 
 ```markdown
-# Story 1.2: Email Verification
 
 ## Objective
 Implement email verification flow for new user registrations.

docs/how-to/workflows/create-tech-spec.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Create Tech Spec
+title: "How to Create a Tech Spec"
 description: How to create a technical specification using Quick Spec Flow
 ---
 
-# How to Create a Tech Spec
 
 Use the `tech-spec` workflow for Quick Flow projects to go directly from idea to implementation-ready specification.
 

docs/how-to/workflows/create-ux-design.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Create UX Design
+title: "How to Create a UX Design"
 description: How to create UX specifications using the BMad Method
 ---
 
-# How to Create a UX Design
 
 Use the `create-ux-design` workflow to create UX specifications for projects where user experience is a primary differentiator.
 

docs/how-to/workflows/implement-story.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Implement Story
+title: "How to Implement a Story"
 description: How to implement a story using the dev-story workflow
 ---
 
-# How to Implement a Story
 
 Use the `dev-story` workflow to implement a story with tests following the architecture and conventions.
 

docs/how-to/workflows/run-brainstorming-session.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Run Brainstorming
+title: "How to Run a Brainstorming Session"
 description: How to run a brainstorming session using the BMad Method
 ---
 
-# How to Run a Brainstorming Session
 
 Use the `brainstorm-project` workflow to explore solution approaches through parallel ideation tracks.
 

docs/how-to/workflows/run-code-review.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Run Code Review
+title: "How to Run Code Review"
 description: How to run code review for quality assurance
 ---
 
-# How to Run Code Review
 
 Use the `code-review` workflow to perform a thorough quality review of implemented code.
 

docs/how-to/workflows/run-implementation-readiness.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Run Implementation Readiness
+title: "How to Run Implementation Readiness"
 description: How to validate planning and solutioning before implementation
 ---
 
-# How to Run Implementation Readiness
 
 Use the `implementation-readiness` workflow to validate that planning and solutioning are complete and aligned before Phase 4 implementation.
 

docs/how-to/workflows/run-sprint-planning.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Run Sprint Planning
+title: "How to Run Sprint Planning"
 description: How to initialize sprint tracking for implementation
 ---
 
-# How to Run Sprint Planning
 
 Use the `sprint-planning` workflow to initialize the sprint tracking file and organize work for implementation.
 

docs/how-to/workflows/run-test-design.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Run Test Design
+title: "How to Run Test Design"
 description: How to create comprehensive test plans using TEA's test-design workflow
 ---
 
-# How to Run Test Design
 
 Use TEA's `*test-design` workflow to create comprehensive test plans with risk assessment and coverage strategies.
 

docs/how-to/workflows/setup-party-mode.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Setup Party Mode
+title: "How to Set Up Party Mode"
 description: How to set up and use Party Mode for multi-agent collaboration
 ---
 
-# How to Set Up Party Mode
 
 Use Party Mode to orchestrate dynamic multi-agent conversations with your entire BMAD team.
 

docs/how-to/workflows/setup-test-framework.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Setup Test Framework
+title: "How to Set Up a Test Framework"
 description: How to set up a production-ready test framework using TEA
 ---
 
-# How to Set Up a Test Framework
 
 Use TEA's `*framework` workflow to scaffold a production-ready test framework for your project.
 

docs/index.md

@@ -1,11 +1,7 @@
 ---
-slug: /
-sidebar_position: 1
 title: Welcome to BMad
 ---
 
-# Welcome to BMad
-
 BMad (**B**uild **M**ore, **A**rchitect **D**reams) 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.
@@ -16,12 +12,10 @@ If you're comfortable working with AI coding assistants like Claude, Cursor, or
 
 The fastest way to understand BMad is to try it. Choose a tutorial to walk through your first project in about 10 minutes.
 
-<a className="button button--primary button--lg margin-right--md" href="/docs/tutorials/getting-started/getting-started-bmadv4">Get Started with v4 (Stable)</a>
+- **[Get Started with v4 (Stable)](./tutorials/getting-started/getting-started-bmadv4.md)** — Production-ready version with battle-tested workflows
-<a className="button button--secondary button--lg" href="/docs/tutorials/getting-started/getting-started-bmadv6">Try v6 (Alpha)</a>
+- **[Try v6 (Alpha)](./tutorials/getting-started/getting-started-bmadv6.md)** — Latest features, still in active development
 
-<br/>
+:::tip[Already familiar with AI-assisted development?]
-
-:::tip Already familiar with AI-assisted development?
 Feel free to skip around. Use the sidebar to jump to any topic, or check out [What Are Agents?](./explanation/core-concepts/what-are-agents.md) to understand how BMad organizes its AI personas.
 :::
 
@@ -31,48 +25,12 @@ Feel free to skip around. Use the sidebar to jump to any topic, or check out [Wh
 
 These docs are organized into four sections based on what you're trying to do:
 
-<div className="row">
+| Section | Purpose |
-  <div className="col col--6 margin-bottom--lg">
+|---------|---------|
-    <div className="card">
+| **[Tutorials](./tutorials/index.md)** | Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new. |
-      <div className="card__header">
+| **[How-To Guides](./how-to/index.md)** | Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here. |
-        <h3>Tutorials</h3>
+| **[Explanation](./explanation/index.md)** | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*. |
-      </div>
+| **[Reference](./reference/index.md)** | Information-oriented. Technical specifications for agents, workflows, and configuration. |
-      <div className="card__body">
-        <p><strong>Learning-oriented.</strong> Step-by-step guides that walk you through building something. Start here if you're new to BMad.</p>
-      </div>
-    </div>
-  </div>
-  <div className="col col--6 margin-bottom--lg">
-    <div className="card">
-      <div className="card__header">
-        <h3>How-To Guides</h3>
-      </div>
-      <div className="card__body">
-        <p><strong>Task-oriented.</strong> Practical guides for solving specific problems. "How do I customize an agent?" lives here.</p>
-      </div>
-    </div>
-  </div>
-  <div className="col col--6 margin-bottom--lg">
-    <div className="card">
-      <div className="card__header">
-        <h3>Explanation</h3>
-      </div>
-      <div className="card__body">
-        <p><strong>Understanding-oriented.</strong> Deep dives into concepts and architecture. Read these when you want to know <em>why</em> something works.</p>
-      </div>
-    </div>
-  </div>
-  <div className="col col--6 margin-bottom--lg">
-    <div className="card">
-      <div className="card__header">
-        <h3>Reference</h3>
-      </div>
-      <div className="card__body">
-        <p><strong>Information-oriented.</strong> Technical specifications for agents, workflows, and configuration. Look things up here.</p>
-      </div>
-    </div>
-  </div>
-</div>
 
 ---
 
@@ -80,7 +38,7 @@ These docs are organized into four sections based on what you're trying to do:
 
 BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:
 
-- **[Claude Code](https://claude.ai/claude-code)** — Anthropic's CLI tool (recommended)
+- **[Claude Code](https://code.claude.com)** — Anthropic's CLI tool (recommended)
 - **[Cursor](https://cursor.sh)** — AI-first code editor
 - **[Windsurf](https://codeium.com/windsurf)** — Codeium's AI IDE
 - **[Roo Code](https://roocode.com)** — VS Code extension
@@ -103,5 +61,5 @@ Get help, share what you're building, or contribute to BMad:
 
 Ready to dive in? Pick a tutorial and start building.
 
-<a className="button button--primary button--lg margin-right--md" href="/docs/tutorials/getting-started/getting-started-bmadv4">Get Started with v4 (Stable)</a>
+- **[Get Started with v4 (Stable)](./tutorials/getting-started/getting-started-bmadv4.md)** — Recommended for production projects
-<a className="button button--secondary button--lg" href="/docs/tutorials/getting-started/getting-started-bmadv6">Try v6 (Alpha)</a>
+- **[Try v6 (Alpha)](./tutorials/getting-started/getting-started-bmadv6.md)** — Explore the latest features

docs/reference/agents/_category_.json

@@ -1 +0,0 @@
-{ "label": "Agents", "position": 1 }

docs/reference/agents/index.md

@@ -1,9 +1,8 @@
 ---
-sidebar_label: Agents Reference
+title: "Agents Reference"
 description: Complete reference for BMad Method agents and their commands
 ---
 
-# Agents Reference
 
 Quick reference of all BMad Method agents and their available commands.
 

docs/reference/configuration/_category_.json

@@ -1 +0,0 @@
-{ "label": "Configuration", "position": 3 }

docs/reference/configuration/core-tasks.md

@@ -1,4 +1,7 @@
-# Core Tasks
+---
+title: "Core Tasks"
+---
+
 
 Core Tasks are reusable task definitions that can be invoked by any BMAD module, workflow, or agent. These tasks provide standardized functionality for common operations.
 

docs/reference/configuration/global-config.md

@@ -1,4 +1,7 @@
-# Core Module Global Inheritable Config
+---
+title: "Core Module Global Inheritable Config"
+---
+
 
 The Core Modules module.yaml file defines configuration values that are useful and unique for all other modules to utilize, and by default all other modules installed will clone the values defined in the core module yaml.config into their own. It is possible for other modules to override these values, but the general intent it to accept the core module values and define their own values as needed, or extend the core values.
 

docs/reference/glossary/_category_.json

@@ -1 +0,0 @@
-{ "label": "Glossary", "position": 4 }

docs/reference/glossary/index.md

@@ -1,4 +1,7 @@
-# BMAD Glossary
+---
+title: "BMAD Glossary"
+---
+
 
 Comprehensive terminology reference for the BMAD Method.
 

docs/reference/index.md

@@ -1,4 +1,7 @@
-# Reference
+---
+title: "Reference"
+---
+
 
 Information-oriented documentation for looking up facts, specifications, and details.
 

docs/reference/workflows/_category_.json

@@ -1 +0,0 @@
-{ "label": "Workflows", "position": 2 }

docs/reference/workflows/bmgd-workflows.md

@@ -1,4 +1,7 @@
-# BMGD Workflows Guide
+---
+title: "BMGD Workflows Guide"
+---
+
 
 Complete reference for all BMGD workflows organized by development phase.
 

docs/reference/workflows/core-workflows.md

@@ -1,4 +1,7 @@
-# Core Workflows
+---
+title: "Core Workflows"
+---
+
 
 Core Workflows are domain-agnostic workflows that can be utilized by any BMAD-compliant module, workflow, or agent. These workflows are installed by default and available at any time.
 

docs/reference/workflows/document-project.md

@@ -1,4 +1,7 @@
-# Document Project Workflow - Technical Reference
+---
+title: "Document Project Workflow - Technical Reference"
+---
+
 
 **Module:** BMM (BMAD Method Module)