CI: add markdownlint + docs-check wrapper; extend link check scope

.github/workflows/ci.yml

@@ -88,9 +88,9 @@ jobs:
           make frontend-build
 
 
-      - name: Docs link check
+      - name: Docs quality gates (lint + relative link check)
         run: |
-          python scripts/check_markdown_links.py
+          make docs-check
 
       - name: Upload coverage artifacts
         if: always()

.markdownlint-cli2.yaml

@@ -0,0 +1,23 @@
+# markdownlint-cli2 config
+# Keep the ruleset intentionally tiny to avoid noisy churn.
+
+config:
+  default: false
+  MD009: true   # no trailing spaces
+  MD010: true   # no hard tabs
+  MD012: true   # no multiple consecutive blank lines
+  MD047: true   # single trailing newline
+
+globs:
+  - "**/*.md"
+
+ignores:
+  - "**/node_modules/**"
+  - "**/.next/**"
+  - "**/dist/**"
+  - "**/build/**"
+  - "**/.venv/**"
+  - "**/__pycache__/**"
+  - "**/.pytest_cache/**"
+  - "**/.mypy_cache/**"
+  - "**/coverage/**"

Makefile

@@ -124,6 +124,13 @@ backend-templates-sync: ## Sync templates to existing gateway agents (usage: mak
 check: lint typecheck backend-coverage frontend-test build ## Run lint + typecheck + tests + coverage + build
 
 
+.PHONY: docs-lint
+docs-lint: frontend-tooling ## Lint markdown files (tiny ruleset; avoids noisy churn)
+	$(NODE_WRAP) npx markdownlint-cli2@0.15.0 --config .markdownlint-cli2.yaml "**/*.md"
+
 .PHONY: docs-link-check
 docs-link-check: ## Check for broken relative links in markdown docs
 	python scripts/check_markdown_links.py
+
+.PHONY: docs-check
+docs-check: docs-lint docs-link-check ## Run all docs quality gates

backend/templates/AUTONOMY.md

@@ -31,4 +31,3 @@ This file defines how you decide when to act vs when to ask.
 ## Collaboration defaults
 - If you are idle/unassigned: pick 1 in-progress/review task owned by someone else and leave a concrete, helpful comment (context gaps, quality risks, validation ideas, edge cases, handoff clarity).
 - If you notice duplicate work: flag it and propose a merge/split so there is one clear DRI per deliverable.
-

backend/templates/SELF.md

@@ -66,4 +66,3 @@ Notes:
 | Date | Change |
 |------|--------|
 | | |
-

docs/03-development.md

@@ -0,0 +1,3 @@
+# Development workflow
+
+Placeholder: see root `README.md` for current setup steps.

docs/README.md

@@ -0,0 +1,18 @@
+# Mission Control docs
+
+This folder is the starting point for Mission Control documentation.
+
+## Sections
+
+- [Development workflow](./03-development.md)
+- [Testing guide](./testing/README.md)
+- [Coverage policy](./coverage-policy.md)
+- [Deployment](./deployment/README.md)
+- [Production notes](./production/README.md)
+- [Troubleshooting](./troubleshooting/README.md)
+- [Gateway WebSocket protocol](./openclaw_gateway_ws.md)
+
+## Status
+
+These pages are minimal placeholders so repo-relative links stay healthy. The actual docs
+information architecture will be defined in the Docs overhaul tasks.

docs/coverage-policy.md

@@ -0,0 +1,3 @@
+# Coverage policy
+
+Placeholder: coverage policy is currently documented in the root `Makefile` (`backend-coverage`).

docs/deployment/README.md

@@ -0,0 +1,3 @@
+# Deployment guide
+
+Placeholder.

docs/openclaw_gateway_ws.md

@@ -0,0 +1,3 @@
+# Gateway WebSocket protocol
+
+Placeholder.

docs/production/README.md

@@ -0,0 +1,3 @@
+# Production notes
+
+Placeholder.

docs/testing/README.md

@@ -0,0 +1,3 @@
+# Testing guide
+
+Placeholder: see root `README.md` and `CONTRIBUTING.md` for current commands.

docs/troubleshooting/README.md

@@ -0,0 +1,3 @@
+# Troubleshooting
+
+Placeholder.

scripts/check_markdown_links.py

@@ -27,18 +27,27 @@ LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
 def iter_md_files(root: Path) -> list[Path]:
     """Return markdown files to check.
 
-    Policy (initial): check only `docs/**/*.md`.
+    Policy:
+    - Always check root contributor-facing markdown (`README.md`, `CONTRIBUTING.md`).
+    - If `docs/` exists, also check `docs/**/*.md`.
 
     Rationale:
-    - Root `README.md` / `CONTRIBUTING.md` may temporarily contain legacy links
-      during docs re-org. Once docs + README are stabilized, we can expand this
-      to include root markdown files.
+    - We want fast feedback on broken *relative* links in the most important entrypoints.
+    - We intentionally do **not** crawl external URLs.
     """
 
+    files: list[Path] = []
+
+    for p in (root / "README.md", root / "CONTRIBUTING.md"):
+        if p.exists():
+            files.append(p)
+
     docs = root / "docs"
-    if not docs.exists():
-        return []
-    return sorted(docs.rglob("*.md"))
+    if docs.exists():
+        files.extend(sorted(docs.rglob("*.md")))
+
+    # de-dupe + stable order
+    return sorted({p.resolve() for p in files})
 
 
 def normalize_target(raw: str) -> str | None: