feat: Complete documentation site with VitePress

[wilcorrea]

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

  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