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:
 

docs/mux-codes.md

@@ -1,4 +1,8 @@
-# Mux Codes
+---
+title: Mux Codes
+description: Redeem free LLM token credits for evaluating Mux
+---
+
 
 Mux codes are free LLM token credits for evaluating Mux. Coder employees disburse them at events to users we think will enjoy Mux. If you want to get your hands on a code, ask the nearest Coder employee.
 

docs/project-secrets.md

@@ -1,4 +1,7 @@
-# Project Secrets
+---
+title: Project Secrets
+description: Manage environment variables and API keys for your projects
+---
 
 Securely manage environment variables for your projects in mux. Project secrets are automatically injected when the agent executes bash commands, making it easy to provide API keys, tokens, and other sensitive configuration.