🤖 fix: add mdbook linkcheck to static-check, rename docs targets

Makefile

@@ -49,7 +49,7 @@ include fmt.mk
 .PHONY: test test-unit test-integration test-watch test-coverage test-e2e smoke-test
 .PHONY: dist dist-mac dist-win dist-linux
 .PHONY: vscode-ext vscode-ext-install
-.PHONY: docs docs-build docs-watch
+.PHONY: docs docs-server docs-watch check-docs-links
 .PHONY: storybook storybook-build test-storybook chromatic
 .PHONY: benchmark-terminal
 .PHONY: ensure-deps rebuild-native
@@ -213,7 +213,7 @@ build/icon.png: docs/img/logo.webp scripts/generate-icons.ts
 	@bun scripts/generate-icons.ts png
 
 ## Quality checks (can run in parallel)
-static-check: lint typecheck fmt-check check-eager-imports check-bench-agent ## Run all static checks (includes startup performance checks)
+static-check: lint typecheck fmt-check check-eager-imports check-bench-agent check-docs-links ## Run all static checks (includes startup performance checks)
 
 check-bench-agent: ## Verify terminal-bench agent configuration and imports
 	@./scripts/check-bench-agent.sh
@@ -337,15 +337,24 @@ vscode-ext-install: ## Build and install VS Code extension locally
 	@$(MAKE) -C vscode install
 
 ## Documentation
-docs: ## Serve documentation locally
-	@./scripts/docs.sh
-
-docs-build: ## Build documentation
+docs: ## Build documentation
 	@./scripts/docs_build.sh
 
+docs-server: ## Serve documentation locally (opens browser)
+	@./scripts/docs.sh
+
 docs-watch: ## Watch and rebuild documentation
 	@cd docs && mdbook watch
 
+check-docs-links: ## Check documentation for broken links (requires mdbook tools via nix)
+	@if command -v mdbook >/dev/null 2>&1 && command -v mdbook-linkcheck >/dev/null 2>&1; then \
+		$(MAKE) docs && \
+		echo "🔗 Checking documentation links..." && \
+		cd docs && mdbook-linkcheck --standalone .; \
+	else \
+		echo "⏭️  Skipping docs link check (mdbook tools not installed - use 'nix develop' for full checks)"; \
+	fi
+
 ## Storybook
 storybook: node_modules/.installed ## Start Storybook development server
 	$(check_node_version)

docs/AGENTS.md

@@ -49,6 +49,7 @@ gh pr view <number> --json mergeable,mergeStateStatus | jq '.'
 - Package manager: bun only. Use `bun install`, `bun add`, `bun run` (which proxies to Make when relevant). Run `bun install` if modules/types go missing.
 - Makefile is source of truth (new commands land there, not `package.json`).
 - Primary targets: `make dev|start|build|lint|lint-fix|fmt|fmt-check|typecheck|test|test-integration|clean|help`.
+- Full `static-check` includes docs link checking which requires mdbook tools. Use `nix develop` to get them, or the check gracefully skips if unavailable.
 
 ## Refactoring & Runtime Etiquette
 

docs/README.md

@@ -5,11 +5,11 @@ This directory contains the source for mux documentation built with [mdbook](htt
 ## Quick Start
 
 ```bash
-# Serve docs with hot reload (opens in browser)
+# Build docs
 bun docs
 
-# Build docs
-bun docs:build
+# Serve docs with hot reload (opens in browser)
+bun docs:serve
 
 # Watch for changes (no server)
 bun docs:watch

flake.nix

@@ -134,6 +134,7 @@
             mdbook
             mdbook-mermaid
             mdbook-linkcheck
+            mdbook-pagetoc
 
             # Terminal bench
             uv

package.json

@@ -37,7 +37,7 @@
     "dist:win": "make dist-win",
     "dist:linux": "make dist-linux",
     "docs": "make docs",
-    "docs:build": "make docs-build",
+    "docs:serve": "make docs-server",
     "docs:watch": "make docs-watch",
     "storybook": "make storybook",
     "storybook:build": "make storybook-build",