docs: radical reduction of documentation scope for v6 beta (#1406)

* docs: radical reduction of documentation scope for v6 beta

Archive and basement unreviewed content to ship a focused, minimal doc set.

Changes:
- Archive stale how-to workflow guides (will rewrite for v6)
- Archive outdated explanation and reference content
- Move unreviewed content to basement for later review
- Reorganize TEA docs into dedicated /tea/ section
- Add workflow-map visual reference page
- Simplify getting-started tutorial and sidebar navigation
- Add explanation pages: brainstorming, adversarial-review, party-mode,
  quick-flow, advanced-elicitation
- Fix base URL handling for subdirectory deployments (GitHub Pages forks)

The goal is a minimal, accurate doc set for beta rather than
comprehensive but potentially misleading content.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: restructure BMM and agents documentation by consolidating and flattening index files.

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

website/astro.config.mjs

@@ -3,6 +3,7 @@ import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
 import sitemap from '@astrojs/sitemap';
 import rehypeMarkdownLinks from './src/rehype-markdown-links.js';
+import rehypeBasePaths from './src/rehype-base-paths.js';
 import { getSiteUrl } from './src/lib/site-url.js';
 
 const siteUrl = getSiteUrl();
@@ -28,7 +29,10 @@ export default defineConfig({
   },
 
   markdown: {
-    rehypePlugins: [rehypeMarkdownLinks],
+    rehypePlugins: [
+      [rehypeMarkdownLinks, { base: basePath }],
+      [rehypeBasePaths, { base: basePath }],
+    ],
   },
 
   integrations: [
@@ -89,121 +93,55 @@ export default defineConfig({
         {
           label: 'Tutorials',
           collapsed: false,
-          items: [
-            {
-              label: 'Getting Started',
-              autogenerate: { directory: 'tutorials/getting-started' },
-            },
-            {
-              label: 'Advanced',
-              autogenerate: { directory: 'tutorials/advanced' },
-            },
-          ],
+          autogenerate: { directory: 'tutorials' },
         },
         {
           label: 'How-To Guides',
           collapsed: true,
-          items: [
-            { slug: 'how-to/get-answers-about-bmad' },
-            {
-              label: 'Installation',
-              autogenerate: { directory: 'how-to/installation' },
-            },
-            {
-              label: 'Workflows',
-              autogenerate: { directory: 'how-to/workflows' },
-            },
-            {
-              label: 'Customization',
-              autogenerate: { directory: 'how-to/customization' },
-            },
-            {
-              label: 'Brownfield Development',
-              autogenerate: { directory: 'how-to/brownfield' },
-            },
-            {
-              label: 'Troubleshooting',
-              autogenerate: { directory: 'how-to/troubleshooting' },
-            },
-          ],
+          autogenerate: { directory: 'how-to' },
         },
         {
           label: 'Explanation',
           collapsed: true,
-          items: [
-            {
-              label: 'Core Concepts',
-              autogenerate: { directory: 'explanation/core-concepts' },
-            },
-            {
-              label: 'Architecture',
-              autogenerate: { directory: 'explanation/architecture' },
-            },
-            {
-              label: 'Philosophy',
-              autogenerate: { directory: 'explanation/philosophy' },
-            },
-            {
-              label: 'Features',
-              autogenerate: { directory: 'explanation/features' },
-            },
-            {
-              label: 'TEA (Test Architect)',
-              autogenerate: { directory: 'explanation/tea' },
-            },
-            {
-              label: 'Agents',
-              autogenerate: { directory: 'explanation/agents' },
-            },
-            {
-              label: 'BMM',
-              autogenerate: { directory: 'explanation/bmm' },
-            },
-            {
-              label: 'BMad Builder',
-              autogenerate: { directory: 'explanation/bmad-builder' },
-            },
-            {
-              label: 'Game Development',
-              autogenerate: { directory: 'explanation/game-dev' },
-            },
-            {
-              label: 'Creative Intelligence',
-              autogenerate: { directory: 'explanation/creative-intelligence' },
-            },
-            {
-              label: 'Core Module',
-              autogenerate: { directory: 'explanation/core' },
-            },
-            {
-              label: 'FAQ',
-              autogenerate: { directory: 'explanation/faq' },
-            },
-          ],
+          autogenerate: { directory: 'explanation' },
         },
         {
           label: 'Reference',
           collapsed: true,
+          autogenerate: { directory: 'reference' },
+        },
+        {
+          label: 'TEA - Testing in BMAD',
+          collapsed: true,
           items: [
             {
-              label: 'Agents',
-              autogenerate: { directory: 'reference/agents' },
+              label: 'Tutorials',
+              autogenerate: { directory: 'tea/tutorials' },
             },
             {
-              label: 'Workflows',
-              autogenerate: { directory: 'reference/workflows' },
+              label: 'How-To Guides',
+              items: [
+                {
+                  label: 'Workflows',
+                  autogenerate: { directory: 'tea/how-to/workflows' },
+                },
+                {
+                  label: 'Customization',
+                  autogenerate: { directory: 'tea/how-to/customization' },
+                },
+                {
+                  label: 'Brownfield',
+                  autogenerate: { directory: 'tea/how-to/brownfield' },
+                },
+              ],
             },
             {
-              label: 'Configuration',
-              autogenerate: { directory: 'reference/configuration' },
+              label: 'Explanation',
+              autogenerate: { directory: 'tea/explanation' },
             },
             {
-              label: 'TEA (Test Architect)',
-              autogenerate: { directory: 'reference/tea' },
-            },
-            {
-              label: 'Glossary',
-              autogenerate: { directory: 'reference/glossary' },
+              label: 'Reference',
+              autogenerate: { directory: 'tea/reference' },
             },
           ],
         },
@@ -215,6 +153,9 @@ export default defineConfig({
       // Pagination
       pagination: false,
 
+      // Use our docs/404.md instead of Starlight's built-in 404
+      disable404Route: true,
+
       // Custom components
       components: {
         Header: './src/components/Header.astro',

website/src/pages/404.astro

@@ -0,0 +1,11 @@
+---
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
+import { getEntry } from 'astro:content';
+
+const entry = await getEntry('docs', '404');
+const { Content } = await entry.render();
+---
+
+<StarlightPage frontmatter={{ title: entry.data.title, template: entry.data.template }}>
+  <Content />
+</StarlightPage>

website/src/rehype-base-paths.js

@@ -0,0 +1,77 @@
+/**
+ * Rehype plugin to prepend base path to absolute URLs
+ *
+ * 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.
+ * Does NOT process .md links (those are handled by rehype-markdown-links).
+ */
+
+import { visit } from 'unist-util-visit';
+
+/**
+ * Create a rehype plugin that prepends the base path to absolute URLs.
+ *
+ * @param {Object} options - Plugin options
+ * @param {string} options.base - The base path to prepend (e.g., '/BMAD-METHOD/')
+ * @returns {function} A HAST tree transformer
+ */
+export default function rehypeBasePaths(options = {}) {
+  const base = options.base || '/';
+
+  // Normalize base: ensure it ends with / and doesn't have double slashes
+  const normalizedBase = base === '/' ? '/' : base.endsWith('/') ? base : base + '/';
+
+  return (tree) => {
+    visit(tree, 'element', (node) => {
+      // Process img tags with src attribute
+      if (node.tagName === 'img' && node.properties?.src) {
+        const src = node.properties.src;
+
+        if (typeof src === 'string' && src.startsWith('/') && !src.startsWith('//')) {
+          // Don't transform if already has the base path
+          if (normalizedBase !== '/' && !src.startsWith(normalizedBase)) {
+            node.properties.src = normalizedBase + src.slice(1);
+          }
+        }
+      }
+
+      // Process anchor tags with href attribute
+      if (node.tagName === 'a' && node.properties?.href) {
+        const href = node.properties.href;
+
+        if (typeof href !== 'string') {
+          return;
+        }
+
+        // Only transform absolute paths starting with / (but not //)
+        if (!href.startsWith('/') || href.startsWith('//')) {
+          return;
+        }
+
+        // Skip if already has the base path
+        if (normalizedBase !== '/' && href.startsWith(normalizedBase)) {
+          return;
+        }
+
+        // Skip .md links - those are handled by rehype-markdown-links
+        // Extract path portion (before ? and #)
+        const firstDelimiter = Math.min(
+          href.indexOf('?') === -1 ? Infinity : href.indexOf('?'),
+          href.indexOf('#') === -1 ? Infinity : href.indexOf('#'),
+        );
+        const pathPortion = firstDelimiter === Infinity ? href : href.substring(0, firstDelimiter);
+
+        if (pathPortion.endsWith('.md')) {
+          return; // Let rehype-markdown-links handle this
+        }
+
+        // Prepend base path
+        node.properties.href = normalizedBase + href.slice(1);
+      }
+    });
+  };
+}

website/src/rehype-markdown-links.js

@@ -6,10 +6,11 @@
  *   ./path/index.md → ./path/ (index.md becomes directory root)
  *   ../path/file.md#anchor → ../path/file/#anchor
  *   ./file.md?query=param → ./file/?query=param
- *   /docs/absolute/path/file.md → /absolute/path/file/
+ *   /docs/absolute/path/file.md → {base}/absolute/path/file/
  *
  * For absolute paths starting with /docs/, the /docs prefix is stripped
  * since the Astro site serves content from the docs directory as the root.
+ * The base path is prepended to absolute paths for subdirectory deployments.
  *
  * Affects relative links (./, ../) and absolute paths (/) - external links are unchanged
  */
@@ -21,9 +22,15 @@ import { visit } from 'unist-util-visit';
  *
  * The returned transformer walks the HTML tree and rewrites anchor `href` values that are relative paths (./, ../) or absolute paths (/) pointing to `.md` files. It preserves query strings and hash anchors, rewrites `.../index.md` to the directory root path (`.../`), and rewrites other `.md` file paths by removing the `.md` extension and ensuring a trailing slash. External links (http://, https://) and non-.md links are left unchanged.
  *
+ * @param {Object} options - Plugin options
+ * @param {string} options.base - The base path to prepend to absolute URLs (e.g., '/BMAD-METHOD/')
  * @returns {function} A HAST tree transformer that mutates `a` element `href` properties as described.
  */
-export default function rehypeMarkdownLinks() {
+export default function rehypeMarkdownLinks(options = {}) {
+  const base = options.base || '/';
+  // Normalize base: ensure it ends with / and doesn't have double slashes
+  const normalizedBase = base === '/' ? '' : base.endsWith('/') ? base.slice(0, -1) : base;
+
   return (tree) => {
     visit(tree, 'element', (node) => {
       // Only process anchor tags with href
@@ -82,6 +89,9 @@ export default function rehypeMarkdownLinks() {
         }
       }
 
+      // Track if this was an absolute path (for base path prepending)
+      const isAbsolute = urlPath.startsWith('/');
+
       // Strip /docs/ prefix from absolute paths (repo-relative → site-relative)
       if (urlPath.startsWith('/docs/')) {
         urlPath = urlPath.slice(5); // Remove '/docs' prefix, keeping the leading /
@@ -95,6 +105,11 @@ export default function rehypeMarkdownLinks() {
         urlPath = urlPath.replace(/\.md$/, '/');
       }
 
+      // Prepend base path to absolute URLs for subdirectory deployments
+      if (isAbsolute && normalizedBase) {
+        urlPath = normalizedBase + urlPath;
+      }
+
       // Reconstruct the href
       node.properties.href = urlPath + query + anchor;
     });