docs: align onboarding and harden docs checks

Makefile

@@ -1,6 +1,6 @@
 # Makefile for Vibe Coding Guide
 
-.PHONY: help lint check-links check-details check-metadata check-ai-citation build test clean
+.PHONY: help lint check-links check-details check-doc-structure check-metadata check-ai-citation build test clean
 
 help:
 	@echo "Makefile for Vibe Coding Guide"
@@ -10,6 +10,7 @@ help:
 	@echo "  lint     - Lint all markdown files"
 	@echo "  check-links - Check local markdown links and anchors"
 	@echo "  check-details - Check markdown details/summary blocks"
+	@echo "  check-doc-structure - Check docs README anchors, order and duplicate anchors"
 	@echo "  check-metadata - Check metadata paths and anchors"
 	@echo "  check-ai-citation - Check llms and AI citation paths and anchors"
 	@echo "  build    - Verify knowledge base has no build step"
@@ -17,10 +18,12 @@ help:
 	@echo "  clean    - Remove ignored generated caches"
 	@echo ""
 
-lint:
+node_modules/.bin/markdownlint: package.json package-lock.json
+	@npm ci
+
+lint: node_modules/.bin/markdownlint
 	@echo "Linting markdown files..."
-	@npm install -g markdownlint-cli
-	@markdownlint --config .github/lint_config.json --ignore .history --ignore tools/external '**/*.md'
+	@npm run lint:md
 
 check-links:
 	@echo "Checking local markdown links and anchors..."
@@ -30,6 +33,10 @@ check-details:
 	@echo "Checking markdown details/summary blocks..."
 	@python3 scripts/check-markdown-details.py
 
+check-doc-structure:
+	@echo "Checking docs README structure..."
+	@python3 scripts/check-doc-structure.py
+
 check-metadata:
 	@echo "Checking metadata paths and anchors..."
 	@python3 scripts/check-metadata.py
@@ -41,7 +48,7 @@ check-ai-citation:
 build:
 	@echo "No build step: this repository is a documentation and knowledge-base project."
 
-test: lint check-links check-details check-metadata check-ai-citation
+test: lint check-links check-details check-doc-structure check-metadata check-ai-citation
 	@echo "Quality gates complete."
 
 clean: