aiox-core 5.0.0

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

@@ -0,0 +1,1253 @@
+# 🔴 AIOX Dashboard - Arquitetura de Observabilidade em Tempo Real
+
+> **PT** | [EN](../architecture/dashboard-realtime.md) | [ES](../es/architecture/dashboard-realtime.md)
+
+> **Versão:** 1.0.0
+> **Data:** 2026-01-29
+> **Status:** Proposta
+> **Autor:** @architect (Aria)
+> **Relacionado:** [dashboard-architecture.md](./dashboard-architecture.md)
+
+---
+
+## 📋 Índice
+
+1. [Visão Geral](#visão-geral)
+2. [Problema Atual](#problema-atual)
+3. [Arquitetura Proposta](#arquitetura-proposta)
+4. [Event Emitter (CLI)](#event-emitter-cli)
+5. [Events Schema](#events-schema)
+6. [Enhanced SSE Endpoint](#enhanced-sse-endpoint)
+7. [Events Store](#events-store)
+8. [Novos Componentes UI](#novos-componentes-ui)
+9. [Fluxo de Dados Completo](#fluxo-de-dados-completo)
+10. [Implementação Faseada](#implementação-faseada)
+
+---
+
+## Visão Geral
+
+Este documento descreve a arquitetura para **observabilidade em tempo real** do AIOX Dashboard, permitindo que usuários acompanhem comandos executados no CLI com máximo detalhe visual.
+
+### Caso de Uso Principal
+
+```
+Usuário executa comandos no CLI → Dashboard mostra TUDO em tempo real
+```
+
+### Princípios
+
+1. **Zero Configuration** - Funciona automaticamente quando CLI e Dashboard estão ativos
+2. **File-Based** - Comunicação via filesystem (não requer servidor adicional)
+3. **Append-Only Events** - Log de eventos imutável para debugging
+4. **Graceful Degradation** - Dashboard funciona mesmo sem eventos (fallback para polling)
+
+---
+
+## Problema Atual
+
+### O que o Dashboard MOSTRA hoje
+
+| Evento no CLI     | Dashboard Atual           | Nota            |
+| ----------------- | ------------------------- | --------------- |
+| `@agent` ativa    | ✅ StatusBar mostra       | Funciona        |
+| `*exit` agent     | ✅ Agent vai para standby | Funciona        |
+| Story status muda | ⚠️ Kanban atualiza        | Sem notificação |
+
+### O que o Dashboard NÃO MOSTRA
+
+| Evento no CLI                | Dashboard Atual |
+| ---------------------------- | --------------- |
+| Comando `*xxx` executando    | ❌ Nada         |
+| Claude "pensando"            | ❌ Nada         |
+| Tool calls (Read/Write/Bash) | ❌ Nada         |
+| Progresso da tarefa          | ❌ Nada         |
+| Output do Claude             | ❌ Nada         |
+| git commit/push              | ❌ Nada         |
+| Erros                        | ❌ Nada         |
+| Tarefa completa              | ❌ Nada         |
+
+### Gap Visual
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    FLUXO: CLI → Dashboard Real-Time                      │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  VOCÊ NO CLI                              DASHBOARD                      │
+│  ────────────                             ─────────                      │
+│                                                                          │
+│  @architect ─────────────────────────────▶ ✅ Agent ativo aparece       │
+│  (ativa agente)                             (StatusBar + AgentMonitor)  │
+│                                                                          │
+│  *create-architecture ───────────────────▶ ❌ NÃO MOSTRA comando        │
+│  (executa tarefa)                           executando                   │
+│                                                                          │
+│  [Claude pensando...] ───────────────────▶ ❌ NÃO MOSTRA progresso      │
+│                                             em tempo real                │
+│                                                                          │
+│  [Criando arquivo X] ────────────────────▶ ❌ NÃO MOSTRA arquivos       │
+│  [Editando arquivo Y]                       sendo criados/editados      │
+│                                                                          │
+│  [Story atualizada] ─────────────────────▶ ⚠️ PARCIAL - status muda     │
+│                                             mas sem detalhes             │
+│                                                                          │
+│  [git commit] ───────────────────────────▶ ❌ NÃO MOSTRA commits        │
+│                                             em tempo real                │
+│                                                                          │
+│  *exit ──────────────────────────────────▶ ✅ Agent vai para standby    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Arquitetura Proposta
+
+### Diagrama Geral
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         CLI / AIOX AGENTS                                │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                      Claude Code Session                         │    │
+│  │  @architect → *create-architecture → [thinking...] → [file ops] │    │
+│  └────────────────────────────┬────────────────────────────────────┘    │
+│                                   │                                      │
+│                                   │ EMIT EVENTS                          │
+│                                   ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │               .aiox/dashboard/events.jsonl (append-only)         │    │
+│  │  {"type":"agent:activated","agent":"architect","ts":"..."}      │    │
+│  │  {"type":"command:start","cmd":"*create-architecture","ts":"..."}│   │
+│  │  {"type":"llm:thinking","duration":0,"ts":"..."}                │    │
+│  │  {"type":"tool:call","tool":"Read","file":"src/index.ts","ts":""}│   │
+│  │  {"type":"file:write","path":"docs/arch.md","lines":50,"ts":""}  │   │
+│  │  {"type":"command:complete","cmd":"*create","success":true,"ts":""}│ │
+│  └────────────────────────────┬────────────────────────────────────┘    │
+│                                   │                                      │
+└───────────────────────────────────┼──────────────────────────────────────┘
+                                    │
+                                    │ SSE Stream
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              DASHBOARD                                   │
+│                                                                          │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │                      /api/events (enhanced SSE)                    │  │
+│  │  - Watch events.jsonl for changes                                 │  │
+│  │  - Stream new events to connected clients                         │  │
+│  │  - Maintain last N events in memory                               │  │
+│  └────────────────────────────┬──────────────────────────────────────┘  │
+│                                   │                                      │
+│                                   ▼                                      │
+│  ┌───────────────────────────────────────────────────────────────────┐  │
+│  │                         events-store (NEW)                         │  │
+│  │  - currentCommand: { name, startedAt, status }                    │  │
+│  │  - llmStatus: 'idle' | 'thinking' | 'responding'                  │  │
+│  │  - recentFiles: { path, action, timestamp }[]                     │  │
+│  │  - recentEvents: Event[] (circular buffer)                        │  │
+│  │  - errors: Error[]                                                │  │
+│  └────────────────────────────┬──────────────────────────────────────┘  │
+│                                   │                                      │
+│                                   ▼                                      │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                         UI COMPONENTS                            │    │
+│  │                                                                   │    │
+│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │    │
+│  │  │  CommandPanel   │  │  ActivityFeed   │  │  FileChangesPanel│  │   │
+│  │  │  ─────────────  │  │  ────────────   │  │  ───────────────  │  │  │
+│  │  │ *create-arch    │  │ 02:45 Thinking  │  │ ✏️ docs/arch.md   │  │  │
+│  │  │ ████████░░ 80%  │  │ 02:44 Read x.ts │  │ ✏️ src/index.ts   │  │  │
+│  │  │ 2m 34s elapsed  │  │ 02:43 Agent on  │  │ 📁 +3 files       │  │  │
+│  │  └─────────────────┘  └─────────────────┘  └─────────────────┘  │    │
+│  │                                                                   │    │
+│  │  ┌───────────────────────────────────────────────────────────┐   │    │
+│  │  │                    TerminalStream (enhanced)               │   │   │
+│  │  │  Real-time Claude output with ANSI colors                  │   │   │
+│  │  │  [02:45:12] Analyzing project structure...                 │   │   │
+│  │  │  [02:45:15] Creating architecture document...              │   │   │
+│  │  │  [02:45:20] ✓ docs/architecture/system-arch.md created     │   │   │
+│  │  └───────────────────────────────────────────────────────────┘   │    │
+│  └──────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Event Emitter (CLI)
+
+### Localização
+
+```
+.aiox-core/core/events/dashboard-emitter.ts
+```
+
+### Interface
+
+```typescript
+// .aiox-core/core/events/types.ts
+
+/**
+ * Apenas eventos de alto nível (Decision #2)
+ * Focado em monitoramento, não debugging
+ */
+export type DashboardEventType =
+  // Ciclo de vida do agente
+  | 'agent:activated'
+  | 'agent:deactivated'
+
+  // Execução de comando
+  | 'command:start'
+  | 'command:complete'
+  | 'command:error'
+
+  // Atualizações de story
+  | 'story:status-change'
+
+  // Sessão
+  | 'session:start'
+  | 'session:end';
+
+export interface DashboardEvent {
+  id: string; // UUID v4
+  type: DashboardEventType;
+  timestamp: string; // ISO 8601
+  agentId?: string; // Agente ativo quando evento ocorreu
+  sessionId?: string; // Identificador de sessão
+  data: Record<string, unknown>; // Payload específico do evento
+}
+```
+
+### Implementação
+
+```typescript
+// .aiox-core/core/events/dashboard-emitter.ts
+
+import { appendFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import type { DashboardEvent, DashboardEventType } from './types';
+
+const EVENTS_DIR = '.aiox/dashboard';
+const EVENTS_FILE = 'events.jsonl';
+const MAX_FILE_SIZE = 10 * 1024 * 1024; // rotação de 10MB
+
+class DashboardEmitter {
+  private projectRoot: string;
+  private sessionId: string;
+  private activeAgentId: string | null = null;
+  private enabled: boolean = true;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+    this.sessionId = randomUUID();
+    this.ensureDirectory();
+  }
+
+  private ensureDirectory(): void {
+    const dir = join(this.projectRoot, EVENTS_DIR);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  private getEventsPath(): string {
+    return join(this.projectRoot, EVENTS_DIR, EVENTS_FILE);
+  }
+
+  emit(type: DashboardEventType, data: Record<string, unknown> = {}): void {
+    if (!this.enabled) return;
+
+    const event: DashboardEvent = {
+      id: randomUUID(),
+      type,
+      timestamp: new Date().toISOString(),
+      agentId: this.activeAgentId ?? undefined,
+      sessionId: this.sessionId,
+      data,
+    };
+
+    try {
+      const line = JSON.stringify(event) + '\n';
+      appendFileSync(this.getEventsPath(), line, 'utf-8');
+    } catch (error) {
+      // Falha silenciosa - dashboard é opcional
+      console.debug('[DashboardEmitter] Failed to emit event:', error);
+    }
+  }
+
+  // Métodos de conveniência de alto nível (Decision #2)
+
+  agentActivated(agentId: string, agentName: string): void {
+    this.activeAgentId = agentId;
+    this.emit('agent:activated', { agentId, agentName });
+  }
+
+  agentDeactivated(): void {
+    const agentId = this.activeAgentId;
+    this.activeAgentId = null;
+    this.emit('agent:deactivated', { agentId });
+  }
+
+  commandStart(command: string): void {
+    this.emit('command:start', { command });
+  }
+
+  commandComplete(command: string, success: boolean): void {
+    this.emit('command:complete', { command, success });
+  }
+
+  commandError(command: string, error: string): void {
+    this.emit('command:error', { command, error });
+  }
+
+  storyStatusChange(storyId: string, oldStatus: string, newStatus: string): void {
+    this.emit('story:status-change', { storyId, oldStatus, newStatus });
+  }
+
+  sessionStart(): void {
+    this.emit('session:start', { sessionId: this.sessionId });
+  }
+
+  sessionEnd(): void {
+    this.emit('session:end', { sessionId: this.sessionId });
+  }
+
+  // Métodos de controle
+  disable(): void {
+    this.enabled = false;
+  }
+
+  enable(): void {
+    this.enabled = true;
+  }
+}
+
+// Exportação Singleton
+let emitter: DashboardEmitter | null = null;
+
+export function getDashboardEmitter(projectRoot?: string): DashboardEmitter {
+  if (!emitter && projectRoot) {
+    emitter = new DashboardEmitter(projectRoot);
+  }
+  if (!emitter) {
+    throw new Error('DashboardEmitter not initialized. Call with projectRoot first.');
+  }
+  return emitter;
+}
+
+export function initDashboardEmitter(projectRoot: string): DashboardEmitter {
+  emitter = new DashboardEmitter(projectRoot);
+  return emitter;
+}
+```
+
+### Integração com Claude Code Hooks
+
+```typescript
+// .aiox-core/integrations/claude-code/hooks.ts
+
+import { getDashboardEmitter } from '../core/events/dashboard-emitter';
+
+/**
+ * Apenas hooks de alto nível (Decision #2)
+ * Eventos de ciclo de vida de agente e comando
+ */
+
+// Hook: Agente ativado (ex: @architect)
+export function onAgentActivated(agentId: string, agentName: string): void {
+  const emitter = getDashboardEmitter();
+  emitter.agentActivated(agentId, agentName);
+}
+
+// Hook: Agente desativado (ex: *exit)
+export function onAgentDeactivated(): void {
+  const emitter = getDashboardEmitter();
+  emitter.agentDeactivated();
+}
+
+// Hook: Comando iniciado (ex: *create-architecture)
+export function onCommandStart(command: string): void {
+  const emitter = getDashboardEmitter();
+  emitter.commandStart(command);
+}
+
+// Hook: Comando completo
+export function onCommandComplete(command: string, success: boolean): void {
+  const emitter = getDashboardEmitter();
+  emitter.commandComplete(command, success);
+}
+
+// Hook: Erro no comando
+export function onCommandError(command: string, error: string): void {
+  const emitter = getDashboardEmitter();
+  emitter.commandError(command, error);
+}
+
+// Hook: Story status muda
+export function onStoryStatusChange(storyId: string, oldStatus: string, newStatus: string): void {
+  const emitter = getDashboardEmitter();
+  emitter.storyStatusChange(storyId, oldStatus, newStatus);
+}
+```
+
+---
+
+## Events Schema
+
+### Localização do Arquivo
+
+```
+.aiox/dashboard/events.jsonl
+```
+
+### Formato
+
+JSON Lines (JSONL) - um objeto JSON por linha, apenas append.
+
+### Payloads de Eventos por Tipo (Apenas Alto Nível)
+
+#### Eventos de Agente
+
+```jsonl
+{"id":"uuid","type":"agent:activated","timestamp":"2026-01-29T14:30:00.000Z","sessionId":"uuid","data":{"agentId":"architect","agentName":"Aria"}}
+{"id":"uuid","type":"agent:deactivated","timestamp":"2026-01-29T15:45:00.000Z","agentId":"architect","sessionId":"uuid","data":{"agentId":"architect"}}
+```
+
+#### Eventos de Comando
+
+```jsonl
+{"id":"uuid","type":"command:start","timestamp":"...","agentId":"architect","data":{"command":"*create-architecture"}}
+{"id":"uuid","type":"command:complete","timestamp":"...","agentId":"architect","data":{"command":"*create-architecture","success":true}}
+{"id":"uuid","type":"command:error","timestamp":"...","agentId":"architect","data":{"command":"*create-architecture","error":"Failed to read config file"}}
+```
+
+#### Eventos de Story
+
+```jsonl
+{
+  "id": "uuid",
+  "type": "story:status-change",
+  "timestamp": "...",
+  "agentId": "architect",
+  "data": {
+    "storyId": "AIOX-123",
+    "oldStatus": "in-progress",
+    "newStatus": "review"
+  }
+}
+```
+
+#### Eventos de Sessão
+
+```jsonl
+{"id":"uuid","type":"session:start","timestamp":"...","data":{"sessionId":"uuid"}}
+{"id":"uuid","type":"session:end","timestamp":"...","data":{"sessionId":"uuid"}}
+```
+
+### Rotação de Arquivo
+
+Quando `events.jsonl` excede 10MB:
+
+1. Renomear para `events.{timestamp}.jsonl`
+2. Criar novo `events.jsonl`
+3. Manter últimos 5 arquivos rotacionados
+
+---
+
+## Enhanced SSE Endpoint
+
+### Atual vs Aprimorado
+
+| Aspecto         | Current `/api/events` | Aprimorado                     |
+| --------------- | --------------------- | ------------------------------ |
+| Source          | `status.json` apenas  | `status.json` + `events.jsonl` |
+| Trigger update  | Polling interval      | File watch + polling           |
+| Event types     | `status:update` apenas| Todos os tipos de evento       |
+| History         | Nenhum                | Últimos N eventos              |
+
+### Implementação
+
+```typescript
+// apps/dashboard/src/app/api/events/route.ts (aprimorado)
+
+import { NextRequest } from 'next/server';
+import { watch, existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { Readable } from 'stream';
+
+const AIOX_DIR = process.env.AIOX_PROJECT_ROOT || process.cwd();
+const STATUS_FILE = join(AIOX_DIR, '.aiox/dashboard/status.json');
+const EVENTS_FILE = join(AIOX_DIR, '.aiox/dashboard/events.jsonl');
+
+interface SSEEvent {
+  type: string;
+  data: unknown;
+  timestamp: string;
+}
+
+export async function GET(request: NextRequest): Promise<Response> {
+  const encoder = new TextEncoder();
+  let lastEventPosition = 0;
+  let isConnected = true;
+
+  // Rastrear últimos tamanhos de arquivo para detecção de mudanças
+  let lastStatusMtime = 0;
+  let lastEventsSize = 0;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      // Enviar evento inicial de conexão
+      sendEvent(controller, {
+        type: 'connection:status',
+        data: { connected: true },
+        timestamp: new Date().toISOString(),
+      });
+
+      // Enviar status atual
+      sendCurrentStatus(controller);
+
+      // Enviar eventos recentes (últimos 50)
+      sendRecentEvents(controller, 50);
+
+      // Setup de file watchers
+      const watchers: ReturnType<typeof watch>[] = [];
+
+      // Watch status.json
+      if (existsSync(STATUS_FILE)) {
+        const statusWatcher = watch(STATUS_FILE, (eventType) => {
+          if (eventType === 'change' && isConnected) {
+            const stat = statSync(STATUS_FILE);
+            if (stat.mtimeMs > lastStatusMtime) {
+              lastStatusMtime = stat.mtimeMs;
+              sendCurrentStatus(controller);
+            }
+          }
+        });
+        watchers.push(statusWatcher);
+      }
+
+      // Watch events.jsonl
+      if (existsSync(EVENTS_FILE)) {
+        const eventsWatcher = watch(EVENTS_FILE, (eventType) => {
+          if (eventType === 'change' && isConnected) {
+            const stat = statSync(EVENTS_FILE);
+            if (stat.size > lastEventsSize) {
+              sendNewEvents(controller, lastEventsSize);
+              lastEventsSize = stat.size;
+            }
+          }
+        });
+        watchers.push(eventsWatcher);
+        lastEventsSize = statSync(EVENTS_FILE).size;
+      }
+
+      // Heartbeat a cada 30s
+      const heartbeatInterval = setInterval(() => {
+        if (isConnected) {
+          sendEvent(controller, {
+            type: 'heartbeat',
+            data: { alive: true },
+            timestamp: new Date().toISOString(),
+          });
+        }
+      }, 30000);
+
+      // Cleanup ao fechar
+      request.signal.addEventListener('abort', () => {
+        isConnected = false;
+        clearInterval(heartbeatInterval);
+        watchers.forEach((w) => w.close());
+        controller.close();
+      });
+    },
+  });
+
+  function sendEvent(controller: ReadableStreamDefaultController, event: SSEEvent): void {
+    const data = `data: ${JSON.stringify(event)}\n\n`;
+    controller.enqueue(encoder.encode(data));
+  }
+
+  function sendCurrentStatus(controller: ReadableStreamDefaultController): void {
+    try {
+      if (existsSync(STATUS_FILE)) {
+        const content = readFileSync(STATUS_FILE, 'utf-8');
+        const status = JSON.parse(content);
+        sendEvent(controller, {
+          type: 'status:update',
+          data: status,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    } catch (error) {
+      sendEvent(controller, {
+        type: 'error',
+        data: { message: 'Failed to read status' },
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  function sendRecentEvents(controller: ReadableStreamDefaultController, count: number): void {
+    try {
+      if (existsSync(EVENTS_FILE)) {
+        const content = readFileSync(EVENTS_FILE, 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        const recentLines = lines.slice(-count);
+
+        const events = recentLines
+          .map((line) => {
+            try {
+              return JSON.parse(line);
+            } catch {
+              return null;
+            }
+          })
+          .filter(Boolean);
+
+        sendEvent(controller, {
+          type: 'events:history',
+          data: { events },
+          timestamp: new Date().toISOString(),
+        });
+
+        lastEventPosition = content.length;
+      }
+    } catch (error) {
+      // Falha silenciosa
+    }
+  }
+
+  function sendNewEvents(controller: ReadableStreamDefaultController, fromPosition: number): void {
+    try {
+      if (existsSync(EVENTS_FILE)) {
+        const content = readFileSync(EVENTS_FILE, 'utf-8');
+        const newContent = content.slice(fromPosition);
+        const lines = newContent.trim().split('\n').filter(Boolean);
+
+        for (const line of lines) {
+          try {
+            const event = JSON.parse(line);
+            sendEvent(controller, {
+              type: 'event:new',
+              data: event,
+              timestamp: new Date().toISOString(),
+            });
+          } catch {
+            // Ignorar linhas malformadas
+          }
+        }
+      }
+    } catch (error) {
+      // Falha silenciosa
+    }
+  }
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+}
+```
+
+---
+
+## Events Store
+
+### Localização
+
+```
+apps/dashboard/src/stores/events-store.ts
+```
+
+### Interface
+
+```typescript
+// apps/dashboard/src/stores/events-store.ts
+
+import { create } from 'zustand';
+import type { DashboardEvent } from '@/types';
+
+// Retenção configurável (Decision #3)
+const DEFAULT_MAX_EVENTS = 100;
+
+export interface CurrentCommand {
+  name: string;
+  startedAt: string;
+  status: 'running' | 'complete' | 'error';
+  errorMessage?: string;
+}
+
+export interface EventRetentionSettings {
+  mode: 'session' | 'hours' | 'persistent';
+  hoursToKeep?: number;
+  maxEvents?: number;
+}
+
+interface EventsState {
+  // Conexão
+  isConnected: boolean;
+  lastUpdate: string | null;
+
+  // Sessão
+  sessionId: string | null;
+  sessionStartedAt: string | null;
+
+  // Comando atual (apenas alto nível)
+  currentCommand: CurrentCommand | null;
+
+  // Eventos recentes (apenas alto nível)
+  recentEvents: DashboardEvent[];
+
+  // Configurações de retenção
+  retentionSettings: EventRetentionSettings;
+
+  // Ações
+  setConnected: (connected: boolean) => void;
+  processEvent: (event: DashboardEvent) => void;
+  processHistoryEvents: (events: DashboardEvent[]) => void;
+  setRetentionSettings: (settings: EventRetentionSettings) => void;
+  clearEvents: () => void;
+}
+
+export const useEventsStore = create<EventsState>((set, get) => ({
+  // Estado inicial
+  isConnected: false,
+  lastUpdate: null,
+  sessionId: null,
+  sessionStartedAt: null,
+  currentCommand: null,
+  recentEvents: [],
+  retentionSettings: {
+    mode: 'session',
+    hoursToKeep: 24,
+    maxEvents: DEFAULT_MAX_EVENTS,
+  },
+
+  // Ações
+  setConnected: (connected) => set({ isConnected: connected }),
+
+  processEvent: (event) => {
+    const state = get();
+    const maxEvents = state.retentionSettings.maxEvents || DEFAULT_MAX_EVENTS;
+
+    // Adicionar a eventos recentes (circular buffer)
+    const newEvents = [...state.recentEvents, event].slice(-maxEvents);
+
+    // Processar por tipo de evento (apenas alto nível)
+    let updates: Partial<EventsState> = {
+      recentEvents: newEvents,
+      lastUpdate: event.timestamp,
+    };
+
+    switch (event.type) {
+      // Eventos de sessão
+      case 'session:start':
+        updates.sessionId = event.data.sessionId as string;
+        updates.sessionStartedAt = event.timestamp;
+        break;
+
+      case 'session:end':
+        updates.sessionId = null;
+        updates.sessionStartedAt = null;
+        updates.currentCommand = null;
+        break;
+
+      // Eventos de comando
+      case 'command:start':
+        updates.currentCommand = {
+          name: event.data.command as string,
+          startedAt: event.timestamp,
+          status: 'running',
+        };
+        break;
+
+      case 'command:complete':
+        if (state.currentCommand) {
+          updates.currentCommand = {
+            ...state.currentCommand,
+            status: 'complete',
+          };
+          // Limpar após 3 segundos
+          setTimeout(() => {
+            set({ currentCommand: null });
+          }, 3000);
+        }
+        break;
+
+      case 'command:error':
+        if (state.currentCommand) {
+          updates.currentCommand = {
+            ...state.currentCommand,
+            status: 'error',
+            errorMessage: event.data.error as string,
+          };
+        }
+        break;
+    }
+
+    set(updates);
+  },
+
+  processHistoryEvents: (events) => {
+    events.forEach((event) => {
+      get().processEvent(event);
+    });
+  },
+
+  setRetentionSettings: (settings) => {
+    set({ retentionSettings: settings });
+  },
+
+  clearEvents: () => {
+    set({
+      recentEvents: [],
+      currentCommand: null,
+    });
+  },
+}));
+
+// Seletores
+export const selectCurrentCommand = (state: EventsState) => state.currentCommand;
+export const selectRecentEvents = (state: EventsState) => state.recentEvents;
+export const selectSessionInfo = (state: EventsState) => ({
+  sessionId: state.sessionId,
+  startedAt: state.sessionStartedAt,
+});
+```
+
+---
+
+## Novos Componentes UI
+
+### Componentes Necessários (Apenas Alto Nível)
+
+| Componente          | Responsabilidade              | Prioridade |
+| ------------------- | ----------------------------- | ---------- |
+| `CommandPanel`      | Mostra comando atual e status | P0         |
+| `ActivityFeed`      | Timeline de eventos recentes  | P0         |
+| `SessionIndicator`  | Status da sessão ativa        | P1         |
+| `RetentionSettings` | Config de retenção de eventos | P2         |
+
+### CommandPanel
+
+```typescript
+// apps/dashboard/src/components/realtime/CommandPanel.tsx
+
+'use client';
+
+import { useEventsStore, selectCurrentCommand } from '@/stores/events-store';
+import { useEffect, useState } from 'react';
+import { cn } from '@/lib/utils';
+import { Loader2, CheckCircle, XCircle, Terminal } from 'lucide-react';
+
+export function CommandPanel() {
+  const currentCommand = useEventsStore(selectCurrentCommand);
+  const [elapsed, setElapsed] = useState(0);
+
+  useEffect(() => {
+    if (!currentCommand || currentCommand.status !== 'running') {
+      setElapsed(0);
+      return;
+    }
+
+    const startTime = new Date(currentCommand.startedAt).getTime();
+    const interval = setInterval(() => {
+      setElapsed(Math.floor((Date.now() - startTime) / 1000));
+    }, 1000);
+
+    return () => clearInterval(interval);
+  }, [currentCommand]);
+
+  if (!currentCommand) {
+    return (
+      <div className="p-3 rounded-lg bg-surface border border-subtle">
+        <div className="flex items-center gap-2 text-muted text-sm">
+          <Terminal className="w-4 h-4" />
+          <span>Aguardando comando...</span>
+        </div>
+      </div>
+    );
+  }
+
+  const formatElapsed = (seconds: number) => {
+    const mins = Math.floor(seconds / 60);
+    const secs = seconds % 60;
+    return mins > 0 ? `${mins}m ${secs}s` : `${secs}s`;
+  };
+
+  const statusConfig = {
+    running: {
+      icon: <Loader2 className="w-4 h-4 animate-spin text-blue-400" />,
+      bg: 'border-blue-500/30 bg-blue-500/5',
+    },
+    complete: {
+      icon: <CheckCircle className="w-4 h-4 text-green-400" />,
+      bg: 'border-green-500/30 bg-green-500/5',
+    },
+    error: {
+      icon: <XCircle className="w-4 h-4 text-red-400" />,
+      bg: 'border-red-500/30 bg-red-500/5',
+    },
+  };
+
+  const config = statusConfig[currentCommand.status];
+
+  return (
+    <div className={cn('p-3 rounded-lg border transition-luxury', config.bg)}>
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          {config.icon}
+          <span className="font-mono text-sm">{currentCommand.name}</span>
+        </div>
+        {currentCommand.status === 'running' && (
+          <span className="text-xs text-muted">{formatElapsed(elapsed)}</span>
+        )}
+      </div>
+
+      {currentCommand.status === 'error' && currentCommand.errorMessage && (
+        <div className="mt-2 p-2 rounded bg-red-500/10 text-red-400 text-xs">
+          {currentCommand.errorMessage}
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### ActivityFeed
+
+```typescript
+// apps/dashboard/src/components/realtime/ActivityFeed.tsx
+
+'use client';
+
+import { useEventsStore, selectRecentEvents } from '@/stores/events-store';
+import { cn } from '@/lib/utils';
+import { User, Terminal, AlertCircle, Play, Square, Kanban } from 'lucide-react';
+import { formatDistanceToNow } from 'date-fns';
+import { ptBR } from 'date-fns/locale';
+
+// Apenas eventos de alto nível (Decision #2)
+const EVENT_CONFIG: Record<
+  string,
+  { icon: React.ElementType; color: string; label: string }
+> = {
+  'agent:activated': { icon: User, color: 'text-purple-400', label: 'Agent ativado' },
+  'agent:deactivated': { icon: User, color: 'text-gray-400', label: 'Agent desativado' },
+  'command:start': { icon: Terminal, color: 'text-blue-400', label: 'Comando' },
+  'command:complete': { icon: Terminal, color: 'text-green-400', label: 'Comando OK' },
+  'command:error': { icon: AlertCircle, color: 'text-red-400', label: 'Erro' },
+  'story:status-change': { icon: Kanban, color: 'text-orange-400', label: 'Story' },
+  'session:start': { icon: Play, color: 'text-green-400', label: 'Sessão iniciada' },
+  'session:end': { icon: Square, color: 'text-gray-400', label: 'Sessão encerrada' },
+};
+
+interface ActivityFeedProps {
+  maxItems?: number;
+  className?: string;
+}
+
+export function ActivityFeed({ maxItems = 15, className }: ActivityFeedProps) {
+  const recentEvents = useEventsStore(selectRecentEvents);
+  const displayEvents = recentEvents.slice(-maxItems).reverse();
+
+  if (displayEvents.length === 0) {
+    return (
+      <div className={cn('p-4 text-center text-muted text-sm', className)}>
+        Nenhuma atividade recente
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn('space-y-1', className)}>
+      {displayEvents.map((event) => {
+        const config = EVENT_CONFIG[event.type] || {
+          icon: Terminal,
+          color: 'text-gray-400',
+          label: event.type,
+        };
+        const Icon = config.icon;
+
+        const getEventDetail = () => {
+          switch (event.type) {
+            case 'agent:activated':
+              return event.data.agentName as string;
+            case 'command:start':
+            case 'command:complete':
+            case 'command:error':
+              return event.data.command as string;
+            case 'story:status-change':
+              return `${event.data.storyId}: ${event.data.oldStatus} → ${event.data.newStatus}`;
+            default:
+              return null;
+          }
+        };
+
+        const detail = getEventDetail();
+        const timeAgo = formatDistanceToNow(new Date(event.timestamp), {
+          addSuffix: true,
+          locale: ptBR,
+        });
+
+        return (
+          <div
+            key={event.id}
+            className="flex items-center gap-2 px-2 py-1.5 rounded hover:bg-surface-hover transition-colors text-xs"
+          >
+            <Icon className={cn('w-3.5 h-3.5 flex-shrink-0', config.color)} />
+            <span className="text-secondary truncate flex-1">
+              {config.label}
+              {detail && (
+                <span className="text-muted ml-1 font-mono">{detail}</span>
+              )}
+            </span>
+            <span className="text-muted text-[10px] flex-shrink-0">{timeAgo}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+```
+
+### SessionIndicator
+
+```typescript
+// apps/dashboard/src/components/realtime/SessionIndicator.tsx
+
+'use client';
+
+import { useEventsStore, selectSessionInfo } from '@/stores/events-store';
+import { formatDistanceToNow } from 'date-fns';
+import { ptBR } from 'date-fns/locale';
+import { Activity, Clock } from 'lucide-react';
+
+export function SessionIndicator() {
+  const { sessionId, startedAt } = useEventsStore(selectSessionInfo);
+
+  if (!sessionId) {
+    return (
+      <div className="flex items-center gap-2 text-muted text-xs">
+        <Activity className="w-3.5 h-3.5" />
+        <span>Sem sessão ativa</span>
+      </div>
+    );
+  }
+
+  const duration = startedAt
+    ? formatDistanceToNow(new Date(startedAt), { locale: ptBR })
+    : '';
+
+  return (
+    <div className="flex items-center gap-3 text-xs">
+      <div className="flex items-center gap-1.5 text-green-400">
+        <Activity className="w-3.5 h-3.5" />
+        <span>Sessão ativa</span>
+      </div>
+      {duration && (
+        <div className="flex items-center gap-1 text-muted">
+          <Clock className="w-3 h-3" />
+          <span>{duration}</span>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Fluxo de Dados Completo (Alto Nível)
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                     COMPLETE DATA FLOW (HIGH-LEVEL ONLY)                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           1. USER ACTION IN CLI                              │
+│                                                                              │
+│  $ claude                                                                    │
+│  > @architect                          ← agent:activated                     │
+│  🏛️ Aria (Visionary) ready                                                  │
+│  > *create-architecture                ← command:start                       │
+│  [Claude working...]                                                         │
+│  ✓ Architecture created                ← command:complete                    │
+│  > *exit                               ← agent:deactivated                   │
+│                                                                              │
+└─────────────────────┬───────────────────────────────────────────────────────┘
+                      │
+                      │  Claude Code Hooks (Decision #1)
+                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    2. EVENTS WRITTEN TO FILESYSTEM                           │
+│                                                                              │
+│  .aiox/dashboard/events.jsonl (HIGH-LEVEL ONLY)                             │
+│  ─────────────────────────────────────────────────────                      │
+│  {"type":"session:start","data":{"sessionId":"uuid"},"ts":"..."}            │
+│  {"type":"agent:activated","data":{"agentId":"architect"},"ts":"..."}       │
+│  {"type":"command:start","data":{"command":"*create-architecture"},"ts":""}│
+│  {"type":"command:complete","data":{"success":true},"ts":"..."}             │
+│  {"type":"agent:deactivated","data":{"agentId":"architect"},"ts":"..."}     │
+│                                                                              │
+└─────────────────────┬───────────────────────────────────────────────────────┘
+                      │
+                      │  File watcher
+                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      3. SSE ENDPOINT STREAMS EVENTS                          │
+│                                                                              │
+│  /api/events (Server-Sent Events)                                           │
+│  ────────────────────────────────                                           │
+│                                                                              │
+│  SSE Output (high-level events only):                                       │
+│  data: {"type":"event:new","data":{"type":"agent:activated",...}}          │
+│  data: {"type":"event:new","data":{"type":"command:start",...}}            │
+│  data: {"type":"event:new","data":{"type":"command:complete",...}}         │
+│                                                                              │
+└─────────────────────┬───────────────────────────────────────────────────────┘
+                      │
+                      │  EventSource
+                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       4. STORES UPDATE STATE                                 │
+│                                                                              │
+│  events-store (simplified)                                                  │
+│  ─────────────────────────                                                  │
+│  {                                                                          │
+│    sessionId: "uuid",                                                       │
+│    currentCommand: { name: '*create-architecture', status: 'complete' },   │
+│    recentEvents: [agent:activated, command:start, command:complete, ...]   │
+│  }                                                                          │
+│                                                                              │
+└─────────────────────┬───────────────────────────────────────────────────────┘
+                      │
+                      │  React re-render
+                      ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       5. UI COMPONENTS UPDATE                                │
+│                                                                              │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                         Dashboard UI                                 │   │
+│  │                                                                       │   │
+│  │  ┌─────────────────────────────┐  ┌─────────────────────────────┐   │   │
+│  │  │       CommandPanel          │  │       ActivityFeed          │   │   │
+│  │  │  ─────────────────────────  │  │  ─────────────────────────  │   │   │
+│  │  │                             │  │                             │   │   │
+│  │  │  ✓ *create-architecture     │  │  14:32 Comando OK           │   │   │
+│  │  │    Completo                 │  │  14:30 Comando iniciado     │   │   │
+│  │  │                             │  │  14:29 Agent ativado Aria   │   │   │
+│  │  │                             │  │  14:28 Sessão iniciada      │   │   │
+│  │  └─────────────────────────────┘  └─────────────────────────────┘   │   │
+│  │                                                                       │   │
+│  │  ┌─────────────────────────────────────────────────────────────┐    │   │
+│  │  │                         StatusBar                            │    │   │
+│  │  │  ● Connected  │  Sessão ativa (5 min)  │  @architect (Aria) │    │   │
+│  │  └─────────────────────────────────────────────────────────────┘    │   │
+│  │                                                                       │   │
+│  └───────────────────────────────────────────────────────────────────────┘   │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Implementação Faseada (Simplificada)
+
+### Fase 1: Fundação (P0)
+
+| Item                          | Descrição                  | Esforço |
+| ----------------------------- | -------------------------- | ------- |
+| Claude Code Hooks Integration | Conectar aos hooks nativos | 2h      |
+| events.jsonl                  | Formato high-level         | 1h      |
+| Enhanced SSE                  | Watch events.jsonl         | 2h      |
+| events-store                  | Store simplificado         | 1h      |
+
+**Entregável:** Eventos high-level fluem do CLI para o Dashboard
+
+### Fase 2: UI Core (P1)
+
+| Item                  | Descrição                  | Esforço |
+| --------------------- | -------------------------- | ------- |
+| CommandPanel          | Comando atual + status     | 1h      |
+| ActivityFeed          | Timeline simplificada      | 1h      |
+| SessionIndicator      | Status da sessão           | 30min   |
+| StatusBar integration | Integrar novos indicadores | 1h      |
+
+**Entregável:** Dashboard mostra atividade high-level em tempo real
+
+### Fase 3: Configuração (P2)
+
+| Item                   | Descrição                       | Esforço |
+| ---------------------- | ------------------------------- | ------- |
+| RetentionSettings UI   | Toggle session/hours/persistent | 1h      |
+| Settings integration   | Persistência de preferências    | 1h      |
+| localStorage/IndexedDB | Implementar modos de retenção   | 2h      |
+
+**Entregável:** Retenção de eventos configurável pelo usuário
+
+---
+
+## Decisões Tomadas
+
+### 1. Fonte de Eventos ✅
+
+**Decisão:** Claude Code Hooks
+
+| Aspecto       | Detalhe                                     |
+| ------------- | ------------------------------------------- |
+| Implementação | Usar hooks nativos do Claude Code           |
+| Vantagem      | Automático, completo, sem wrapper adicional |
+| Dependência   | API de hooks do Claude Code                 |
+
+### 2. Nível de Detalhe ✅
+
+**Decisão:** High-level apenas
+
+| Eventos Incluídos              | Eventos Excluídos             |
+| ------------------------------ | ----------------------------- |
+| `agent:activated/deactivated`  | `tool:call` (Read/Write/Bash) |
+| `command:start/complete/error` | `file:read/write/create`      |
+| `session:start/end`            | `llm:thinking/responding`     |
+| `story:status-change`          | Output streaming              |
+
+**Rationale:** Foco em monitoramento, não debug. Menor volume de dados, melhor performance.
+
+### 3. Retenção de Eventos ✅
+
+**Decisão:** Configurável pelo usuário
+
+```typescript
+// settings-store.ts
+interface EventRetentionSettings {
+  mode: 'session' | 'hours' | 'persistent';
+  hoursToKeep?: number; // quando mode = 'hours'
+  maxEvents?: number; // limite máximo em qualquer modo
+}
+
+// Defaults
+const DEFAULT_RETENTION: EventRetentionSettings = {
+  mode: 'session',
+  hoursToKeep: 24,
+  maxEvents: 1000,
+};
+```
+
+| Modo         | Comportamento             | Storage      |
+| ------------ | ------------------------- | ------------ |
+| `session`    | Limpa ao fechar dashboard | Memory       |
+| `hours`      | Mantém últimas N horas    | localStorage |
+| `persistent` | Mantém até limite         | IndexedDB    |
+
+**UI:** Toggle em Settings → Events → Retention
+
+---
+
+_Documentação gerada por @architect (Aria) - AIOX Core v2.0_