migrate docs to mintlify (#913)

<img width="1595" height="1186" alt="image"
src="https://github.com/user-attachments/assets/debb0c65-72ba-427d-9ebe-62c7be61c136"
/>

---------

Co-authored-by: Ammar <ammar+ai@ammar.io>

Author: mattvollmer

.github/workflows/docs.yml

@@ -0,0 +1,2 @@
+# Mintlify docs that use JSX comments which prettier mangles
+docs/system-prompt.md

.prettierignore

@@ -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-server docs-watch check-docs-links
+.PHONY: docs-server
 .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 check-docs-links ## Run all static checks (includes startup performance checks)
+static-check: lint typecheck fmt-check check-eager-imports check-bench-agent ## Run all static checks
 
 check-bench-agent: ## Verify terminal-bench agent configuration and imports
 	@./scripts/check-bench-agent.sh
@@ -337,23 +337,8 @@ vscode-ext-install: ## Build and install VS Code extension locally
 	@$(MAKE) -C vscode install
 
 ## 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
+docs-server: node_modules/.installed ## Serve documentation locally (Mintlify dev server)
+	@cd docs && npx mintlify dev
 
 ## Storybook
 storybook: node_modules/.installed ## Start Storybook development server

Makefile

@@ -1,4 +1,7 @@
-# AGENT INSTRUCTIONS
+---
+title: AGENTS.md
+description: Agent instructions for AI assistants working on the mux codebase
+---
 
 **Prime directive:** keep edits minimal and token-efficient—say only what conveys actionable signal.
 
@@ -153,7 +156,7 @@ Avoid mock-heavy tests that verify implementation details rather than behavior.
 - Prefer fixes that simplify existing code; such simplifications often do not need new tests.
 - When adding complexity, add or extend tests. If coverage requires new infrastructure, propose the harness and then add the tests there.
 
-<!-- IMPORTANT: Do not rename these Mode headings; the parser extracts them verbatim. -->
+{/_ IMPORTANT: Do not rename these Mode headings; the parser extracts them verbatim. _/}
 
 ## Mode: Exec
 

docs/AGENTS.md

@@ -1,4 +1,7 @@
-# Agentic Git Identity
+---
+title: Agentic Git Identity
+description: Configure a separate Git identity for AI-generated commits
+---
 
 Configure mux to use a separate Git identity for AI-generated commits, making it easy to distinguish between human and AI contributions. Reasons to use a separate identity include:
 
@@ -23,7 +26,7 @@ Create a separate GitHub account for your agent:
 2. Use a distinctive username (e.g., `yourname-agent`, `yourname-ai`)
 3. Use a separate email (GitHub allows plus-addressing: `yourname+ai@example.com`)
 
-> **Note**: This is optional but recommended. You can also use your main account with a different email/name.
+<Info>This is optional but recommended. You can also use your main account with a different email/name.</Info>
 
 ## Step 2: Generate Classic GitHub Token
 
@@ -54,7 +57,7 @@ Add the Git identity environment variables as [Project Secrets](./project-secret
 
 These environment variables will be automatically injected when the agent runs Git commands in that project.
 
-> **Note**: If you need the agent identity outside of mux, you can alternatively set these as global environment variables in your shell configuration (`~/.zshrc`, `~/.bashrc`, etc.)
+<Info>If you need the agent identity outside of mux, you can alternatively set these as global environment variables in your shell configuration (`~/.zshrc`, `~/.bashrc`, etc.)</Info>
 
 ## Step 4: Configure GitHub Authentication
 
@@ -98,4 +101,4 @@ git config --global credential.helper ""
 git config --global --add credential.helper '!gh auth git-credential'
 ```
 
-⚠️ **Warning**: The "replace all" approach will disable platform keychain helpers and may break Git authentication for non-GitHub remotes (GitLab, Bitbucket, etc.).
+<Warning>The "replace all" approach will disable platform keychain helpers and may break Git authentication for non-GitHub remotes (GitLab, Bitbucket, etc.).</Warning>

docs/SUMMARY.md

@@ -1,11 +1,14 @@
-# Terminal Benchmarking
+---
+title: Terminal Benchmarking
+description: Run Terminal-Bench benchmarks with the mux adapter
+---
 
 mux ships with a headless adapter for [Terminal-Bench](https://www.tbench.ai/). The adapter runs the Electron backend without opening a window and exercises it through the same IPC paths we use in integration tests. This page documents how to launch benchmarks from the repository tree.
 
 ## Prerequisites
 
 - Docker must be installed and running. Terminal-Bench executes each task inside a dedicated Docker container.
-- `uv` is available in the nix `devShell` (provided via `flake.nix`), or install it manually from <https://docs.astral.sh/uv/>.
+- `uv` is available in the nix `devShell` (provided via `flake.nix`), or install it manually from [docs.astral.sh/uv](https://docs.astral.sh/uv/).
 - Standard provider API keys (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`) should be exported so mux can stream responses.
 
 Optional environment overrides:

docs/agentic-git-identity.md

@@ -1,4 +1,7 @@
-# Command Line Interface
+---
+title: Command Line Interface
+description: Run one-off agent tasks from the command line with mux run
+---
 
 Mux provides a CLI for running one-off agent tasks without the desktop app. Unlike the interactive desktop experience, `mux run` executes a single request to completion and exits.
 

docs/benchmarking.md

@@ -1,4 +1,7 @@
-# Context Management
+---
+title: Context Management
+description: Commands for managing conversation history and token usage
+---
 
 Commands for managing conversation history length and token usage.
 
@@ -149,7 +152,7 @@ Remove oldest 50% of messages.
 
 ### OpenAI Responses API Limitation
 
-⚠️ **`/truncate` does not work with OpenAI models** due to the Responses API architecture:
+<Warning>`/truncate` does not work with OpenAI models due to the Responses API architecture:</Warning>
 
 - OpenAI's Responses API stores conversation state server-side
 - Manual message deletion via `/truncate` doesn't affect the server-side state