# aimux Documentation Site Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Build a Starlight (Astro) documentation site for aimux with custom dark/light theming matching the aimux dashboard palette, deployed to GitHub Pages.

**Architecture:** Starlight project lives in `docs-site/` at the repo root. Custom CSS overrides Starlight's theme variables to match aimux's dark and light palettes. Content is authored as `.mdx` files. GitHub Actions deploys on push to main.

**Tech Stack:** Astro/Starlight, CSS custom properties, GitHub Actions, GitHub Pages

## File Structure

```
docs-site/
  package.json
  astro.config.mjs
  src/
    content/docs/
      index.mdx
      getting-started.mdx
      configuration.mdx
      guides/
        web-dashboard.mdx
        tui-keybindings.mdx
        launch-modes.mdx
        tracing.mdx
        cost-tracking.mdx
        notifications.mdx
        plugins.mdx
        tasks.mdx
      advanced/
        adding-a-provider.mdx
        k8s-quickstart.mdx
    styles/
      custom.css
  public/
    favicon.svg
.github/workflows/
  docs.yml
```

## Task 1: Scaffold Starlight Project

**Files:**
- Create: `docs-site/package.json`
- Create: `docs-site/astro.config.mjs`
- Create: `docs-site/tsconfig.json`

- [ ] **Step 1: Initialize Starlight**

```bash
cd /Users/azaalouk/go/src/github.com/zanetworker/aimux
npm create starlight@latest docs-site -- --template basics --install --no-git
```

- [ ] **Step 2: Configure astro.config.mjs**

Replace `docs-site/astro.config.mjs` with:

```js
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  site: 'https://zanetworker.github.io',
  base: '/aimux',
  integrations: [
    starlight({
      title: 'aimux',
      description: 'Tame the agent sprawl. See all your agents. Trace what they did. Judge if it was good.',
      social: { github: 'https://github.com/zanetworker/aimux' },
      customCss: ['./src/styles/custom.css'],
      sidebar: [
        { label: 'Home', slug: '' },
        { label: 'Getting Started', slug: 'getting-started' },
        { label: 'Configuration', slug: 'configuration' },
        {
          label: 'Guides',
          items: [
            { label: 'Web Dashboard', slug: 'guides/web-dashboard' },
            { label: 'TUI Keybindings', slug: 'guides/tui-keybindings' },
            { label: 'Launch Modes', slug: 'guides/launch-modes' },
            { label: 'Tracing & Annotations', slug: 'guides/tracing' },
            { label: 'Cost Tracking', slug: 'guides/cost-tracking' },
            { label: 'Notifications', slug: 'guides/notifications' },
            { label: 'Plugins', slug: 'guides/plugins' },
            { label: 'Tasks Integration', slug: 'guides/tasks' },
          ],
        },
        {
          label: 'Advanced',
          items: [
            { label: 'Adding a Provider', slug: 'advanced/adding-a-provider' },
            { label: 'Kubernetes Quickstart', slug: 'advanced/k8s-quickstart' },
          ],
        },
      ],
    }),
  ],
});
```

- [ ] **Step 3: Verify scaffold builds**

```bash
cd docs-site && npm run build
```

Expected: build succeeds, output in `docs-site/dist/`

- [ ] **Step 4: Commit**

```bash
git add docs-site/
git commit -m "feat(docs): scaffold Starlight docs site"
```

## Task 2: Custom Theme CSS

**Files:**
- Create: `docs-site/src/styles/custom.css`

- [ ] **Step 1: Create custom.css with dark theme overrides**

Create `docs-site/src/styles/custom.css`:

```css
/* aimux dark theme (Starlight default is dark) */
:root {
  --sl-color-accent-low: #3b1010;
  --sl-color-accent: #FF3131;
  --sl-color-accent-high: #FF6B6B;
  --sl-color-white: #e6e6e6;
  --sl-color-gray-1: #d4d4d4;
  --sl-color-gray-2: #a6a6a6;
  --sl-color-gray-3: #666666;
  --sl-color-gray-4: #404040;
  --sl-color-gray-5: #1a1a1a;
  --sl-color-gray-6: #0d0d0d;
  --sl-color-black: #000000;
  --sl-color-bg-nav: #0d0d0d;
  --sl-color-bg-sidebar: #0d0d0d;
  --sl-color-hairline-light: #1a1a1a;
  --sl-color-hairline-shade: #0d0d0d;
  --sl-font: 'Inter', system-ui, -apple-system, sans-serif;
  --sl-font-mono: 'SF Mono', 'Fira Code', monospace;
}

/* aimux light theme */
:root[data-theme='light'] {
  --sl-color-accent-low: #FCE3E3;
  --sl-color-accent: #EE0000;
  --sl-color-accent-high: #A60000;
  --sl-color-white: #151515;
  --sl-color-gray-1: #4D4D4D;
  --sl-color-gray-2: #6B6B6B;
  --sl-color-gray-3: #8A8A8A;
  --sl-color-gray-4: #D4D4D4;
  --sl-color-gray-5: #F5F5F5;
  --sl-color-gray-6: #FFFFFF;
  --sl-color-black: #FFFFFF;
  --sl-color-bg-nav: #FFFFFF;
  --sl-color-bg-sidebar: #FFFFFF;
  --sl-color-hairline-light: #D4D4D4;
  --sl-color-hairline-shade: #E0E0E0;
}

/* Code block styling */
pre {
  border: 1px solid var(--sl-color-hairline-light) !important;
}
```

- [ ] **Step 2: Verify theme renders**

```bash
cd docs-site && npm run dev
```

Open `http://localhost:4321/aimux/` in browser. Toggle dark/light theme. Verify accent color is red, backgrounds match aimux palette.

- [ ] **Step 3: Commit**

```bash
git add docs-site/src/styles/custom.css
git commit -m "feat(docs): add aimux dark/light theme overrides"
```

## Task 3: Copy Favicon

**Files:**
- Create: `docs-site/public/favicon.svg`

- [ ] **Step 1: Copy the aimux logo**

```bash
cp assets/logo.png docs-site/public/favicon.png
```

If an SVG version exists, use that instead. Otherwise create a minimal SVG favicon:

```bash
cat > docs-site/public/favicon.svg << 'EOF'
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
  <text x="2" y="24" font-family="system-ui" font-weight="700" font-size="18">
    <tspan fill="#FF3131">ai</tspan><tspan fill="#e6e6e6">m</tspan>
  </text>
</svg>
EOF
```

- [ ] **Step 2: Commit**

```bash
git add docs-site/public/
git commit -m "feat(docs): add favicon"
```

## Task 4: Landing Page (index.mdx)

**Files:**
- Create: `docs-site/src/content/docs/index.mdx`
- Remove: default Starlight index page

- [ ] **Step 1: Write index.mdx**

Create `docs-site/src/content/docs/index.mdx`:

```mdx
---
title: aimux
description: Tame the agent sprawl. See all your agents. Trace what they did. Judge if it was good.
template: splash
hero:
  tagline: You're running 5 agents across 3 projects. One just edited 47 files. Was it right? Every other tool tells you which agents are running. aimux tells you what they actually did, and whether it was good.
  actions:
    - text: Get Started
      link: /aimux/getting-started/
      icon: right-arrow
    - text: View on GitHub
      link: https://github.com/zanetworker/aimux
      icon: external
      variant: minimal
---

import { Card, CardGrid } from '@astrojs/starlight/components';

## Three Differentiators

<CardGrid stagger>
  <Card title="Trace" icon="magnifier">
    Turn-by-turn view of prompts, responses, and tool calls. Live streaming as agents work. Available in TUI split view and web dashboard.
  </Card>
  <Card title="Annotate" icon="pencil">
    Label turns GOOD, BAD, or WASTE. Add notes. Build eval datasets from real agent sessions.
  </Card>
  <Card title="Export" icon="rocket">
    OTEL to MLflow or Jaeger. JSONL to disk. Annotations become feedback assessments for model evaluation.
  </Card>
  <Card title="Multi-Provider" icon="list-format">
    Auto-discovers Claude, Codex, and Gemini agents. Extensible provider interface for adding new agent types.
  </Card>
</CardGrid>

## Two Interfaces

**TUI Dashboard** (`aimux`) - Terminal-based dashboard with agent table, split-view trace, live PTY embedding, and keybinding-driven workflow.

**Web Dashboard** (`aimux web`) - Browser-based dashboard with card grid, session history, trace panel, cost tracking, dark/light themes, and plugin system.
```

- [ ] **Step 2: Remove default Starlight content**

Delete any default `.mdx` files that Starlight scaffolded (e.g., `index.mdx`, `getting-started.mdx` in the template).

- [ ] **Step 3: Verify**

```bash
cd docs-site && npm run build
```

- [ ] **Step 4: Commit**

```bash
git add docs-site/src/content/docs/index.mdx
git commit -m "feat(docs): add landing page"
```

## Task 5: Getting Started Page

**Files:**
- Create: `docs-site/src/content/docs/getting-started.mdx`

- [ ] **Step 1: Write getting-started.mdx**

Create `docs-site/src/content/docs/getting-started.mdx`:

```mdx
---
title: Getting Started
description: Install aimux and run your first dashboard.
---

## Install

```bash
# Homebrew (macOS/Linux)
brew install zanetworker/aimux/aimux

# From source
git clone https://github.com/zanetworker/aimux.git
cd aimux
make install       # builds and copies to /usr/local/bin
```

## Requirements

- **tmux** - required for split-pane session embedding and agent launch
- **Go 1.24+** - only if building from source
- Running AI coding agents: Claude Code, Codex CLI, or Gemini CLI

## Launch the TUI

```bash
aimux
```

aimux auto-discovers running Claude, Codex, and Gemini processes. The agent table refreshes every 2 seconds.

## Launch the Web Dashboard

```bash
aimux web              # web dashboard on port 9090
aimux web --port 8080  # custom port
aimux --web            # both TUI and web simultaneously
```

Open `http://localhost:9090` in your browser.

## CLI Commands

| Command | Description |
|---------|-------------|
| `aimux` | Launch TUI dashboard |
| `aimux web` | Launch web dashboard (default port 9090) |
| `aimux --web` | Launch both TUI and web |
| `aimux sessions` | List/search session history |
| `aimux resume` | Resume a previous session |
| `aimux --version` | Print version |

## Quick Tour

1. **Start some agents** - Run Claude Code, Codex, or Gemini in other terminals
2. **Open aimux** - They appear automatically in the dashboard
3. **Select an agent** - Press Enter (TUI) or click a card (web) to see its trace
4. **Annotate** - Mark turns as good/bad/waste to build eval datasets
5. **Export** - Send traces to MLflow via OTEL, or save as JSONL
```

- [ ] **Step 2: Commit**

```bash
git add docs-site/src/content/docs/getting-started.mdx
git commit -m "feat(docs): add getting started page"
```

## Task 6: Configuration Page

**Files:**
- Create: `docs-site/src/content/docs/configuration.mdx`

- [ ] **Step 1: Write configuration.mdx**

Create `docs-site/src/content/docs/configuration.mdx` with the full config reference. Document every field from `internal/config/config.go`:

```mdx
---
title: Configuration
description: Full reference for ~/.aimux/config.yaml
---

All configuration lives in `~/.aimux/config.yaml`. Every setting is optional. Defaults are shown below.

## Full Example

```yaml
providers:
  claude:
    enabled: true
  codex:
    enabled: true
  gemini:
    enabled: true

refresh_interval: "2s"
default_runtime: "tmux"
shell: "/bin/zsh"

sessions:
  auto_title: false
  title_model: "flash"

notifications:
  enabled: true
  on_waiting: true
  on_error: true
  on_idle: false
  on_done: true
  sound: false
  bell: true
  desktop: true

export:
  endpoint: "localhost:5001"
  insecure: true
  mlflow:
    experiment_id: "1"

otel:
  enabled: false
  port: 4318

quick_launch:
  directories:
    - "~/projects/my-app"
    - "~/projects/my-lib"

tasks:
  backend: "auto"
  default_list: ""
  prompt_template: "Work on the following task: {title}\n\nDetails: {notes}\n\nAdditional instructions: {user_prompt}\n\nWhen done, summarize what you did."

kubernetes:
  enabled: false
  redis_url: ""
  team_id: ""
  namespace: "agents"
  kubeconfig: ""
  otel_endpoint: ""
```

## Providers

Enable or disable agent providers. Unknown providers default to enabled.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `true` | Whether to discover agents from this provider |
| `binary` | string | auto-detect | Override the binary path for this provider |

## General

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `refresh_interval` | string | `"2s"` | How often to scan for agents |
| `default_runtime` | string | `"tmux"` | Default launch mode: `"tmux"` or `"direct"` |
| `shell` | string | `$SHELL` | Login shell for spawning agents. Falls back to `$SHELL`, then `/bin/sh` |

## Sessions

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `auto_title` | bool | `false` | Generate titles via LLM on session discovery |
| `title_model` | string | `"flash"` | LLM for title generation: `"flash"`, `"haiku"`, `"sonnet"`, `"opus"` |
| `api_key` | string | env var | API key for title generation (overrides `GOOGLE_API_KEY` / `ANTHROPIC_API_KEY`) |

## Notifications

macOS notification settings. All default to sensible values.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `true` | Master switch for all notifications |
| `on_waiting` | bool | `true` | Notify when agent needs permission |
| `on_error` | bool | `true` | Notify when agent crashes |
| `on_idle` | bool | `false` | Notify when agent finishes a turn |
| `on_done` | bool | `true` | Notify when agent finishes |
| `sound` | bool | `false` | Play macOS notification sound |
| `bell` | bool | `true` | Terminal bell on attention events |
| `desktop` | bool | `true` | macOS Notification Center alerts |

## Export

OTEL/HTTP export settings for sending traces to MLflow, Jaeger, or any OTLP-compatible backend.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `endpoint` | string | | OTLP/HTTP endpoint (e.g., `"localhost:5001"`) |
| `insecure` | bool | `true` | Use HTTP instead of HTTPS |
| `headers` | map | | Extra HTTP headers for the export endpoint |
| `mlflow.experiment_id` | string | | MLflow experiment ID for trace grouping |

## OTEL Receiver

Embedded OTLP/HTTP receiver for collecting live telemetry from agents.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `false` | Enable the OTEL receiver |
| `port` | int | `4318` | Port to listen on |

## Quick Launch

Pre-configured directories for the agent launcher.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `directories` | list | `[]` | Directories shown at the top of the launcher's directory picker |

## Tasks

Google Tasks integration for task-driven agent launches.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `backend` | string | `"auto"` | Task backend: `"auto"`, `"mcp"`, or `"api"` |
| `mcp_endpoint` | string | | MCP server endpoint URL for tasks |
| `default_list` | string | | Default task list ID |
| `prompt_template` | string | see above | Template for agent prompts. Placeholders: `{title}`, `{notes}`, `{user_prompt}` |

## Kubernetes

See [Kubernetes Quickstart](/aimux/advanced/k8s-quickstart/) for full setup guide.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `enabled` | bool | `false` | Enable K8s agent discovery |
| `redis_url` | string | | Redis connection string (required when enabled) |
| `team_id` | string | | Redis key prefix for team isolation |
| `namespace` | string | `"agents"` | K8s namespace for agent deployments |
| `kubeconfig` | string | auto | Path to kubeconfig (omit for in-cluster) |
| `otel_endpoint` | string | | OTEL collector URL for remote agent traces |
```

- [ ] **Step 2: Commit**

```bash
git add docs-site/src/content/docs/configuration.mdx
git commit -m "feat(docs): add configuration reference"
```

## Task 7: Guide Pages (8 files)

**Files:**
- Create: `docs-site/src/content/docs/guides/web-dashboard.mdx`
- Create: `docs-site/src/content/docs/guides/tui-keybindings.mdx`
- Create: `docs-site/src/content/docs/guides/launch-modes.mdx`
- Create: `docs-site/src/content/docs/guides/tracing.mdx`
- Create: `docs-site/src/content/docs/guides/cost-tracking.mdx`
- Create: `docs-site/src/content/docs/guides/notifications.mdx`
- Create: `docs-site/src/content/docs/guides/plugins.mdx`
- Create: `docs-site/src/content/docs/guides/tasks.mdx`

- [ ] **Step 1: Create guides/web-dashboard.mdx**

```mdx
---
title: Web Dashboard
description: Browser-based agent dashboard with cards, sessions, traces, and themes.
---

Launch the web dashboard:

```bash
aimux web              # default port 9090
aimux web --port 8080  # custom port
```

## Card Grid

The main view shows agent cards grouped by project. Each card displays:

- **Provider badge** (Claude, Codex, Gemini) with color coding
- **Status** (Active, Idle, Waiting, Error)
- **Launch mode badge** (tmux or direct)
- **Title** from the session's first prompt or auto-generated
- **Project name** and git branch
- **Last activity snippet** showing the most recent tool call
- **Model**, token counts, and cost

Click a card to toggle the trace panel. Click again to close it.

## Views

Toggle between views using the tab bar:

- **Agents** - Live agent cards with filtering and sorting
- **Sessions** - Historical session table with search
- **Plugin tabs** - Custom dashboards from plugins (e.g., Skill Dashboard)

### List vs Card View

Toggle between card grid and compact list view using the view mode buttons in the filter bar (grid/list icons).

## Filtering and Sorting

The filter bar provides:

- **Status filters**: All, Active, Idle, Waiting, Error
- **Provider filters**: Claude, Codex, Gemini
- **Recent filter**: Show only agents active in the last 5 minutes
- **Text search**: Filter by project name or branch
- **Content search**: Search inside session traces across all agents
- **Sort**: Last Active, Cost, Tokens

## Trace Panel

Selecting an agent opens the right panel with:

- **Trace view**: Turn-by-turn conversation with tool calls, diffs, and outputs
- **Annotations**: Label turns as good/bad/waste with notes
- **Export**: JSONL to `~/.aimux/exports/` or OTEL to configured endpoint
- **Fullscreen**: Expand the trace panel to fill the viewport

## Dark/Light Theme

Toggle between dark and light themes using the sun/moon button in the header bar. The preference is saved to localStorage and persists across sessions.

- **Dark**: Pure black base (`#000000`), red accent (`#FF3131`)
- **Light**: Light grey base (`#F5F5F5`), Red Hat Red accent (`#EE0000`)

## Stats Bar

The header shows aggregate statistics:

- Session count, active/idle/waiting/error counts
- Repository count
- Total tokens in/out
- Total cost across all agents
```

- [ ] **Step 2: Create guides/tui-keybindings.mdx**

```mdx
---
title: TUI Keybindings
description: Keyboard shortcuts for the terminal dashboard.
---

## Agent List

| Key | Action |
|-----|--------|
| `Enter` | Open split view (trace + session) |
| `j` / `k` | Move selection down/up |
| `Tab` / `x` | Expand/collapse process tree |
| `/` | Search across agent traces |
| `$` | Toggle cost-per-turn display |
| `d` | Toggle diff view |
| `s` | Cycle sort order |
| `m` | Mute/unmute notifications |
| `:new` | Open agent launcher |
| `?` | Show help overlay |
| `q` | Quit |

## Split View (Trace + Session)

| Key | Action |
|-----|--------|
| `j` / `k` | Scroll trace up/down |
| `g` | Annotate turn as GOOD |
| `b` | Annotate turn as BAD |
| `w` | Annotate turn as WASTE |
| `n` | Add note to current turn |
| `e` | Open export menu |
| `Esc` | Close split view |
| `Tab` | Switch focus between trace and session panes |

## Export Menu

| Key | Action |
|-----|--------|
| `j` | Export as JSONL to `~/.aimux/exports/` |
| `o` | Export as OTEL to configured endpoint |
| `Esc` | Cancel |

## Command Palette

Type `:` to open the command palette:

| Command | Action |
|---------|--------|
| `:new` | Launch new agent session |
| `:export-otel` | Export current trace via OTEL |
```

- [ ] **Step 3: Create guides/launch-modes.mdx**

```mdx
---
title: Launch Modes
description: Direct and tmux launch modes, quick launch directories, and task-driven launches.
---

## Launch Modes

When spawning a new agent, choose between two runtime modes:

### Direct Mode

The agent runs as a direct child process. Simpler, but the session dies if you close aimux.

### Tmux Mode (default)

The agent runs inside a tmux session named `aimux-<provider>-<timestamp>`. Benefits:

- **Persistent**: Sessions survive aimux restarts
- **Detachable**: Close aimux, reattach later
- **Visible**: Sessions appear with `tmux ls`

Set the default in config:

```yaml
default_runtime: "tmux"  # or "direct"
```

## Launching Agents

### TUI

Type `:new` to open the launcher. Steps:

1. Pick a provider (Claude, Codex, Gemini)
2. Choose a directory (recent dirs, browse filesystem, or quick launch)
3. Select model and mode
4. Choose runtime (tmux or direct)

### Web Dashboard

Click **+ Launch** in the header bar. The launch dialog provides:

- Directory browser with recent directories
- Quick launch directories from config
- Provider, model, and mode selection

## Quick Launch Directories

Pre-configure directories for fast access:

```yaml
quick_launch:
  directories:
    - "~/projects/my-app"
    - "~/projects/my-lib"
```

These appear at the top of the directory picker in both TUI and web launchers.

## Task-Driven Launch

With Google Tasks integration enabled, you can launch agents with task context:

1. Open the Tasks panel in the web dashboard
2. Click "Launch" on a task
3. The task title and notes are injected into the agent's prompt
4. A "Session started" note is added to the task automatically

See [Tasks Integration](/aimux/guides/tasks/) for setup.
```

- [ ] **Step 4: Create guides/tracing.mdx**

```mdx
---
title: Tracing & Annotations
description: View agent traces, annotate turns, and export to OTEL or JSONL.
---

## Trace View

Every agent session produces a trace: a turn-by-turn record of prompts, responses, and tool calls. aimux parses provider-specific log formats (Claude JSONL, Codex JSONL, Gemini JSON) into a unified trace view.

### What You See Per Turn

- **User prompt** text
- **Assistant response** text
- **Tool calls** with name, input snippet, success/failure status
- **Edit diffs** showing old/new strings for file edits
- **Token counts** (in/out) and cost per turn
- **Model** used for the turn

### Live Streaming

Traces update in real-time as agents work. The TUI tails the JSONL file; the web dashboard polls via SSE.

## OTEL Dual Mode

aimux has two trace data paths:

1. **File-based** (display): Parses provider log files for full response text. This is what you see in the trace view.
2. **OTEL receiver** (export): Collects live telemetry on port 4318 for re-export. Claude Code sends events via the OTEL logs protocol (no response text due to Anthropic privacy design).

Enable the receiver:

```yaml
otel:
  enabled: true
  port: 4318
```

## Annotations

Label turns to build evaluation datasets:

| Label | Meaning |
|-------|---------|
| GOOD | Turn produced correct, useful output |
| BAD | Turn produced incorrect or harmful output |
| WASTE | Turn was unnecessary (redundant, off-topic) |

Add free-text notes to any annotation for context.

### TUI

In split view, navigate to a turn and press `g` (good), `b` (bad), or `w` (waste). Press `n` to add a note.

### Web Dashboard

Click annotation buttons in the trace panel. Click the note icon to add notes.

## Export

### JSONL

Exports the annotated trace as JSONL to `~/.aimux/exports/`. Each line is a turn with annotations attached.

- TUI: Press `e` then `j`
- Web: Click export button, select JSONL

### OTEL

Exports trace spans to the configured OTLP/HTTP endpoint. Annotations become span attributes.

- TUI: Press `e` then `o`, or `:export-otel`
- Web: Click export button, select OTEL

Configure the endpoint:

```yaml
export:
  endpoint: "localhost:5001"
  insecure: true
  mlflow:
    experiment_id: "1"
```

### MLflow Integration

When exporting to MLflow, traces appear as runs in the configured experiment. Each turn becomes a span. Annotations become feedback assessments.

See the [MLflow integration example](https://github.com/zanetworker/aimux/blob/main/docs/examples/mlflow-integration.md) for a complete walkthrough.
```

- [ ] **Step 5: Create guides/cost-tracking.mdx**

```mdx
---
title: Cost Tracking
description: Per-agent and per-turn cost estimation with model-aware pricing.
---

## How It Works

aimux tracks token usage (input, output, cache read, cache write) per agent and calculates cost using per-million-token pricing. Costs appear on agent cards, in the trace view per turn, and in the stats bar as a total.

## Supported Models

| Model | Input ($/M) | Output ($/M) | Cache Read | Cache Write |
|-------|-------------|--------------|------------|-------------|
| claude-opus-4-6 | $15.00 | $75.00 | $1.50 | $18.75 |
| claude-sonnet-4-5 | $3.00 | $15.00 | $0.30 | $3.75 |
| claude-haiku-3-5 | $0.80 | $4.00 | $0.08 | $1.00 |
| o3 | $2.00 | $8.00 | - | - |
| o4-mini | $1.10 | $4.40 | - | - |
| gemini-2.5-pro | $1.25 | $10.00 | - | - |
| gemini-2.5-flash | $0.15 | $0.60 | - | - |
| gemini-3-pro | $1.25 | $10.00 | - | - |
| gemini-3.1-flash | $0.15 | $0.60 | - | - |

Short aliases: `opus` = claude-opus-4-6, `sonnet` = claude-sonnet-4-5, `haiku` = claude-haiku-3-5.

Pricing data last verified: 2026-02-28.

## TUI

Press `$` to toggle cost-per-turn display in the trace view. The cost dashboard shows per-project breakdowns.

## Web Dashboard

Costs appear on agent cards and in the stats bar header. The trace panel shows per-turn cost when expanded.

## Unknown Models

Models not in the pricing table show `$0.00`. To add custom model pricing, submit a PR to `internal/cost/tracker.go`.
```

- [ ] **Step 6: Create guides/notifications.mdx**

```mdx
---
title: Notifications
description: Terminal bell and macOS desktop notifications.
---

## Overview

aimux can notify you when agents need attention: permission prompts, errors, completion, or idle state changes. Notifications work via terminal bell and macOS Notification Center.

## Configuration

```yaml
notifications:
  enabled: true       # master switch
  on_waiting: true    # agent needs permission
  on_error: true      # agent crashed
  on_idle: false      # agent finished a turn
  on_done: true       # agent finished
  sound: false        # macOS notification sound
  bell: true          # terminal bell
  desktop: true       # macOS Notification Center
```

## Events

| Event | Default | When |
|-------|---------|------|
| Waiting | On | Agent needs user permission (tool approval) |
| Error | On | Agent process crashed or errored |
| Idle | Off | Agent finished a turn (noisy if on) |
| Done | On | Agent session completed |

## Muting

Press `m` in the TUI to mute all notifications for the current session. This does not change the config file.
```

- [ ] **Step 7: Create guides/plugins.mdx**

```mdx
---
title: Plugins
description: Plugin system and skill dashboard.
---

## Overview

aimux supports plugins that add custom dashboard tabs to the web UI. Plugins are defined in `~/.aimux/plugins/` and execute shell commands to collect data, which is rendered as tables, charts, and metric rows.

## Skill Dashboard

The built-in Skill Dashboard plugin tracks Claude Code skill usage, correction rates, and learning funnel metrics. It appears as a tab in the web dashboard when skill analytics data is available.

## Plugin Structure

Each plugin is a YAML file in `~/.aimux/plugins/`:

```yaml
name: my-dashboard
tab: My Dashboard
panels:
  - id: metrics
    type: metric-row
    title: Key Metrics
  - id: data-table
    type: table
    title: Data
    sortable: true
    expandable: true
```

## Panel Types

| Type | Description |
|------|-------------|
| `metric-row` | Horizontal row of key-value metric chips |
| `table` | Sortable, expandable data table |
| `bar-chart` | Horizontal bar chart |
| `list` | Simple list of items |

## API

Plugins are served via the web API:

- `GET /api/plugins` - List all registered plugins
- `GET /api/plugins/{name}/data` - Execute plugin and return data
```

- [ ] **Step 8: Create guides/tasks.mdx**

```mdx
---
title: Tasks Integration
description: Google Tasks integration for task-driven agent launches.
---

## Overview

aimux integrates with Google Tasks to enable task-driven agent workflows. View your task lists, launch agents with task context, and track progress.

## Setup

Configure the tasks backend in `~/.aimux/config.yaml`:

```yaml
tasks:
  backend: "auto"        # "auto", "mcp", or "api"
  default_list: ""       # default task list ID
  prompt_template: "Work on the following task: {title}\n\nDetails: {notes}\n\nAdditional instructions: {user_prompt}\n\nWhen done, summarize what you did."
```

### Backends

| Backend | Description |
|---------|-------------|
| `auto` | Tries MCP first, falls back to Google Workspace API |
| `mcp` | Uses an MCP server endpoint for task operations |
| `api` | Uses Google Workspace API directly |

## Web Dashboard

Click the **Tasks** button in the header to open the tasks panel. Features:

- View task lists and tasks
- See task status (needs action / completed)
- Launch an agent directly from a task
- Complete or reopen tasks

### Task-Driven Launch

1. Click "Launch" on a task in the tasks panel
2. Select provider, directory, and model
3. The task title and notes are injected into the agent prompt using the configured template
4. A "Session started by aimux" note is automatically added to the task

## Prompt Template

Customize how task context is passed to agents:

```yaml
tasks:
  prompt_template: "Task: {title}\n\nDetails:\n{notes}\n\nUser input: {user_prompt}"
```

Available placeholders:

| Placeholder | Description |
|-------------|-------------|
| `{title}` | Task title |
| `{notes}` | Task notes/description |
| `{user_prompt}` | Additional user instructions from the launch dialog |
```

- [ ] **Step 9: Verify all guides build**

```bash
cd docs-site && npm run build
```

Expected: build succeeds with all 8 guide pages.

- [ ] **Step 10: Commit**

```bash
git add docs-site/src/content/docs/guides/
git commit -m "feat(docs): add all guide pages"
```

## Task 8: Advanced Pages

**Files:**
- Create: `docs-site/src/content/docs/advanced/adding-a-provider.mdx`
- Create: `docs-site/src/content/docs/advanced/k8s-quickstart.mdx`

- [ ] **Step 1: Convert adding-a-provider.md to .mdx**

Copy `docs/adding-a-provider.md` to `docs-site/src/content/docs/advanced/adding-a-provider.mdx` and add frontmatter:

```mdx
---
title: Adding a Provider
description: How to add a new AI agent provider to aimux.
---
```

Paste the existing content below the frontmatter. No other changes needed; the content is already comprehensive.

- [ ] **Step 2: Convert k8s-quickstart.md to .mdx**

Copy `docs/k8s-quickstart.md` to `docs-site/src/content/docs/advanced/k8s-quickstart.mdx` and add frontmatter:

```mdx
---
title: Kubernetes Quickstart
description: Run AI coding agents on Kubernetes, controlled from your laptop via aimux.
---
```

Paste the existing content below the frontmatter.

- [ ] **Step 3: Verify build**

```bash
cd docs-site && npm run build
```

- [ ] **Step 4: Commit**

```bash
git add docs-site/src/content/docs/advanced/
git commit -m "feat(docs): add advanced pages (provider guide, k8s quickstart)"
```

## Task 9: GitHub Actions Deploy

**Files:**
- Create: `.github/workflows/docs.yml`

- [ ] **Step 1: Create docs.yml workflow**

Create `.github/workflows/docs.yml`:

```yaml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ['docs-site/**']
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: docs-site/package-lock.json
      - run: npm ci
        working-directory: docs-site
      - run: npm run build
        working-directory: docs-site
      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs-site/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
```

- [ ] **Step 2: Commit**

```bash
git add .github/workflows/docs.yml
git commit -m "ci: add GitHub Actions workflow for docs deployment"
```

## Task 10: Final Verification

- [ ] **Step 1: Full build**

```bash
cd docs-site && npm run build
```

Expected: build succeeds, 13 pages in `dist/`.

- [ ] **Step 2: Local preview**

```bash
cd docs-site && npm run preview
```

Open `http://localhost:4321/aimux/`. Verify:

- All 13 pages load and render correctly
- Sidebar navigation works
- Dark/light theme toggle works and matches aimux palette
- Code blocks render with proper syntax highlighting
- Search (Pagefind) indexes all pages
- Links between pages work (especially cross-references in guides)

- [ ] **Step 3: Commit any fixes**

```bash
git add -A docs-site/
git commit -m "fix(docs): final adjustments"
```
