.markdownlint-cli2.jsonc

@@ -0,0 +1,23 @@
+// .markdownlint-cli2.jsonc
+{
+  "config": {
+    // Disable all rules that conflict with Prettier (23 rules — line-length, list-indent,
+    // blanks-around-fences, emphasis-style, etc.)
+    "extends": "markdownlint/style/prettier",
+
+    // Content rules to KEEP:
+    "MD001": true, // heading-increment: no skipping h1→h3
+    "MD024": true, // no-duplicate-heading
+    "MD040": true, // fenced-code-language: all fences must declare a language
+    "MD031": true, // blanks-around-fences (re-enabled — see Pitfall 4 in RESEARCH.md)
+    "MD051": true, // link-fragments: broken anchor links
+    "MD052": true, // reference-links-images: undefined link references
+
+    // Rules DISABLED (Prettier owns these OR they fire on non-author-controlled files):
+    "MD041": false, // first-line-h1: CLAUDE.md legitimately starts with ## Project
+    "MD034": false, // no-bare-urls: CLAUDE.md version table uses pkg@version syntax
+    "MD036": false // no-emphasis-as-heading: docs/API.md uses **Response 200** as label
+  },
+  "globs": ["docs/**/*.md", "*.md", "apps/**/*.md"],
+  "ignores": [".planning/**", "node_modules/**", "**/node_modules/**", ".pnpm-store/**"]
+}

package.json

@@ -12,7 +12,8 @@
     "lint": "pnpm -r --if-present lint",
     "typecheck": "pnpm -r typecheck",
     "format": "prettier --write .",
-    "format:check": "prettier --check ."
+    "format:check": "prettier --check .",
+    "md:lint": "markdownlint-cli2"
   },
   "devDependencies": {
     "@eslint/js": "9.39.4",
@@ -20,6 +21,7 @@
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-react": "7.37.5",
     "eslint-plugin-react-hooks": "7.1.1",
+    "markdownlint-cli2": "0.22.1",
     "prettier": "3.8.4",
     "typescript-eslint": "8.61.0"
   }