aidocs 0.18.0
AI-powered documentation generator for web applications. Install docs commands into your Claude Code project.
License: MIT
Requires Python: >=3.11
Keywords: ai, automation, claude, documentation, playwright

# aidocs

AI-powered documentation generator for web applications.

[![Watch the video](https://img.youtube.com/vi/cmwt4XizcTw/maxresdefault.jpg)](https://youtu.be/cmwt4XizcTw)

▶️ **[Watch the demo on YouTube](https://youtu.be/cmwt4XizcTw)**

## How It Works

aidocs generates comprehensive documentation by combining **three sources of truth**:

1. **Vision Analysis** - Playwright captures screenshots, Claude analyzes what users actually see
2. **Codebase Analysis** - Scans your frontend components, backend routes, validation rules, and models
3. **Interactive Exploration** - Clicks buttons, fills forms, discovers conditional UI and validation messages

This produces documentation that's accurate to both the code AND the actual user experience.

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  📸 Screenshots │  +  │  📄 Code Analysis │  +  │  🖱️ UI Testing   │
│  (what users    │     │  (validation,     │     │  (conditional   │
│   see)          │     │   routes, models) │     │   fields, flows)│
└────────┬────────┘     └────────┬─────────┘     └────────┬────────┘
         │                       │                        │
         └───────────────────────┼────────────────────────┘
                                 ▼
                    ┌────────────────────────┐
                    │  📚 Smart Documentation │
                    │  that stays in sync    │
                    └────────────────────────┘
```

## Quick Start

```bash
# 1. Install the CLI
brew install binarcode/aidocs/aidocs

# 2. Add to your project
cd your-project
aidocs init .

# 3. Generate docs (in Claude Code)
/docs:generate https://myapp.com/dashboard
```

**Alternative installation:**
```bash
# Homebrew (macOS/Linux)
brew install binarcode/aidocs/aidocs

# uv (recommended for Python users)
uv tool install aidocs

# pipx
pipx install aidocs

# From GitHub (latest)
uv tool install aidocs --from git+https://github.com/binarcode/aidocs-cli.git
```

**Updating:**
```bash
brew upgrade aidocs            # Homebrew
aidocs update                  # PyPI (uv/pipx/pip)
aidocs update --github         # GitHub (latest)
aidocs init . --force          # Reinstall commands in project
```

## Usage Flow

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                              SETUP (once)                                    │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  $ aidocs init .                    Install commands into project            │
│           │                                                                  │
│           ▼                                                                  │
│  /docs:init                         Configure: name, auth, style, output     │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                    OPTION A: Document a Single Page                          │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  /docs:generate https://myapp.com/users    ← Give it any URL!                │
│           │                                                                  │
│           ├──→ Takes screenshots with Playwright                             │
│           ├──→ Analyzes codebase for that route                              │
│           ├──→ Documents UI elements and interactions                        │
│           └──→ Creates docs/users/index.md                                   │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                    OPTION B: Document a Code Flow                            │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  /docs:flow "sync users from discord"    ← Describe the flow in words!       │
│           │                                                                  │
│           ├──→ Searches codebase for relevant files                          │
│           ├──→ Traces execution path and builds call graph                   │
│           ├──→ Generates mermaid sequence diagram                            │
│           ├──→ Captures UI screenshots (if Playwright + route detected)      │
│           └──→ Creates docs/flows/sync-users-from-discord.md                 │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                    OPTION C: Document Entire Project                         │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  /docs:discover                     Scan codebase, find all modules          │
│           │                                                                  │
│           ▼                                                                  │
│  /docs:plan                         Create ordered documentation plan        │
│           │                         → Outputs docs/plan.yml                 │
│           ▼                                                                  │
│  /docs:execute                      Run through plan, generate all docs      │
│                                     → Resume with --continue if interrupted  │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                         KEEP DOCS IN SYNC                                    │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  # After implementing a feature:                                             │
│  /docs:update --base main           Detect changes, update affected docs     │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌──────────────────────────────────────────────────────────────────────────────┐
│                      ENABLE SEMANTIC SEARCH (optional)                       │
├──────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  # After docs are generated, setup RAG for AI-powered search:                │
│  /docs:rag                          ← One command does it all!               │
│           │                                                                  │
│           ├──→ Chunks your docs into searchable pieces                       │
│           ├──→ Creates database migration (pgvector)                         │
│           ├──→ Generates OpenAI embeddings                                   │
│           └──→ Outputs sync.sql ready to import                              │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
```

### Quick Commands

```bash
# Simple: Generate docs for one page
/docs:generate https://myapp.com/dashboard

# Flow: Document a feature (user-focused by default)
/docs:flow "how to create employees"
/docs:flow "import payments" --technical    # Developer docs

# Batch: Document entire project
/docs:discover && /docs:plan && /docs:execute

# Maintain: Update after code changes
/docs:update --base main

# RAG: Setup semantic search for your docs
/docs:rag
```

## CLI Commands

### `aidocs init [PROJECT_NAME]`

Initialize the docs module in a project.

```bash
aidocs init .                  # Current directory
aidocs init my-project         # New directory
aidocs init . --force          # Overwrite existing
aidocs init . --ai cursor      # Use with Cursor
```

**Options:**
| Option | Description |
|--------|-------------|
| `--ai` | AI assistant: `claude`, `cursor`, `copilot` (default: `claude`) |
| `--force, -f` | Overwrite existing files |
| `--no-git` | Skip git initialization |

### `aidocs check`

Check for required tools and dependencies.

```bash
aidocs check
```

### `aidocs version`

Show version information.

### `aidocs update`

Update aidocs to the latest version.

```bash
aidocs update              # Update from PyPI
aidocs update --github     # Update from GitHub (latest)
```

**Options:**
| Option | Description |
|--------|-------------|
| `--github` | Install latest from GitHub instead of PyPI |

Automatically detects and uses the appropriate package manager (uv, pipx, or pip).

### `aidocs rag`

Prepare documentation for RAG: chunk files and generate embeddings in one command.

```bash
aidocs rag                      # Chunk and generate embeddings
aidocs rag docs/users           # Specific directory
aidocs rag --dry                # Preview only
aidocs rag --force              # Re-process everything
aidocs rag --skip-vectors       # Only chunk, no embeddings
```

**Options:**
| Option | Description |
|--------|-------------|
| `--force, -f` | Re-chunk and re-sync all files |
| `--dry` | Preview without making changes |
| `--table, -t` | Target table name (default: `doc_embeddings`) |
| `--skip-vectors` | Only chunk files, skip embedding generation |

**What it does:**
1. Chunks markdown files at `##` headings (creates `.chunks.json` files)
2. Generates embeddings via OpenAI API (requires `OPENAI_API_KEY`)
3. Creates `docs/.chunks/sync.sql` for database import

**Workflow:**
```bash
# Prepare docs for MCP server
aidocs rag docs/

# Start MCP server
aidocs mcp docs/
```

**Note:** If `OPENAI_API_KEY` is not set, chunking completes but embeddings are skipped. The MCP server works with just chunks (keyword search).

**Environment:** Reads `OPENAI_API_KEY` from `.env` file in current directory or global environment.

### `aidocs rag-chunks`

Chunk markdown files for vector database import.

```bash
aidocs rag-chunks                   # Chunk all files in docs/
aidocs rag-chunks docs/users        # Chunk specific directory
aidocs rag-chunks --force           # Re-chunk all files
aidocs rag-chunks --dry             # Preview only
```

**Options:**
| Option | Description |
|--------|-------------|
| `--force, -f` | Re-chunk all files (ignore cache) |
| `--dry` | Preview without writing files |

**What it does:**
1. Scans directory for `.md` files
2. Splits at `##` headings into chunks
3. Creates `.chunks.json` files alongside each `.md`
4. Maintains `docs/.chunks/manifest.json` for change tracking

**Output structure:**
```
docs/
├── users/
│   ├── lifecycle.md
│   └── lifecycle.chunks.json    # Chunks for this file
├── campaigns/
│   ├── lifecycle.md
│   └── lifecycle.chunks.json
└── .chunks/
    └── manifest.json            # Tracking file
```

**Next step:** Run `aidocs rag-vectors` to generate embeddings

### `aidocs export-pdf`

Export markdown documentation to PDF with auto-generated table of contents.

```bash
aidocs export-pdf docs/projects/index.md                    # Export to docs/exports/
aidocs export-pdf docs/flows/sync-users.md -o manual.pdf    # Custom output path
```

**Options:**
| Option | Description |
|--------|-------------|
| `--output, -o` | Output PDF path (default: `docs/exports/{name}.pdf`) |

**What it does:**
1. Reads the markdown file
2. Extracts H1/H2 headings for table of contents
3. Converts markdown to styled HTML
4. Uses Chrome/Chromium headless to render PDF
5. Saves with proper page breaks and formatting

**Output:**
```
╭──────────── Success ────────────╮
│ PDF exported successfully!      │
│                                 │
│ Title: Projects Overview        │
│ TOC entries: 8                  │
│ Size: 245.3 KB                  │
│                                 │
│ Output: docs/exports/index.pdf  │
╰─────────────────────────────────╯
```

**Requirements:**
- Chrome or Chromium installed (uses headless mode)

### `aidocs rag-vectors`

Generate embeddings and SQL for vector database import.

```bash
aidocs rag-vectors                  # Generate embeddings and SQL
aidocs rag-vectors --dry            # Preview what would be synced
aidocs rag-vectors --force          # Re-sync all files
aidocs rag-vectors --table my_docs  # Custom table name
```

**Options:**
| Option | Description |
|--------|-------------|
| `--force, -f` | Re-sync all files (ignore last sync) |
| `--dry` | Preview without generating embeddings |
| `--table, -t` | Target table name (default: `doc_embeddings`) |

**Requires:** `OPENAI_API_KEY` (from `.env` file or environment variable)

**What it does:**
1. Reads chunk files from `docs/.chunks/`
2. Calls OpenAI API to generate embeddings (text-embedding-3-small)
3. Creates `docs/.chunks/sync.sql` with INSERT statements
4. Tracks sync state to avoid re-processing unchanged files

**Output:** `docs/.chunks/sync.sql`

```sql
BEGIN;
INSERT INTO doc_embeddings (file_path, content, chunk_index, title, metadata, embedding)
VALUES ('docs/users/lifecycle.md', '...', 0, 'Overview', '{...}'::jsonb, '[0.001, ...]'::vector);
-- ... more inserts
COMMIT;
```

**Import to database:**
```bash
psql $DATABASE_URL -f docs/.chunks/sync.sql
```

### `aidocs serve`

Serve documentation with live reload using MkDocs Material theme.

![aidocs serve](docs/aidocs-serve.png)

```bash
aidocs serve                    # Serve docs/ on port 8000
aidocs serve --port 3000        # Custom port
aidocs serve docs/users         # Serve specific subdirectory
aidocs serve --build            # Build static site only
aidocs serve --build -o ./site  # Build to custom output
aidocs serve --no-open          # Don't auto-open browser
```

**Options:**
| Option | Description |
|--------|-------------|
| `--port, -p` | Port to serve on (default: 8000) |
| `--host` | Host to bind to (default: 127.0.0.1) |
| `--open/--no-open` | Open browser automatically (default: --open) |
| `--build, -b` | Build static site only, no server |
| `--output, -o` | Output directory for built site |

**Features:**
- Auto-generates navigation from folder structure
- Material Design theme with light/dark mode
- Live reload when files change
- Full-text search
- Code syntax highlighting

### `aidocs mcp`

Start a local MCP server to expose documentation via tools. Allows Claude Code and other MCP clients to search and read your docs.

```bash
aidocs mcp                      # Serve docs/ directory
aidocs mcp docs/users           # Serve specific subdirectory
```

**MCP Tools exposed:**

| Tool | Description |
|------|-------------|
| `list_docs` | List all documentation files with chunk counts |
| `search_docs` | Search through documentation by keyword |
| `read_doc` | Read full content of a file or specific chunk |
| `get_doc_structure` | Get heading hierarchy for navigation |

**Configuration (`.mcp.json`):**

```json
{
  "mcpServers": {
    "aidocs": {
      "command": "aidocs",
      "args": ["mcp", "docs/"]
    }
  }
}
```

**Features:**
- Works without pre-chunking (chunks markdown on-the-fly if needed)
- Uses existing `.chunks.json` files if available (faster)
- Keyword search with weighted scoring (title matches weighted 3x)
- Returns content previews and hierarchy context

**Example search result:**
```json
{
  "file_path": "users/lifecycle.md",
  "chunk_index": 2,
  "title": "Creating Users",
  "hierarchy": ["Users", "Creating Users"],
  "content_preview": "To create a new user, navigate to...",
  "score": 12
}
```

**Usage Examples in Claude Code:**

Once configured, Claude Code can use these tools automatically. You can prompt:

```
# Search documentation
"Search our docs for authentication setup"
"Find documentation about API rate limits"

# Read specific docs
"Read the user lifecycle documentation"
"Show me the API reference section"

# Explore structure
"What documentation do we have?"
"List all docs about payments"
```

**Best Practices:**

1. **Prepare docs first** - Run `aidocs rag docs/` before starting MCP server for faster searches
2. **Use descriptive headings** - The MCP chunks at `##` headings, clear titles improve search
3. **Keep docs updated** - Re-run `aidocs rag --force` after major doc changes
4. **Project-level config** - Add `.mcp.json` to your repo so the team shares the same setup
5. **Combine with code context** - Ask Claude to "check our docs for X" while reviewing code

**Troubleshooting:**

| Issue | Solution |
|-------|----------|
| MCP not connecting | Restart Claude Code or run `/mcp` to reload servers |
| Empty search results | Ensure docs directory has `.md` files |
| Slow searches | Run `aidocs rag` to pre-chunk files |

### `aidocs watch`

Watch documentation directory for changes and automatically re-chunk files and regenerate embeddings.

```bash
aidocs watch                    # Watch docs/ with auto-embeddings
aidocs watch --with-vectors     # Generate also embeddings
aidocs watch --debounce 5       # Wait 5 seconds before processing
aidocs watch docs/users         # Watch specific subdirectory
```

**Options:**
| Option | Description |
|--------|-------------|
| `--with-vectors` | Include embedding generation |
| `--debounce, -d` | Seconds to wait after last change (default: 10) |
| `--table, -t` | Target table name for embeddings (default: `doc_embeddings`) |

**What it does:**
1. Monitors the docs directory for `.md` file changes
2. Debounces rapid changes (waits 10 seconds after last edit by default)
3. Re-chunks modified files automatically
4. Generates embeddings if `OPENAI_API_KEY` is set (use `--with-vectors` to enable)
5. Updates manifest and sync state

**Real-time display:**
```
╭─────────────────────────────────────────╮
│ Watching docs/                          │
│                                         │
│ Last update: 14:32:05                   │
│ Files: 12 | Chunks: 45 | Embeddings: 45 │
│                                         │
│ Embeddings: enabled                     │
│                                         │
│ Recent:                                 │
│   ✓ users/index.md (3 chunks)          │
│   ✓ api/auth.md (5 chunks)             │
│                                         │
│ Press Ctrl+C to stop                    │
╰─────────────────────────────────────────╯
```

**Use cases:**
- Keep chunks updated while editing documentation
- Auto-sync embeddings during documentation sprints
- Run alongside `aidocs serve` for a complete dev workflow

**Example workflow:**
```bash
# Terminal 1: Watch for changes
aidocs watch

# Terminal 2: Serve documentation
aidocs serve

# Edit docs in your editor - changes auto-sync!
```

### `aidocs coverage`

Analyze documentation coverage for your codebase. Scans for routes, components, and models, then checks which items are mentioned in your documentation.

```bash
aidocs coverage                     # Show coverage summary
aidocs coverage --format json       # Machine-readable output
aidocs coverage --format csv        # CSV export
aidocs coverage --ci                # Exit code 1 if below 80%
aidocs coverage --threshold 70      # Custom threshold
aidocs coverage -c ./src            # Specify codebase path
aidocs coverage --all               # Show all items
```

**Options:**
| Option | Description |
|--------|-------------|
| `--codebase, -c` | Path to codebase root (default: parent of docs dir) |
| `--format, -f` | Output format: `summary`, `json`, or `csv` |
| `--threshold, -t` | Minimum coverage percentage (exit 1 if below) |
| `--ci` | CI mode: exit 1 if coverage below 80% |
| `--save/--no-save` | Save report to `.chunks/coverage.json` (default: save) |
| `--all, -a` | Show all items (documented and undocumented) |

**Example output:**
```
╭───────────────────────────────────────────────╮
│ Documentation Coverage Report                 │
│ ───────────────────────────────────────────── │
│                                               │
│   Routes:       12/15  ( 80%)  █████████░░░   │
│   Components:    8/20  ( 40%)  ████░░░░░░░░   │
│   Models:        5/5   (100%)  ████████████   │
│                                               │
│   Overall:    25/40  (63%)  ███████░░░░░      │
╰───────────────────────────────────────────────╯

Missing documentation:
  Routes:
    ✗ POST /api/webhooks/stripe
      src/app/api/webhooks/stripe/route.ts:1
  Components:
    ✗ PaymentForm
      src/components/PaymentForm.tsx:1
```

**Supported frameworks:**
- **Next.js** - App Router routes and pages
- **React** - Function and class components
- **Vue/Svelte** - Single-file components
- **Express** - Route handlers
- **FastAPI/Flask** - Python API routes
- **Laravel** - PHP routes
- **Prisma** - Database models
- **TypeScript** - Interfaces and types

**CI/CD integration:**
```yaml
# GitHub Actions example
- name: Check documentation coverage
  run: aidocs coverage --ci
```

## Slash Commands

After running `aidocs init`, these commands are available in Claude Code:

| Command | Description | Requires Playwright |
|---------|-------------|---------------------|
| `/docs:init` | Configure project settings, credentials, output style | No |
| `/docs:generate <url>` | Generate docs for a single page with screenshots | Yes |
| `/docs:analyze <route>` | Analyze codebase for a route (no browser) | No |
| `/docs:batch` | Generate docs for multiple pages | Yes |
| `/docs:update` | Update docs based on git diff | Optional |
| `/docs:discover` | Scan codebase, discover all modules | No |
| `/docs:plan` | Create ordered documentation plan | No |
| `/docs:execute` | Execute plan, generate all docs | Yes |
| `/docs:explore <module>` | Interactive UI exploration with Playwright | Yes |
| `/docs:flow "<description>"` | Document a feature with screenshots (use `--technical` for dev docs) | Optional |
| `/docs:rag-vectors` | Generate embeddings and SQL for vector DB import | No |
| `/docs:rag-init` | Generate database migration for vector embeddings | No |
| `/docs:rag` | Setup RAG: chunks → migration → embeddings (all-in-one) | No |
| `/docs:export-pdf` | Export markdown documentation to PDF with TOC | Yes (Playwright) |

### `/docs:init`

Interactive setup wizard that:
- Detects your tech stack (Laravel, Vue, React, Next.js, etc.)
- Asks for project name, audience, and documentation tone
- Configures authentication method (file, env vars, or manual)
- Sets output directory and screenshot preferences

### `/docs:generate <url>`

Generate documentation for a single page:

```bash
/docs:generate https://myapp.com/campaigns
/docs:generate /campaigns                      # Uses base URL from config
/docs:generate /settings --auth user:pass      # With authentication
```

**Features:**
- Captures full-page screenshots
- Analyzes UI elements visually
- Searches codebase for related code
- Detects forms, buttons, and interactive elements
- Offers to document user flows step-by-step

### `/docs:update`

Update existing documentation based on code changes:

```bash
/docs:update                    # Compare against main
/docs:update --base staging     # Compare against staging branch
/docs:update --dry-run          # Preview changes without applying
/docs:update --screenshots      # Also refresh screenshots
```

**What it does:**
1. Gets git diff between current branch and base
2. Analyzes changed frontend/backend files
3. Maps code changes to affected features
4. Finds and updates related documentation
5. Optionally refreshes screenshots
6. Offers to stage/commit doc changes

**Perfect for:** Running before creating a PR to ensure docs stay in sync with code.

### `/docs:analyze <route>`

Analyze codebase without browser automation:

```bash
/docs:analyze /campaigns
/docs:analyze /api/users
```

### `/docs:batch`

Generate documentation for multiple pages:

```bash
/docs:batch urls.txt                           # From file
/docs:batch --discover --base-url https://myapp.com  # Auto-discover routes
```

### `/docs:discover`

Scan your codebase to discover all modules and their structure:

```bash
/docs:discover                     # Discover all modules
/docs:discover --dry               # Preview without saving
/docs:discover campaigns           # Analyze only one module
```

**What it analyzes:**
- Backend: Models, controllers, routes, validation rules
- Frontend: Pages, components, forms, state management
- Relationships: Foreign keys, ORM relationships, cross-module navigation

**Creates `docs/.knowledge/` with:**
```
docs/.knowledge/
├── _meta/
│   ├── project.json              # Project-level info
│   └── modules-index.json        # List of discovered modules
├── modules/
│   ├── campaigns/
│   │   ├── entity.json           # Fields, types, relationships
│   │   ├── routes.json           # API endpoints
│   │   ├── components.json       # UI components
│   │   └── validation.json       # Validation rules
│   └── users/
│       └── ...
└── relationships/                # Cross-module relationships
```

**Next step:** Run `/docs:plan` to create documentation plan

### `/docs:plan`

Create an ordered documentation plan based on discovered modules:

```bash
/docs:plan                         # Create plan interactively
/docs:plan --auto                  # Auto-generate plan (no prompts)
/docs:plan --show                  # Show existing plan
```

**What it does:**
1. Reads discovered modules from `docs/.knowledge/`
2. Analyzes dependencies and relationships
3. Suggests documentation order (core modules first)
4. Creates `docs/plan.yml` with the plan

**Output: `docs/plan.yml`**
```yaml
modules:
  - name: users
    priority: 1
    reason: "Core module - other modules depend on it"
    document:
      lifecycle: true
      include_errors: true
    status: pending

  - name: campaigns
    priority: 2
    document:
      lifecycle: true
      flows:
        - "duplicate campaign"
    status: pending

cross_module_flows:
  - name: "user registration to first campaign"
    modules: [users, campaigns]
    status: pending
```

**Next step:** Run `/docs:execute` to generate documentation

### `/docs:execute`

Execute the documentation plan and generate all docs:

```bash
/docs:execute                      # Execute full plan
/docs:execute --module campaigns   # Execute only one module
/docs:execute --continue           # Continue from where it stopped
/docs:execute --dry                # Preview what would be generated
```

**What it does:**
1. Reads `docs/plan.yml`
2. For each module in order:
   - Runs explore (if needed)
   - Generates lifecycle documentation
   - Captures screenshots
   - Writes to `docs/{module}/`
3. Updates plan status as it progresses
4. Generates cross-module flows last

**Output structure:**
```
docs/
├── index.md                    # Auto-generated with links
├── users/
│   ├── index.md               # Module overview
│   ├── lifecycle.md           # CRUD documentation
│   ├── user-registration-to-campaign.md  # Cross-module flow (first module)
│   └── images/
└── campaigns/
    ├── index.md
    ├── lifecycle.md
    ├── duplicate-campaign.md  # Custom flow
    └── images/
```

**Resume support:** If execution stops, run `/docs:execute --continue` to resume

### `/docs:explore <module>`

Interactively explore a module's UI with Playwright:

```bash
/docs:explore campaigns                    # Explore all campaign pages
/docs:explore users --page /users/create   # Specific page
/docs:explore orders --depth deep          # Thorough exploration
```

**What it discovers:**
- Conditional fields (checkbox reveals more inputs)
- Validation messages (tries invalid data)
- UI state changes (what happens when you click)
- Cross-page effects (create here → appears there)

### `/docs:flow "<description>"`

Document a feature with screenshots and step-by-step instructions. By default, creates **user-focused** documentation. Use `--technical` for developer documentation.

```bash
/docs:flow "how to create employees"              # User guide with screenshots
/docs:flow "import payments from csv"             # User guide with screenshots
/docs:flow "payment processing" --technical       # Developer docs with code
/docs:flow "stripe webhooks" --technical          # Developer docs with code
/docs:flow "user registration" --no-screenshots   # Skip screenshots
```

**Arguments:**
- `--technical` - Generate developer-focused documentation with code snippets
- `--no-screenshots` - Skip UI screenshot capture

**Output modes:**

| Mode | Audience | Output |
|------|----------|--------|
| Default | End users | Screenshots, plain English, step-by-step guide |
| `--technical` | Developers | Code snippets, file paths, mermaid diagrams |

**Output:** `docs/flows/{kebab-case-title}.md`

**Example: User-focused (default)**

```markdown
# How to Import Payments

Import payment records from a CSV file.

## Before You Start
- Prepare a CSV with columns: date, amount, description
- Maximum 10,000 rows per import

## Steps

### Step 1: Go to Payroll
Navigate to **Payroll** from the sidebar.

![Payroll Page](./images/payroll-page.png)

### Step 2: Click Import
Click the **Import Payments** button.

![Import Button](./images/import-button.png)

### Step 3: Upload Your File
Select your CSV file and click **Start Import**.

## What Happens Next
- Import runs in background
- You'll receive an email when complete
```

**Example: Technical (`--technical`)**

```markdown
# Import Payments Flow

## Architecture
sequenceDiagram: User → Controller → Job → Database

## Entry Points
| Trigger | Route |
|---------|-------|
| UI | POST /payroll/import |
| CLI | php artisan payments:import |

## Execution Flow

**File:** `app/Http/Controllers/PayrollController.php:45`
public function import(Request $request) { ... }

**File:** `app/Jobs/ImportPaymentsJob.php:28`
public function handle() { ... }
```

**Screenshots require:**
- Playwright MCP installed
- `urls.base` configured in `docs/config.yml`

### `/docs:rag-vectors`

Generate embeddings and SQL for syncing documentation to a PostgreSQL vector database.

```bash
/docs:rag-vectors                    # Generate sync SQL (smart)
/docs:rag-vectors --dry              # Preview what would be synced
/docs:rag-vectors --force            # Re-sync all files
```

**Prerequisites:**
- Run `aidocs rag-chunks` first to create chunk files
- Set `OPENAI_API_KEY` environment variable

**What it does:**
1. Reads chunk files from `docs/.chunks/manifest.json`
2. Compares against last sync to find changes
3. Generates embeddings via OpenAI API (only for new/changed chunks)
4. Creates `docs/.chunks/sync.sql` with INSERT statements

**Smart sync:**
- Unchanged files → Skip (no API calls)
- Changed files → Re-generate embeddings
- New files → Generate embeddings
- Deleted files → Add DELETE statements

**Output:**
```
📊 Sync Summary:
   Unchanged: 12 files (skipped)
   Changed: 2 files (8 chunks)
   New: 1 file (3 chunks)

📄 Generated: docs/.chunks/sync.sql

Run with:
   psql $DATABASE_URL -f docs/.chunks/sync.sql
```

### `/docs:rag-init`

Generate a database migration for storing documentation embeddings with pgvector.

```bash
/docs:rag-init                     # Default: 1536 dimensions
/docs:rag-init --dimensions 3072   # For text-embedding-3-large
/docs:rag-init --table my_docs     # Custom table name
```

**What it does:**
1. Detects your framework (Laravel, Prisma, TypeORM, Drizzle, Django)
2. Generates the appropriate migration file
3. Creates table with pgvector support for similarity search

**Supported Frameworks:**

| Framework | Detection | Output |
|-----------|-----------|--------|
| Laravel | `composer.json` | PHP migration with `$table->vector()` |
| Prisma | `schema.prisma` | Prisma schema addition |
| TypeORM | `package.json` | TypeScript migration class |
| Drizzle | `drizzle-orm` | Schema + SQL migration |
| Django | `manage.py` | Django migration with pgvector |
| Fallback | None detected | Raw PostgreSQL SQL |

**Table Structure:**

```
doc_embeddings
├── id             UUID PRIMARY KEY
├── file_path      VARCHAR(500)      # Path to .md file
├── content        TEXT              # Document content
├── chunk_index    INTEGER           # For large docs split into chunks
├── title          VARCHAR(255)      # Document title
├── metadata       JSONB             # Tags, module, category, etc.
├── embedding      VECTOR(1536)      # OpenAI embedding
├── created_at     TIMESTAMP
└── updated_at     TIMESTAMP
```

**Indexes:**
- `file_path` - B-tree index for path lookups
- `embedding` - HNSW index for fast vector similarity search

**Requirements:**
- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) extension

**Example workflow:**
```bash
# 1. Generate migration
/docs:rag-init

# 2. Run migration
php artisan migrate          # Laravel
npx prisma migrate dev       # Prisma
python manage.py migrate     # Django

# 3. Chunk your docs
aidocs rag-chunks

# 4. Generate embeddings and sync
aidocs rag-vectors
```

### `/docs:rag`

**The easy way** - Setup RAG (Retrieval Augmented Generation) for your documentation in one command:

```bash
/docs:rag                     # Full setup
/docs:rag --skip-migration    # Skip migration (table already exists)
/docs:rag --force             # Re-chunk and re-sync everything
/docs:rag --dry               # Preview what would happen
```

**What it does automatically:**
1. Checks/creates documentation chunks (`aidocs rag-chunks`)
2. Generates database migration (`/docs:rag-init`)
3. Prompts you to run the migration
4. Generates embeddings and SQL (`aidocs rag-vectors`)

**Output:**
```
✅ RAG Setup Complete!

📊 Summary:
   Documentation files: 8
   Chunks created: 24
   Embeddings generated: 24

📄 Files created:
   ✓ docs/.chunks/manifest.json
   ✓ database/migrations/..._create_doc_embeddings_table.php
   ✓ docs/.chunks/sync.sql

🚀 Final step:
   psql $DATABASE_URL -f docs/.chunks/sync.sql
```

**Requirements:**
- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) extension
- `OPENAI_A