migrate docs to mintlify

docs/AGENTS.md

@@ -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/agentic-git-identity.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/benchmarking.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/cli.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/context-management.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

docs/custom.css

@@ -0,0 +1,82 @@
+/* Override logo height */
+.nav-logo {
+  height: 2.4rem !important;
+}
+
+/* Target logo images specifically */
+img[src*="/img/light.svg"],
+img[src*="/img/dark.svg"] {
+  height: 2.4rem !important;
+}
+
+/* Override Tailwind h-6 class specifically for logo */
+.nav-logo.h-6,
+.h-6[src*="/img/"] {
+  height: 2.4rem !important;
+}
+
+/* More specific targeting for Mintlify logo classes */
+.w-auto.relative.object-contain.hidden.dark\:block.px-1.h-6.max-w-48,
+.w-auto.relative.object-contain.block.dark\:hidden.px-1.h-6.max-w-48 {
+  height: 2.4rem !important;
+}
+
+/* Override link colors to match grayscale theme */
+a,
+.prose a,
+main a,
+[data-testid="main-content"] a {
+  color: #999 !important;
+}
+
+a:hover,
+.prose a:hover,
+main a:hover,
+[data-testid="main-content"] a:hover {
+  color: #FFF !important;
+}
+
+/* Apply styling to all images in docs */
+main img,
+.prose img,
+[data-testid="main-content"] img,
+.content img {
+  margin: 24px 0 !important;
+  border-radius: 8px !important;
+}
+
+/* Apply same styling to videos in docs */
+main video,
+.prose video,
+[data-testid="main-content"] video,
+.content video {
+  margin: 24px 0 !important;
+  border-radius: 8px !important;
+}
+
+/* Make table headers left-aligned */
+main th,
+.prose th,
+[data-testid="main-content"] th,
+.content th {
+  text-align: left !important;
+}
+
+/* Hide only the Powered by Mintlify attribution in footer */
+[data-testid="footer-powered-by"],
+footer a[href*="mintlify.com"],
+footer a[href*="//mintlify.com"],
+footer a[href^="https://mintlify"],
+footer a[href^="http://mintlify"],
+footer a[href*="mintlify.app"],
+footer a[href*="mintcdn.com"][aria-label*="Mintlify"],
+footer [aria-label*="Powered by Mintlify"],
+footer [aria-label="Powered by Mintlify"] {
+  display: none !important;
+}
+
+/* Preserve footer layout even if attribution is removed */
+footer [data-testid="footer-powered-by"] + *,
+footer a[href*="mintlify.com"] + * {
+  margin-left: 0 !important;
+}

docs/docs.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "maple",
+  "name": "mux",
+  "logo": {
+    "light": "/img/light.svg",
+    "dark": "/img/dark.svg"
+  },
+  "favicon": "/favicon.svg",
+  "colors": {
+    "primary": "#999",
+    "light": "#FFF",
+    "dark": "#000"
+  },
+  "appearance": {
+    "default": "dark"
+  },
+  "interaction": {
+    "drilldown": true
+  },
+  "icons": {
+    "library": "lucide"
+  },
+  "css": ["/custom.css"],
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          {
+            "group": "Introduction",
+            "pages": ["index", "install", "cli", "why-parallelize"]
+          },
+          {
+            "group": "Features",
+            "pages": [
+              {
+                "group": "Workspaces",
+                "pages": [
+                  "workspaces",
+                  {
+                    "group": "Runtimes",
+                    "pages": ["runtime", "runtime/local", "runtime/worktree", "runtime/ssh"]
+                  },
+                  "fork",
+                  "init-hooks"
+                ]
+              },
+              "vscode-extension",
+              "models",
+              {
+                "group": "Keyboard Shortcuts",
+                "pages": ["keybinds", "vim-mode"]
+              },
+              "context-management",
+              "instruction-files",
+              {
+                "group": "Project Secrets",
+                "pages": ["project-secrets", "agentic-git-identity"]
+              }
+            ]
+          },
+          {
+            "group": "Advanced",
+            "pages": ["prompting-tips", "system-prompt", "telemetry", "mux-codes"]
+          },
+          {
+            "group": "Development",
+            "pages": ["storybook", "benchmarking", "AGENTS"]
+          }
+        ]
+      }
+    ]
+  },
+  "footerSocials": {
+    "github": "https://github.com/coder/mux"
+  }
+}

docs/fork.md

@@ -1,4 +1,7 @@
-# Forking Workspaces
+---
+title: Forking Workspaces
+description: Clone workspaces with conversation history to explore alternatives
+---
 
 Use `/fork` to clone a workspace with its full conversation history and UI state. The forked workspace gets a new workspace on a new branch (using the same backend as the current workspace).
 

docs/intro.md → docs/index.md

@@ -1,6 +1,9 @@
-# Introduction
+---
+title: Introduction
+description: mux - Coding Agent Multiplexer for AI-assisted development
+---
 
-![mux product screenshot](img/product-hero.webp)
+![mux product screenshot](/img/product-hero.webp)
 
 **mux** (Coding Agent Multiplexer) is a cross-platform desktop application for AI-assisted development with isolated workspace management.
 

docs/init-hooks.md

@@ -1,4 +1,7 @@
-# Init Hooks
+---
+title: Init Hooks
+description: Run setup commands automatically when creating new workspaces
+---
 
 Add a `.mux/init` executable script to your project root to run commands when creating new workspaces.
 

docs/install.md

@@ -1,4 +1,7 @@
-# Install
+---
+title: Install
+description: Download and install mux for macOS, Linux, and Windows
+---
 
 ## Downloads
 
@@ -19,7 +22,7 @@ Download pre-built binaries of `main` from [GitHub Actions](https://github.com/c
   - `macos-dmg-arm64` (Apple Silicon)
 - **Linux**: AppImage (portable, works on most distros)
 
-> **Note**: Windows builds are only available from [releases](https://github.com/coder/mux/releases), not from development builds.
+<Info>Windows builds are only available from [releases](https://github.com/coder/mux/releases), not from development builds.</Info>
 
 To download:
 
@@ -54,11 +57,11 @@ The app is code-signed and notarized by Apple, so it will open without security
 3. Follow the installation prompts
 4. Launch Mux from the Start menu or desktop shortcut
 
-> ⚠️ Windows support is currently in alpha. Please [report any issues](https://github.com/coder/mux/issues) you encounter.
+<Warning>Windows support is currently in alpha. Please [report any issues](https://github.com/coder/mux/issues) you encounter.</Warning>
 
 ### Testing Pre-Release Builds
 
-⚠️ **Note**: Only builds from the `main` branch are signed and notarized. If you're testing a build from a pull request or other branch, you'll need to bypass macOS Gatekeeper:
+<Warning>Only builds from the `main` branch are signed and notarized. If you're testing a build from a pull request or other branch, you'll need to bypass macOS Gatekeeper:</Warning>
 
 1. After installing, open Terminal
 2. Run: `xattr -cr /Applications/Mux.app`

docs/instruction-files.md

@@ -1,4 +1,7 @@
-# Instruction Files
+---
+title: Instruction Files
+description: Configure agent behavior with AGENTS.md files
+---
 
 ## Overview
 
@@ -9,7 +12,7 @@ mux layers instructions from two locations:
 
 Priority within each location: `AGENTS.md` → `AGENT.md` → `CLAUDE.md` (first match wins). If the base file is found, mux also appends `AGENTS.local.md` from the same directory when present.
 
-> **Note:** mux strips HTML-style markdown comments (`<!-- ... -->`) from instruction files before sending them to the model. Use these comments for editor-only metadata—they will not reach the agent.
+<Info>mux strips HTML-style markdown comments (`<!-- ... -->`) from instruction files before sending them to the model. Use these comments for editor-only metadata—they will not reach the agent.</Info>
 
 ## Scoped Instructions
 

docs/keybinds.md

@@ -1,8 +1,11 @@
-# Keyboard Shortcuts
+---
+title: Keyboard Shortcuts
+description: Complete keyboard shortcut reference for mux
+---
 
 mux is designed to be keyboard-driven for maximum efficiency. All major actions have keyboard shortcuts.
 
-> **Note**: This document should be kept in sync with `src/utils/ui/keybinds.ts`, which is the source of truth for keybind definitions.
+<Info>This document should be kept in sync with `src/utils/ui/keybinds.ts`, which is the source of truth for keybind definitions.</Info>
 
 ## Platform Conventions
 

docs/models.md

@@ -1,4 +1,7 @@
-## Models
+---
+title: Models
+description: Configure AI providers including Anthropic, OpenAI, Google, xAI, and more
+---
 
 See also: