Commit Graph

41 Commits

Author SHA1 Message Date
Alex Verkhovsky e3f935fd6d
fix(docs): community feedback — typo, locale 404s, llms-full (#2091)
* fix(docs): correct Hasselhoff spelling, add locale-aware 404 redirect

Fix "Hasslehoff" → "Hasselhoff" typo in customize-bmad.md across all
three locales (en, zh-cn, fr).

Add client-side locale detection to 404.astro so GitHub Pages serves
the correct localized 404 page instead of always showing English.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(build): exclude translated locales from llms-full.txt

llms-full.txt was including zh-cn and fr docs, tripling the content
with duplicate information in different languages. Restrict to English
only — translations add no value for LLM context consumption.

Reduces output from ~393K to ~114K chars (~29k tokens).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(i18n): extract locale config to shared module

Move locale definitions from astro.config.mjs into a shared
website/src/lib/locales.mjs consumed by astro config, build-docs,
and 404.astro. Adding a new locale is now a single-file change.

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-21 16:42:57 -06:00
Alex Verkhovsky c28206dca4
refactor(installer): remove dead agent compilation pipeline (#2080)
* refactor(installer): remove dead agent compilation pipeline

Delete 9 files (~2,600 lines) that compiled .agent.yaml to .md.
No .agent.yaml files exist in the source tree — agents now ship
as pre-built SKILL.md. Clean up all references in installer,
module manager, custom handler, base IDE, UI, and tests.

* refactor(custom-handler): remove dead install/copy/find methods

CustomHandler.install(), copyDirectory(), and findFilesRecursively()
are never called — custom modules are installed via moduleManager.install()
since Dec 2025. Also removes unused FileOps import and constructor.

Verified with before/after clean-installer comparison (codex + custom
modules with custom.yaml): output is identical.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(installer): remove dead compilation refs from docs and module manager

Address review findings from PR #2080 triage:
- Remove compile-agents from CLI action docs (en, fr, zh-cn)
- Remove dead vendorCrossModuleWorkflows() and .agent.yaml skip logic
- Clean stale compilation-era comments in manifest-generator

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-20 22:52:02 -06:00
Emmanuel Atsé a2839cbee0
docs: fix duplicate sidebar order number (#2071)
how-to/ customize-bmad.md and project-context.md had the same order
number

Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
2026-03-20 11:38:35 -06:00
Alex Verkhovsky 3fad46849f docs: rewrite quick-fixes how-to around Quick Dev workflow
Remove DEV agent references and simplify to Quick Dev as the single
entry point. Show free-form intent examples, add deferred work section,
clarify that Quick Dev commits for you.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 00:05:30 -06:00
Alex Verkhovsky 43c59f0cff docs: replace quick-flow explainer with quick-dev, remove stale Quick Spec refs
Quick Flow was an umbrella for quick-spec + quick-dev. Quick Spec is
gone and the new preview was promoted to bmad-quick-dev, so the explainer
should be about quick-dev directly. Replaces quick-flow.md with the
original quick-dev-new-preview.md content (renamed), including the
diagram reference. zh-cn uses the original hand-written Chinese
translation. Also removes stale Quick Spec references from agents.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-18 23:47:49 -06:00
Brian 0380656de6
refactor: consolidate agents into phase-based skill directories (#2050)
* refactor: consolidate agents into phase-based skill directories

Remove separate agent/workflow/skill directories (src/bmm/agents,
src/bmm/workflows, src/core/skills, src/utility/agent-components) and
reorganize all content into phase-based structures under src/bmm-skills
(1-analysis, 2-plan-workflows, 3-solutioning, 4-implementation) and
src/core-skills. Eliminates the agent/skill distinction by treating
agents as skills within their workflow phase.

* fix: update broken file references to use new bmm-skills paths

* docs: update all references for unified bmad-quick-dev workflow

Remove all references to the old separate bmad-quick-spec and
bmad-quick-dev-new-preview workflows. The new bmad-quick-dev is a
unified workflow that handles intent clarification, planning,
implementation, review, and presentation in a single run.

Updated files across English docs, Chinese translations, source
skill manifests, website diagram, and build tooling.
2026-03-18 01:01:33 -05:00
Brian 9fa51d996b
prototype preview of new version of product brief skill (#1959)
* prototype preview of new version of product brief skill

* chore: re-enable bmad-builder external module

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* config loading with existing location

* refactor: rename bmad-bmm-product-brief-preview to bmad-product-brief-preview

Drop the redundant bmm prefix from the product brief preview skill folder
to align with the standard naming convention.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add core tools reference and apply Diataxis style fixes

Add comprehensive reference doc for all 11 built-in core tools (tasks
and workflows) that ship with every BMad installation — bmad-help,
brainstorming, party-mode, distillator, advanced-elicitation, both
review tools, both editorial tools, shard-doc, and index-docs. Each
entry follows the Configuration Reference structure with purpose,
use cases, how it works, inputs, and outputs.

Style fixes across existing docs:
- reference/commands.md: convert #### headers to bold text, replace
  sparse task table with link to new core-tools reference
- how-to/get-answers-about-bmad.md: remove horizontal rule between
  sections (Diataxis violation)
- how-to/project-context.md: consolidate 4 consecutive tip admonitions
  into single admonition with bullet list, add AGENTS.md reference

Also includes:
- Add bmad-distillator task to core module with compression agents,
  format reference, splitting strategy, and analysis scripts
- Add Distillator entry to module-help.csv
- Rename supports-autonomous to supports-headless in product-brief
  manifest

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* core items to skills folder

* fix calls to invoke party mode

* fix calls to invoke party mode and AE as skills

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-15 00:05:53 -05:00
Alex Verkhovsky 2a12c6b2f0
docs: drop slash-command prefix from skill references (#1892)
* docs: drop slash-command syntax from skill references (editorial)

Skill names like bmad-help are now shown without a / prefix since
invocation syntax varies across platforms. First-encounter locations
(README, getting-started, get-answers, installer message, bmad-help
display rules) get editorial framing so new users understand these
are skill names to invoke by name.

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

* docs: mechanical removal of slash prefix from all remaining skill references

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-11 02:35:16 -06:00
Alex Verkhovsky bb046f5062
docs: mention next install channel (#1887) 2026-03-11 02:34:26 -06:00
Alex Verkhovsky db8f856fce
docs: update terminology from commands to skills across all documentation (#1850)
Align documentation with the skills-based architecture migration by
replacing references to "commands", "slash commands", and legacy command
names with the new "skills" terminology and skill names.
2026-03-07 16:14:25 -07:00
Alex Verkhovsky 811d03262d
fix(config): remove Windsurf from recommended/preferred IDEs (#1727)
Windsurf is no longer a preferred IDE. Only Claude Code and Cursor
are now recommended. Windsurf remains a supported platform (installer
still works, templates stay, reference tables stay).

- Set preferred: false in both platform-codes.yaml files
- Move windsurf entry to "Other IDEs" section in tools/platform-codes.yaml
- Fix codex.js hardcoding preferred: true in constructor
- Remove stale "3 preferred tools" count from ui.js JSDoc
- Update docs to list only Claude Code and Cursor as recommended
- Update docs/index.md popular tools to Claude Code, Cursor, Codex CLI
2026-02-20 20:16:43 -06:00
Brian Madison 1782e97731 docs: elevate bmad-help as primary on-ramp across all documentation
BMad-Help is one of V6's flagship features but was undersold in docs.
This update positions it properly as the intelligent guide that:

- Inspects project state and detects what's completed
- Understands natural language queries
- Varies options based on installed modules
- Auto-invokes after every workflow
- Recommends first required tasks

Changes:
- Add dedicated "Meet BMad-Help" section to getting-started
- Expand commands.md with full BMad-Help subsection and examples
- Reposition get-answers-about-bmad.md to start with BMad-Help
- Enhance install-bmad.md and established-projects.md with query examples
- Add index.md tip box promoting /bmad-help as quickest way to dive in
2026-02-18 00:22:12 -06:00
Brian Madison 9247146397 docs: update workflow names and standardize table formatting
- Prefix all workflows with 'bmad-bmm-' for clarity
- Standardize table column alignment
- Update workflow path references to use relative paths
- Clarify project-context documentation
- Simplify workflow loading information
2026-02-18 00:00:54 -06:00
Brian Madison d4b4bdfa12 docs: improve project-context documentation and fix folder structure
- Add explanation/how-to docs for project-context.md feature
- Update workflow-map Context Management section with comprehensive guidance
- Fix folder structure examples to show proper nested subdirectories
  (planning-artifacts/ and implementation-artifacts/ under _bmad-output/)
- Update established-projects.md with project-context creation step
- Standardize terminology: use "existing projects" instead of "brownfield"
2026-02-15 17:32:05 -06:00
Alex Verkhovsky a1101534b2
fix(docs): comprehensive documentation site review fixes (#1578)
* fix(docs): comprehensive documentation site review fixes

Rehype plugins:
- Rewrite rehype-markdown-links for correct relative .md resolution
- Handle raw HTML base paths and bare .md links in rehype-base-paths
- Guard protocol-relative URLs (//...) in all link processors
- Use file.path instead of file.history[0] for vfile compatibility
- Fail build when content directory cannot be detected
- Export helpers for testability; add 107 unit tests

Build & CI:
- Revert cancel-in-progress to false to avoid mid-deploy cancellation
- Remove redundant link-validation CI step (build validates internally)
- Remove unnecessary fetch-depth:0 from docs deploy workflow
- Refuse docs build on Windows (platform guard)
- Remove dead build scripts and stale references

Tooling:
- Add DOCS_ROOT boundary check in validate-doc-links.js
- Handle directory paths and prefix stripping in link validator
- Remove dead regex and add // guard in fix-doc-links.js

Accessibility & CSS:
- Darken caution/danger aside title colors for WCAG AA 4.5:1 contrast
- Fix 100vw scrollbar overflow (banner width:100%, html overflow-x:clip)
- Add :focus-visible ring to banner link for keyboard navigation
- Remove dead CSS declaration and add missing code block lang

Documentation content:
- Convert /docs/ absolute links to relative paths and fix llms.txt URLs
- Correct command file paths and naming in commands reference
- Update stale shard-doc command to current /bmad-shard-doc format
- Fix incomplete sentence in install-bmad.md
- Add Quick Flow next steps and fix 404 link path
- Expand thin content pages with substantive detail
- Add sidebar ordering frontmatter to all content pages
- Remove BMGD docs (moved to dedicated repo)
- Remove unused assets and misleading diagram caption
- Add non-iframe fallback link to workflow map diagram
- Remove dead noscript block from workflow-map
- Standardize BMAD to BMad, fix spelling/grammar, normalize headings

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

* fix(docs): add non-interactive installation to sidebar, rewrite and reorder how-to guides

- Move non-interactive-installation.md into how-to/ directory so it appears
  in the sidebar navigation (was orphaned at docs root)
- Rewrite the page based on editorial review: consolidate redundant sections,
  add missing how-to structure (prerequisites, "What You Get"), condense
  installation modes from 5 subsections to a table, cut speculative examples
- Reorder how-to sidebar: Install (1), Non-Interactive (2), Upgrade to v6 (3),
  then the rest following user journey order
- Fix README link to point to docs site instead of repo-internal markdown path

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

* fix(docs): address documentation review findings

Fix broken directory tree, grammar errors, inconsistent naming,
missing admonition/headings, enable lastUpdated timestamps in CI,
and remove footer CSS that misapplied to the content footer.

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

* fix(docs): move bleeding-edge install command out of Verify Installation

The alternative npx command for installing from main was misplaced
inside the "Verify Installation" section. Move it to a tip admonition
under Step 1 where users look for install options.

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

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-08 11:58:22 -06:00
Alex Verkhovsky fc5ef57a5a
feat: add Kiro IDE support via config-driven installer (#1589)
Replace broken kiro-cli.js custom installer with config-driven approach
using platform-codes.yaml. Creates Kiro-specific templates with
inclusion: manual frontmatter and #[[file:...]] reference syntax.
2026-02-08 09:18:28 -06:00
Alex Verkhovsky ecf7fbcb2c
docs: add description front matter to documentation pages (#1566) 2026-02-07 10:43:16 -06:00
Alex Verkhovsky a8cda7c6fa
refactor: remove downloads page and bundle generation (#1577)
The downloads page offered bmad-sources.zip and bmad-prompts.zip, both
redundant: GitHub provides source archives for every tag natively, and
npx bmad-method install is the supported path for compiled prompts.

Remove the downloads page, all bundle generation code, the archiver
dependency, and nav links. The llms.txt and llms-full.txt files (the
genuinely useful artifacts) continue to be generated as before.
2026-02-06 23:26:39 -06:00
Brian Madison 6c2d0195d3 minor doc updates 2026-02-06 22:54:47 -06:00
Alex Verkhovsky 2aab028f96
docs: rename brownfield to established projects (#1539)
* docs: rename brownfield to established projects

Flatten how-to/brownfield/ subdirectory and replace jargon term
"brownfield" with more accessible "established projects" throughout.

- brownfield/index.md → established-projects.md
- brownfield/quick-fix-in-brownfield.md → quick-fixes.md
- brownfield-faq.md → established-projects-faq.md
- Update all internal links and references

* docs: remove redundant phrase from quick-fixes description

* docs: restore natural language in established-projects body
2026-02-05 18:57:40 -06:00
The Chef 7d3d51ff4f
docs: fix typos in README and customization guide (#1424)
- Remove duplicate "for" in README example command
- Fix "this is" to "thing is" in README
- Remove extra "at" in "star project icon at near" in README
- Fix "MEthod" to "Method" in customize-bmad.md
2026-01-26 23:25:08 -08:00
Brian Madison d0c9cd7b0b removed dead code and obsolete levels 0-4 ref 2026-01-25 22:23:36 -06:00
Brian Madison c352e03d18 add interactive diagram to test final doc build and layout 2026-01-25 22:12:23 -06:00
Brian Madison 9b12f6f86c docs updates 2026-01-25 21:18:09 -06:00
Alex Verkhovsky 91f6c41be1
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>
2026-01-25 14:00:26 -06:00
Murat K Ozcan 6eb7c34752
docs: update test-design workflow to generate two documents for system-level mode (#1367)
* docs: update test-design workflow to generate two documents for system-level mode

* addressed pr comments
2026-01-22 14:29:33 -06:00
Brian Madison 73135bee8e gitignore ide installs settings and removed gamedev doc reference 2026-01-19 02:18:14 -06:00
Brian Madison 6f8f0871cf Project Cleanup of Agents Menus, BMB module removal to other repo 2026-01-19 02:04:14 -06:00
Brian Madison d022e569bd remove gamedev and cis docs 2026-01-17 02:03:48 -06:00
jheyworth d83a88da66 Fix remaining TodoMVC URL references in documentation
Updated 2 additional files to use the correct /dist/ path:
- docs/how-to/workflows/run-automate.md: Standalone mode example
- docs/reference/tea/configuration.md: Playwright BASE_URL example

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-16 12:09:19 +00:00
Brian Madison 0fa53ad144 removing docs accidentally added to wrong repo docs folder 2026-01-15 22:30:43 -06:00
Murat K Ozcan abba7ee987
docs: removed enterprise folder (#1340) 2026-01-15 19:32:55 -06:00
Murat K Ozcan 87b1292e3f
docs: named TEA links consistently (#1337) 2026-01-15 18:01:37 -06:00
Murat K Ozcan 66e7d3a36d
docs: tea in 4; Diátaxis (#1320)
* docs: tea in 4; Diátaxis

* docs: addressed review comments

* docs: refined the docs
2026-01-15 13:18:37 -06:00
Brian Madison 3360666c2a remove hard inclusion of AV from installer, to replace with module soon 2026-01-14 23:04:19 -06:00
forcetrainer c0f6401902 docs: add token usage FAQ and fix broken links
- Add "Why does BMad use so many tokens?" FAQ explaining design tradeoff
  (decision quality over code velocity)
- Fix stale anchor #adversarial-review-general → #adversarial-review
- Remove link to archived customize-workflows.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 00:31:54 -05:00
forcetrainer e535f94325 docs: comprehensive style guide update with reference and glossary standards
Style Guide Additions:
- Add Reference Structure section with 6 document types (Index, Catalog,
  Deep-Dive, Configuration, Glossary, Comprehensive)
- Add Glossary Structure section with table-based format leveraging
  Starlight's right-nav for navigation
- Include checklists for both new document types

Reference Docs Updated:
- agents/index.md: Catalog format, universal commands tip admonition
- configuration/core-tasks.md: Configuration format with admonitions
- configuration/global-config.md: Table-based config reference
- workflows/index.md: Minimal index format
- workflows/core-workflows.md: Catalog format
- workflows/document-project.md: Deep-dive with Quick Facts admonition
- workflows/bmgd-workflows.md: Comprehensive format, removed ~30 hr rules

Glossary Rewritten:
- Converted from 373 lines with ### headers to 123 lines with tables
- Right nav now shows 9 categories instead of 50+ terms
- Added italic context markers (*BMGD.*, *Brownfield.*, etc.)
- Alphabetized terms within categories
- Removed redundant inline TOC

All Docs:
- Remove horizontal rules (---) per style guide
- Remove "Related" sections (sidebar handles navigation)
- Standardize admonition usage
- Archive deleted workflow customization docs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-12 00:23:05 -05:00
Alex Verkhovsky c18904d674
refactor: rename create-tech-spec to quick-spec for QuickFlow branding (#1290) 2026-01-10 11:33:00 +08:00
forcetrainer 12d3492e0c
Add link auditor, reorganize documentation, and README update (#1277)
* feat: add link auditor tools and fix broken docs links

- Add audit-doc-links.js to scan docs for broken links with auto-resolution
- Add fix-doc-links.js to apply suggested fixes (dry-run by default)
- Remove stale "Back to Core Concepts" breadcrumb links
- Update BMad acronym to "Breakthrough Method of Agile AI Driven Development"
- Update README links to docs.bmad-method.org
- Simplify upgrade callout in getting-started tutorial

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

* docs: reorganize docs structure and archive v4 tutorial

- Remove unused section index files (tutorials, how-to, explanation, reference)
- Move getting-started-bmadv4.md to _archive
- Update quick-start-bmgd.md to remove archived file reference
- Update upgrade-to-v6.md
- Update astro.config.mjs for new structure

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

* fix: ignore underscore directories in link checker

Update check-doc-links.js to skip _archive, _planning, and other
underscore-prefixed directories when validating links.

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

* docs: add v4 users section to README

Add links to v4 documentation archive and upgrade guide for users
migrating from previous versions.

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

* feat: convert docs to site-relative links and add validation tools

- Convert all relative links (./  ../) to site-relative paths (/path/)
- Strip .md extensions and use trailing slashes for Astro/Starlight
- Add fix-doc-links.js to convert relative links to site-relative
- Add validate-doc-links.js to check links point to existing files
- Remove old audit-doc-links.js and check-doc-links.js
- Update build-docs.js to use new validation script
- Add npm scripts: docs:fix-links, docs:validate-links
- Update style guide with validation steps

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

* docs: standardize acronym to BMad across documentation

Replace incorrect "BMAD" with correct "BMad" in text and frontmatter
while preserving "BMAD-METHOD" in GitHub URLs.

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

* docs: fix BMad acronym and remove draft README

- Correct acronym to "Breakthrough Method of Agile AI Driven Development"
- Remove unused README-draft.md

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

* docs: standardize BMad acronym in README

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

* docs: standardize FAQ format across all FAQ pages

- Add TOC with jump links under "## Questions"
- Use ### headers for questions (no Q: prefix)
- Direct answers without **A:** prefix
- Remove horizontal rules and "Related Documentation" sections
- End each FAQ with issue/Discord CTA
- Update style guide with new FAQ guidelines
- Delete redundant faq/index.md (sidebar handles navigation)

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

* fix: use repo-relative links with .md for GitHub compatibility

Convert all documentation links to repo-relative format (/docs/path/file.md)
so they work when browsing on GitHub. The rehype plugin strips /docs/ prefix
and converts .md to trailing slash at build time for Astro/Starlight.

- Update rehype-markdown-links.js to strip /docs/ prefix from absolute paths
- Update fix-doc-links.js to generate /docs/ prefixed paths with .md extension
- Convert 217 links across 64 files to new format

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

* fix: handle /docs/ prefix in link validator

Update resolveLink to strip /docs/ prefix from repo-relative links
before checking if files exist.

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

* docs: restore FAQ index page

Re-add the FAQ index page that was accidentally deleted, with
updated repo-relative link format.

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

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
2026-01-10 02:55:33 +08:00
Alex Verkhovsky 692f14f2e7
docs: add how-to guide for getting BMAD answers + fix Discord channels (#1265)
* docs: add how-to guide for getting BMAD answers + fix Discord channels

- New guide: docs/how-to/get-answers-about-bmad.md
  Teaches users to point LLMs at BMAD sources for self-serve answers

- Fixed outdated Discord channel references across 8 files:
  #general-dev → #bmad-development
  #bugs-issues → #report-bugs-and-issues
  Added #suggestions-feedback and #bmad-method-help where appropriate

* docs: add Mayakovsky-style poem to how-to guide
2026-01-07 16:05:05 +08:00
Alex Verkhovsky 2e16650067
feat(docs): Diataxis restructure + Astro/Starlight migration (#1263)
* feat(docs): add Diataxis folder structure and update sidebar styling

- Create tutorials, how-to, explanation, reference directories with subdirectories
- Add index.md files for each main Diataxis section
- Update homepage with Diataxis card navigation layout
- Implement clean React Native-inspired sidebar styling
- Convert sidebar to autogenerated for both Diataxis and legacy sections
- Update docusaurus config with dark mode default and navbar changes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* feat(docs): migrate Phase 1 files to Diataxis structure

Move 21 files to new locations:
- Tutorials: quick-start guides, agent creation guide
- How-To: installation, customization, workflows
- Explanation: core concepts, features, game-dev, builder
- Reference: merged glossary from BMM and BMGD

Also:
- Copy images to new locations
- Update internal links via migration script (73 links updated)
- Build verified successfully

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix(docs): add category labels for sidebar folders

Add _category_.json files to control display labels and position
for autogenerated sidebar categories.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* style(docs): improve welcome page and visual styling

- Rewrite index.md with React Native-inspired welcoming layout
- Add Diataxis section cards with descriptions
- Remove sidebar separator, add spacing instead
- Increase navbar padding with responsive breakpoints
- Add rounded admonitions without left border bar
- Use system font stack for better readability
- Add lighter chevron styling in sidebar
- Constrain max-width to 1600px for wide viewports

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix: use baseUrl in meta tag paths for correct deployment URLs

* feat(docs): complete Phase 2 - split files and fix broken links

Phase 2 of Diataxis migration:
- Split 16 large legacy files into 42+ focused documents
- Created FAQ section with 7 topic-specific files
- Created brownfield how-to guides (3 files)
- Created workflow how-to guides (15+ files)
- Created architecture explanation files (3 files)
- Created TEA/testing explanation files
- Moved remaining legacy module files to proper Diataxis locations

Link fixes:
- Fixed ~50 broken internal links across documentation
- Updated relative paths for new file locations
- Created missing index files for installation, advanced tutorials
- Simplified TOC anchors to fix Docusaurus warnings

Cleanup:
- Removed legacy sidebar entries for deleted folders
- Deleted duplicate and empty placeholder files
- Moved workflow diagram assets to tutorials/images

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix(build): use file glob instead of sidebar parsing for llms-full.txt

Replace brittle sidebar.js regex parsing with recursive file glob.
The old approach captured non-file strings like 'autogenerated' and
category labels, resulting in only 5 files being processed.

Now correctly processes all 86+ markdown files (~95k tokens).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix(seo): use absolute URLs in AI meta tags for agent discoverability

AI web-browsing agents couldn't follow relative paths in meta tags due to
URL security restrictions. Changed llms-full.txt and llms.txt meta tag
URLs from relative (baseUrl) to absolute (urlParts.origin + baseUrl).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* refactor(docs): recategorize misplaced files per Diataxis analysis

Phase 2.5 categorization fixes based on post-migration analysis:

Moved to correct Diataxis categories:
- tutorials/installation.md → deleted (duplicate of how-to/install-bmad.md)
- tutorials/brownfield-onboarding.md → how-to/brownfield/index.md
- reference/faq/* (8 files) → explanation/faq/
- reference/agents/barry-quick-flow.md → explanation/agents/
- reference/agents/bmgd-agents.md → explanation/game-dev/agents.md

Created:
- explanation/agents/index.md

Fixed all broken internal links (14 total)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* feat(docs): add Getting Started tutorial and simplify build script

- Add comprehensive Getting Started tutorial with installation as Step 1
- Simplify build-docs.js to read directly from docs/ (no consolidation)
- Remove backup/restore dance that could corrupt docs folder on build failure
- Remove ~150 lines of unused consolidation code

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* fix(css): use fixed width layout to prevent content shifting

Apply React Native docs approach: set both width and max-width at
largest breakpoint (1400px) so content area maintains consistent
size regardless of content length. Switches to fluid 100% below
1416px breakpoint.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* refactor(docs): restructure tutorials with renamed entry point

- Rename index.md to bmad-tutorial.md for clearer navigation
- Remove redundant tutorials/index.md
- Update sidebar and config references

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* feat(docs): add tutorial style guide and AI agent announcement bar

- Add docs/_contributing/ with tutorial style guide
- Reformat quick-start-bmm.md and bmad-tutorial.md per style guide
- Remove horizontal separators, add strategic admonitions
- Add persistent announcement bar for AI agents directing to llms-full.txt
- Fix footer broken link to tutorials

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* feat(docs): add markdown demo page and UI refinements

- Add comprehensive markdown-demo.md for style testing
- Remove doc category links from navbar (use sidebar instead)
- Remove card buttons from welcome page
- Add dark mode styling for announcement bar
- Clean up index.md card layout

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* feat(docs): apply unified tutorial style and update references

- Reformat create-custom-agent.md to follow tutorial style guide
- Update tutorial-style.md with complete unified structure
- Update all internal references to renamed tutorial files
- Remove obsolete advanced/index.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

* 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

---------

Co-authored-by: forcetrainer <bryan@inagaki.us>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-07 14:42:15 +08:00