Add Astro + Starlight documentation site

- Set up website/ with Astro, Starlight, and custom styling
- Add tools/build-docs.mjs for LLM-friendly doc generation
- Add docs:build, docs:dev, docs:preview npm scripts
- Configure GitHub Pages deployment via workflow
- Add CNAME for bmad-builder-docs.bmad-method.org
- Update README with documentation link

Author: Brian Madison

.github/workflows/docs.yaml

@@ -6,9 +6,8 @@ on:
       - main
     paths:
       - "docs/**"
-      - "src/modules/*/docs/**"
       - "website/**"
-      - "tools/build-docs.js"
+      - "tools/build-docs.mjs"
       - ".github/workflows/docs.yaml"
   workflow_dispatch:
 

CNAME

@@ -0,0 +1 @@
+bmad-builder-docs.bmad-method.org

README.md

@@ -83,8 +83,10 @@ See [bmad-module-template](https://github.com/bmad-code-org/bmad-module-template
 
 ## Documentation
 
-- [BMad Method Docs](http://docs.bmad-method.org)
-- [Module Development Guide](http://docs.bmad-method.org/how-to/module-development/)
+**[BMad Builder Documentation](http://bmad-builder-docs.bmad-method.org)** — Tutorials, how-to guides, and reference
+
+- [Getting Started](http://bmad-builder-docs.bmad-method.org/tutorials/)
+- [BMad Method Docs](http://docs.bmad-method.org) — Core framework documentation
 
 ## Community
 

docs/how-to/index.md

@@ -0,0 +1,8 @@
+---
+title: How-To Guides
+description: Practical guides for specific BMad Builder tasks
+---
+
+# How-To Guides
+
+Step-by-step guides for completing specific tasks with BMad Builder.

docs/index.md

@@ -1 +1,26 @@
-# BMad Builder Docs Index
+---
+title: Welcome
+description: BMad Builder - Tool for creating custom BMad agents and modules
+template: splash
+hero:
+  title: BMad Builder
+  subtitle: Tool for creating custom BMad agents and modules
+  tagline: Create specialized AI agents with unique personalities, commands, and persistent memory.
+  actions:
+    - text: Get Started
+      link: /tutorials/
+      variant: primary
+    - text: View on GitHub
+      link: https://github.com/bmad-code-org/bmad-builder
+      variant: minimal
+---
+
+## Quick Start
+
+[**Tutorials**](/tutorials/) - Step-by-step guides to create your first agent.
+
+[**How-To Guides**](/how-to/) - Practical guides for specific tasks.
+
+[**Explanation**](/explanation/) - Learn how BMad Builder works under the hood.
+
+[**Reference**](/reference/) - Technical reference for configuration and options.

docs/reference/index.md

@@ -0,0 +1,8 @@
+---
+title: Reference
+description: Technical reference for BMad Builder
+---
+
+# Reference
+
+Technical documentation for BMad Builder configuration and options.

docs/tutorials/index.md

@@ -0,0 +1,8 @@
+---
+title: Tutorials
+description: Step-by-step tutorials for BMad Builder
+---
+
+# Tutorials
+
+Learn BMad Builder through step-by-step tutorials.

package.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-builder",
+  "type": "module",
   "version": "0.1.5",
   "description": "A BMad Core expansion module that guides users through the creation of Modules Workflow and Agents",
   "keywords": [
@@ -15,6 +16,9 @@
   "main": "",
   "bin": {},
   "scripts": {
+    "docs:build": "node tools/build-docs.mjs",
+    "docs:dev": "astro dev --root website",
+    "docs:preview": "astro preview --root website",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",