aiox-core 5.0.0

package/docs/pt/architecture/dashboard-architecture.md

@@ -0,0 +1,928 @@
+# 🏛️ AIOX Dashboard - Arquitetura Completa
+
+> **Versão:** 2.0.0
+> **Data:** 2026-01-29
+> **Status:** Produção
+> **Autor:** @architect (Aria)
+
+---
+
+> **PT** | [EN](../../architecture/dashboard-architecture.md) | [ES](../architecture/dashboard-architecture.md)
+
+---
+
+## 📋 Índice
+
+1. [Visão Geral](#visão-geral)
+2. [Stack Tecnológico](#stack-tecnológico)
+3. [Estrutura de Diretórios](#estrutura-de-diretórios)
+4. [Arquitetura de Componentes](#arquitetura-de-componentes)
+5. [Sistema de State Management](#sistema-de-state-management)
+6. [APIs e Comunicação](#apis-e-comunicação)
+7. [Design System](#design-system)
+8. [Fluxo de Dados](#fluxo-de-dados)
+9. [Padrões e Convenções](#padrões-e-convenções)
+10. [Extensibilidade](#extensibilidade)
+
+### 📚 Documentos Relacionados
+
+| Documento                                        | Descrição                                                |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| [dashboard-realtime.md](./dashboard-realtime.md) | Arquitetura de Real-Time Observability (CLI → Dashboard) |
+
+---
+
+## Visão Geral
+
+O AIOX Dashboard é uma aplicação web Next.js que fornece uma interface visual para monitorar e gerenciar o sistema AIOX. Ele se comunica com o CLI/AIOX através de arquivos de status no filesystem e Server-Sent Events (SSE).
+
+### Princípios Arquiteturais
+
+1. **CLI-First**: Dashboard é complementar ao CLI, não substituto
+2. **File-Based Communication**: Status via `.aiox/dashboard/status.json`
+3. **Real-Time Updates**: SSE com fallback para polling
+4. **Offline-Capable**: Funciona com dados mock em desenvolvimento
+5. **Type-Safe**: TypeScript em toda a stack
+
+### Diagrama de Arquitetura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           AIOX DASHBOARD                                 │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │                         PRESENTATION LAYER                        │   │
+│  │  ┌─────────┐ ┌──────────────────────────────────────────────┐    │   │
+│  │  │ Sidebar │ │               Main Content                    │    │   │
+│  │  │         │ │  ┌────────────────────────────────────────┐  │    │   │
+│  │  │ Kanban  │ │  │           ProjectTabs                  │  │    │   │
+│  │  │ Agents  │ │  ├────────────────────────────────────────┤  │    │   │
+│  │  │ Termnls │ │  │                                        │  │    │   │
+│  │  │ Insight │ │  │    Page Content (KanbanBoard,          │  │    │   │
+│  │  │ Context │ │  │    AgentMonitor, TerminalGrid, etc)    │  │    │   │
+│  │  │ Roadmap │ │  │                                        │  │    │   │
+│  │  │ GitHub  │ │  └────────────────────────────────────────┘  │    │   │
+│  │  │ Settngs │ │                                              │    │   │
+│  │  └─────────┘ └──────────────────────────────────────────────┘    │   │
+│  │  ┌───────────────────────────────────────────────────────────┐   │   │
+│  │  │                      StatusBar                             │   │   │
+│  │  │  [Connection] [Rate Limit] [Claude]    [@agent] [Notifs]  │   │   │
+│  │  └───────────────────────────────────────────────────────────┘   │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │                         STATE LAYER (Zustand)                     │   │
+│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │   │
+│  │  │  story   │ │  agent   │ │ terminal │ │    ui    │ │settings│ │   │
+│  │  │  store   │ │  store   │ │  store   │ │  store   │ │ store  │ │   │
+│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │                         DATA LAYER (SWR + Hooks)                  │   │
+│  │  ┌────────────────┐ ┌────────────────┐ ┌────────────────────────┐│   │
+│  │  │  useStories()  │ │  useAgents()   │ │  useRealtimeStatus()   ││   │
+│  │  │  useAioxStatus │ │                │ │  (SSE + Polling)       ││   │
+│  │  └────────────────┘ └────────────────┘ └────────────────────────┘│   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │                         API LAYER (Next.js Routes)                │   │
+│  │  /api/stories  │  /api/status  │  /api/events  │  /api/github    │   │
+│  │      (CRUD)    │   (polling)   │    (SSE)      │   (webhook)     │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     │ File I/O + SSE
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              FILESYSTEM                                  │
+│  ┌──────────────────────────┐  ┌──────────────────────────────────────┐ │
+│  │ .aiox/dashboard/         │  │ docs/stories/                        │ │
+│  │   status.json (CLI→UI)   │  │   *.md (Stories Markdown)            │ │
+│  └──────────────────────────┘  └──────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     ▲
+                                     │ Write
+                                     │
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         CLI / AIOX AGENTS                                │
+│  @dev │ @qa │ @architect │ @pm │ @po │ @analyst │ @devops               │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Stack Tecnológico
+
+### Framework Principal
+
+| Tecnologia     | Versão | Propósito                           |
+| -------------- | ------ | ----------------------------------- |
+| **Next.js**    | 16.1.6 | Framework full-stack com App Router |
+| **React**      | 19.2.3 | UI library com Server Components    |
+| **TypeScript** | 5.x    | Type safety em toda a codebase      |
+
+### Gerenciamento de Estado
+
+| Tecnologia  | Versão | Propósito                     |
+| ----------- | ------ | ----------------------------- |
+| **Zustand** | 5.0.10 | Global state com persistência |
+| **SWR**     | 2.3.8  | Data fetching e cache         |
+
+### UI e Estilos
+
+| Tecnologia       | Versão  | Propósito                                    |
+| ---------------- | ------- | -------------------------------------------- |
+| **Tailwind CSS** | 4.x     | Utility-first CSS                            |
+| **Radix UI**     | latest  | Primitivos acessíveis (Dialog, Context Menu) |
+| **Lucide React** | 0.563.0 | Sistema de ícones SVG                        |
+| **dnd-kit**      | 6.3.1   | Drag and drop para Kanban                    |
+
+### Utilitários
+
+| Tecnologia         | Versão | Propósito                             |
+| ------------------ | ------ | ------------------------------------- |
+| **gray-matter**    | 4.0.3  | Parse de frontmatter YAML em Markdown |
+| **clsx**           | 2.1.1  | Conditional class names               |
+| **tailwind-merge** | 3.4.0  | Merge de classes Tailwind             |
+
+---
+
+## Estrutura de Diretórios
+
+```
+apps/dashboard/
+├── src/
+│   ├── app/                          # Next.js App Router
+│   │   ├── (dashboard)/              # Dashboard route group
+│   │   │   ├── layout.tsx            # Dashboard layout (AppShell)
+│   │   │   ├── agents/page.tsx       # Agent monitor page
+│   │   │   ├── github/page.tsx       # GitHub integration
+│   │   │   ├── kanban/page.tsx       # Story board
+│   │   │   ├── settings/page.tsx     # Settings panel
+│   │   │   └── terminals/page.tsx    # Terminal sessions
+│   │   ├── api/                      # API routes
+│   │   │   ├── events/route.ts       # SSE endpoint
+│   │   │   ├── github/route.ts       # GitHub API proxy
+│   │   │   ├── logs/route.ts         # Log streaming
+│   │   │   ├── qa/metrics/route.ts   # QA metrics
+│   │   │   ├── status/route.ts       # AIOX status polling
+│   │   │   └── stories/              # Stories CRUD
+│   │   │       ├── route.ts          # GET/POST /api/stories
+│   │   │       └── [id]/route.ts     # GET/PUT/DELETE /api/stories/:id
+│   │   ├── globals.css               # Design tokens + utilities
+│   │   ├── layout.tsx                # Root layout
+│   │   └── page.tsx                  # Root redirect
+│   │
+│   ├── components/                   # React components
+│   │   ├── agents/                   # Agent-related
+│   │   │   ├── AgentCard.tsx
+│   │   │   ├── AgentMonitor.tsx
+│   │   │   └── index.ts
+│   │   ├── context/                  # Context panel
+│   │   │   ├── ContextPanel.tsx
+│   │   │   └── index.ts
+│   │   ├── github/                   # GitHub integration
+│   │   │   ├── GitHubPanel.tsx
+│   │   │   └── index.ts
+│   │   ├── insights/                 # Analytics/insights
+│   │   │   ├── InsightsPanel.tsx
+│   │   │   └── index.ts
+│   │   ├── kanban/                   # Kanban board
+│   │   │   ├── KanbanBoard.tsx
+│   │   │   ├── KanbanColumn.tsx
+│   │   │   ├── SortableStoryCard.tsx
+│   │   │   └── index.ts
+│   │   ├── layout/                   # Layout components
+│   │   │   ├── AppShell.tsx
+│   │   │   ├── ProjectTabs.tsx
+│   │   │   ├── Sidebar.tsx
+│   │   │   ├── StatusBar.tsx
+│   │   │   └── index.ts
+│   │   ├── qa/                       # QA components
+│   │   │   └── QAMetricsPanel.tsx
+│   │   ├── roadmap/                  # Roadmap view
+│   │   │   ├── RoadmapCard.tsx
+│   │   │   ├── RoadmapView.tsx
+│   │   │   └── index.ts
+│   │   ├── settings/                 # Settings
+│   │   │   ├── SettingsPanel.tsx
+│   │   │   └── index.ts
+│   │   ├── stories/                  # Story components
+│   │   │   ├── StoryCard.tsx
+│   │   │   ├── StoryCreateModal.tsx
+│   │   │   ├── StoryDetailModal.tsx
+│   │   │   ├── StoryEditModal.tsx
+│   │   │   └── index.ts
+│   │   ├── terminal/                 # Terminal output
+│   │   │   ├── TerminalOutput.tsx
+│   │   │   └── index.ts
+│   │   ├── terminals/                # Terminal sessions grid
+│   │   │   ├── TerminalCard.tsx
+│   │   │   ├── TerminalGrid.tsx
+│   │   │   ├── TerminalOutput.tsx
+│   │   │   ├── TerminalStream.tsx
+│   │   │   └── index.ts
+│   │   └── ui/                       # Base UI components
+│   │       ├── badge.tsx
+│   │       ├── button.tsx
+│   │       ├── context-menu.tsx
+│   │       ├── dialog.tsx
+│   │       ├── fab.tsx
+│   │       ├── icon.tsx
+│   │       ├── progress-bar.tsx
+│   │       ├── section-label.tsx
+│   │       ├── skeleton.tsx
+│   │       ├── status-badge.tsx
+│   │       ├── status-dot.tsx
+│   │       └── tag.tsx
+│   │
+│   ├── hooks/                        # Custom React hooks
+│   │   ├── index.ts
+│   │   ├── use-agents.ts             # Agent data + polling
+│   │   ├── use-aiox-status.ts        # Status with SWR
+│   │   ├── use-realtime-status.ts    # SSE connection
+│   │   └── use-stories.ts            # Stories data fetching
+│   │
+│   ├── lib/                          # Utilities
+│   │   ├── icons.ts                  # Icon system (lucide mapping)
+│   │   ├── mock-data.ts              # Mock data for dev/demo
+│   │   └── utils.ts                  # cn(), formatDate(), etc.
+│   │
+│   ├── stores/                       # Zustand stores
+│   │   ├── agent-store.ts            # Agent state
+│   │   ├── index.ts
+│   │   ├── projects-store.ts         # Multi-project tabs
+│   │   ├── settings-store.ts         # User settings
+│   │   ├── story-store.ts            # Stories + Kanban order
+│   │   ├── terminal-store.ts         # Terminal sessions
+│   │   └── ui-store.ts               # UI state (sidebar, view)
+│   │
+│   └── types/                        # TypeScript types
+│       └── index.ts                  # All shared types
+│
+├── components.json                   # shadcn/ui config
+├── next-env.d.ts                     # Next.js types
+├── next.config.ts                    # Next.js config
+├── package.json                      # Dependencies
+├── tailwind.config.ts                # Tailwind config (if used)
+└── tsconfig.json                     # TypeScript config
+```
+
+---
+
+## Arquitetura de Componentes
+
+### Hierarquia de Componentes
+
+```
+<RootLayout>                          # src/app/layout.tsx
+  └── <DashboardLayout>               # src/app/(dashboard)/layout.tsx
+        └── <AppShell>                # Wrapper principal
+              ├── <Sidebar>           # Navegação lateral
+              │     └── <SidebarNavItem>[]
+              │
+              ├── <Main>              # Área de conteúdo
+              │     ├── <ProjectTabs> # Tabs de projetos
+              │     └── {children}    # Conteúdo da página
+              │
+              └── <StatusBar>         # Barra de status
+                    ├── <StatusIndicator>
+                    ├── <RateLimitDisplay>
+                    ├── <ActiveAgentBadge>
+                    └── <NotificationBadge>
+```
+
+### Componentes Principais
+
+#### AppShell
+
+```typescript
+// Responsabilidades:
+// - Layout master (sidebar + content + statusbar)
+// - Keyboard shortcuts globais ([ para toggle sidebar)
+// - Hydration mismatch prevention
+
+interface AppShellProps {
+  children: React.ReactNode;
+}
+```
+
+#### KanbanBoard
+
+```typescript
+// Responsabilidades:
+// - Renderizar colunas de status
+// - Drag & drop entre colunas
+// - Gerenciar modais (create/edit story)
+
+interface KanbanBoardProps {
+  onStoryClick?: (story: Story) => void;
+  onRefresh?: () => void;
+  isLoading?: boolean;
+}
+```
+
+#### AgentMonitor
+
+```typescript
+// Responsabilidades:
+// - Grid de agentes ativos/idle
+// - Auto-refresh toggle (Live/Paused)
+// - Polling status indicator
+```
+
+---
+
+## Sistema de State Management
+
+### Arquitetura de Stores
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           ZUSTAND STORES                                 │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                        story-store                               │    │
+│  │  State:                                                          │    │
+│  │    - stories: Record<string, Story>                             │    │
+│  │    - storyOrder: Record<StoryStatus, string[]>  ← PERSISTED     │    │
+│  │    - isLoading, error                                           │    │
+│  │  Actions:                                                        │    │
+│  │    - setStories(), addStory(), updateStory(), deleteStory()     │    │
+│  │    - moveStory(), reorderInColumn()                             │    │
+│  │  Selectors:                                                      │    │
+│  │    - getStoriesByStatus(), getStoryById(), getEpics()           │    │
+│  │  Features:                                                       │    │
+│  │    - Race condition protection (operationsInProgress)            │    │
+│  │    - Status change listeners (pub/sub pattern)                   │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                        agent-store                               │    │
+│  │  State:                                                          │    │
+│  │    - agents: Record<AgentId, Agent>                             │    │
+│  │    - activeAgentId: AgentId | null                              │    │
+│  │    - pollingInterval, isPolling, lastPolledAt                   │    │
+│  │  Actions:                                                        │    │
+│  │    - setActiveAgent(), clearActiveAgent(), updateAgent()        │    │
+│  │    - handleRealtimeUpdate()  ← SSE handler                      │    │
+│  │  Selectors:                                                      │    │
+│  │    - getActiveAgents(), getIdleAgents(), getAgentById()         │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                        ui-store                                  │    │
+│  │  State:  (PERSISTED)                                            │    │
+│  │    - sidebarCollapsed: boolean                                  │    │
+│  │    - activeView: SidebarView                                    │    │
+│  │  Actions:                                                        │    │
+│  │    - toggleSidebar(), setSidebarCollapsed(), setActiveView()    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                        projects-store                            │    │
+│  │  State:  (PERSISTED)                                            │    │
+│  │    - projects: Project[]                                        │    │
+│  │    - activeProjectId: string | null                             │    │
+│  │  Actions:                                                        │    │
+│  │    - addProject(), removeProject(), setActiveProject()          │    │
+│  │    - reorderProjects(), closeOtherProjects(), closeAllProjects()│    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                        settings-store                            │    │
+│  │  State:  (PERSISTED)                                            │    │
+│  │    - settings: DashboardSettings                                │    │
+│  │      - theme: 'dark' | 'light' | 'system'                       │    │
+│  │      - useMockData: boolean                                     │    │
+│  │      - autoRefresh: boolean                                     │    │
+│  │      - refreshInterval: number                                  │    │
+│  │      - storiesPath: string                                      │    │
+│  │      - agentColors: Record<string, string>                      │    │
+│  │  Actions:                                                        │    │
+│  │    - updateSettings(), setTheme(), resetToDefaults()            │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                        terminal-store                            │    │
+│  │  State:                                                          │    │
+│  │    - terminals: Record<string, Terminal>                        │    │
+│  │    - activeTerminalId: string | null                            │    │
+│  │  Actions:                                                        │    │
+│  │    - createTerminal(), removeTerminal()                         │    │
+│  │    - appendLine(), appendLines(), clearTerminal()               │    │
+│  │    - setTerminalStatus()                                        │    │
+│  │  Features:                                                       │    │
+│  │    - Max lines buffer (default 1000)                            │    │
+│  │    - Auto-trim when exceeds limit                               │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Persistência
+
+| Store            | localStorage Key          | O que persiste                   |
+| ---------------- | ------------------------- | -------------------------------- |
+| `story-store`    | `aiox-stories`            | `storyOrder` (ordem das colunas) |
+| `ui-store`       | `aiox-ui`                 | `sidebarCollapsed`, `activeView` |
+| `projects-store` | `aiox-projects`           | `projects`, `activeProjectId`    |
+| `settings-store` | `aiox-dashboard-settings` | Todo o objeto `settings`         |
+
+### Padrão de Listeners
+
+Os stores usam um padrão pub/sub para notificar mudanças:
+
+```typescript
+// Registrar listener (fora do componente React)
+const unsubscribe = registerStoryStatusListener((storyId, oldStatus, newStatus) => {
+  console.log(`Story ${storyId} moved from ${oldStatus} to ${newStatus}`);
+});
+
+// Cleanup
+unsubscribe();
+```
+
+---
+
+## APIs e Comunicação
+
+### Endpoints
+
+#### GET /api/status
+
+```typescript
+// Retorna status atual do AIOX
+// Lê de: .aiox/dashboard/status.json
+
+interface AioxStatus {
+  version: string;
+  updatedAt: string;
+  connected: boolean;
+  project: { name: string; path: string } | null;
+  activeAgent: {
+    id: AgentId;
+    name: string;
+    activatedAt: string;
+    currentStory?: string;
+  } | null;
+  session: {
+    startedAt: string;
+    commandsExecuted: number;
+    lastCommand?: string;
+  } | null;
+  stories: {
+    inProgress: string[];
+    completed: string[];
+  };
+  rateLimit?: {
+    used: number;
+    limit: number;
+    resetsAt?: string;
+  };
+}
+```
+
+#### GET /api/events (SSE)
+
+```typescript
+// Server-Sent Events para updates real-time
+// Eventos:
+//   - status:update     → AioxStatus
+//   - connection:status → { connected: boolean }
+//   - heartbeat         → { alive: true }
+//   - error             → { message: string }
+
+// Formato do evento:
+interface SSEEvent {
+  type: 'status:update' | 'connection:status' | 'heartbeat' | 'error';
+  data: unknown;
+  timestamp: string;
+}
+```
+
+#### GET/POST /api/stories
+
+```typescript
+// GET: Lista todas as stories de docs/stories/
+// POST: Cria nova story
+
+interface StoriesResponse {
+  stories: Story[];
+  source: 'filesystem' | 'mock' | 'empty' | 'error';
+  count?: number;
+  message?: string;
+}
+
+interface CreateStoryRequest {
+  title: string;
+  description?: string;
+  status?: StoryStatus;
+  type?: StoryType;
+  priority?: StoryPriority;
+  complexity?: StoryComplexity;
+  category?: StoryCategory;
+  agent?: AgentId;
+  epicId?: string;
+  acceptanceCriteria?: string[];
+  technicalNotes?: string;
+}
+```
+
+### Comunicação CLI ↔ Dashboard
+
+```
+┌─────────────┐                              ┌──────────────────┐
+│   CLI/AIOX  │                              │    Dashboard     │
+│   (Claude)  │                              │    (Next.js)     │
+└──────┬──────┘                              └────────┬─────────┘
+       │                                              │
+       │  1. Agent ativado                            │
+       │  ─────────────────────────────────────────▶  │
+       │     Escreve .aiox/dashboard/status.json      │
+       │                                              │
+       │                                              │ 2. Dashboard detecta
+       │                                              │    (SSE poll 2s)
+       │                                              │
+       │                                              │ 3. UI atualiza
+       │                                              │    (real-time)
+       │                                              │
+       │  4. Story status muda                        │
+       │  ─────────────────────────────────────────▶  │
+       │     Escreve status.json                      │
+       │                                              │
+       │                                              │ 5. Kanban atualiza
+       │                                              │    posição do card
+       │                                              │
+       │  6. Agent termina                            │
+       │  ─────────────────────────────────────────▶  │
+       │     status.json: activeAgent = null          │
+       │                                              │
+       │                                              │ 7. Agent vai para
+       │                                              │    "Standby" no UI
+       │                                              │
+```
+
+### Hooks de Data Fetching
+
+#### useAioxStatus
+
+```typescript
+// SWR-based polling do status
+const { status, isLoading, isConnected, statusError, mutate } = useAioxStatus({
+  interval: 5000, // Poll every 5s
+  paused: false, // Pausar polling
+});
+```
+
+#### useRealtimeStatus
+
+```typescript
+// SSE connection com fallback para polling
+const { status, isConnected, isRealtime, lastUpdate, reconnect } = useRealtimeStatus({
+  enabled: true,
+  fallbackInterval: 5000,
+  maxReconnectAttempts: 3,
+  onStatusUpdate: (status) => {
+    /* ... */
+  },
+  onConnectionChange: (connected) => {
+    /* ... */
+  },
+});
+```
+
+#### useStories
+
+```typescript
+// Stories com toggle mock/real
+const { isLoading, isError, source, useMockData, refresh } = useStories({
+  refreshInterval: 30000, // Auto-refresh every 30s
+});
+```
+
+---
+
+## Design System
+
+### Design Tokens
+
+O dashboard usa um sistema de design tokens CSS customizados definidos em `globals.css`:
+
+#### Cores de Background
+
+```css
+--bg-base: #000000; /* Fundo principal */
+--bg-elevated: #050505; /* Sidebar, modais */
+--bg-surface: #0a0a0a; /* Cards */
+--bg-surface-hover: #0f0f0f;
+```
+
+#### Hierarquia de Texto (WCAG AA)
+
+```css
+--text-primary: #fafaf8; /* 19.5:1 contrast */
+--text-secondary: #b8b8ac; /* 8.2:1 contrast */
+--text-tertiary: #8a8a7f; /* 4.8:1 contrast */
+--text-muted: #6a6a5e; /* 3.2:1 - decorative */
+--text-disabled: #3a3a32; /* Disabled state */
+```
+
+#### Sistema de Cores por Agente
+
+```css
+--agent-dev: #22c55e; /* Verde */
+--agent-qa: #eab308; /* Amarelo */
+--agent-architect: #8b5cf6; /* Roxo */
+--agent-pm: #3b82f6; /* Azul */
+--agent-po: #f97316; /* Laranja */
+--agent-analyst: #06b6d4; /* Cyan */
+--agent-devops: #ec4899; /* Pink */
+```
+
+#### Sistema de Accent Gold
+
+```css
+--accent-gold: #c9b298;
+--accent-gold-light: #e4d8ca;
+--accent-gold-bg: rgba(201, 178, 152, 0.08);
+--border-gold: rgba(201, 178, 152, 0.25);
+```
+
+#### Status Colors
+
+```css
+--status-success: #4ade80;
+--status-warning: #fbbf24;
+--status-error: #f87171;
+--status-info: #60a5fa;
+--status-idle: #4a4a42;
+```
+
+### Sistema de Ícones
+
+O dashboard usa `lucide-react` com um mapeamento centralizado em `src/lib/icons.ts`:
+
+```typescript
+import type { IconName } from '@/lib/icons';
+
+// Uso em componentes:
+const { iconMap } = require('@/lib/icons');
+const IconComponent = iconMap['code']; // <Code /> do Lucide
+```
+
+Ícones disponíveis por categoria:
+
+- **Navigation**: dashboard, kanban, terminal, settings, menu, chevron-*
+- **Status**: circle, check-circle, x-circle, alert-circle, clock, loader
+- **Actions**: play, pause, refresh, search, copy, plus, trash, edit, save
+- **Agents**: bot, code, test-tube, building, bar-chart, target, wrench
+
+### Utility Classes
+
+```css
+/* Transições elegantes */
+.transition-luxury {
+  transition: all 300ms cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+/* Cards refinados */
+.card-refined {
+  background: var(--card);
+  border: 1px solid var(--border);
+}
+.card-refined:hover {
+  transform: translateY(-1px);
+  border-color: var(--border-medium);
+}
+
+/* Gold accent hover */
+.hover-gold:hover {
+  border-color: var(--border-gold);
+}
+
+/* Scrollbar customizada */
+.scrollbar-refined::-webkit-scrollbar {
+  width: 6px;
+}
+```
+
+---
+
+## Fluxo de Dados
+
+### Story Lifecycle
+
+```
+                    ┌─────────────────────────────────────────────────────┐
+                    │               STORY LIFECYCLE                        │
+                    └─────────────────────────────────────────────────────┘
+                                           │
+                    ┌──────────────────────┼──────────────────────┐
+                    ▼                      ▼                      ▼
+              ┌──────────┐          ┌──────────┐          ┌──────────┐
+              │ CREATE   │          │ UPDATE   │          │ DELETE   │
+              └────┬─────┘          └────┬─────┘          └────┬─────┘
+                   │                     │                     │
+                   ▼                     ▼                     ▼
+         ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
+         │ StoryCreateModal │   │ StoryEditModal  │   │ Confirm Dialog  │
+         │  onCreated()     │   │  onUpdated()    │   │  onDeleted()    │
+         └────────┬────────┘   └────────┬────────┘   └────────┬────────┘
+                  │                     │                     │
+                  └──────────┬──────────┴──────────┬──────────┘
+                             │                     │
+                             ▼                     ▼
+                    ┌─────────────────┐   ┌─────────────────┐
+                    │  story-store    │   │  /api/stories   │
+                    │  addStory()     │   │  POST/PUT/DELETE│
+                    │  updateStory()  │   │                 │
+                    │  deleteStory()  │   └────────┬────────┘
+                    └────────┬────────┘            │
+                             │                     │
+                             │                     ▼
+                             │            ┌─────────────────┐
+                             │            │ docs/stories/   │
+                             │            │   *.md files    │
+                             │            └─────────────────┘
+                             │
+                             ▼
+                    ┌─────────────────┐
+                    │  KanbanBoard    │
+                    │  re-renders     │
+                    └─────────────────┘
+```
+
+### Fluxo de Drag & Drop
+
+```
+User drags story card
+         │
+         ▼
+┌─────────────────────────────────────┐
+│     DndContext.onDragStart()        │
+│  1. Find story by activeId          │
+│  2. setActiveStory(story)           │
+│  3. Show DragOverlay                │
+└─────────────────┬───────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│     DndContext.onDragEnd()          │
+│  1. Determine target column         │
+│  2. Calculate new index             │
+│  3. Same column? reorderInColumn()  │
+│  4. Different? moveStory()          │
+│  5. Clear activeStory               │
+└─────────────────┬───────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────┐
+│     story-store.moveStory()         │
+│  1. Race condition check            │
+│  2. Remove from old position        │
+│  3. Insert at new position          │
+│  4. Update story.status             │
+│  5. notifyStatusChange()            │
+│  6. Clear operation lock            │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Padrões e Convenções
+
+### Convenções de Nomenclatura
+
+| Tipo        | Padrão                  | Exemplo                  |
+| ----------- | ----------------------- | ------------------------ |
+| Components  | PascalCase              | `StoryCard.tsx`          |
+| Hooks       | camelCase com `use`     | `useStories.ts`          |
+| Stores      | kebab-case com `-store` | `story-store.ts`         |
+| Types       | PascalCase              | `StoryStatus`            |
+| CSS Classes | kebab-case              | `card-refined`           |
+| Files       | kebab-case              | `use-realtime-status.ts` |
+
+### Component Structure
+
+```typescript
+// Ordem recomendada em componentes
+'use client';
+
+// 1. Imports - React primeiro
+import { useState, useEffect, useCallback } from 'react';
+
+// 2. Imports - Third-party
+import { DndContext } from '@dnd-kit/core';
+import { cn } from '@/lib/utils';
+
+// 3. Imports - Types
+import type { Story, StoryStatus } from '@/types';
+
+// 4. Imports - Internal components
+import { StoryCard } from '@/components/stories';
+
+// 5. Imports - Hooks & Stores
+import { useStoryStore } from '@/stores/story-store';
+
+// 6. Interface Props
+interface ComponentProps {
+  story: Story;
+  onUpdate?: (story: Story) => void;
+}
+
+// 7. Component
+export function Component({ story, onUpdate }: ComponentProps) {
+  // 7a. Hooks
+  const [state, setState] = useState();
+  const { action } = useStore();
+
+  // 7b. Callbacks
+  const handleClick = useCallback(() => {}, []);
+
+  // 7c. Effects
+  useEffect(() => {}, []);
+
+  // 7d. Render
+  return <div>...</div>;
+}
+```
+
+### Padrão de Export
+
+Cada diretório de componentes tem um `index.ts`:
+
+```typescript
+// components/stories/index.ts
+export { StoryCard } from './StoryCard';
+export { StoryCreateModal } from './StoryCreateModal';
+export { StoryEditModal } from './StoryEditModal';
+export { StoryDetailModal } from './StoryDetailModal';
+```
+
+---
+
+## Extensibilidade
+
+### Adicionando Nova View
+
+1. **Criar página**: `src/app/(dashboard)/nova-view/page.tsx`
+2. **Criar componente**: `src/components/nova-view/NovaViewPanel.tsx`
+3. **Adicionar ao sidebar**: `src/types/index.ts` → `SidebarView` e `SIDEBAR_ITEMS`
+4. **Criar store (se necessário)**: `src/stores/nova-view-store.ts`
+
+### Adicionando Novo Agente
+
+1. **Adicionar tipo**: `src/types/index.ts` → `AgentId`
+2. **Adicionar config**: `src/types/index.ts` → `AGENT_CONFIG`
+3. **Adicionar cor**: `src/app/globals.css` → `--agent-{id}`
+4. **Adicionar mock**: `src/lib/mock-data.ts` → `MOCK_AGENTS`
+
+### Adicionando Novo Status (Kanban)
+
+1. **Adicionar tipo**: `src/types/index.ts` → `StoryStatus`
+2. **Adicionar coluna**: `src/types/index.ts` → `KANBAN_COLUMNS`
+3. **Adicionar cor**: `src/types/index.ts` → `STATUS_COLORS`
+4. **Adicionar CSS**: `src/app/globals.css` → variáveis se necessário
+5. **Atualizar store**: `src/stores/story-store.ts` → `DEFAULT_ORDER`
+
+### Adicionando Nova API
+
+1. **Criar route**: `src/app/api/nova-rota/route.ts`
+2. **Implementar handlers**: GET, POST, PUT, DELETE
+3. **Criar hook (opcional)**: `src/hooks/use-nova-rota.ts`
+4. **Adicionar tipos**: `src/types/index.ts`
+
+---
+
+## Próximos Passos (Roadmap)
+
+> 📖 **Arquitetura detalhada de Real-Time:** Ver [dashboard-realtime.md](./dashboard-realtime.md)
+
+### Prioridade Alta
+
+- [ ] **Real-Time Observability** - CLI → Dashboard em tempo real ([arquitetura](./dashboard-realtime.md))
+- [ ] **Background Tasks UI** - Visualizar tasks ADE em execução
+- [ ] **Dynamic Status System** - Status customizáveis por projeto
+- [ ] **Multi-File Diff View** - Ver mudanças antes de aprovar
+
+### Prioridade Média
+
+- [ ] **Permission Modes UI** - Toggle visual de permissões
+- [ ] **Notification System** - Toast notifications para eventos
+- [ ] **Terminal Streaming** - Output real-time dos agentes
+
+### Prioridade Baixa
+
+- [ ] **Worktrees View** - Gerenciar git worktrees
+- [ ] **Ideas Panel** - Capturar ideias durante desenvolvimento
+- [ ] **Export/Import** - Backup de configurações
+
+---
+
+_Documentação gerada por @architect (Aria) - AIOX Core v2.0_