docs: polish README and publish MkDocs site to GitHub Pages

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install MkDocs Material
+        run: pip install mkdocs-material
+
+      - name: Build docs
+        run: mkdocs build
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -16,3 +16,6 @@ node_modules
 
 # Bun
 bun.lockb
+
+# MkDocs build output
+site/

README.md

@@ -6,39 +6,39 @@
 [![CI](https://github.com/dropdevrahul/campy/actions/workflows/ci.yml/badge.svg)](https://github.com/dropdevrahul/campy/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 [![Made with bun](https://img.shields.io/badge/made%20with-bun-black.svg)](https://bun.sh)
+[![Docs](https://img.shields.io/badge/docs-github.io-blue.svg)](https://dropdevrahul.github.io/campy/)
 
-Animated terminal pets for CLI coding agents — Claude Code, OpenCode, Pi, Gemini CLI, Codex CLI, Cursor CLI, Aider.
+**Animated ASCII terminal pets for CLI coding agents.**
 
-[Features](#features) • [Installation](#installation) • [Per-agent setup](#per-agent-setup) • [Slash Commands](#slash-commands) * [Discord](https://discord.gg/aY9Fv5ZRj)
-
-
-</div>
-
-## Demo
+Claude Code · OpenCode · Pi · Gemini CLI · Codex CLI · Cursor CLI · Aider
 
 ![campy demo](./campy.gif)
 
-## Overview
+[Features](#features) • [Installation](#installation) • [Per-agent setup](#per-agent-setup) • [Slash Commands](#slash-commands) • [Docs](https://dropdevrahul.github.io/campy/) • [Discord](https://discord.gg/aY9Fv5ZRj)
+
+</div>
 
-campy brings delightful ASCII pets to your terminal sidebar. Pets animate through states, react to coding events, and display contextual speech bubbles—adding personality to your coding sessions.
+---
 
 ## Features
 
-- **4 Pet Types**: Cat, Hamster, Ghost, and Robot
-- **7 Animation States**: idle, happy, sleeping, eating, playing, excited, sad—with multi-frame animations and blinking
-- **Speech Bubbles**: Context-aware messages ("Edited file!", "Thinking...", "Need a hand?")
-- **Happiness System**: Feed, play, or pet your companion to increase happiness
-- **Event Reactions**: Automatic responses to tool use, file edits, errors, and idle states
-- **Multi-agent**: One CLI + per-agent adapters for Claude Code, OpenCode, Pi, Gemini CLI, Codex CLI, Cursor CLI, and Aider
-- **MCP server**: One stdio server unlocks Gemini / Codex / Cursor at once
+Your pet lives in a terminal sidebar and reacts to what you're doing. It blinks, animates through moods, and drops speech bubbles when something happens — a file gets edited, a command runs, an error fires. There are four pets to choose from (Cat, Hamster, Ghost, Robot), each with seven animation states and a layered blinking system.
+
+- **Four pets, seven states each** — idle, happy, sleeping, eating, playing, excited, sad, all multi-frame animated
+- **Happiness system** — feed (+15), play (+20), or pet (+10) to keep your companion content
+- **Speech bubbles** — context-aware messages like "Edited a file!", "Thinking…", "Need a hand?"
+- **Automatic event reactions** — hooks fire on tool use, file edits, errors, and idle time
+- **One CLI, every agent** — a single `campy` binary with per-agent adapters; no per-agent installs beyond a one-time `campy setup`
+- **MCP server included** — one stdio server wires Gemini CLI, Codex CLI, and Cursor CLI at once
+- **Zero-token for Claude Code** — hooks and the statusline are Bash scripts that run outside the model
 
 ## Installation
 
-> **Prerequisite:** [bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`). The CLI is a single TypeScript file with a `#!/usr/bin/env bun` shebang — no build step.
+**Prerequisite:** [bun](https://bun.sh) (`curl -fsSL https://bun.sh/install | bash`). The CLI is a single TypeScript file with a `#!/usr/bin/env bun` shebang — no build step required.
 
-campy isn't on npm yet. Pick one of these:
+campy isn't on the public npm registry yet. There are two ways to install it:
 
-### Option 1 — install straight from GitHub (recommended)
+### Option 1 — install from GitHub (recommended)
 
 ```bash
 # via bun
@@ -48,101 +48,107 @@ bun add -g github:dropdevrahul/campy
 npm install -g github:dropdevrahul/campy
 ```
 
-This registers `campy` on your `$PATH`. Verify:
+This registers `campy` on your `$PATH`. Verify with:
 
 ```bash
 campy status
 ```
 
 ### Option 2 — clone and symlink
 
+If you'd rather keep the source around to hack on it:
+
 ```bash
 git clone https://github.com/dropdevrahul/campy.git ~/work/campy
 cd ~/work/campy && bun install
 chmod +x cli/campy.ts
-ln -s "$PWD/cli/campy.ts" ~/.bun/bin/campy   # or any dir on $PATH
+ln -s "$PWD/cli/campy.ts" ~/.bun/bin/campy   # or any directory on $PATH
 ```
 
-### Auto-detect & wire every agent you have installed
+### Wire your agents
+
+After installing, run the auto-setup to detect and wire every agent on your machine:
 
 ```bash
 campy setup
 ```
 
-This detects which agents are installed on your machine (`~/.claude`, `~/.gemini`, `~/.codex`, `~/.cursor`, `~/.pi`, `.opencode/`, `.aider.conf.yml`) and wires each natively. Or install for one agent:
+This looks for `~/.claude`, `~/.gemini`, `~/.codex`, `~/.cursor`, `~/.pi`, `.opencode/`, and `.aider.conf.yml`, and wires each natively. To install for one agent specifically:
 
 ```bash
 campy install claude-code   # | opencode | pi | gemini | codex | cursor | aider
 ```
 
-### Render the pet
+### Show the pet
 
 ```bash
-campy watch     # run inline in any terminal
-campy attach    # auto-split a side pane (tmux / zellij / wezterm / kitty)
+campy watch     # full-screen animated pet — run this in a side pane
+campy attach    # auto-split a pane (tmux / zellij / wezterm / kitty)
 ```
 
 ## Per-agent setup
 
-| Agent       | Surface                         | Install                         |
-|-------------|---------------------------------|---------------------------------|
-| Claude Code | statusline + hooks              | `campy install claude-code`     |
-| OpenCode    | native sidebar widget           | `campy install opencode`        |
-| Pi          | native sidebar widget           | `campy install pi`              |
-| Gemini CLI  | MCP tools (inline ASCII card)   | `campy install gemini`          |
-| Codex CLI   | MCP tools (inline ASCII card)   | `campy install codex`           |
-| Cursor CLI  | MCP tools (inline ASCII card)   | `campy install cursor`          |
-| Aider       | `.git/hooks/post-commit`        | `campy install aider`           |
+Different agents have different native surfaces. campy meets each one where it lives:
 
-For agents with no built-in render surface, run `campy attach` in a side pane.
+| Agent       | Surface                          | Install                         |
+|-------------|----------------------------------|---------------------------------|
+| Claude Code | statusline + reactive hooks      | `campy install claude-code`     |
+| OpenCode    | native sidebar widget            | `campy install opencode`        |
+| Pi          | native sidebar widget            | `campy install pi`              |
+| Gemini CLI  | MCP tools (inline ASCII card)    | `campy install gemini`          |
+| Codex CLI   | MCP tools (inline ASCII card)    | `campy install codex`           |
+| Cursor CLI  | MCP tools (inline ASCII card)    | `campy install cursor`          |
+| Aider       | `.git/hooks/post-commit`         | `campy install aider`           |
 
-### Token usage
+For agents that don't have a built-in render surface, `campy attach` spawns a side pane automatically.
 
-The Claude Code adapter is **zero-token** for normal operation. Hooks and the statusline are bash scripts run outside the model. Slash commands (`/campy:feed`, etc.) cost a small prompt when *you* invoke them.
+**Claude Code note:** The adapter is zero-token during normal operation. Hooks and the statusline are Bash scripts that run outside the model. Slash commands (`/campy:feed`, etc.) cost a small prompt only when you explicitly invoke them.
 
 ## Slash Commands
 
-The slash-command prefix depends on the host:
+The prefix depends on which agent you're using:
 
 - **OpenCode / Pi**: `/pet feed`, `/pet play`, `/pet robot`, …
 - **Claude Code**: `/campy:feed`, `/campy:play`, `/campy:pet`, `/campy:switch <pet>`
-- **MCP agents** (Gemini / Codex / Cursor): call the tools `campy_feed`, `campy_play`, `campy_pet`, `campy_switch`, `campy_status`
-
-| Command       | Effect                          |
-|---------------|---------------------------------|
-| `feed`        | Feed your pet (+15 happiness)   |
-| `play`        | Play with your pet (+20 happiness) |
-| `pet`         | Pet your pet (+10 happiness)    |
-| `sleep`       | Put pet to sleep                |
-| `wake`        | Wake pet                        |
-| `status`      | Show mood & happiness           |
-| `switch <pet>` | `cat` \| `hamster` \| `ghost` \| `robot` |
+- **MCP agents** (Gemini / Codex / Cursor): call tools `campy_feed`, `campy_play`, `campy_pet`, `campy_switch`, `campy_status`
+
+| Command          | Effect                               |
+|------------------|--------------------------------------|
+| `feed`           | Feed your pet (+15 happiness)        |
+| `play`           | Play with your pet (+20 happiness)   |
+| `pet`            | Pet your pet (+10 happiness)         |
+| `sleep`          | Put the pet to sleep                 |
+| `wake`           | Wake the pet                         |
+| `status`         | Show current mood and happiness      |
+| `switch <name>`  | `cat` \| `hamster` \| `ghost` \| `robot` |
 
 ## Available Pets
 
-| Pet | States | Blinking | Emoji |
-|-----|--------|----------|-------|
-| Cat | 7 states | Yes (layered eyes) | 🐱 |
-| Hamster | 7 states | Yes (frame-step) | 🐹 |
-| Ghost | 7 states | Yes (layered eyes) | 👻 |
-| Robot | 7 states | Yes (layered eyes) | 🤖 |
+| Pet     | Emoji | States | Blinking        |
+|---------|-------|--------|-----------------|
+| Cat     | 🐱    | 7      | Layered eyes    |
+| Hamster | 🐹    | 7      | Frame-step      |
+| Ghost   | 👻    | 7      | Layered eyes    |
+| Robot   | 🤖    | 7      | Layered eyes    |
+
+All pets cycle through: idle, happy, sleeping, eating, playing, excited, sad.
 
 ## File Structure
 
 ```
-core/             # portable pet logic (animation, store, runtime, render)
-cli/campy.ts      # the campy binary (bun)
+core/             # portable pet logic — animation, store, runtime, render
+cli/campy.ts      # the campy binary (bun, no build step)
 adapters/
 ├── claude-code/  # hooks + statusline + slash commands
 ├── pi/           # in-process TUI widget
 ├── mcp/          # stdio MCP server (Gemini / Codex / Cursor)
 └── gemini/       # gemini-extension.json + GEMINI.md
-.opencode/        # OpenCode plugins (re-export from core/)
-.claude-plugin/   # Claude Code marketplace manifest
+.opencode/        # OpenCode plugins (thin re-exports of core/)
+.claude-plugin/   # Claude Code plugin marketplace manifest
 ghost-pet/        # legacy standalone Bash plugin (kept for back-compat)
 ```
 
-See `CLAUDE.md` for the full architecture, and `docs/superpowers/specs/2026-06-13-cli-agent-support-design.md` for the multi-agent design spec.
+The full architecture is in [`CLAUDE.md`](./CLAUDE.md). The multi-agent design spec lives at `docs/superpowers/specs/2026-06-13-cli-agent-support-design.md`.
 
 ## License
 

docs/agents.md

@@ -0,0 +1,71 @@
+# Agents
+
+campy supports seven agents. Each one is wired through its own native extension surface so the pet shows up where you're actually looking while you code.
+
+## Supported agents
+
+| Agent       | Surface                          | Install command                 |
+|-------------|----------------------------------|---------------------------------|
+| Claude Code | statusline + reactive hooks      | `campy install claude-code`     |
+| OpenCode    | native sidebar widget            | `campy install opencode`        |
+| Pi          | native sidebar widget            | `campy install pi`              |
+| Gemini CLI  | MCP tools (inline ASCII card)    | `campy install gemini`          |
+| Codex CLI   | MCP tools (inline ASCII card)    | `campy install codex`           |
+| Cursor CLI  | MCP tools (inline ASCII card)    | `campy install cursor`          |
+| Aider       | `.git/hooks/post-commit`         | `campy install aider`           |
+
+For agents without a built-in render surface, `campy attach` spawns a side pane in your terminal multiplexer.
+
+## Claude Code
+
+Claude Code is wired via the plugin marketplace. The adapter installs two reactive hooks (`PostToolUse` and `Stop`) and a `SessionStart` hook, plus a statusline script. Hooks are Bash scripts that run outside the model — they call the campy CLI to mutate pet state. The statusline renders the current pet inline.
+
+```bash
+campy install claude-code
+```
+
+!!! note "Zero-token operation"
+    Hooks and the statusline never touch the model. Slash commands (`/campy:feed`, etc.) cost a small prompt only when you invoke them explicitly.
+
+Available slash commands: `/campy:feed`, `/campy:play`, `/campy:pet`, `/campy:switch <pet>`.
+
+## OpenCode and Pi
+
+OpenCode and Pi both support in-process TUI widgets. campy ships a native sidebar plugin that registers at `order: 350` in the sidebar slot and reacts to OpenCode events (`file.edited`, `command.executed`, `session.error`, `session.idle`, `message.part.delta`, `tui.prompt.append`).
+
+```bash
+campy install opencode
+campy install pi
+```
+
+Slash commands use the `/pet` prefix: `/pet feed`, `/pet play`, `/pet cat`, etc.
+
+## Gemini CLI, Codex CLI, Cursor CLI
+
+These agents support MCP (Model Context Protocol). campy runs a stdio MCP server that watches the project directory for file edits, fires `file_edited` events automatically, and exposes five tools:
+
+| Tool             | Effect                         |
+|------------------|--------------------------------|
+| `campy_feed`     | Feed the pet (+15 happiness)   |
+| `campy_play`     | Play with the pet (+20)        |
+| `campy_pet`      | Pet the pet (+10)              |
+| `campy_switch`   | Switch to a different pet      |
+| `campy_status`   | Get current state as ASCII card |
+
+```bash
+campy install gemini   # writes ~/.gemini/extensions/campy/
+campy install codex    # adds [mcp_servers.campy] to ~/.codex/config.toml
+campy install cursor   # updates ~/.cursor/mcp.json
+```
+
+The MCP server is started with `campy mcp`.
+
+## Aider
+
+Aider is wired via a `post-commit` git hook that fires `file_edited` events after each commit.
+
+```bash
+campy install aider
+```
+
+Since Aider has no built-in widget surface, run `campy attach` or `campy watch` in a side pane to see the pet.