feat(docs): Add sidebar order validator for doc frontmatter (#2409)

* feat(docs): add sidebar order validator

Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.

Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.

* fix(validate-sidebar): tighten language detection and drift guard, add docstrings

* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching

detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.

Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.

* fix(validate-sidebar): guard drift check against undefined order values

extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".

Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.

* chore(validate-sidebar): add JSDoc docstrings to all functions

Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.

* fix(validate-sidebar): add to pre-commit hook

* refactor(validate-sidebar): harden parsing and edge-case handling

Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).

* docs: fix sidebar.order duplicates and gaps across all locales

Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.

English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
  for new explanation pages added since orders were last set.

Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
  compacted to 1..N within each directory to eliminate gaps
  caused by missing translation files.

Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.

---------

Co-authored-by: Brian Madison <bmadcode@gmail.com>

.husky/pre-commit

@@ -10,11 +10,13 @@ npm test
 if command -v rg >/dev/null 2>&1; then
   if git diff --cached --name-only | rg -q '^docs/'; then
     npm run docs:validate-links
+		npm run docs:validate-sidebar
 		npm run docs:build
   fi
 else
   if git diff --cached --name-only | grep -Eq '^docs/'; then
     npm run docs:validate-links
+		npm run docs:validate-sidebar
 		npm run docs:build
   fi
 fi

docs/cs/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Pokročilá elicitace"
 description: Přimějte LLM přehodnotit svou práci pomocí strukturovaných metod uvažování
 sidebar:
-  order: 6
+  order: 3
 ---
 
 Přimějte LLM přehodnotit, co právě vygeneroval. Vyberete metodu uvažování, LLM ji aplikuje na svůj vlastní výstup, a vy rozhodnete, zda si vylepšení ponecháte.

docs/cs/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Adversariální revize"
 description: Technika vynuceného uvažování, která zabraňuje líným „vypadá dobře“ revizím
 sidebar:
-  order: 5
+  order: 7
 ---
 
 Vynuťte hlubší analýzu tím, že budete vyžadovat nalezení problémů.

docs/cs/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "FAQ pro existující projekty"
 description: Časté otázky o používání BMad Method na existujících projektech
 sidebar:
-  order: 8
+  order: 10
 ---
 Rychlé odpovědi na časté otázky o práci na existujících projektech s BMad Method (BMM).
 

docs/cs/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Party Mode"
 description: Spolupráce více agentů — všichni vaši AI agenti v jedné konverzaci
 sidebar:
-  order: 7
+  order: 8
 ---
 
 Všichni vaši AI agenti v jedné konverzaci.

docs/cs/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Předcházení konfliktům agentů"
 description: Jak architektura zabraňuje konfliktům, když více agentů implementuje systém
 sidebar:
-  order: 4
+  order: 5
 ---
 
 Když více AI agentů implementuje různé části systému, mohou dělat protichůdná technická rozhodnutí. Dokumentace architektury tomu zabraňuje stanovením sdílených standardů.

docs/cs/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Kontext projektu"
 description: Jak project-context.md vede AI agenty s pravidly a preferencemi vašeho projektu
 sidebar:
-  order: 7
+  order: 9
 ---
 
 Soubor `project-context.md` je implementační průvodce vašeho projektu pro AI agenty. Podobně jako „ústava“ v jiných vývojových systémech zachycuje pravidla, vzory a preference, které zajišťují konzistentní generování kódu napříč všemi workflow.

docs/cs/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Quick Dev"
 description: Snižte tření human-in-the-loop bez ztráty kontrolních bodů chránících kvalitu výstupu
 sidebar:
-  order: 2
+  order: 6
 ---
 
 Záměr na vstupu, změny kódu na výstupu, s co nejmenším počtem human-in-the-loop kroků — bez obětování kvality.

docs/cs/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Proč je solutioning důležitý"
 description: Pochopení toho, proč je fáze solutioningu klíčová pro projekty s více epicy
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Fáze 3 (Solutioning) překládá **co** budovat (z plánování) na **jak** to budovat (technický návrh). Tato fáze zabraňuje konfliktům agentů v projektech s více epicy tím, že dokumentuje architektonická rozhodnutí před zahájením implementace.

docs/cs/reference/commands.md

@@ -2,7 +2,7 @@
 title: Skills
 description: Reference BMad skills — co to je, jak fungují a kde je najít.
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Skills jsou předpřipravené prompty, které načítají agenty, spouštějí workflow nebo provádějí úkoly ve vašem IDE. Instalátor BMad je generuje z vašich nainstalovaných modulů při instalaci. Pokud později přidáte, odeberete nebo změníte moduly, přeinstalujte pro synchronizaci skills (viz [Řešení problémů](#řešení-problémů)).

docs/cs/reference/core-tools.md

@@ -2,7 +2,7 @@
 title: Základní nástroje
 description: Reference všech vestavěných úkolů a workflow dostupných v každé instalaci BMad bez dalších modulů.
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Každá instalace BMad zahrnuje sadu základních skills, které lze použít v kombinaci s čímkoli — samostatné úkoly a workflow, které fungují napříč všemi projekty, všemi moduly a všemi fázemi. Ty jsou vždy dostupné bez ohledu na to, které volitelné moduly nainstalujete.

docs/cs/reference/modules.md

@@ -2,7 +2,7 @@
 title: Oficiální moduly
 description: Doplňkové moduly pro tvorbu vlastních agentů, kreativní inteligenci, vývoj her a testování
 sidebar:
-  order: 4
+  order: 5
 ---
 
 BMad se rozšiřuje prostřednictvím oficiálních modulů, které vyberete během instalace. Tyto doplňkové moduly poskytují specializované agenty, workflow a úkoly pro specifické domény nad rámec vestavěného jádra a BMM (Agile suite).

docs/cs/reference/testing.md

@@ -2,7 +2,7 @@
 title: Možnosti testování
 description: Srovnání vestavěného QA agenta (Quinn) s modulem Test Architect (TEA) pro automatizaci testů.
 sidebar:
-  order: 5
+  order: 6
 ---
 
 BMad poskytuje dvě testovací cesty: vestavěného QA agenta pro rychlé generování testů a instalovatelný modul Test Architect pro podnikovou testovací strategii.

docs/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Advanced Elicitation"
 description: Push the LLM to rethink its work using structured reasoning methods
 sidebar:
-  order: 6
+  order: 4
 ---
 
 Make the LLM reconsider what it just generated. You pick a reasoning method, it applies that method to its own output, you decide whether to keep the improvements.

docs/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Adversarial Review"
 description: Forced reasoning technique that prevents lazy "looks good" reviews
 sidebar:
-  order: 5
+  order: 9
 ---
 
 Force deeper analysis by requiring problems to be found.

docs/explanation/analysis-phase.md

@@ -2,7 +2,7 @@
 title: "Analysis Phase: From Idea to Foundation"
 description: What brainstorming, research, product briefs, and PRFAQs are — and when to use each
 sidebar:
-  order: 1
+  order: 2
 ---
 
 The Analysis phase (Phase 1) helps you think clearly about your product before committing to building it. Every tool in this phase is optional, but skipping analysis entirely means your PRD is built on assumptions instead of insight.

docs/explanation/brainstorming.md

@@ -2,7 +2,7 @@
 title: "Brainstorming"
 description: Interactive creative sessions using 60+ proven ideation techniques
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Unlock your creativity through guided exploration.

docs/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "Checkpoint Preview"
 description: LLM-assisted human-in-the-loop review that guides you through a change from purpose to details
 sidebar:
-  order: 3
+  order: 8
 ---
 
 `bmad-checkpoint-preview` is an interactive, LLM-assisted human-in-the-loop review workflow. It walks you through a code change — from purpose and context into details — so you can make an informed decision about whether to ship, rework, or dig deeper.

docs/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "Established Projects FAQ"
 description: Common questions about using BMad Method on established projects
 sidebar:
-  order: 8
+  order: 13
 ---
 Quick answers to common questions about working on established projects with the BMad Method (BMM).
 

docs/explanation/forensic-investigation.md

@@ -2,7 +2,7 @@
 title: "Forensic Investigation"
 description: How bmad-investigate treats every issue like a crime scene, grades evidence, and produces a structured case file engineers can act on
 sidebar:
-  order: 6
+  order: 10
 ---
 
 You hand `bmad-investigate` a crash log, a stack trace, or just a "this used to work, now it doesn't". The skill takes

docs/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Party Mode"
 description: Multi-agent collaboration - get all your AI agents in one conversation
 sidebar:
-  order: 7
+  order: 11
 ---
 
 Get all your AI agents in one conversation.

docs/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Preventing Agent Conflicts"
 description: How architecture prevents conflicts when multiple agents implement a system
 sidebar:
-  order: 4
+  order: 6
 ---
 
 When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.

docs/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Project Context"
 description: How project-context.md guides AI agents with your project's rules and preferences
 sidebar:
-  order: 7
+  order: 12
 ---
 
 The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.

docs/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Quick Dev"
 description: Reduce human-in-the-loop friction without giving up the checkpoints that protect output quality
 sidebar:
-  order: 2
+  order: 7
 ---
 
 Intent in, code changes out, with as few human-in-the-loop turns as possible — without sacrificing quality.

docs/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Why Solutioning Matters"
 description: Understanding why the solutioning phase is critical for multi-epic projects
 sidebar:
-  order: 3
+  order: 5
 ---
 
 

docs/fr/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Élicitation Avancée"
 description: Pousser le LLM à repenser son travail en utilisant des méthodes de raisonnement structurées
 sidebar:
-  order: 8
+  order: 3
 ---
 
 Faites repenser au LLM ce qu'il vient de générer. Vous choisissez une méthode de raisonnement, il l'applique à sa propre sortie, et vous décidez de conserver ou non les améliorations.

docs/fr/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Revue Contradictoire"
 description: Technique de raisonnement forcée qui empêche les revues paresseuses du style "ça à l'air bon"
 sidebar:
-  order: 7
+  order: 8
 ---
 
 Forcez une analyse plus approfondie en exigeant que des problèmes soient trouvés.

docs/fr/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "Checkpoint Preview"
 description: Revue assistée par LLM, avec intervention humaine, qui vous guide à travers une modification, de son objectif jusqu’aux détails
 sidebar:
-  order: 4
+  order: 7
 ---
 
 `bmad-checkpoint-preview` est un workflow de revue interactif, assisté par LLM, avec intervention humaine. Il vous guide à travers une modification de code — de l'intention et du contexte jusqu'aux détails — afin que vous puissiez prendre une décision éclairée sur la mise en production, la refonte ou l'approfondissement.

docs/fr/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "FAQ Projets Existants"
 description: Questions courantes sur l'utilisation de la méthode BMad sur des projets existants
 sidebar:
-  order: 11
+  order: 12
 ---
 Réponses rapides aux questions courantes sur l'utilisation de la méthode BMad (BMM) sur des projets existants.
 

docs/fr/explanation/forensic-investigation.md

@@ -2,7 +2,7 @@
 title: "Enquête de code"
 description: Comment bmad-investigate traite chaque problème comme une scène d'enquête, classe les preuves et produit un dossier structuré sur lequel les ingénieurs peuvent agir
 sidebar:
-  order: 6
+  order: 9
 ---
 
 Vous confiez à `bmad-investigate` un journal de plantage, une trace de pile, ou simplement un « ça marchait avant, plus

docs/fr/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Party Mode"
 description: Collaboration multi-agents - regroupez tous vos agents IA dans une seule conversation
 sidebar:
-  order: 9
+  order: 10
 ---
 
 Regroupez tous vos agents IA dans une seule conversation.

docs/fr/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Prévention des conflits entre agents"
 description: Comment l'architecture empêche les conflits lorsque plusieurs agents implémentent un système
 sidebar:
-  order: 6
+  order: 5
 ---
 
 Lorsque plusieurs agents IA implémentent différentes parties d'un système, ils peuvent prendre des décisions techniques contradictoires. La documentation d'architecture prévient cela en établissant des standards partagés.

docs/fr/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Contexte du Projet"
 description: Comment project-context.md guide les agents IA avec les règles et préférences de votre projet
 sidebar:
-  order: 10
+  order: 11
 ---
 
 Le fichier `project-context.md` est le guide d'implémentation de votre projet pour les agents IA. Similaire à une « constitution » dans d'autres systèmes de développement, il capture les règles, les patterns et les préférences qui garantissent une génération de code cohérente à travers tous les workflows.

docs/fr/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Quick Dev"
 description: Réduire la friction de l’interaction humaine sans renoncer aux points de contrôle qui protègent la qualité des résultats
 sidebar:
-  order: 3
+  order: 6
 ---
 
 Intention en entrée, modifications de code en sortie, avec aussi peu d'interactions humaines dans la boucle que possible — sans sacrifier la qualité.

docs/fr/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Pourquoi le Solutioning est Important"
 description: Comprendre pourquoi la phase de solutioning est critique pour les projets multi-epics
 sidebar:
-  order: 5
+  order: 4
 ---
 
 La Phase 3 (Solutioning) traduit le **quoi** construire (issu de la Planification) en **comment** le construire (conception technique). Cette phase évite les conflits entre agents dans les projets multi-epics en documentant les décisions architecturales avant le début de l'implémentation.

docs/how-to/expand-bmad-for-your-org.md

@@ -2,7 +2,7 @@
 title: 'How to Expand BMad for Your Organization'
 description: Six customization patterns that reshape BMad without forking — agent-wide rules, workflow conventions, external publishing, template swaps, agent roster changes, and advanced integration patterns
 sidebar:
-  order: 9
+  order: 11
 ---
 
 BMad's customization surface lets an organization reshape behavior without editing installed files or forking skills. This guide walks through six recipes that cover most enterprise needs.

docs/reference/commands.md

@@ -2,7 +2,7 @@
 title: Skills
 description: Reference for BMad skills — what they are, how they work, and where to find them.
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Skills are pre-built prompts that load agents, run workflows, or execute tasks inside your IDE. The BMad installer generates them from your installed modules at install time. If you later add, remove, or change modules, re-run the installer to keep skills in sync (see [Troubleshooting](#troubleshooting)).

docs/reference/core-tools.md

@@ -2,7 +2,7 @@
 title: Core Tools
 description: Reference for all built-in tasks and workflows available in every BMad installation without additional modules.
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Every BMad installation includes a set of core skills that can be used in conjunction with any anything you are doing — standalone tasks and workflows that work across all projects, all modules, and all phases. These are always available regardless of which optional modules you install.

docs/reference/modules.md

@@ -2,7 +2,7 @@
 title: Official Modules
 description: Add-on modules for building custom agents, creative intelligence, game development, and testing
 sidebar:
-  order: 4
+  order: 5
 ---
 
 BMad extends through official modules that you select during installation. These add-on modules provide specialized agents, workflows, and tasks for specific domains beyond the built-in core and BMM (Agile suite).

docs/reference/testing.md

@@ -2,7 +2,7 @@
 title: Testing Options
 description: Comparing the built-in QA workflow with the Test Architect (TEA) module for test automation.
 sidebar:
-  order: 5
+  order: 6
 ---
 
 BMad provides two testing paths: a built-in QA workflow for fast test generation and an installable Test Architect module for enterprise-grade test strategy.

docs/vi-vn/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "Khai thác nâng cao"
 description: Buộc LLM xem xét lại kết quả của nó bằng các phương pháp lập luận có cấu trúc
 sidebar:
-  order: 6
+  order: 4
 ---
 
 Buộc LLM xem xét lại những gì nó vừa tạo ra. Bạn chọn một phương pháp lập luận, nó áp dụng phương pháp đó lên chính output của mình, rồi bạn quyết định có giữ các cải tiến hay không.

docs/vi-vn/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "Đánh giá đối kháng"
 description: Kỹ thuật lập luận ép buộc giúp tránh các bản review lười kiểu "nhìn ổn"
 sidebar:
-  order: 5
+  order: 9
 ---
 
 Buộc quá trình phân tích đi sâu hơn bằng cách ép phải tìm ra vấn đề.

docs/vi-vn/explanation/analysis-phase.md

@@ -2,7 +2,7 @@
 title: "Giai đoạn phân tích: từ ý tưởng đến nền tảng"
 description: Động não, nghiên cứu, product brief và PRFAQ là gì, và nên dùng từng công cụ khi nào
 sidebar:
-  order: 1
+  order: 2
 ---
 
 Giai đoạn phân tích (giai đoạn 1) giúp bạn suy nghĩ rõ ràng về sản phẩm trước khi cam kết bắt tay vào xây dựng. Mọi công cụ trong giai đoạn này đều là tùy chọn, nhưng nếu bỏ qua toàn bộ phần phân tích thì PRD của bạn sẽ được dựng trên giả định thay vì hiểu biết thực chất.

docs/vi-vn/explanation/brainstorming.md

@@ -2,7 +2,7 @@
 title: "Động não ý tưởng"
 description: Các phiên sáng tạo tương tác sử dụng hơn 60 kỹ thuật khơi ý đã được kiểm chứng
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Mở khóa sự sáng tạo của bạn thông qua quá trình khám phá có hướng dẫn.

docs/vi-vn/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "Xem trước Checkpoint"
 description: Review có người trong vòng lặp với hỗ trợ của LLM, dẫn bạn đi qua thay đổi từ mục đích đến chi tiết
 sidebar:
-  order: 3
+  order: 8
 ---
 
 `bmad-checkpoint-preview` là một workflow review tương tác có người trong vòng lặp với hỗ trợ của LLM. Nó dẫn bạn đi qua một thay đổi mã nguồn, từ mục đích và bối cảnh đến các chi tiết quan trọng, để bạn có thể quyết định có nên phát hành, làm lại, hay đào sâu thêm.

docs/vi-vn/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "FAQ cho dự án đã tồn tại"
 description: Các câu hỏi phổ biến khi dùng BMad Method trên dự án đã tồn tại
 sidebar:
-  order: 8
+  order: 12
 ---
 
 Các câu trả lời nhanh cho những câu hỏi thường gặp khi làm việc với dự án đã tồn tại bằng BMad Method (BMM).

docs/vi-vn/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "Chế độ Party"
 description: Cộng tác đa agent - đưa tất cả agent AI vào cùng một cuộc trò chuyện
 sidebar:
-  order: 7
+  order: 10
 ---
 
 Đưa tất cả agent AI của bạn vào cùng một cuộc trò chuyện.

docs/vi-vn/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "Ngăn xung đột giữa các agent"
 description: Cách kiến trúc ngăn xung đột khi nhiều agent cùng triển khai một hệ thống
 sidebar:
-     order: 4
+     order: 6
 ---
 
 Khi nhiều agent AI cùng triển khai các phần khác nhau của hệ thống, chúng có thể đưa ra các quyết định kỹ thuật mâu thuẫn nhau. Tài liệu kiến trúc ngăn điều đó bằng cách thiết lập các tiêu chuẩn dùng chung.

docs/vi-vn/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "Bối cảnh dự án"
 description: Cách project-context.md định hướng các agent AI theo quy tắc và ưu tiên của dự án
 sidebar:
-  order: 7
+  order: 11
 ---
 
 Tệp `project-context.md` là kim chỉ nam cho việc triển khai của các agent AI trong dự án của bạn. Tương tự như một "bản hiến pháp" trong các hệ thống phát triển khác, nó ghi lại các quy tắc, pattern và ưu tiên giúp việc sinh mã được nhất quán trong mọi workflow.

docs/vi-vn/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "Phát triển nhanh"
 description: Giảm ma sát có người trong vòng lặp mà vẫn giữ các điểm kiểm tra bảo vệ chất lượng đầu ra
 sidebar:
-  order: 2
+  order: 7
 ---
 
 Đưa ý định vào, nhận thay đổi mã nguồn ra, với số lần cần con người nhảy vào giữa quy trình ít nhất có thể - nhưng không đánh đổi chất lượng.

docs/vi-vn/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "Vì sao solutioning quan trọng"
 description: Hiểu vì sao giai đoạn solutioning là tối quan trọng đối với dự án nhiều epic
 sidebar:
-  order: 3
+  order: 5
 ---
 
 Giai đoạn 3 (Solutioning) biến **xây gì** (từ giai đoạn Planning) thành **xây như thế nào** (thiết kế kỹ thuật). Giai đoạn này ngăn xung đột giữa các agent trong dự án nhiều epic bằng cách ghi lại các quyết định kiến trúc trước khi bắt đầu triển khai.

docs/vi-vn/how-to/established-projects.md

@@ -2,7 +2,7 @@
 title: "Dự án đã tồn tại"
 description: Cách sử dụng BMad Method trên các codebase hiện có
 sidebar:
-  order: 6
+  order: 7
 ---
 
 Sử dụng BMad Method hiệu quả khi làm việc với các dự án hiện có và codebase legacy.

docs/vi-vn/how-to/expand-bmad-for-your-org.md

@@ -2,7 +2,7 @@
 title: 'Cách mở rộng BMad cho tổ chức của bạn'
 description: Năm mẫu tùy chỉnh giúp thay đổi BMad mà không cần fork, gồm quy tắc ở cấp agent, quy ước workflow, xuất bản ra hệ thống ngoài, thay template và điều chỉnh danh sách agent
 sidebar:
-  order: 9
+  order: 11
 ---
 
 Bề mặt tùy chỉnh của BMad cho phép một tổ chức định hình lại hành vi mà không phải sửa file đã cài hay fork skill. Hướng dẫn này trình bày năm công thức mẫu (recipe) bao phủ phần lớn nhu cầu ở môi trường doanh nghiệp.

docs/vi-vn/how-to/get-answers-about-bmad.md

@@ -2,7 +2,7 @@
 title: "Cách tìm câu trả lời về BMad"
 description: Sử dụng LLM để tự nhanh chóng trả lời các câu hỏi về BMad
 sidebar:
-        order: 4
+        order: 5
 ---
 
 Hãy dùng trợ giúp tích hợp sẵn của BMad, tài liệu nguồn, hoặc cộng đồng để tìm câu trả lời, theo thứ tự từ nhanh nhất đến đầy đủ nhất.

docs/vi-vn/how-to/project-context.md

@@ -2,7 +2,7 @@
 title: "Quản lý bối cảnh dự án"
 description: Tạo và duy trì project-context.md để định hướng cho các agent AI
 sidebar:
-  order: 8
+  order: 9
 ---
 
 Sử dụng tệp `project-context.md` để đảm bảo các agent AI tuân theo ưu tiên kỹ thuật và quy tắc triển khai của dự án trong suốt mọi workflow. Để đảm bảo tệp này luôn sẵn có, bạn cũng có thể thêm dòng `Important project context and conventions are located in [path to project context]/project-context.md` vào file context của công cụ hoặc file always rules của bạn (như `AGENTS.md`).

docs/vi-vn/how-to/quick-fixes.md

@@ -2,7 +2,7 @@
 title: "Sửa nhanh"
 description: Cách thực hiện các sửa nhanh và thay đổi ad-hoc
 sidebar:
-  order: 5
+  order: 6
 ---
 
 Sử dụng **Quick Dev** cho sửa lỗi, refactor, hoặc các thay đổi nhỏ có mục tiêu rõ ràng mà không cần quy trình BMad Method đầy đủ.

docs/vi-vn/how-to/shard-large-documents.md

@@ -2,7 +2,7 @@
 title: "Hướng dẫn chia nhỏ tài liệu"
 description: Tách các tệp markdown lớn thành nhiều tệp nhỏ có tổ chức để quản lý context tốt hơn
 sidebar:
-       order: 9
+       order: 10
 ---
 
 Sử dụng công cụ `bmad-shard-doc` nếu bạn cần tách các tệp markdown lớn thành nhiều tệp nhỏ có tổ chức để quản lý context tốt hơn.

docs/vi-vn/how-to/upgrade-to-v6.md

@@ -2,7 +2,7 @@
 title: "Cách nâng cấp lên v6"
 description: Di chuyển từ BMad v4 sang v6
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Sử dụng trình cài đặt BMad để nâng cấp từ v4 lên v6, bao gồm khả năng tự động phát hiện bản cài đặt cũ và hỗ trợ di chuyển.

docs/vi-vn/reference/commands.md

@@ -2,7 +2,7 @@
 title: Các skill
 description: Tài liệu tham chiếu cho skill của BMad — skill là gì, hoạt động ra sao và tìm ở đâu.
 sidebar:
-  order: 3
+  order: 4
 ---
 
 Skills là các prompt dựng sẵn để nạp agent, chạy workflow hoặc thực thi task bên trong IDE của bạn. Trình cài đặt BMad sinh chúng từ các module bạn đã chọn tại thời điểm cài đặt. Nếu sau này bạn thêm, xóa hoặc thay đổi module, hãy chạy lại trình cài đặt để đồng bộ skills (xem [Khắc phục sự cố](#khắc-phục-sự-cố)).

docs/vi-vn/reference/core-tools.md

@@ -2,7 +2,7 @@
 title: Công cụ cốt lõi
 description: Tài liệu tham chiếu cho mọi tác vụ và quy trình tích hợp sẵn có trong mọi bản cài BMad mà không cần module bổ sung.
 sidebar:
-  order: 2
+  order: 3
 ---
 
 Mọi bản cài BMad đều bao gồm một tập skill cốt lõi có thể dùng cùng với bất cứ việc gì bạn đang làm, các tác vụ và quy trình độc lập hoạt động xuyên suốt mọi dự án, mọi module và mọi giai đoạn. Chúng luôn có sẵn bất kể bạn cài những module tùy chọn nào.

docs/vi-vn/reference/modules.md

@@ -2,7 +2,7 @@
 title: Các Module Chính Thức
 description: Các module bổ sung để xây agent tùy chỉnh, tăng cường sáng tạo, phát triển game và kiểm thử
 sidebar:
-  order: 4
+  order: 5
 ---
 
 BMad được mở rộng thông qua các module chính thức mà bạn chọn trong quá trình cài đặt. Những module bổ sung này cung cấp agent, workflow và task chuyên biệt cho các lĩnh vực cụ thể, vượt ra ngoài phần lõi tích hợp sẵn và BMM (Agile suite).

docs/vi-vn/reference/testing.md

@@ -2,7 +2,7 @@
 title: Các Tùy Chọn Kiểm Thử
 description: So sánh workflow QA tích hợp sẵn với module Test Architect (TEA) cho tự động hóa kiểm thử.
 sidebar:
-  order: 5
+  order: 6
 ---
 
 BMad cung cấp hai hướng kiểm thử: workflow QA tích hợp sẵn để tạo test nhanh và module Test Architect có thể cài thêm cho chiến lược kiểm thử c<><63>p doanh nghiệp.

docs/zh-cn/explanation/advanced-elicitation.md

@@ -2,7 +2,7 @@
 title: "高级启发"
 description: 使用结构化推理方法推动 LLM 重新思考其工作
 sidebar:
-  order: 6
+  order: 4
 ---
 
 高级启发（advanced elicitation）是“第二轮思考”机制：不是笼统地让模型“再来一次”，而是让它按指定推理方法重审自己的输出。

docs/zh-cn/explanation/adversarial-review.md

@@ -2,7 +2,7 @@
 title: "对抗性评审"
 description: 防止懒惰“看起来不错”评审的强制推理技术
 sidebar:
-  order: 5
+  order: 9
 ---
 
 对抗性评审（adversarial review）是一种“强制找问题”的评审方法：不允许直接“Looks good”，必须给出可验证发现，或者明确解释为什么没有发现。

docs/zh-cn/explanation/analysis-phase.md

@@ -2,7 +2,7 @@
 title: "分析阶段：从想法到基础"
 description: 头脑风暴、调研、产品简报和 PRFAQ 分别是什么——以及何时使用
 sidebar:
-  order: 1
+  order: 2
 ---
 
 分析阶段（Phase 1）帮助你在决定动手构建之前，把产品想清楚。这个阶段的每个工具都是可选的，但如果完全跳过分析，你的 PRD 就是建立在假设而非洞察之上。

docs/zh-cn/explanation/brainstorming.md

@@ -2,7 +2,7 @@
 title: "头脑风暴"
 description: 使用 60+ 种经过验证的构思技术进行互动创意会议
 sidebar:
-  order: 2
+  order: 3
 ---
 
 `bmad-brainstorming` 是一个“思考引导”工作流：它不替你拍脑袋给答案，而是用结构化提问把你的想法挖出来、扩展开、再收敛成可执行方向。

docs/zh-cn/explanation/checkpoint-preview.md

@@ -2,7 +2,7 @@
 title: "检查点预览"
 description: LLM 辅助的人机协作审查，引导你从目的到细节逐步走过一个变更
 sidebar:
-  order: 3
+  order: 8
 ---
 
 `bmad-checkpoint-preview` 是一个交互式的、LLM 辅助的人机协作审查工作流。它带你逐步走过一个代码变更——从目的和上下文到细节——让你能做出知情决策：是发布、返工，还是深入挖掘。

docs/zh-cn/explanation/established-projects-faq.md

@@ -2,7 +2,7 @@
 title: "既有项目常见问题"
 description: 关于在既有项目上使用 BMad Method 的常见问题
 sidebar:
-  order: 8
+  order: 12
 ---
 关于在 established projects（既有项目）中使用 BMad Method 的高频问题，快速说明如下。
 

docs/zh-cn/explanation/party-mode.md

@@ -2,7 +2,7 @@
 title: "派对模式"
 description: 多智能体协作——将所有 AI 智能体汇聚到一次对话中
 sidebar:
-  order: 7
+  order: 10
 ---
 
 `bmad-party-mode` 用于多角色协作讨论：把 PM、架构、开发、UX 等视角放到同一轮对话里，快速暴露分歧、对齐取舍。

docs/zh-cn/explanation/preventing-agent-conflicts.md

@@ -2,7 +2,7 @@
 title: "防止智能体冲突"
 description: 架构如何在多个智能体实现系统时防止冲突
 sidebar:
-  order: 4
+  order: 6
 ---
 
 当多个 AI 智能体并行实现系统时，冲突并不罕见。`architecture` 的作用，就是在 `solutioning` 阶段先统一关键决策，避免到 `epic/story` 实施时才暴露分歧。

docs/zh-cn/explanation/project-context.md

@@ -2,7 +2,7 @@
 title: "项目上下文"
 description: project-context.md 如何使用项目规则和偏好指导 AI 智能体
 sidebar:
-  order: 7
+  order: 11
 ---
 
 `project-context.md` 是面向 AI 智能体的项目级上下文文件。它的定位不是教程步骤，而是“实现约束说明”：把你的技术偏好、架构边界和工程约定沉淀成可复用规则，让不同工作流、不同智能体在多个 `story` 中做出一致决策。

docs/zh-cn/explanation/quick-dev.md

@@ -2,7 +2,7 @@
 title: "快速开发"
 description: 在不牺牲输出质量检查点的情况下减少人机交互的摩擦
 sidebar:
-  order: 2
+  order: 7
 ---
 
 `bmad-quick-dev` 的目标很直接：在保证质量边界的前提下，把“意图到代码”的人机往返轮次降到最低。

docs/zh-cn/explanation/why-solutioning-matters.md

@@ -2,7 +2,7 @@
 title: "为什么解决方案阶段很重要"
 description: 理解为什么解决方案阶段对于多史诗项目至关重要
 sidebar:
-  order: 3
+  order: 5
 ---
 
 Phase 3（solutioning）把“要做什么”（planning 产出）转成“如何实现”（`architecture` 设计 + 工作拆分）。它的核心价值是：在开发前先把跨 `epic` 的关键技术决策写清楚，让后续 `story` 实施保持一致。

docs/zh-cn/how-to/customize-bmad.md

@@ -2,7 +2,7 @@
 title: "如何自定义 BMad"
 description: 自定义智能体、工作流和模块，同时保持更新兼容性
 sidebar:
-  order: 7
+  order: 8
 ---
 
 使用 `.customize.yaml` 文件，自定义智能体（agent）的行为、角色（persona）和菜单，同时在后续更新中保留你的改动。

docs/zh-cn/how-to/established-projects.md

@@ -2,7 +2,7 @@
 title: "既有项目"
 description: 如何在现有代码库中使用 BMad Method
 sidebar:
-  order: 6
+  order: 7
 ---
 
 当你在现有项目或遗留代码库上工作时，本指南帮助你更稳妥地使用 BMad Method。

docs/zh-cn/how-to/expand-bmad-for-your-org.md

@@ -2,7 +2,7 @@
 title: "如何为组织扩展 BMad"
 description: 五个自定义方案，无需 fork 即可重塑 BMad——涵盖智能体全局规则、工作流约定、外部发布、模板替换和花名册变更
 sidebar:
-  order: 9
+  order: 11
 ---
 
 BMad 的自定义机制让组织无需编辑已安装文件或 fork 技能就能重塑行为。本指南介绍五个方案，覆盖大部分企业级需求。

docs/zh-cn/how-to/get-answers-about-bmad.md

@@ -2,7 +2,7 @@
 title: "如何获取关于 BMad 的答案"
 description: 使用 LLM 快速回答您自己的 BMad 问题
 sidebar:
-  order: 4
+  order: 5
 ---
 
 ## 先从 BMad-Help 开始

docs/zh-cn/how-to/project-context.md

@@ -2,7 +2,7 @@
 title: "管理项目上下文"
 description: 创建并维护 project-context.md 以指导 AI 智能体
 sidebar:
-  order: 8
+  order: 9
 ---
 
 使用 `project-context.md`，确保 AI 智能体在各类工作流中遵循项目的技术偏好与实现规则。

docs/zh-cn/how-to/quick-fixes.md

@@ -2,7 +2,7 @@
 title: "快速修复"
 description: 如何进行快速修复和临时更改
 sidebar:
-  order: 5
+  order: 6
 ---
 
 对于 bug 修复、重构或小范围改动，使用 **Quick Dev** 即可，不必走完整的 BMad Method。

docs/zh-cn/how-to/shard-large-documents.md

@@ -2,7 +2,7 @@
 title: "文档分片指南"
 description: 将大型 Markdown 文件拆分为更小的组织化文件，以更好地管理上下文
 sidebar:
-  order: 9
+  order: 10
 ---
 
 当单个 Markdown 文档过大、影响模型读取时，可使用 `bmad-shard-doc` 工作流把文档拆成按章节组织的小文件，降低上下文压力。

docs/zh-cn/how-to/upgrade-to-v6.md

@@ -2,7 +2,7 @@
 title: "如何升级到 v6"
 description: 从 BMad v4 迁移到 v6
 sidebar:
-  order: 3
+  order: 4
 ---
 
 使用 BMad 安装程序把 v4 升级到 v6。安装程序会自动识别旧安装，并提供迁移辅助，帮助你在已有项目中平滑过渡。

docs/zh-cn/reference/commands.md

@@ -2,7 +2,7 @@
 title: "技能（Skills）"
 description: BMad 技能参考：它们是什么、如何生成以及如何调用。
 sidebar:
-  order: 3
+  order: 4
 ---
 
 每次运行 `npx bmad-method install`，BMad 会基于你选择的模块生成一组 **skills**。你可以直接输入 skill 名称调用 workflow、任务、工具或智能体角色。

docs/zh-cn/reference/core-tools.md

@@ -2,7 +2,7 @@
 title: "核心工具"
 description: 每个 BMad 安装默认可用的任务与 workflow 参考。
 sidebar:
-  order: 2
+  order: 3
 ---
 
 核心工具是跨模块可复用的一组通用能力：不依赖特定业务项目，也不要求先进入某个智能体角色。只要安装了 BMad，你就可以直接调用它们。

docs/zh-cn/reference/modules.md

@@ -2,7 +2,7 @@
 title: "官方模块"
 description: BMad 可选模块参考：能力边界、适用场景与外部资源
 sidebar:
-  order: 4
+  order: 5
 ---
 
 BMad 通过可选模块扩展能力。你可以在安装时按需选择模块，为当前项目增加特定领域的 `agent`、`workflow` 与 `skill`。

docs/zh-cn/reference/testing.md

@@ -2,7 +2,7 @@
 title: "测试选项"
 description: 内置 QA workflow 与 TEA 模块对比：何时用哪个、各自边界是什么
 sidebar:
-  order: 5
+  order: 6
 ---
 
 BMad 有两条测试路径：

package.json

@@ -31,6 +31,7 @@
     "docs:fix-links": "node tools/fix-doc-links.js",
     "docs:preview": "astro preview --root website",
     "docs:validate-links": "node tools/validate-doc-links.js",
+    "docs:validate-sidebar": "node tools/validate-sidebar-order.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix:staged": "prettier --write",
@@ -39,7 +40,7 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
     "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",

tools/validate-sidebar-order.js

@@ -0,0 +1,388 @@
+/**
+ * Sidebar Order Validator
+ *
+ * Validates sidebar.order values in YAML frontmatter of markdown doc files.
+ *
+ * English docs — strict (errors):
+ *   - Duplicate sidebar.order values within the same directory
+ *   - Gaps in the ordering sequence
+ *   - sidebar: block present but missing or invalid order: field
+ *
+ * Translations — errors + warnings:
+ *   - Same structural rules as English (duplicates, gaps) — errors
+ *   - Order drift from English counterpart — warnings (non-blocking)
+ *
+ * Usage:
+ *   node tools/validate-sidebar-order.js
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DOCS_ROOT = path.resolve(__dirname, '../docs');
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const LOCALE_RE = /^[a-z]{2}(?:-[a-zA-Z0-9]+)*$/;
+const MAX_GAPS = 50;
+
+// ── Main ─────────────────────────────────────────────────────────────────
+
+/**
+ * Scan all docs, validate sidebar orders, and report errors/warnings.
+ * Exits 0 on success, 1 if any errors found.
+ */
+function main() {
+  if (!fs.existsSync(DOCS_ROOT)) {
+    console.error(`Error: docs directory not found at ${DOCS_ROOT}`);
+    process.exit(1);
+  }
+
+  const { languageDirs, englishSections } = classifyDocsDirs();
+  console.log(`\nValidating sidebar ordering in: ${DOCS_ROOT}\n`);
+  console.log(`English sections: ${englishSections.join(', ')}`);
+  console.log(`Translation languages: ${languageDirs.join(', ')}\n`);
+
+  const allErrors = [];
+  const allWarnings = [];
+  const englishOrderMaps = new Map();
+
+  for (const section of englishSections) {
+    const sectionDir = path.join(DOCS_ROOT, section);
+    if (!fs.existsSync(sectionDir)) continue;
+
+    console.log(`\nChecking English docs/${section}/`);
+    const { orderMap, issues } = checkDirectory(sectionDir);
+    englishOrderMaps.set(section, orderMap);
+
+    for (const issue of issues) {
+      allErrors.push(issue);
+      reportIssue(issue, '  ', `docs/${section}`);
+    }
+    if (issues.length === 0) {
+      console.log(`  [OK] docs/${section}/ — all orders valid`);
+    }
+  }
+
+  for (const lang of languageDirs) {
+    const langDir = path.join(DOCS_ROOT, lang);
+    const langSections = fs
+      .readdirSync(langDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('_'))
+      .map((e) => e.name);
+
+    console.log(`\nChecking ${lang}/ docs`);
+
+    for (const section of langSections) {
+      const sectionDir = path.join(langDir, section);
+      if (!fs.existsSync(sectionDir)) continue;
+
+      console.log(`  ${lang}/${section}/`);
+      const { issues } = checkDirectory(sectionDir);
+
+      for (const issue of issues) {
+        allErrors.push(issue);
+        reportIssue(issue, '    ', `${lang}/${section}`);
+      }
+      if (issues.length === 0) {
+        console.log(`    [OK] ${lang}/${section}/ — all orders valid`);
+      }
+    }
+
+    for (const w of checkTranslationDrift(lang, langSections, englishOrderMaps)) {
+      allWarnings.push(w);
+      const langDisplay = w.langOrder === null ? 'no order' : `order ${w.langOrder}`;
+      console.log(`  [WARN] ${rel(w.file)}: ${langDisplay} (English: ${w.englishOrder})`);
+    }
+  }
+
+  printSummary(allErrors, allWarnings);
+  process.exit(allErrors.length > 0 ? 1 : 0);
+}
+
+// ── Directory classification ─────────────────────────────────────────────
+
+/**
+ * Classify top-level docs/ subdirectories as language dirs or English sections.
+ * Language dirs match BCP 47 locale pattern; everything else is English.
+ * @returns {{ languageDirs: string[], englishSections: string[] }}
+ */
+function classifyDocsDirs() {
+  const dirs = fs.readdirSync(DOCS_ROOT, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('_'));
+
+  const languageDirs = [];
+  const englishSections = [];
+
+  for (const d of dirs) {
+    (LOCALE_RE.test(d.name) ? languageDirs : englishSections).push(d.name);
+  }
+
+  return { languageDirs, englishSections };
+}
+
+// ── Per-directory validation ─────────────────────────────────────────────
+
+/**
+ * Validate sidebar.order values for all markdown files in a directory.
+ * Detects duplicates, gaps in sequence, missing-order, and invalid-order fields.
+ * @param {string} dirPath - Absolute path to the directory to scan.
+ * @returns {{ orderMap: Map<number, string[]>, issues: object[] }}
+ */
+function checkDirectory(dirPath) {
+  const issues = [];
+  const orderMap = new Map();
+  const missingOrder = [];
+  const invalidOrder = [];
+
+  for (const entry of listMdEntries(dirPath)) {
+    const fullPath = path.join(dirPath, entry.name);
+    const result = extractSidebarOrder(fs.readFileSync(fullPath, 'utf-8'));
+
+    if (!result.hasSidebar) continue;
+    if (result.order === null) {
+      if (result.orderInvalid) {
+        invalidOrder.push(fullPath);
+      } else {
+        missingOrder.push(fullPath);
+      }
+      continue;
+    }
+
+    if (!orderMap.has(result.order)) orderMap.set(result.order, []);
+    orderMap.get(result.order).push(fullPath);
+  }
+
+  for (const file of missingOrder) {
+    issues.push({ level: 'error', type: 'missing-order', file, message: 'Has sidebar: block but no order: field' });
+  }
+
+  for (const file of invalidOrder) {
+    issues.push({ level: 'error', type: 'invalid-order', file, message: 'Invalid sidebar.order: must be a positive integer' });
+  }
+
+  for (const [order, files] of orderMap) {
+    if (files.length > 1) {
+      for (const file of files) {
+        issues.push({ level: 'error', type: 'duplicate-order', file, order, message: `Duplicate sidebar.order: ${order}` });
+      }
+    }
+  }
+
+  if (orderMap.size > 0) {
+    let max = -Infinity;
+    for (const k of orderMap.keys()) if (k > max) max = k;
+
+    let gapCount = 0;
+    for (let i = 1; i <= max; i++) {
+      if (!orderMap.has(i)) {
+        issues.push({
+          level: 'error',
+          type: 'gap',
+          directory: dirPath,
+          missing: i,
+          message: `Gap in sidebar order: missing position ${i}`,
+        });
+        gapCount++;
+        if (gapCount >= MAX_GAPS) {
+          issues.push({
+            level: 'error',
+            type: 'gap-truncated',
+            directory: dirPath,
+            message: `Too many gaps (stopped after ${MAX_GAPS}) — check for typos in sidebar.order values`,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { orderMap, issues };
+}
+
+// ── Cross-language drift ─────────────────────────────────────────────────
+
+/**
+ * Compare translated sidebar orders against English counterparts and warn on drift.
+ * Warns on numeric drift and on translation having sidebar but missing order.
+ * Files without an English counterpart are skipped silently.
+ * @param {string} lang - Language directory name (e.g. "cs", "zh-cn").
+ * @param {string[]} langSections - Section subdirectories within the language folder.
+ * @param {Map<string, Map<number, string[]>>} englishOrderMaps - English order maps keyed by section name.
+ * @returns {object[]} Drift warnings.
+ */
+function checkTranslationDrift(lang, langSections, englishOrderMaps) {
+  const warnings = [];
+
+  for (const section of langSections) {
+    const sectionDir = path.join(DOCS_ROOT, lang, section);
+    if (!fs.existsSync(sectionDir)) continue;
+
+    const englishMap = englishOrderMaps.get(section);
+    if (!englishMap) continue;
+
+    for (const entry of listMdEntries(sectionDir)) {
+      const langFile = path.join(sectionDir, entry.name);
+      const englishFile = path.join(DOCS_ROOT, section, entry.name);
+      if (!fs.existsSync(englishFile)) continue;
+
+      const langResult = extractSidebarOrder(fs.readFileSync(langFile, 'utf-8'));
+      const engResult = extractSidebarOrder(fs.readFileSync(englishFile, 'utf-8'));
+
+      const langHasOrder = typeof langResult.order === 'number';
+      const engHasOrder = typeof engResult.order === 'number';
+
+      if (langHasOrder && engHasOrder && langResult.order !== engResult.order) {
+        warnings.push({
+          level: 'warning',
+          type: 'order-drift',
+          file: langFile,
+          englishFile,
+          langOrder: langResult.order,
+          englishOrder: engResult.order,
+        });
+      } else if (engHasOrder && langResult.hasSidebar && !langHasOrder) {
+        warnings.push({
+          level: 'warning',
+          type: 'order-drift',
+          file: langFile,
+          englishFile,
+          langOrder: null,
+          englishOrder: engResult.order,
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
+
+// ── Output ───────────────────────────────────────────────────────────────
+
+/**
+ * Print a single validation issue to stdout.
+ * @param {object} issue - Issue object with type, file/order/message fields.
+ * @param {string} indent - Whitespace prefix for indentation.
+ * @param {string} ctxPath - Display path for gap issues (e.g. "docs/explanation").
+ */
+function reportIssue(issue, indent, ctxPath) {
+  switch (issue.type) {
+    case 'duplicate-order': {
+      console.log(`${indent}[ERROR] Duplicate order ${issue.order}: ${rel(issue.file)}`);
+      break;
+    }
+    case 'gap': {
+      console.log(`${indent}[ERROR] ${issue.message} in ${ctxPath}/`);
+      break;
+    }
+    case 'gap-truncated': {
+      console.log(`${indent}[ERROR] ${issue.message}`);
+      break;
+    }
+    case 'missing-order': {
+      console.log(`${indent}[ERROR] ${issue.message}: ${rel(issue.file)}`);
+      break;
+    }
+    case 'invalid-order': {
+      console.log(`${indent}[ERROR] ${issue.message}: ${rel(issue.file)}`);
+      break;
+    }
+  }
+}
+
+/**
+ * Print summary with error/warning counts and error type breakdown.
+ * @param {object[]} errors - All collected errors.
+ * @param {object[]} warnings - All collected warnings.
+ */
+function printSummary(errors, warnings) {
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log('\nSummary:');
+  console.log(`   Errors:   ${errors.length}`);
+  console.log(`   Warnings: ${warnings.length}`);
+
+  if (errors.length > 0) {
+    const breakdown = {};
+    for (const e of errors) breakdown[e.type] = (breakdown[e.type] || 0) + 1;
+    console.log('\n   Error breakdown:');
+    for (const [type, count] of Object.entries(breakdown)) console.log(`     ${type}: ${count}`);
+  }
+
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log('\n   All sidebar orders valid!');
+  }
+
+  console.log('');
+}
+
+// ── Leaf helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Convert an absolute path to one relative to DOCS_ROOT.
+ * @param {string} filePath - Absolute file path.
+ * @returns {string} Relative path from docs root.
+ */
+function rel(filePath) {
+  return path.relative(DOCS_ROOT, filePath);
+}
+
+/**
+ * Extract sidebar.order from YAML frontmatter.
+ * Handles block mapping (sidebar:\n  order: 5) and flow mapping (sidebar: { order: 5 }).
+ * Only matches order: as a direct child of sidebar:, not from nested blocks.
+ * @param {string} content - Full file contents of a markdown file.
+ * @returns {{ hasSidebar: boolean, order?: number|null, orderInvalid?: boolean }}
+ */
+function extractSidebarOrder(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return { hasSidebar: false };
+
+  const frontmatter = match[1];
+
+  // Flow mapping: sidebar: { order: 5 }
+  const inline = frontmatter.match(/^sidebar:[ \t]*\{[^}]*\border:[ \t]*(\d+)/m);
+  if (inline) return validateOrder(inline[1]);
+
+  // Block mapping: sidebar:\n  order: 5
+  if (!/^sidebar:[ \t]*$/m.test(frontmatter)) return { hasSidebar: false };
+
+  const lines = frontmatter.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^sidebar:[ \t]*$/.test(l));
+  let baseIndent = null;
+
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*$/.test(line)) continue;
+
+    const indent = line.search(/\S/);
+    if (indent === 0) break;
+    if (baseIndent === null) baseIndent = indent;
+    if (indent < baseIndent) break;
+    if (indent > baseIndent) continue;
+
+    const m = line.match(/^\s+order:[ \t]*(\d+)/);
+    if (m) return validateOrder(m[1]);
+  }
+
+  return { hasSidebar: true, order: null };
+}
+
+/**
+ * Validate a parsed order value and return a result object.
+ * Rejects non-finite values (Infinity, NaN) and non-positive values (0, negative).
+ * @param {string} raw - Raw digit string from frontmatter.
+ * @returns {{ hasSidebar: boolean, order?: number|null, orderInvalid?: boolean }}
+ */
+function validateOrder(raw) {
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1) return { hasSidebar: true, order: null, orderInvalid: true };
+  return { hasSidebar: true, order: n };
+}
+
+/**
+ * List markdown files (.md/.mdx) in a directory, excluding subdirectories.
+ * @param {string} dirPath - Absolute path to the directory.
+ * @returns {fs.Dirent[]} Dirent entries for markdown files.
+ */
+function listMdEntries(dirPath) {
+  return fs.readdirSync(dirPath, { withFileTypes: true }).filter((e) => e.isFile() && (e.name.endsWith('.md') || e.name.endsWith('.mdx')));
+}
+
+main();