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>

docs/explanation/faq/index.md

@@ -0,0 +1,16 @@
+---
+title: "Frequently Asked Questions"
+description: Frequently asked questions about the BMad Method
+---
+
+Quick answers to common questions about the BMad Method, organized by topic.
+
+## Topics
+
+- [Getting Started](/docs/explanation/faq/getting-started-faq.md) - Questions about starting with BMad
+- [Levels & Tracks](/docs/explanation/faq/levels-and-tracks-faq.md) - Choosing the right level
+- [Workflows](/docs/explanation/faq/workflows-faq.md) - Workflow and phase questions
+- [Planning](/docs/explanation/faq/planning-faq.md) - Planning document questions
+- [Implementation](/docs/explanation/faq/implementation-faq.md) - Implementation questions
+- [Brownfield](/docs/explanation/faq/brownfield-faq.md) - Existing codebase questions
+- [Tools & Advanced](/docs/explanation/faq/tools-faq.md) - Tools, IDEs, and advanced topics

tools/validate-doc-links.js

@@ -102,11 +102,17 @@ function extractAnchors(content) {
 
 /**
  * Resolve a site-relative link to a file path
+ * /docs/how-to/installation/install-bmad.md -> docs/how-to/installation/install-bmad.md
  * /how-to/installation/install-bmad/ -> docs/how-to/installation/install-bmad.md or .../index.md
  */
 function resolveLink(siteRelativePath) {
   // Strip anchor and query
-  const checkPath = siteRelativePath.split('#')[0].split('?')[0];
+  let checkPath = siteRelativePath.split('#')[0].split('?')[0];
+
+  // Strip /docs/ prefix if present (repo-relative links)
+  if (checkPath.startsWith('/docs/')) {
+    checkPath = checkPath.slice(5); // Remove '/docs' but keep leading '/'
+  }
 
   if (checkPath.endsWith('/')) {
     // Could be file.md or directory/index.md
@@ -118,11 +124,11 @@ function resolveLink(siteRelativePath) {
     return null;
   }
 
-  // Direct path
+  // Direct path (e.g., /path/file.md)
   const direct = path.join(DOCS_ROOT, checkPath);
   if (fs.existsSync(direct)) return direct;
 
-  // Try with .md
+  // Try with .md extension
   const withMd = direct + '.md';
   if (fs.existsSync(withMd)) return withMd;