docs: convert to Mintlify .mdx format with navigation

Move docs into claude-code-plugin/ subdirectory as .mdx files with
Mintlify frontmatter (title, description, icon, sidebarTitle). Add
Claude Code Plugin group to docs.json navigation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/claude-code-plugin/architecture.mdx

@@ -1,6 +1,9 @@
-# Architecture
-
-This document describes the plugin's components, data flow, and internal protocols.
+---
+title: "Architecture"
+description: "Plugin components, data flow, and internal protocols"
+icon: "sitemap"
+sidebarTitle: "Architecture"
+---
 
 ## Data flow
 
@@ -56,7 +59,7 @@ allowed-tools: Task
 ---
 ```
 
-The `context: fork` setting means the skill runs in a forked context -- the optimizer agent gets its own conversation branch, keeping the main session clean.
+The `context: fork` setting means the skill runs in a forked context — the optimizer agent gets its own conversation branch, keeping the main session clean.
 
 ## Agent format
 
@@ -99,14 +102,15 @@ The agent body contains the full workflow: project detection, environment verifi
 }
 ```
 
-- **Event**: `Stop` -- fires every time Claude finishes a response
-- **Matcher**: `*` -- matches all stops (no filtering by tool or content)
+- **Event**: `Stop` — fires every time Claude finishes a response
+- **Matcher**: `*` — matches all stops (no filtering by tool or content)
 - **Timeout**: 30 seconds for the hook script to complete
 - **`${CLAUDE_PLUGIN_ROOT}`**: Resolved by Claude Code to the plugin's install directory
 
 ### Hook stdin/stdout protocol
 
 **Input** (JSON on stdin):
+
 ```json
 {
   "stop_hook_active": false,
@@ -115,6 +119,7 @@ The agent body contains the full workflow: project detection, environment verifi
 ```
 
 **Output** (JSON on stdout):
+
 ```json
 {"decision": "block", "reason": "message for Claude to act on"}
 ```
@@ -122,8 +127,8 @@ The agent body contains the full workflow: project detection, environment verifi
 Or no output / exit 0 to allow the stop (no blocking).
 
 The `decision` field can be:
-- `"block"` -- prevents Claude from stopping, injects `reason` as a new prompt for Claude to act on
-- Absent / script exits 0 without output -- allows the stop
+- `"block"` — prevents Claude from stopping, injects `reason` as a new prompt for Claude to act on
+- Absent / script exits 0 without output — allows the stop
 
 ## State files
 

docs/claude-code-plugin/configuration.mdx

@@ -1,6 +1,9 @@
-# Configuration
-
-This document covers all configuration surfaces: plugin manifests, project-level codeflash config, and Claude Code permissions.
+---
+title: "Configuration"
+description: "Configuration reference for plugin manifests, project config, and Claude Code permissions"
+icon: "gear"
+sidebarTitle: "Configuration"
+---
 
 ## Plugin manifests
 
@@ -43,8 +46,8 @@ formatter-cmds = ["disabled"]  # Formatter commands, or ["disabled"] to skip for
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
-| `module-root` | Yes | -- | Relative path to the module root. If your tests do `from mypackage import ...`, then `mypackage/` is the module root |
-| `tests-root` | Yes | -- | Relative path to the tests directory |
+| `module-root` | Yes | — | Relative path to the module root. If your tests do `from mypackage import ...`, then `mypackage/` is the module root |
+| `tests-root` | Yes | — | Relative path to the tests directory |
 | `ignore-paths` | No | `[]` | List of paths to exclude from optimization |
 | `formatter-cmds` | No | `["disabled"]` | List of formatter commands. Each can include flags, e.g. `"black --line-length 88 {file}"`. Use `["disabled"]` to skip formatting |
 
@@ -76,8 +79,8 @@ Codeflash reads its configuration from a `"codeflash"` key at the root level of
 
 | Field | Required | Default | Description |
 |-------|----------|---------|-------------|
-| `moduleRoot` | Yes | -- | Relative path to the JS/TS module root (e.g. `.` or `src`) |
-| `testsRoot` | Yes | -- | Relative path to the tests directory |
+| `moduleRoot` | Yes | — | Relative path to the JS/TS module root (e.g. `.` or `src`) |
+| `testsRoot` | Yes | — | Relative path to the tests directory |
 | `formatterCmds` | No | `["disabled"]` | Formatter commands. Use `npx` prefix for project-local tools, e.g. `"npx prettier --write {file}"` |
 | `ignorePaths` | No | `[]` | Glob patterns to exclude from optimization |
 
@@ -114,4 +117,6 @@ The permission can be placed at different levels:
 | `.claude/settings.local.json` | Project-wide, personal (gitignored) |
 | `~/.claude/settings.json` | User-wide, all projects |
 
+<Note>
 The stop hook checks `.claude/settings.json` in the repo root to determine if auto-allow is already configured. If the `permissions.allow` array contains any entry matching `codeflash`, the hook skips adding auto-allow instructions to its suggestions.
+</Note>

docs/claude-code-plugin/getting-started.mdx

@@ -1,4 +1,9 @@
-# Getting Started
+---
+title: "Getting Started"
+description: "Install the Codeflash Claude Code plugin and run your first optimization"
+icon: "rocket"
+sidebarTitle: "Getting Started"
+---
 
 This guide walks you through installing the Codeflash Claude Code plugin and running your first optimization.
 
@@ -10,7 +15,7 @@ This guide walks you through installing the Codeflash Claude Code plugin and run
 
 ## Installation
 
-### 1. Add the marketplace and install
+### Add the marketplace and install
 
 ```bash
 /plugin marketplace add codeflash-ai/codeflash-cc-plugin
@@ -25,7 +30,7 @@ git clone https://github.com/codeflash-ai/codeflash-cc-plugin.git
 /plugin install codeflash
 ```
 
-### 2. Choose installation scope
+### Choose installation scope
 
 By default, plugins install at the **user** level (available across all projects). You can change this:
 
@@ -39,7 +44,7 @@ By default, plugins install at the **user** level (available across all projects
 /plugin install codeflash --scope project
 ```
 
-### 3. Verify installation
+### Verify installation
 
 Run `/plugin` to open the plugin manager. Confirm **codeflash** appears under the **Installed** tab.
 
@@ -74,6 +79,17 @@ This adds `Bash(*codeflash*)` to the `permissions.allow` array in `.claude/setti
 
 ## Next steps
 
-- [Usage Guide](usage-guide.md) -- all commands, flags, and workflows
-- [Configuration](configuration.md) -- config reference for Python and JS/TS projects
-- [Troubleshooting](troubleshooting.md) -- common problems and fixes
+<CardGroup cols={2}>
+  <Card title="Usage Guide" icon="book" href="/claude-code-plugin/usage-guide">
+    All commands, flags, and workflows
+  </Card>
+  <Card title="Configuration" icon="gear" href="/claude-code-plugin/configuration">
+    Config reference for Python and JS/TS projects
+  </Card>
+  <Card title="Troubleshooting" icon="wrench" href="/claude-code-plugin/troubleshooting">
+    Common problems and fixes
+  </Card>
+  <Card title="Architecture" icon="sitemap" href="/claude-code-plugin/architecture">
+    How the plugin works internally
+  </Card>
+</CardGroup>

docs/claude-code-plugin/hook-lifecycle.mdx

@@ -1,6 +1,11 @@
-# Hook Lifecycle
+---
+title: "Hook Lifecycle"
+description: "Deep dive into the Stop hook: commit detection, deduplication, and decision tree"
+icon: "arrows-rotate"
+sidebarTitle: "Hook Lifecycle"
+---
 
-Deep dive into `scripts/suggest-optimize.sh` -- the Stop hook that detects commits and suggests optimizations.
+Deep dive into `scripts/suggest-optimize.sh` — the Stop hook that detects commits and suggests optimizations.
 
 ## When the hook fires
 
@@ -12,41 +17,43 @@ The hook evaluates a series of conditions and takes the first matching exit path
 
 ```
 1. stop_hook_active == true?
-   YES -> exit 0 (allow stop, prevent infinite loop)
+   YES → exit 0 (allow stop, prevent infinite loop)
 
 2. Not inside a git repo?
-   YES -> exit 0
+   YES → exit 0
 
 3. No transcript_path or file doesn't exist?
-   YES -> exit 0
+   YES → exit 0
 
 4. Session start time unavailable?
-   YES -> exit 0
+   YES → exit 0
 
 5. No commits with .py/.js/.ts/.jsx/.tsx files since session start?
-   YES -> exit 0
+   YES → exit 0
 
 6. Commit hash set already seen (in codeflash-seen)?
-   YES -> exit 0
+   YES → exit 0
 
 7. JS/TS project with JS changes?
-   7a. Not configured -> block: set up config (+ install if needed)
-   7b. Configured, not installed -> block: install codeflash
-   7c. Configured + installed -> block: run codeflash
+   7a. Not configured → block: set up config (+ install if needed)
+   7b. Configured, not installed → block: install codeflash
+   7c. Configured + installed → block: run codeflash
 
 8. No Python changes?
-   YES -> exit 0
+   YES → exit 0
 
 9. Python project, no venv found?
-   YES -> block: create venv, install, configure, run
+   YES → block: create venv, install, configure, run
 
 10. Python project with venv:
-    10a. Not configured -> block: set up config (+ install if needed)
-    10b. Configured, not installed -> block: install codeflash
-    10c. Configured + installed -> block: run codeflash
+    10a. Not configured → block: set up config (+ install if needed)
+    10b. Configured, not installed → block: install codeflash
+    10c. Configured + installed → block: run codeflash
 ```
 
+<Note>
 Every `block` decision also appends auto-allow instructions if `Bash(*codeflash*)` is not yet in `.claude/settings.json`.
+</Note>
 
 ## Infinite loop prevention
 
@@ -74,9 +81,9 @@ git log --after="@$SESSION_START" --name-only --diff-filter=ACMR \
   --pretty=format: -- '*.py' '*.js' '*.ts' '*.jsx' '*.tsx'
 ```
 
-- `--after=@$SESSION_START` -- only commits after session start (Unix timestamp)
-- `--diff-filter=ACMR` -- Added, Copied, Modified, Renamed files only
-- `--pretty=format:` -- suppress commit metadata, show only file names
+- `--after=@$SESSION_START` — only commits after session start (Unix timestamp)
+- `--diff-filter=ACMR` — Added, Copied, Modified, Renamed files only
+- `--pretty=format:` — suppress commit metadata, show only file names
 - File patterns filter to Python and JS/TS extensions
 
 The results are sorted and deduplicated. The hook also determines which language families have changes (`HAS_PYTHON_CHANGES`, `HAS_JS_CHANGES`) by grepping the file list for extension patterns.
@@ -87,7 +94,8 @@ The hook prevents suggesting optimization for the same set of commits twice:
 
 1. It computes the commit hashes of all matching commits:
    ```bash
-   git log --after="@$SESSION_START" --pretty=format:%H -- '*.py' '*.js' '*.ts' '*.jsx' '*.tsx'
+   git log --after="@$SESSION_START" --pretty=format:%H \
+     -- '*.py' '*.js' '*.ts' '*.jsx' '*.tsx'
    ```
 2. It hashes the full list with SHA-256:
    ```bash
@@ -113,7 +121,7 @@ The `detect_project` function walks from `$PWD` upward to `$REPO_ROOT`:
 
 For Python, it checks for `[tool.codeflash]` in `pyproject.toml`. For JS/TS, it checks for a `"codeflash"` key in `package.json` using `jq`.
 
-The walk stops at `$REPO_ROOT` -- it never searches above the git repository root.
+The walk stops at `$REPO_ROOT` — it never searches above the git repository root.
 
 ## Auto-allow suggestion
 

docs/claude-code-plugin/troubleshooting.mdx

@@ -1,4 +1,9 @@
-# Troubleshooting
+---
+title: "Troubleshooting"
+description: "Common problems and fixes for the Codeflash Claude Code plugin"
+icon: "wrench"
+sidebarTitle: "Troubleshooting"
+---
 
 ## Plugin not appearing after install
 
@@ -16,7 +21,7 @@
 **Possible causes**:
 - No project config found. The agent walks from CWD to the git root looking for `pyproject.toml` or `package.json`. Make sure you're inside a git repository.
 - Codeflash CLI not installed. For Python: `pip install codeflash` in your venv. For JS/TS: `npm install --save-dev codeflash`.
-- The agent is running in the background. Check if you see "Codeflash is optimizing in the background" -- results appear when the background task completes.
+- The agent is running in the background. Check if you see "Codeflash is optimizing in the background" — results appear when the background task completes.
 
 ## Permission prompts every time
 
@@ -55,6 +60,7 @@ The plugin searches for venvs in this order:
 **Symptom**: `npx codeflash --version` fails or package not found.
 
 **Fix**:
+
 ```bash
 npm install --save-dev codeflash
 ```
@@ -83,7 +89,9 @@ This shouldn't happen due to deduplication (the hook tracks seen commit hashes i
 
 ## "Attempting to repair broken tests..."
 
+<Info>
 This is **normal codeflash behavior**, not an error. Codeflash generates tests and sometimes needs to fix them. Let it continue.
+</Info>
 
 ## 10-minute timeout exceeded
 

docs/claude-code-plugin/usage-guide.mdx

@@ -1,4 +1,9 @@
-# Usage Guide
+---
+title: "Usage Guide"
+description: "Commands, flags, and workflows for the Codeflash Claude Code plugin"
+icon: "book"
+sidebarTitle: "Usage Guide"
+---
 
 ## The `/optimize` skill
 
@@ -44,7 +49,9 @@ The agent has up to **15 turns** to complete its work (install codeflash, config
 3. If not, adds it (creating the file and directory if needed)
 4. Preserves any existing settings
 
-Running `/setup` multiple times is safe -- it's idempotent. If permissions are already configured, it reports "No changes needed."
+<Info>
+Running `/setup` multiple times is safe — it's idempotent. If permissions are already configured, it reports "No changes needed."
+</Info>
 
 ## Automatic post-commit suggestions
 
@@ -89,4 +96,4 @@ For JavaScript/TypeScript projects, the optimizer agent:
 3. Always runs from the project root (the directory containing `package.json`)
 4. Runs: `npx codeflash --subagent [flags]`
 
-No virtual environment is needed -- JS/TS projects use `npx`/`npm` directly.
+No virtual environment is needed — JS/TS projects use `npx`/`npm` directly.

docs/docs.json

@@ -65,6 +65,17 @@
               "editor-plugins/vscode/configuration",
               "editor-plugins/vscode/troubleshooting"
             ]
+          },
+          {
+            "group": "Claude Code Plugin",
+            "pages": [
+              "claude-code-plugin/getting-started",
+              "claude-code-plugin/usage-guide",
+              "claude-code-plugin/configuration",
+              "claude-code-plugin/architecture",
+              "claude-code-plugin/hook-lifecycle",
+              "claude-code-plugin/troubleshooting"
+            ]
           }
         ]
       }