feat: Complete documentation site with VitePress

## Context

Arandu has mature features (Whisper, ACP Workspace, Document Review) but no formal documentation beyond internal READMEs. This issue tracks the creation of a comprehensive documentation site using VitePress, inspired by the Vue.js docs structure and devi.tools aesthetic, deployed to `docs.arandu.app` via Cloudflare Pages + GitHub Pages.

---

## Project Structure

```
docs/
├── package.json                    # Isolated (no root package.json in the monorepo)
├── .vitepress/
│   ├── config.ts                   # Central config with locales
│   ├── locales/
│   │   ├── pt-BR.ts               # Sidebar, nav, labels in Portuguese
│   │   └── en.ts                   # Sidebar, nav, labels in English
│   └── theme/
│       ├── index.ts                # Extends default theme
│       └── custom.css              # Brand colors (purple/gold), typography
├── public/
│   ├── icon.svg                    # Copied from shared/icon.svg
│   ├── favicon-32x32.png           # Copied from website/
│   └── apple-touch-icon.png        # Copied from website/
├── index.md                        # pt-BR home (layout: home)
├── guia/
│   ├── introducao.md               # What it is, pronunciation, philosophy
│   ├── instalacao.md               # Homebrew, manual download, all OS
│   ├── inicio-rapido.md            # First steps
│   ├── visualizando-markdown.md    # GFM, syntax highlighting
│   ├── navegacao.md                # Outline sidebar, smooth scroll
│   ├── temas.md                    # Light/dark/system
│   └── atalhos.md                  # Keyboard shortcuts
├── funcionalidades/
│   ├── markdown.md                 # GFM deep dive
│   ├── live-reload.md              # File watching
│   ├── temas.md                    # Theme system, CSS vars
│   ├── whisper.md                  # ★ Voice-to-text, why it matters
│   ├── whisper-config.md           # Models, devices, shortcuts
│   ├── workspace.md                # ★ Workspace concept + ACP
│   ├── sessoes.md                  # Sessions, 6 interaction modes
│   ├── plano.md                    # Plan workflow (idle→planning→reviewing→executing)
│   ├── comentarios.md              # ★ Block comments in markdown
│   ├── review.md                   # ★ Review prompt, EDITOR integration
│   └── integracoes.md              # Shell aliases, IPC, multi-window
├── referencia/
│   ├── cli.md                      # CLI commands
│   ├── ipc.md                      # Unix socket + TCP
│   ├── configuracoes.md            # All settings
│   └── idiomas.md                  # i18n, contributing translations
└── en/                             # English mirror (same structure)
    ├── index.md
    ├── guide/ (7 pages)
    ├── features/ (11 pages)
    └── reference/ (4 pages)
```

**Total: 44 pages** (22 pt-BR + 22 en)

---

## VitePress Configuration

### `docs/package.json`
- VitePress ^1.6.3, Vue ^3.5.13
- Scripts: `docs:dev`, `docs:build`, `docs:preview`

### `docs/.vitepress/config.ts`
- `locales`: root = pt-BR, `/en/` = English
- `head`: favicon, fonts (Inter + JetBrains Mono via Google Fonts), OG meta, theme-color `#2D1B69`
- `cleanUrls: true`, `lastUpdated: true`
- `socialLinks`: GitHub repo
- `search`: local provider (built-in)

### Custom theme (`custom.css`)
- Brand colors mapped to VitePress CSS vars:
  - Light: `--vp-c-brand-1: #2D1B69` (purple), tip borders in gold
  - Dark: `--vp-c-brand-1: #8B7BC7` (light purple), gold accents
- Hero gradient: `linear-gradient(135deg, #F4C430, #D4821E)` on the name
- Typography: Inter (body), JetBrains Mono (code)
- `.pronunciation` class for pronunciation guide with IPA

### Sidebar (Vue.js docs-inspired)
Progressive navigation in 3 sections:

| Section | Content |
|---------|---------|
| **Guide** | Getting Started (3) + Essentials (4) |
| **Features** | Viewing (3) + Voice (2) + Workspace (3) + Review (3) |
| **Reference** | CLI, IPC, Configuration, Languages (4) |

---

## Key Page Content

### Home (`index.md`)
- VitePress `layout: home` with hero, 6 feature cards
- Pronunciation: **arandu** `/a.ɾan.ˈdu/` — from Guarani, meaning "wisdom"
- Actions: Get Started, Download, GitHub

### Introduction (`guia/introducao.md`)
- Three pillars: markdown viewer, AI workspace, review tool
- Guarani etymology and pronunciation with IPA `/a.ɾan.ˈdu/`
- Placeholder for pronunciation audio (future: record and embed `<audio>`)
- Design philosophy: monochrome, reading-focused

### Whisper (`funcionalidades/whisper.md`) ★
- **Why it matters**: Prompt engineering requires heavy typing. Voice speeds up the workflow
- whisper.cpp (C++, open-source, offline, no API keys)
- Model table: tiny→base→small→medium with sizes and recommendations
- Global shortcut Alt+Space, always-on-top floating window
- Two modes: field (inline) and button (clipboard)
- Audio device selection, automatic model download

### Block Comments (`funcionalidades/comentarios.md`) ★
- Cmd/Ctrl+Click on any markdown block to add a comment
- Block ID system (para, list, code, quote, heading)
- Visual indicators for comment counts
- Resolve/unresolve comments
- Staleness detection via file hash

### Document Review (`funcionalidades/review.md`) ★
- Two modes: "comments" (list) and "review" (consolidated prompt)
- **Key use case**: `EDITOR=arandu` with coding agents
  ```bash
  alias claude='EDITOR=arandu ~/.local/bin/claude'
  ```
- Flow: Agent generates plan → Arandu opens as EDITOR → User comments inline → Generates review prompt → Feedback to agent
- Future: prompt patterns for review, diff between plan versions

### Workspace (`funcionalidades/workspace.md`) ★
- Workspace = a directory that connects a code agent via ACP
- Agent installed locally (GitHub Copilot), used remotely via JSON-RPC stdin/stdout
- Session management with plan tracking
- Current: chat with Copilot + plan review
- Future: tasks, full review workflow, SDD flow

### Sessions & Modes (`funcionalidades/sessoes.md`)
- 6 modes: ask, plan, code, edit, agent, autopilot
- Response streaming with cancel support
- SQLite persistence

---

## Deployment

### GitHub Actions (`.github/workflows/deploy-docs.yml`)
- Trigger: push to `main` on `docs/**`
- Build: `cd docs && npm ci && npm run docs:build`
- Primary deploy: Cloudflare Pages (`arandu-docs` project → `docs.arandu.app`)
- Fallback deploy: GitHub Pages via `peaceiris/actions-gh-pages@v4`

### Cloudflare Pages
- Separate project `arandu-docs` (distinct from the `arandu` landing page)
- Custom domain: `docs.arandu.app`
- Deploy via `cloudflare/wrangler-action@v3`

### Update landing page
- `website/index.html`: "Docs" link points to `https://docs.arandu.app`

### Update `.gitignore`
Append to root `.gitignore`:
```
docs/.vitepress/dist
docs/.vitepress/cache
docs/node_modules
```

---

## Implementation Order

| Step | What | Files |
|------|------|-------|
| 1 | Worktree + VitePress scaffold | package.json, config.ts, locales, theme, public, .gitignore |
| 2 | Home pages (pt-BR + en) | index.md, en/index.md |
| 3 | Guide pt-BR (7 pages) | guia/*.md |
| 4 | Features pt-BR (11 pages) | funcionalidades/*.md |
| 5 | Reference pt-BR (4 pages) | referencia/*.md |
| 6 | English translation (22 pages) | en/**/*.md |
| 7 | Deploy workflow | .github/workflows/deploy-docs.yml |
| 8 | Polish: cross-links, landing page update, README | website/index.html, README.md |

---

## Verification

- [ ] `cd docs && npm run docs:dev` starts without errors
- [ ] Home page renders with purple/gold hero gradient
- [ ] Locale switcher pt-BR ↔ English works
- [ ] Sidebar navigates correctly across all sections
- [ ] Local search finds content
- [ ] `npm run docs:build` generates `docs/.vitepress/dist/` without warnings
- [ ] Inter-page links work (prev/next, cross-links)
- [ ] Dark mode respects brand colors

---

## Critical Files to Create/Modify

- `docs/package.json` — VitePress dependencies
- `docs/.vitepress/config.ts` — central config
- `docs/.vitepress/locales/pt-BR.ts` — PT sidebar and labels
- `docs/.vitepress/locales/en.ts` — EN sidebar and labels
- `docs/.vitepress/theme/custom.css` — brand colors
- `docs/index.md` — home page with pronunciation
- `docs/funcionalidades/whisper.md` — main feature
- `docs/funcionalidades/comentarios.md` — review system
- `docs/funcionalidades/workspace.md` — ACP workspace
- `.github/workflows/deploy-docs.yml` — CI/CD
- `.gitignore` — exclude dist/cache/node_modules
- `website/index.html` — link to docs.arandu.app

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Complete documentation site with VitePress #44

Context

Project Structure

VitePress Configuration

`docs/package.json`

`docs/.vitepress/config.ts`

Custom theme (`custom.css`)

Sidebar (Vue.js docs-inspired)

Key Page Content

Home (`index.md`)

Introduction (`guia/introducao.md`)

Whisper (`funcionalidades/whisper.md`) ★

Block Comments (`funcionalidades/comentarios.md`) ★

Document Review (`funcionalidades/review.md`) ★

Workspace (`funcionalidades/workspace.md`) ★

Sessions & Modes (`funcionalidades/sessoes.md`)

Deployment

GitHub Actions (`.github/workflows/deploy-docs.yml`)

Cloudflare Pages

Update landing page

Update `.gitignore`

Implementation Order

Verification

Critical Files to Create/Modify

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Section	Content
Guide	Getting Started (3) + Essentials (4)
Features	Viewing (3) + Voice (2) + Workspace (3) + Review (3)
Reference	CLI, IPC, Configuration, Languages (4)

Step	What	Files
1	Worktree + VitePress scaffold	package.json, config.ts, locales, theme, public, .gitignore
2	Home pages (pt-BR + en)	index.md, en/index.md
3	Guide pt-BR (7 pages)	guia/*.md
4	Features pt-BR (11 pages)	funcionalidades/*.md
5	Reference pt-BR (4 pages)	referencia/*.md
6	English translation (22 pages)	en/*/.md
7	Deploy workflow	.github/workflows/deploy-docs.yml
8	Polish: cross-links, landing page update, README	website/index.html, README.md

feat: Complete documentation site with VitePress #44

Description

Context

Project Structure

VitePress Configuration

docs/package.json

docs/.vitepress/config.ts

Custom theme (custom.css)

Sidebar (Vue.js docs-inspired)

Key Page Content

Home (index.md)

Introduction (guia/introducao.md)

Whisper (funcionalidades/whisper.md) ★

Block Comments (funcionalidades/comentarios.md) ★

Document Review (funcionalidades/review.md) ★

Workspace (funcionalidades/workspace.md) ★

Sessions & Modes (funcionalidades/sessoes.md)

Deployment

GitHub Actions (.github/workflows/deploy-docs.yml)

Cloudflare Pages

Update landing page

Update .gitignore

Implementation Order

Verification

Critical Files to Create/Modify

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`docs/package.json`

`docs/.vitepress/config.ts`

Custom theme (`custom.css`)

Home (`index.md`)

Introduction (`guia/introducao.md`)

Whisper (`funcionalidades/whisper.md`) ★

Block Comments (`funcionalidades/comentarios.md`) ★

Document Review (`funcionalidades/review.md`) ★

Workspace (`funcionalidades/workspace.md`) ★

Sessions & Modes (`funcionalidades/sessoes.md`)

GitHub Actions (`.github/workflows/deploy-docs.yml`)

Update `.gitignore`