bmad-game-dev-studio 0.1.4 → 0.1.6

package/CNAME

@@ -0,0 +1 @@
+game-dev-studio-docs.bmad-method.org

package/README.md

@@ -70,7 +70,7 @@ Select **Game Dev Studio** from the modules list.
 After installing, run from your project root:
 
 ```
-/bmgd-help          # Get guided help for game development
+/bmad-help          # Get guided help for game development
 /bmgd-quick-dev     # Jump straight into prototyping
 /bmgd-gdd           # Create a Game Design Document
 /bmgd-narrative     # Design your game's story
@@ -81,12 +81,12 @@ After installing, run from your project root:
 | Approach | When to Use | Workflow |
 |----------|-------------|----------|
 | **Quick Flow** | Rapid prototyping, small projects | `/bmgd-quick-dev` |
-| **Full Production** | Full games, teams, long-term | `/bmgd-help` for guided path |
+| **Full Production** | Full games, teams, long-term | `/bmad-help` for guided path |
 
 ## Example: Starting a New Game
 
 ```
-You: /bmgd-help
+You: /bmad-help
 BMGD: What kind of game are you making?
 You: A tactical sci-fi RPG
 BMGD: Great choice! Here's what I recommend...
@@ -96,8 +96,10 @@ BMGD: Great choice! Here's what I recommend...
 
 ## Documentation
 
-- [BMad Method Docs](http://docs.bmad-method.org)
-- [BMGD Guide](http://docs.bmad-method.org/bmgd/)
+**[BMad Game Dev Studio Documentation](http://game-dev-studio-docs.bmad-method.org)** — Tutorials, how-to guides, and reference
+
+- [Getting Started](http://game-dev-studio-docs.bmad-method.org/tutorials/)
+- [BMad Method Docs](http://docs.bmad-method.org) — Core framework documentation
 
 ## Community
 

package/eslint.config.mjs

@@ -114,17 +114,6 @@ export default [
     },
   },
 
-  // Module installer scripts use CommonJS for compatibility
-  {
-    files: ['**/_module-installer/**/*.js'],
-    rules: {
-      // Allow CommonJS patterns for installer scripts
-      'unicorn/prefer-module': 'off',
-      'n/no-missing-require': 'off',
-      'n/no-unpublished-require': 'off',
-    },
-  },
-
   // ESLint config file should not be checked for publish-related Node rules
   {
     files: ['eslint.config.mjs'],

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-game-dev-studio",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "A BMad MEthod Core Module that offers a substantial stand alone module for Game Development across multiple supported platforms",
   "keywords": [
     "bmad",
@@ -13,8 +13,12 @@
   },
   "license": "MIT",
   "author": "Brian (BMad) Madison",
+  "type": "module",
   "main": "",
   "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",
@@ -46,10 +50,6 @@
       "markdownlint-cli2"
     ]
   },
-  "dependencies": {
-    "chalk": "^4.1.2",
-    "fs-extra": "^11.3.0"
-  },
   "devDependencies": {
     "@astrojs/sitemap": "^3.6.0",
     "@astrojs/starlight": "^0.37.0",

package/src/module-help.csv

@@ -1,26 +1,26 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
-gds,anytime,Document Project,DP,20,_bmad/gds/workflows/document-project/workflow.yaml,bmad-gds-document-project,false,tech-writer,Create Mode,"Analyze an existing game project to produce useful documentation",project_knowledge,"project documentation",
-gds,anytime,Quick Prototype,QP,30,_bmad/gds/workflows/gds-quick-flow/quick-prototype/workflow.yaml,bmad-gds-quick-prototype,false,game-solo-dev,Create Mode,"Rapid game prototyping - test mechanics and ideas quickly",,,
-gds,anytime,Quick Spec,TS,35,_bmad/gds/workflows/gds-quick-flow/quick-spec/workflow.yaml,bmad-gds-quick-spec,false,game-solo-dev,Create Mode,"Quick one-off tasks small changes simple apps utilities without extensive planning",planning_artifacts,"tech spec",
-gds,anytime,Quick Dev,QD,40,_bmad/gds/workflows/gds-quick-flow/quick-dev/workflow.yaml,bmad-gds-quick-dev,false,game-solo-dev,Create Mode,"Flexible game development - implement features with game-specific considerations",,,
-gds,anytime,Correct Course,CC,50,_bmad/gds/workflows/4-production/correct-course/workflow.yaml,bmad-gds-correct-course,false,game-scrum-master,Create Mode,"Navigate significant changes during game dev sprint when implementation is off-track",planning_artifacts,"change proposal",
-gds,1-preproduction,Brainstorm Game,BG,10,_bmad/gds/workflows/1-preproduction/brainstorm-game/workflow.yaml,bmad-gds-brainstorm-game,false,game-designer,Create Mode,"Facilitate game brainstorming sessions with game-specific context and techniques",output_folder,"brainstorming session",
-gds,1-preproduction,Game Brief,GB,20,_bmad/gds/workflows/1-preproduction/game-brief/workflow.yaml,bmad-gds-game-brief,false,game-designer,Create Mode,"Interactive game brief creation workflow that guides users through defining their game vision",output_folder,"game brief",
-gds,2-design,Game Design Document,GDD,10,_bmad/gds/workflows/2-design/gdd/workflow.yaml,bmad-gds-gdd,false,game-designer,Create Mode,"Create a Game Design Document with mechanics, systems, progression, and implementation guidance",planning_artifacts,"gdd",
-gds,2-design,Narrative Design,ND,20,_bmad/gds/workflows/2-design/narrative/workflow.yaml,bmad-gds-narrative,false,game-designer,Create Mode,"Create comprehensive narrative documentation including story structure, character arcs, and world-building",planning_artifacts,"narrative design",
-gds,3-technical,Project Context,PC,10,_bmad/gds/workflows/3-technical/generate-project-context/workflow.md,bmad-gds-project-context,false,game-architect,Create Mode,"Create optimized project-context.md for AI agent consistency",,,
-gds,3-technical,Game Architecture,GA,20,_bmad/gds/workflows/3-technical/game-architecture/workflow.yaml,bmad-gds-game-architecture,true,game-architect,Create Mode,"Produce a scale adaptive game architecture with engine, systems, networking, and technical design",planning_artifacts,"game architecture",
-gds,3-technical,Test Framework,TF,30,_bmad/gds/workflows/gametest/test-framework/workflow.yaml,bmad-gds-test-framework,false,game-qa,Create Mode,"Initialize game test framework architecture for Unity, Unreal Engine, or Godot projects",,,
-gds,3-technical,Test Design,TD,35,_bmad/gds/workflows/gametest/test-design/workflow.yaml,bmad-gds-test-design,false,game-qa,Create Mode,"Create comprehensive game test scenarios covering gameplay, progression, and quality requirements",planning_artifacts,"test design",
-gds,4-production,Sprint Planning,SP,10,_bmad/gds/workflows/4-production/sprint-planning/workflow.yaml,bmad-gds-sprint-planning,true,game-scrum-master,Create Mode,"Generate or update sprint-status.yaml from epic files",implementation_artifacts,"sprint status",
-gds,4-production,Sprint Status,SS,20,_bmad/gds/workflows/4-production/sprint-status/workflow.yaml,bmad-gds-sprint-status,false,game-scrum-master,Create Mode,"View sprint progress, surface risks, and get next action recommendation",,,
-gds,4-production,Create Story,CS,30,_bmad/gds/workflows/4-production/create-story/workflow.yaml,bmad-gds-create-story,true,game-scrum-master,Create Mode,"Create Story with direct ready-for-dev marking",implementation_artifacts,"story",
-gds,4-production,Validate Story,VS,35,_bmad/gds/workflows/4-production/create-story/workflow.yaml,bmad-gds-validate-story,false,game-scrum-master,Validate Mode,"Validate Story Draft with Independent Review",implementation_artifacts,"story validation report",
-gds,4-production,Dev Story,DS,40,_bmad/gds/workflows/4-production/dev-story/workflow.yaml,bmad-gds-dev-story,true,game-dev,Create Mode,"Execute Dev Story workflow implementing tasks and tests",,,
-gds,4-production,Code Review,CR,50,_bmad/gds/workflows/4-production/code-review/workflow.yaml,bmad-gds-code-review,false,game-dev,Create Mode,"Perform a thorough clean context QA code review on a story flagged Ready for Review",,,
-gds,4-production,Retrospective,ER,60,_bmad/gds/workflows/4-production/retrospective/workflow.yaml,bmad-gds-retrospective,false,game-scrum-master,Create Mode,"Facilitate team retrospective after a game development epic is completed",implementation_artifacts,"retrospective",
-gds,gametest,Test Automate,TA,10,_bmad/gds/workflows/gametest/automate/workflow.yaml,bmad-gds-test-automate,false,game-qa,Create Mode,"Generate automated game tests",,,
-gds,gametest,E2E Scaffold,ES,20,_bmad/gds/workflows/gametest/e2e-scaffold/workflow.yaml,bmad-gds-e2e-scaffold,false,game-qa,Create Mode,"Scaffold E2E testing infrastructure",,,
-gds,gametest,Playtest Plan,PP,30,_bmad/gds/workflows/gametest/playtest-plan/workflow.yaml,bmad-gds-playtest-plan,false,game-qa,Create Mode,"Create structured playtesting plan",planning_artifacts,"playtest plan",
-gds,gametest,Performance Test,PT,40,_bmad/gds/workflows/gametest/performance/workflow.yaml,bmad-gds-performance-test,false,game-qa,Create Mode,"Design performance testing strategy",planning_artifacts,"performance strategy",
-gds,gametest,Test Review,TR,50,_bmad/gds/workflows/gametest/test-review/workflow.yaml,bmad-gds-test-review,false,game-qa,Create Mode,"Review test quality and coverage",,,
+gds,anytime,Document Project,DP,,_bmad/gds/workflows/document-project/workflow.yaml,bmad-gds-document-project,false,tech-writer,Create Mode,"Analyze an existing game project to produce useful documentation. Use when onboarding to existing projects or creating project docs.",project_knowledge,"project documentation",
+gds,anytime,Quick Prototype,QP,,_bmad/gds/workflows/gds-quick-flow/quick-prototype/workflow.yaml,bmad-gds-quick-prototype,false,game-solo-dev,Create Mode,"Rapid game prototyping to test mechanics and ideas quickly. Use when experimenting with gameplay concepts or validating mechanics.",,,
+gds,anytime,Quick Spec,TS,,_bmad/gds/workflows/gds-quick-flow/quick-spec/workflow.yaml,bmad-gds-quick-spec,false,game-solo-dev,Create Mode,"Quick one-off tasks, small changes, simple apps utilities without extensive planning. Use for straightforward game features or well-defined tasks.",planning_artifacts,"tech spec",
+gds,anytime,Quick Dev,QD,,_bmad/gds/workflows/gds-quick-flow/quick-dev/workflow.yaml,bmad-gds-quick-dev,false,game-solo-dev,Create Mode,"Flexible game development with game-specific considerations. Use for rapid feature implementation or mechanics work.",,,
+gds,1-preproduction,Brainstorm Game,BG,10,_bmad/gds/workflows/1-preproduction/brainstorm-game/workflow.yaml,bmad-gds-brainstorm-game,false,game-designer,Create Mode,"Facilitate game brainstorming sessions with game-specific context and techniques. Use early in ideation phase or when generating game concepts.",output_folder,"brainstorming session",
+gds,1-preproduction,Game Brief,GB,20,_bmad/gds/workflows/1-preproduction/game-brief/workflow.yaml,bmad-gds-game-brief,false,game-designer,Create Mode,"Interactive game brief creation that guides users through defining their game vision. Use when clarifying game concept and core mechanics.",output_folder,"game brief",
+gds,2-design,Game Design Document,GDD,10,_bmad/gds/workflows/2-design/gdd/workflow.yaml,bmad-gds-gdd,false,game-designer,Create Mode,"Create a Game Design Document with mechanics, systems, progression, and implementation guidance. Use when documenting comprehensive game design specifications.",planning_artifacts,"gdd",
+gds,2-design,Narrative Design,ND,20,_bmad/gds/workflows/2-design/narrative/workflow.yaml,bmad-gds-narrative,false,game-designer,Create Mode,"Create comprehensive narrative documentation including story structure, character arcs, and world-building. Use for story-driven games or narrative integration.",planning_artifacts,"narrative design",
+gds,3-technical,Project Context,PC,10,_bmad/gds/workflows/3-technical/generate-project-context/workflow.md,bmad-gds-project-context,false,game-architect,Create Mode,"Create optimized project-context.md for chosen agentic tool consistency. Use when setting up new projects or improving AI coordination.",,,
+gds,3-technical,Game Architecture,GA,20,_bmad/gds/workflows/3-technical/game-architecture/workflow.yaml,bmad-gds-game-architecture,true,game-architect,Create Mode,"Produce a scale-adaptive game architecture with engine, systems, networking, and technical design. Use when planning technical implementation or system architecture.",planning_artifacts,"game architecture",
+gds,3-technical,Test Framework,TF,30,_bmad/gds/workflows/gametest/test-framework/workflow.yaml,bmad-gds-test-framework,false,game-qa,Create Mode,"Initialize game test framework architecture for Unity, Unreal Engine, or Godot projects. Use when setting up automated testing infrastructure.",,,
+gds,3-technical,Test Design,TD,35,_bmad/gds/workflows/gametest/test-design/workflow.yaml,bmad-gds-test-design,false,game-qa,Create Mode,"Create comprehensive game test scenarios covering gameplay, progression, and quality requirements. Use when planning test coverage or quality strategy.",planning_artifacts,"test design",
+gds,4-production,Sprint Planning,SP,10,_bmad/gds/workflows/4-production/sprint-planning/workflow.yaml,bmad-gds-sprint-planning,true,game-scrum-master,Create Mode,"Generate or update sprint-status.yaml from epic files. Use when starting development phase or planning sprints.",implementation_artifacts,"sprint status",
+gds,4-production,Sprint Status,SS,20,_bmad/gds/workflows/4-production/sprint-status/workflow.yaml,bmad-gds-sprint-status,false,game-scrum-master,Create Mode,"View sprint progress, surface risks, and get next action recommendation. Use when checking sprint health or planning next steps.",,,
+gds,4-production,Create Story,CS,30,_bmad/gds/workflows/4-production/create-story/workflow.yaml,bmad-gds-create-story,true,game-scrum-master,Create Mode,"Create Story with direct ready-for-dev marking. Use when preparing stories for development.",implementation_artifacts,"story",
+gds,4-production,Validate Story,VS,35,_bmad/gds/workflows/4-production/create-story/workflow.yaml,bmad-gds-validate-story,false,game-scrum-master,Validate Mode,"Validate Story Draft with independent review. Use for quality assurance before development begins.",implementation_artifacts,"story validation report",
+gds,4-production,Dev Story,DS,40,_bmad/gds/workflows/4-production/dev-story/workflow.yaml,bmad-gds-dev-story,true,game-dev,Create Mode,"Execute Dev Story workflow implementing tasks and tests. Use when developing story features and functionality.",,,
+gds,4-production,Code Review,CR,50,_bmad/gds/workflows/4-production/code-review/workflow.yaml,bmad-gds-code-review,false,game-dev,Create Mode,"Perform thorough clean context QA code review on stories flagged Ready for Review. Use after story development for quality checks.",,,
+gds,4-production,Correct Course,CC,55,_bmad/gds/workflows/4-production/correct-course/workflow.yaml,bmad-gds-correct-course,false,game-scrum-master,Create Mode,"Navigate significant changes during game dev sprint when implementation is off-track. Use when major course corrections are needed.",planning_artifacts,"change proposal",
+gds,4-production,Retrospective,ER,60,_bmad/gds/workflows/4-production/retrospective/workflow.yaml,bmad-gds-retrospective,false,game-scrum-master,Create Mode,"Facilitate team retrospective after a game development epic is completed. Use for continuous improvement after epic completion.",implementation_artifacts,"retrospective",
+gds,gametest,Test Automate,TA,10,_bmad/gds/workflows/gametest/automate/workflow.yaml,bmad-gds-test-automate,false,game-qa,Create Mode,"Generate automated game tests. Use for automated test coverage of gameplay systems.",,,
+gds,gametest,E2E Scaffold,ES,20,_bmad/gds/workflows/gametest/e2e-scaffold/workflow.yaml,bmad-gds-e2e-scaffold,false,game-qa,Create Mode,"Scaffold E2E testing infrastructure. Use when setting up end-to-end automated testing.",,,
+gds,gametest,Playtest Plan,PP,30,_bmad/gds/workflows/gametest/playtest-plan/workflow.yaml,bmad-gds-playtest-plan,false,game-qa,Create Mode,"Create structured playtesting plan. Use when planning user testing sessions or gathering player feedback.",planning_artifacts,"playtest plan",
+gds,gametest,Performance Test,PT,40,_bmad/gds/workflows/gametest/performance/workflow.yaml,bmad-gds-performance-test,false,game-qa,Create Mode,"Design performance testing strategy. Use when optimizing game performance or profiling resource usage.",planning_artifacts,"performance strategy",
+gds,gametest,Test Review,TR,50,_bmad/gds/workflows/gametest/test-review/workflow.yaml,bmad-gds-test-review,false,game-qa,Create Mode,"Review test quality and coverage. Use when evaluating test effectiveness or identifying coverage gaps.",,,

package/src/module.yaml

@@ -63,3 +63,9 @@ primary_platform:
       label: "Godot"
     - value: "other"
       label: "Custom / Other"
+
+# Directories to create during installation (declarative, no code execution)
+directories:
+  - "{planning_artifacts}"
+  - "{implementation_artifacts}"
+  - "{project_knowledge}"

package/tools/build-docs.mjs

@@ -0,0 +1,450 @@
+/**
+ * BMad Game Dev Studio Documentation Build Pipeline
+ *
+ * Consolidates docs from multiple sources, generates LLM-friendly files,
+ * and builds the Astro+Starlight site.
+ *
+ * Build outputs:
+ *   build/artifacts/     - With llms.txt, llms-full.txt
+ *   build/site/          - Final Astro output (deployable)
+ */
+
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getSiteUrl } from '../website/src/lib/site-url.mjs';
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+const PROJECT_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const BUILD_DIR = path.join(PROJECT_ROOT, 'build');
+
+const REPO_URL = 'https://github.com/bmad-code-org/bmad-module-game-dev-studio';
+
+// DO NOT CHANGE THESE VALUES!
+// llms-full.txt is consumed by AI agents as context. Most LLMs have ~200k token limits.
+// 600k chars ≈ 150k tokens (safe margin). Exceeding this breaks AI agent functionality.
+const LLM_MAX_CHARS = 600_000;
+const LLM_WARN_CHARS = 500_000;
+
+const LLM_EXCLUDE_PATTERNS = [
+  'changelog',
+  'archived',
+  // Note: Files/dirs starting with _ (like _STYLE_GUIDE.md, _archive/) are excluded in shouldExcludeFromLlm()
+];
+
+// =============================================================================
+// Main Entry Point
+/**
+ * Orchestrates the full BMad Game Dev Studio documentation build pipeline.
+ *
+ * Executes the high-level build steps in sequence: prints headers and paths, validates internal
+ * documentation links, cleans the build directory, generates artifacts from the `docs/` folder,
+ * builds the Astro site, and prints a final build summary.
+ */
+
+async function main() {
+  console.log();
+  printBanner('BMad Game Dev Studio Documentation Build Pipeline');
+  console.log();
+  console.log(`Project root: ${PROJECT_ROOT}`);
+  console.log(`Build directory: ${BUILD_DIR}`);
+  console.log();
+
+  cleanBuildDirectory();
+
+  const docsDir = path.join(PROJECT_ROOT, 'docs');
+  const artifactsDir = await generateArtifacts(docsDir);
+  const siteDir = buildAstroSite();
+
+  printBuildSummary(docsDir, artifactsDir, siteDir);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+
+// =============================================================================
+// Pipeline Stages
+/**
+ * Generate LLM files for the documentation pipeline.
+ *
+ * Creates the build/artifacts directory and writes `llms.txt` and `llms-full.txt` (sourced from the provided docs directory).
+ *
+ * @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');
+
+  const outputDir = path.join(BUILD_DIR, 'artifacts');
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  // Generate LLM files reading from docs/, output to artifacts/
+  generateLlmsTxt(outputDir);
+  generateLlmsFullTxt(docsDir, outputDir);
+
+  console.log();
+  console.log(`  \u001B[32m✓\u001B[0m Artifact generation complete`);
+
+  return outputDir;
+}
+
+/**
+ * Builds the Astro + Starlight site and copies generated artifacts into the site output directory.
+ *
+ * @returns {string} The filesystem path to the built site directory (e.g., build/site).
+ */
+function buildAstroSite() {
+  printHeader('Building Astro + Starlight site');
+
+  const siteDir = path.join(BUILD_DIR, 'site');
+  const artifactsDir = path.join(BUILD_DIR, 'artifacts');
+
+  // Build Astro site (outputs to build/site via astro.config.mjs)
+  runAstroBuild();
+  copyArtifactsToSite(artifactsDir, siteDir);
+
+  console.log();
+  console.log(`  \u001B[32m✓\u001B[0m Astro build complete`);
+
+  return siteDir;
+}
+
+// =============================================================================
+// LLM File Generation
+/**
+ * Create a concise llms.txt summary file containing project metadata, core links, and quick navigation entries for LLM consumption.
+ *
+ * Writes the file to `${outputDir}/llms.txt`.
+ *
+ * @param {string} outputDir - Destination directory where `llms.txt` will be written.
+ */
+
+function generateLlmsTxt(outputDir) {
+  console.log('  → Generating llms.txt...');
+
+  const siteUrl = getSiteUrl();
+  const content = [
+    '# BMad Game Dev Studio Documentation',
+    '',
+    '> Game development (Unity, Unreal, Godot) module for the BMad Method.',
+    '',
+    `Documentation: ${siteUrl}`,
+    `Repository: ${REPO_URL}`,
+    `Full docs: ${siteUrl}/llms-full.txt`,
+    '',
+    '## Quick Start',
+    '',
+    `- **[Quick Start](${siteUrl}/tutorials/quick-start)** - Get started with BMGD`,
+    `- **[Installation](${siteUrl}/reference/installation)** - Installation guide`,
+    '',
+    '## Core Concepts',
+    '',
+    `- **[What is BMGD?](${siteUrl}/explanation/what-is-bmgd)** - Understanding the module`,
+    `- **[Unity Support](${siteUrl}/how-to/unity)** - Unity game development`,
+    `- **[Unreal Support](${siteUrl}/how-to/unreal)** - Unreal game development`,
+    `- **[Godot Support](${siteUrl}/how-to/godot)** - Godot game development`,
+    '',
+    '---',
+    '',
+    '## Quick Links',
+    '',
+    `- [Full Documentation (llms-full.txt)](${siteUrl}/llms-full.txt) - Complete docs for AI context`,
+    '',
+  ].join('\n');
+
+  const outputPath = path.join(outputDir, 'llms.txt');
+  fs.writeFileSync(outputPath, content, 'utf-8');
+  console.log(`    Generated llms.txt (${content.length.toLocaleString()} chars)`);
+}
+
+/**
+ * Builds a consolidated llms-full.txt containing all Markdown files under docsDir wrapped in <document path="..."> tags for LLM consumption.
+ *
+ * Writes the generated file to outputDir/llms-full.txt. Files matching LLM_EXCLUDE_PATTERNS are skipped; read errors for individual files are logged. The combined content is validated against configured size thresholds (will exit on overflow and warn if near limit).
+ * @param {string} docsDir - Root directory containing source Markdown files; paths in the output are relative to this directory.
+ * @param {string} outputDir - Directory where llms-full.txt will be written.
+ */
+function generateLlmsFullTxt(docsDir, outputDir) {
+  console.log('  → Generating llms-full.txt...');
+
+  const date = new Date().toISOString().split('T')[0];
+  const files = getAllMarkdownFiles(docsDir).sort(compareLlmDocs);
+
+  const output = [
+    '# BMad Game Dev Studio Documentation (Full)',
+    '',
+    '> Complete documentation for AI consumption',
+    `> Generated: ${date}`,
+    `> Repository: ${REPO_URL}`,
+    '',
+  ];
+
+  let fileCount = 0;
+  let skippedCount = 0;
+
+  for (const mdPath of files) {
+    if (shouldExcludeFromLlm(mdPath)) {
+      skippedCount++;
+      continue;
+    }
+
+    const fullPath = path.join(docsDir, mdPath);
+    try {
+      const content = readMarkdownContent(fullPath);
+      output.push(`<document path="${mdPath}">`, content, '</document>', '');
+      fileCount++;
+    } catch (error) {
+      console.error(`    Warning: Could not read ${mdPath}: ${error.message}`);
+    }
+  }
+
+  const result = output.join('\n');
+  validateLlmSize(result);
+
+  const outputPath = path.join(outputDir, 'llms-full.txt');
+  fs.writeFileSync(outputPath, result, 'utf-8');
+
+  const tokenEstimate = Math.floor(result.length / 4).toLocaleString();
+  console.log(
+    `    Processed ${fileCount} files (skipped ${skippedCount}), ${result.length.toLocaleString()} chars (~${tokenEstimate} tokens)`,
+  );
+}
+
+function compareLlmDocs(a, b) {
+  const aKey = getLlmSortKey(a);
+  const bKey = getLlmSortKey(b);
+
+  if (aKey !== bKey) return aKey - bKey;
+  return a.localeCompare(b);
+}
+
+function getLlmSortKey(filePath) {
+  if (filePath === 'index.md') return 0;
+  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;
+  if (filePath.startsWith(`reference${path.sep}`) || filePath.startsWith('reference/')) return 5;
+  if (filePath.startsWith(`game-dev${path.sep}`) || filePath.startsWith('game-dev/')) return 6;
+  return 7;
+}
+
+/**
+ * Collects all Markdown (.md) files under a directory and returns their paths relative to a base directory.
+ * @param {string} dir - Directory to search for Markdown files.
+ * @param {string} [baseDir=dir] - Base directory used to compute returned relative paths.
+ * @returns {string[]} An array of file paths (relative to `baseDir`) for every `.md` file found under `dir`.
+ */
+function getAllMarkdownFiles(dir, baseDir = dir) {
+  const files = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...getAllMarkdownFiles(fullPath, baseDir));
+    } else if (entry.name.endsWith('.md')) {
+      // Return relative path from baseDir
+      const relativePath = path.relative(baseDir, fullPath);
+      files.push(relativePath);
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Determine whether a file path matches any configured LLM exclusion pattern.
+ * Also excludes any files or directories starting with underscore.
+ * @param {string} filePath - The file path to test.
+ * @returns {boolean} `true` if excluded, `false` otherwise.
+ */
+function shouldExcludeFromLlm(filePath) {
+  // Exclude if ANY path component starts with underscore
+  // (e.g., _STYLE_GUIDE.md, _archive/file.md, dir/_STYLE_GUIDE.md)
+  const pathParts = filePath.split(path.sep);
+  if (pathParts.some((part) => part.startsWith('_'))) return true;
+
+  // Check configured patterns
+  return LLM_EXCLUDE_PATTERNS.some((pattern) => filePath.includes(pattern));
+}
+
+function readMarkdownContent(filePath) {
+  let content = fs.readFileSync(filePath, 'utf-8');
+
+  if (content.startsWith('---')) {
+    const end = content.indexOf('---', 3);
+    if (end !== -1) {
+      content = content.slice(end + 3).trim();
+    }
+  }
+
+  return content;
+}
+
+function validateLlmSize(content) {
+  const charCount = content.length;
+
+  if (charCount > LLM_MAX_CHARS) {
+    console.error(`    ERROR: Exceeds ${LLM_MAX_CHARS.toLocaleString()} char limit`);
+    process.exit(1);
+  } else if (charCount > LLM_WARN_CHARS) {
+    console.warn(`    \u001B[33mWARNING: Approaching ${LLM_WARN_CHARS.toLocaleString()} char limit\u001B[0m`);
+  }
+}
+
+// =============================================================================
+// Astro Build
+/**
+ * Builds the Astro site to build/site (configured in astro.config.mjs).
+ */
+function runAstroBuild() {
+  console.log('  → Running astro build...');
+  execSync('npx astro build --root website', {
+    cwd: PROJECT_ROOT,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+    },
+  });
+}
+
+/**
+ * Copy generated artifact files into the built site directory.
+ *
+ * Copies llms.txt and llms-full.txt from the artifacts directory into the site directory.
+ *
+ * @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.
+ */
+function copyArtifactsToSite(artifactsDir, siteDir) {
+  console.log('  → Copying artifacts to site...');
+
+  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'));
+}
+
+// =============================================================================
+// Build Summary
+/**
+ * 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} siteDir - Path to the final built site directory whose contents will be listed.
+ */
+
+function printBuildSummary(docsDir, artifactsDir, siteDir) {
+  console.log();
+  printBanner('Build Complete!');
+  console.log();
+  console.log('Build artifacts:');
+  console.log(`  Source docs:     ${docsDir}`);
+  console.log(`  Generated files: ${artifactsDir}`);
+  console.log(`  Final site:      ${siteDir}`);
+  console.log();
+  console.log(`Deployable output: ${siteDir}/`);
+  console.log();
+
+  listDirectoryContents(siteDir);
+}
+
+function listDirectoryContents(dir) {
+  const entries = fs.readdirSync(dir).slice(0, 15);
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry);
+    const stat = fs.statSync(fullPath);
+
+    if (stat.isFile()) {
+      const sizeStr = formatFileSize(stat.size);
+      console.log(`  ${entry.padEnd(40)} ${sizeStr.padStart(8)}`);
+    } else {
+      console.log(`  ${entry}/`);
+    }
+  }
+}
+
+/**
+ * Format a byte count into a compact human-readable string using B, K, or M units.
+ * @param {number} bytes - The number of bytes to format.
+ * @returns {string} The formatted size: bytes as `N B` (e.g. `512B`), kilobytes truncated to an integer with `K` (e.g. `2K`), or megabytes with one decimal and `M` (e.g. `1.2M`).
+ */
+function formatFileSize(bytes) {
+  if (bytes > 1024 * 1024) {
+    return `${(bytes / 1024 / 1024).toFixed(1)}M`;
+  } else if (bytes > 1024) {
+    return `${Math.floor(bytes / 1024)}K`;
+  }
+  return `${bytes}B`;
+}
+
+// =============================================================================
+// File System Utilities
+/**
+ * Remove any existing build output and recreate the build directory.
+ *
+ * Ensures the configured BUILD_DIR is empty by deleting it if present and then creating a fresh directory.
+ */
+
+function cleanBuildDirectory() {
+  console.log('Cleaning previous build...');
+
+  if (fs.existsSync(BUILD_DIR)) {
+    fs.rmSync(BUILD_DIR, { recursive: true });
+  }
+  fs.mkdirSync(BUILD_DIR, { recursive: true });
+}
+
+/**
+ * Recursively copies all files and subdirectories from one directory to another, creating the destination if needed.
+ *
+ * @param {string} src - Path to the source directory to copy from.
+ * @param {string} dest - Path to the destination directory to copy to.
+ * @param {string[]} [exclude=[]] - List of file or directory names (not paths) to skip while copying.
+ * @returns {boolean} `true` if the source existed and copying proceeded, `false` if the source did not exist.
+ */
+function copyDirectory(src, dest, exclude = []) {
+  if (!fs.existsSync(src)) return false;
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (exclude.includes(entry.name)) continue;
+
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectory(srcPath, destPath, exclude);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+  return true;
+}
+
+// =============================================================================
+// Console Output Formatting
+// =============================================================================
+
+function printHeader(title) {
+  console.log();
+  console.log('┌' + '─'.repeat(62) + '┐');
+  console.log(`│ ${title.padEnd(60)} │`);
+  console.log('└' + '─'.repeat(62) + '┘');
+}
+
+/**
+ * Prints a centered decorative ASCII banner to the console using the provided title.
+ * @param {string} title - Text to display centered inside the banner. */
+function printBanner(title) {
+  console.log('╔' + '═'.repeat(62) + '╗');
+  console.log(`║${title.padStart(31 + title.length / 2).padEnd(62)}║`);
+  console.log('╚' + '═'.repeat(62) + '╝');
+}