🤖 fix: mintlify migration cleanup (#914)

Follow-up to #913 - cleanup after Mintlify migration.

## Changes

- **Add docs link check to CI**: `make check-docs-links` runs `mintlify
broken-links` as part of `static-check`
- **Update docs/README.md**: Replace mdbook instructions with Mintlify
workflow
- **Update docs/AGENTS.md**: Reference `docs.json` instead of
`SUMMARY.md`, update tooling section
- **Fix .html links**: Remove `.html` suffix from all mux.coder.com
links (Mintlify uses clean URLs)
  - README.md: 8 links fixed
  - src/browser/utils/commands/sources.ts: keybinds link fixed

_Generated with mux_

Author: ammar-agent

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-server
+.PHONY: docs-server 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
+static-check: lint typecheck fmt-check check-eager-imports check-bench-agent check-docs-links ## Run all static checks
 
 check-bench-agent: ## Verify terminal-bench agent configuration and imports
 	@./scripts/check-bench-agent.sh
@@ -340,6 +340,10 @@ vscode-ext-install: ## Build and install VS Code extension locally
 docs-server: node_modules/.installed ## Serve documentation locally (Mintlify dev server)
 	@cd docs && npx mintlify dev
 
+check-docs-links: ## Check documentation for broken links
+	@echo "🔗 Checking documentation links..."
+	@cd docs && npx mintlify broken-links
+
 ## Storybook
 storybook: node_modules/.installed ## Start Storybook development server
 	$(check_node_version)

README.md

@@ -35,19 +35,19 @@ Here are some specific use cases we enable:
 
 ## Features
 
-- **Isolated workspaces** with central view on git divergence ([docs](https://mux.coder.com/runtime.html))
-  - **[Local](https://mux.coder.com/runtime/local.html)**: run directly in your project directory
-  - **[Worktree](https://mux.coder.com/runtime/worktree.html)**: git worktrees on your local machine
-  - **[SSH](https://mux.coder.com/runtime/ssh.html)**: remote execution on a server over SSH
+- **Isolated workspaces** with central view on git divergence ([docs](https://mux.coder.com/runtime))
+  - **[Local](https://mux.coder.com/runtime/local)**: run directly in your project directory
+  - **[Worktree](https://mux.coder.com/runtime/worktree)**: git worktrees on your local machine
+  - **[SSH](https://mux.coder.com/runtime/ssh)**: remote execution on a server over SSH
 - **Multi-model** (`sonnet-4-*`, `grok-*`, `gpt-5-*`, `opus-4-*`)
-  - Ollama supported for local LLMs ([docs](https://mux.coder.com/models.html#ollama-local))
-  - OpenRouter supported for long-tail of LLMs ([docs](https://mux.coder.com/models.html#openrouter-cloud))
-- **VS Code Extension**: Jump into mux workspaces directly from VS Code ([docs](https://mux.coder.com/vscode-extension.html))
+  - Ollama supported for local LLMs ([docs](https://mux.coder.com/models#ollama-local))
+  - OpenRouter supported for long-tail of LLMs ([docs](https://mux.coder.com/models#openrouter-cloud))
+- **VS Code Extension**: Jump into mux workspaces directly from VS Code ([docs](https://mux.coder.com/vscode-extension))
 - Supporting UI and keybinds for efficiently managing a suite of agents
 - Rich markdown outputs (mermaid diagrams, LaTeX, etc.)
 
 mux has a custom agent loop but much of the core UX is inspired by Claude Code. You'll find familiar features like Plan/Exec mode, vim inputs, `/compact` and new ones
-like [opportunistic compaction](https://mux.coder.com/context-management.html) and [mode prompts](https://mux.coder.com/instruction-files.html#mode-prompts).
+like [opportunistic compaction](https://mux.coder.com/context-management) and [mode prompts](https://mux.coder.com/instruction-files#mode-prompts).
 
 **[Read the full documentation →](https://mux.coder.com)**
 
@@ -60,7 +60,7 @@ like [opportunistic compaction](https://mux.coder.com/context-management.html) a
 Download pre-built binaries from [the releases page](https://github.com/coder/mux/releases) for
 macOS and Linux.
 
-[More on installation →](https://mux.coder.com/install.html)
+[More on installation →](https://mux.coder.com/install)
 
 ## Screenshots
 

docs/AGENTS.md

@@ -36,7 +36,7 @@ gh pr view <number> --json mergeable,mergeStateStatus | jq '.'
 
 ## Documentation Rules
 
-- No free-floating Markdown. User docs live in `docs/` (read `docs/README.md`, update `docs/SUMMARY.md`, use standard Markdown + mermaid). Developer/test notes belong inline as comments.
+- No free-floating Markdown. User docs live in `docs/` (read `docs/README.md`, add pages to `docs.json` navigation, use standard Markdown + mermaid). Developer/test notes belong inline as comments.
 - For planning artifacts, use the `propose_plan` tool or inline comments instead of ad-hoc docs.
 - Do not add new root-level docs without explicit request; during feature work rely on code + tests + inline comments.
 - Test documentation stays inside the relevant test file as commentary explaining setup/edge cases.
@@ -52,7 +52,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.
+- Full `static-check` includes docs link checking via `mintlify broken-links`.
 
 ## Refactoring & Runtime Etiquette
 

docs/README.md

@@ -1,66 +1,53 @@
 # mux Documentation
 
-This directory contains the source for mux documentation built with [mdbook](https://rust-lang.github.io/mdBook/).
+This directory contains the source for mux documentation hosted on [Mintlify](https://mintlify.com/).
 
-## Quick Start
+**Live docs:** https://mux.coder.com
 
-```bash
-# Build docs
-bun docs
-
-# Serve docs with hot reload (opens in browser)
-bun docs:serve
+## Local Development
 
-# Watch for changes (no server)
-bun docs:watch
+```bash
+# Serve docs locally with hot reload
+make docs-server
 ```
 
 ## Features
 
 - ✅ **Mermaid diagrams** - Add diagrams with ` ```mermaid ` code blocks
-- ✅ **Link checking** - Automatically validates all links during build
-- ✅ **GitHub Pages** - Auto-deploys to https://mux.io on push to main
+- ✅ **Link checking** - CI validates all internal links via `mintlify broken-links`
+- ✅ **Auto-deploy** - Mintlify automatically deploys on push to main
 
 ## Structure
 
 ```
 docs/
-├── book.toml        # mdbook configuration
-├── src/
-│   ├── SUMMARY.md   # Table of contents
-│   └── *.md         # Documentation pages
-└── book/            # Build output (gitignored)
+├── docs.json        # Mintlify configuration (navigation, theme, etc.)
+├── custom.css       # Custom styling
+├── img/             # Images and logos
+└── *.md             # Documentation pages
 ```
 
 ## Adding Content
 
-1. Create a new `.md` file in `src/`
-2. Add it to `src/SUMMARY.md` to make it appear in the sidebar
-3. Use standard markdown + mermaid diagrams
+1. Create a new `.md` file in `docs/`
+2. Add frontmatter with title and description
+3. Add the page to `docs.json` navigation
+4. Use standard markdown + mermaid diagrams
+
+Example frontmatter:
+
+```markdown
+---
+title: Page Title
+description: Brief description for SEO
+---
+```
 
 ## Writing Guidelines
 
 See [STYLE.md](./STYLE.md) for documentation writing guidelines.
 
 ## CI/CD
 
-Docs are automatically built and deployed via `.github/workflows/docs.yml` when:
-
-- Changes are pushed to `main` branch in the `docs/` directory
-- Workflow is manually triggered
-
-## Requirements
-
-The following tools are needed to build locally:
-
-- `mdbook` (v0.4.52+)
-- `mdbook-mermaid` (v0.16.0+)
-- `mdbook-linkcheck` (v0.7.7+)
-- `mdbook-pagetoc` (v0.2.1+)
-
-Install via cargo:
-
-```bash
-cargo install mdbook mdbook-mermaid mdbook-linkcheck mdbook-pagetoc
-mdbook-mermaid install docs
-```
+- **Link checking**: CI runs `mintlify broken-links` on every PR
+- **Deployment**: Mintlify GitHub app auto-deploys on push to main

src/browser/utils/commands/sources.ts

@@ -483,7 +483,7 @@ export function buildCoreSources(p: BuildSourcesParams): Array<() => CommandActi
       section: section.help,
       run: () => {
         try {
-          window.open("https://mux.coder.com/keybinds.html", "_blank");
+          window.open("https://mux.coder.com/keybinds", "_blank");
         } catch {
           /* ignore */
         }