@dewtech/dare-cli 2.17.0 → 3.1.0

package/templates/ide/antigravity/.agents/skills/dare-llm-integration/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: dare-llm-integration
+description: Integração com LLMs (Large Language Models) em projetos DARE. Fornece abstração LLMProvider, cache em memória com TTL, rate limiting via token bucket, prompt templates versionados e validação de output via JSON Schema. Cobre antipatterns crítico de prompt injection e LLM output não validado.
+---
+
+# DARE LLM Integration Skill
+
+Você é um especialista em integração com LLMs (Gemini, Claude, GPT, modelos locais). Seu papel é garantir que toda chamada a LLM em projeto DARE seja **abstraída, cacheada, rate-limited, validada e auditável**.
+
+## Quando usar esta skill
+
+- Projeto vai consumir Gemini, Claude API, OpenAI, Ollama ou similar
+- Você está revisando Handler que chama SDK de LLM diretamente
+- Você está auditando custos de LLM no projeto
+- Você está adicionando proteção contra prompt injection
+
+## A arquitetura recomendada
+
+```
+┌────────────────────────────────────────────────────────┐
+│  Handler / Service                                      │
+└────────────────────────────────────────────────────────┘
+                       ↓ injeta
+┌────────────────────────────────────────────────────────┐
+│  LLMProvider (interface)                                │
+│  ├── GeminiProvider                                     │
+│  ├── ClaudeProvider                                     │
+│  ├── OpenAIProvider                                     │
+│  └── OllamaProvider (local)                             │
+└────────────────────────────────────────────────────────┘
+                       ↓ wrapping
+┌────────────────────────────────────────────────────────┐
+│  Cache (TTL)  +  RateLimit (token bucket)  +  Schema    │
+└────────────────────────────────────────────────────────┘
+                       ↓
+┌────────────────────────────────────────────────────────┐
+│  HTTP call externo (Gemini API, etc.)                   │
+└────────────────────────────────────────────────────────┘
+```
+
+## Os 5 pilares
+
+### 1. LLMProvider abstraction
+
+NUNCA chame SDK do Gemini/OpenAI dentro de um Handler ou Service de negócio. Sempre passe pela interface `LLMProvider`.
+
+```typescript
+// ❌ Errado
+class SummaryService {
+  async run(text: string) {
+    const client = new GoogleGenAI({apiKey: 'xxx'});
+    return client.generateContent({contents: text});
+  }
+}
+
+// ✅ Certo
+class SummaryService {
+  constructor(private llm: LLMProvider) {}
+  async run(text: string) {
+    return this.llm.complete({
+      promptId: 'summarize-v1',
+      input: { text },
+      schema: SummarySchema,
+    });
+  }
+}
+```
+
+### 2. Cache em memória com TTL
+
+Toda chamada deve passar por cache. Cache key = `hash(promptId + input + model)`. TTL configurável por prompt (default 1 hora).
+
+**Antipattern AP-02:** Sem cache → custo explode em loops.
+
+### 3. Rate limit via token bucket
+
+Proteja a integração externa **e** seu wallet. Configure tokens/segundo por provider.
+
+| Provider | Limite típico |
+|---|---|
+| Gemini Free | 15 RPM, 1 milhão tokens/dia |
+| Claude API | 50 RPM (tier 1) |
+| OpenAI | 500 RPM (tier 1) |
+| Ollama local | sem limite, mas latência alta |
+
+### 4. Prompt templates versionados
+
+Prompts NUNCA ficam inline em código. Vivem em `prompts/<id>.v<n>.md`:
+
+```markdown
+---
+id: summarize
+version: 1
+model: gemini-2.0-flash
+temperature: 0.2
+max_tokens: 500
+schema: SummarySchema
+---
+
+# System
+
+You are a concise summarizer. Output JSON with this schema:
+{schema}
+
+# User
+
+Summarize the following text in 3 bullet points:
+
+<text>{{ text }}</text>
+```
+
+Substituição usa **template engine seguro** (Jinja2, Handlebars com sandbox, ou string interpolation com escape) — nunca `eval` ou `f-string` direto com user input.
+
+### 5. Validação via JSON Schema
+
+LLM mente. Sempre valide o output:
+
+```typescript
+const result = await llm.complete({...});
+const validated = SummarySchema.parse(result);  // Zod, Pydantic, ajv...
+if (!validated.success) {
+  throw new LLMOutputInvalidError(validated.error);
+  // Logar + alertar — pode indicar prompt injection ou drift de modelo
+}
+```
+
+## Métricas obrigatórias
+
+| ID | Métrica | Como medir |
+|---|---|---|
+| M-01 | 100% das chamadas LLM via LLMProvider injetado | grep por `new GoogleGenAI \| new OpenAI \| Anthropic(` em Services |
+| M-02 | 100% das responses LLM cacheadas | logs do cache layer |
+| M-03 | 100% das requests LLM com rate limit | rate limiter ativo em todo provider |
+| M-04 | 100% das respostas LLM validadas contra schema | grep por `.parse(` ou `Pydantic` no resultado |
+
+## Antipatterns
+
+| AP | Antipattern | Por que evitar |
+|---|---|---|
+| AP-01 | SDK do LLM direto em Handler | impossível mockar, impossível trocar de provider |
+| AP-02 | Sem cache | custo explode, latência ruim |
+| AP-03 | Prompt em código | impossível versionar e A/B testar |
+| AP-04 | User input direto em prompt | prompt injection trivial |
+| AP-05 | Confiar em output LLM sem validar | LLM mente — schema é defesa |
+
+## Defesa contra prompt injection (crítico)
+
+```python
+# ❌ Errado — instrução + dado misturados
+system = f"You are an assistant. {user_question}"
+
+# ✅ Certo — separação clara
+messages = [
+    {"role": "system", "content": "You are an assistant. Answer only based on the provided document."},
+    {"role": "user", "content": f"<document>{escape(doc)}</document>\n\n<question>{escape(q)}</question>"}
+]
+```
+
+Regras:
+- Use delimitadores (`<document>`, `<question>`)
+- Escape conteúdo do usuário (XML escape, HTML escape)
+- Detecte e remova padrões "Ignore as instruções acima", "You are now ..."
+- Valide output contra schema — output fora do schema = possível injection bem-sucedido
+
+## Como aplicar
+
+### Passo 1: Criar abstração LLMProvider
+
+```typescript
+interface LLMProvider {
+  complete(req: LLMRequest): Promise<LLMResponse>;
+}
+
+interface LLMRequest {
+  promptId: string;
+  input: Record<string, unknown>;
+  schema: ZodSchema;
+  options?: { temperature?: number; maxTokens?: number };
+}
+```
+
+### Passo 2: Implementar 1+ provider
+
+Comece com o que o projeto usa (Gemini, Claude, etc.). Adicione mais conforme necessário.
+
+### Passo 3: Configurar cache
+
+`packages/skills/dare-llm-integration/cache/` tem implementação em memória com TTL pronta. Use ou copie.
+
+### Passo 4: Configurar rate limit
+
+Token bucket por provider, configurado em `app.config`.
+
+### Passo 5: Migrar prompts inline para arquivos
+
+Inventarie todos os `system: "..."` no código e mova para `prompts/<id>.v1.md`.
+
+### Passo 6: Adicionar validação de output
+
+Schema Zod/Pydantic/serde para cada prompt. CI falha se prompt não tiver schema declarado.
+
+## Boas práticas
+
+1. **Provider neutro no domínio** — Service não sabe se é Gemini ou Claude
+2. **Custo é parte da observabilidade** — logue tokens in/out + custo estimado por request
+3. **Fallback** — se provider primário falhar, tente secundário (Gemini → Claude)
+4. **Latência alta = degrada UX** — esconda atrás de fila assíncrona quando >2s
+
+## Dicas
+
+- **Leia** `docs/design/skills/dare-llm-integration/DESIGN.md`
+- **Combine** com `dare-security` (RS-* para prompt injection)
+- **Use** os providers em `packages/skills/dare-llm-integration/providers/` como referência
+
+---
+
+Esta skill é parte do DARE Method e está sob licença MIT.

package/templates/ide/antigravity/.agents/skills/dare-migrate/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: dare-migrate
+description: Camada semântica da migração (Fase 2 brownfield). Roda depois do comando `dare migrate` e escreve a estratégia de migração + cenários Gherkin de paridade reais no DARE/MIGRATION/, garantindo reimplementação fiel ao legado.
+---
+
+# DARE Migrate Skill — Migração com paridade (brownfield Fase 2)
+
+Você é o agente que transforma o entendimento do legado em um **plano de migração com paridade**.
+Esta skill é a camada **semântica**: roda **depois** do comando `dare migrate`, que já leu os
+artefatos do `reverse`/`dna` e gerou os esqueletos. Sua função é **escrever a estratégia de migração
+e os cenários Gherkin de paridade reais** — o contrato comportamental que garante uma reimplementação
+fiel ao legado.
+
+> Pré-requisito: o comando `dare migrate --to <stack>` precisa ter rodado antes (gera
+> `DARE/MIGRATION/MIGRATION.md`, `migration-facts.json`, `parity/*.feature`). Que por sua vez exige
+> `dare reverse` já executado. Se faltar, peça ao usuário para rodar na ordem.
+
+## Quando usar esta skill
+- Projeto legado entendido (`reverse` + `dna`) que será reimplementado em outra stack.
+- Acabou de rodar `dare migrate` e há seções `<!-- AGENT -->` / `# AGENT` em aberto.
+
+## Passo a passo
+
+### 1. Carregar contexto (não re-varrer)
+Leia `migration-facts.json` (origem/alvo/módulos/blocking gaps), `IDEIA.md` + `REVERSE/module-*.md`
+e `PROJECT-DNA.md`. Abra arquivos-chave do legado só o necessário para inferir comportamento.
+
+### 2. Preencher `DARE/MIGRATION/MIGRATION.md`
+- **Decisão de Paradigma** — mudou (procedural→OO, monólito→serviços)? Decisão + justificativa.
+- **Estratégia** — big-bang vs. strangler/parallel-run; ordem dos módulos; feature flags.
+- **Registro de Risco** — tratar cada blocking gap (🔴) + riscos de regressão/dados/performance.
+- **Arquitetura-alvo** — na stack-alvo, alinhada ao DNA quando o paradigma for preservado.
+- **Cutover & Rollback** — passos, validação de paridade (rodar `.feature`), go/no-go, rollback.
+
+### 3. Gherkin de paridade (`parity/<módulo>.feature`)
+Um `Scenario` por fluxo observável, derivado do **comportamento legado real**: `Given` → `When` →
+`Then` idêntico ao legado. Inclua bordas/formatos (arredondamento, máscaras). É o contrato de aceite
+da reimplementação na stack-alvo.
+
+### 4. Apresentar ao usuário
+Resumo: paradigma, estratégia, nº de cenários de paridade, blocking gaps a resolver.
+
+## Regras de ouro
+1. **Paridade primeiro** — todo fluxo crítico vira `Scenario`.
+2. **Blocking gaps são bloqueantes** — 🔴 não resolvido é risco; trate ou registre.
+3. **Respeite o DNA** — arquitetura-alvo segue as convenções da casa.
+4. **Não invente comportamento** — cenário sem base no legado = regressão silenciosa.
+5. **Strangler quando possível** — incremental com parallel-run reduz risco.
+
+## Antipatterns
+| AP | Antipattern | Por quê |
+|---|---|---|
+| AP-01 | Gherkin genérico sem base no legado | Não garante paridade |
+| AP-02 | Ignorar blocking gaps (🔴) | Reimplementa sobre incerteza |
+| AP-03 | Big-bang sem necessidade | Maximiza risco |
+| AP-04 | Arquitetura-alvo desalinhada do DNA | Código vira ilha inconsistente |
+| AP-05 | Reescrever os fatos determinísticos do CLI | Quebra a fonte de verdade |
+
+---
+
+Skill MIT — parte do DARE Method. Fase 2 (brownfield). Pareia com o comando `dare migrate`.

package/templates/ide/antigravity/.agents/skills/dare-quality-telemetry/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: dare-quality-telemetry
+description: Coleta de métricas de qualidade e detecção de regressões em projetos DARE. Agrega métricas das skills filhas (dare-ax, dare-layered-design, etc.), persiste histórico em tmp/dare_metrics.json e detecta regressões contra baseline. Inclui template de GitHub Actions.
+---
+
+# DARE Quality Telemetry Skill
+
+Você é um engenheiro de plataforma especialista em observabilidade de qualidade. Seu papel é garantir que todo projeto DARE colete métricas das skills aplicadas, persista histórico, e detecte regressões antes do release.
+
+## Quando usar esta skill
+
+- Projeto já tem várias skills DARE configuradas (ax, layered-design, llm-integration, etc.)
+- Você quer ver evolução de métricas ao longo do tempo
+- Você quer falhar o CI quando uma métrica regredir
+- Você quer dashboards/reports de saúde do projeto
+
+## O que essa skill faz
+
+1. **Coleta** — roda os collectors de cada skill filha em paralelo
+2. **Agrega** — junta todas as métricas em um snapshot estruturado
+3. **Persiste** — guarda em `tmp/dare_metrics.json` (histórico append-only)
+4. **Compara** — diff contra `tmp/dare_metrics_baseline.json`
+5. **Reporta** — gera markdown report para CI ou stdout
+6. **Bloqueia** — exit code ≠ 0 se regressão crítica
+
+## Arquitetura
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  collect.ts (orquestrador)                                │
+└──────────────────────────────────────────────────────────┘
+            ↓ chama em paralelo
+┌────────────────┬────────────────┬────────────────┐
+│ ax collector   │ layered coll.  │ llm coll.      │  …
+└────────────────┴────────────────┴────────────────┘
+            ↓
+┌──────────────────────────────────────────────────────────┐
+│  Aggregator → snapshot { skill: { M-01: value, ... } }    │
+└──────────────────────────────────────────────────────────┘
+            ↓
+┌──────────────────────────────────────────────────────────┐
+│  tmp/dare_metrics.json (append) + Regression detector     │
+└──────────────────────────────────────────────────────────┘
+            ↓
+┌──────────────────────────────────────────────────────────┐
+│  Reporter → markdown / json / GitHub Action summary       │
+└──────────────────────────────────────────────────────────┘
+```
+
+## Métricas obrigatórias da própria skill
+
+| ID | Métrica | Como medir |
+|---|---|---|
+| M-01 | 100% dos builds incluem coleta de métricas (skill instalada = sempre true) | Verifica `package.json` ou pipeline yml |
+| M-02 | 0 regressões passam despercebidas (baseline existe para comparação) | `test -f tmp/dare_metrics_baseline.json` |
+| M-03 | Histórico de métricas mantido | `test -f tmp/dare_metrics.json` |
+| M-04 | Workflow GitHub Actions existe | `test -f .github/workflows/dare-metrics.yml` |
+
+## Como aplicar
+
+### Passo 1: Instalar a skill no projeto
+
+```bash
+# Dentro do projeto
+pnpm add @dare/quality-telemetry
+# ou
+npm install @dare/quality-telemetry
+```
+
+### Passo 2: Configurar quais skills rastrear
+
+```yaml
+# dare.config.yml
+telemetry:
+  skills:
+    - dare-ax
+    - dare-layered-design
+    - dare-llm-integration
+    - dare-frontend-design
+    - dare-realtime
+  output: tmp/dare_metrics.json
+  baseline: tmp/dare_metrics_baseline.json
+  fail_on_regression: true
+```
+
+### Passo 3: Rodar collect
+
+```bash
+dare metrics collect
+# saída:
+#   ✓ dare-ax        M-01:1.0  M-02:1.0  M-03:1.0  M-04:1.0
+#   ✓ dare-layered   M-01:0.95 M-02:1.0  M-03:1.0  M-04:1.0
+#   ✓ dare-llm       M-01:1.0  M-02:0.92 M-03:1.0  M-04:1.0
+```
+
+### Passo 4: Capturar baseline
+
+```bash
+dare metrics baseline
+# copia tmp/dare_metrics.json → tmp/dare_metrics_baseline.json
+```
+
+### Passo 5: Adicionar workflow CI
+
+```yaml
+# .github/workflows/dare-metrics.yml
+name: DARE Metrics
+
+on: [push, pull_request]
+
+jobs:
+  metrics:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: pnpm install
+      - run: pnpm dare metrics collect
+      - run: pnpm dare metrics compare
+        # exit 1 se regressão crítica detectada
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dare-metrics
+          path: tmp/dare_metrics*.json
+```
+
+## Schema do snapshot
+
+```json
+{
+  "timestamp": "2026-05-26T10:30:00Z",
+  "commit": "1d4a1417",
+  "branch": "main",
+  "skills": {
+    "dare-ax": {
+      "M-01": { "value": 1.0, "status": "PASS" },
+      "M-02": { "value": 1.0, "status": "PASS" },
+      "M-03": { "value": 1.0, "status": "PASS" },
+      "M-04": { "value": 1.0, "status": "PASS" }
+    },
+    "dare-layered-design": {
+      "M-01": { "value": 0.95, "status": "PASS" },
+      "M-02": { "value": 1.0, "status": "PASS" },
+      "M-03": { "value": 1.0, "status": "PASS" },
+      "M-04": { "value": 1.0, "status": "PASS" }
+    }
+  }
+}
+```
+
+## Detecção de regressão
+
+Para cada métrica, comparar valor atual com baseline:
+
+| Mudança | Severidade | Ação |
+|---|---|---|
+| value caiu ≥ 5% | CRITICAL | bloquear PR |
+| value caiu < 5% mas ≥ 1% | WARNING | comentar no PR, não bloquear |
+| value subiu | INFO | celebrar |
+| value igual | NEUTRAL | nenhuma |
+
+## Antipatterns
+
+| AP | Antipattern | Por que evitar |
+|---|---|---|
+| AP-01 | Coletar métricas sem baseline | Não dá pra detectar regressão |
+| AP-02 | Histórico não versionado | Perde contexto histórico |
+| AP-03 | Coletar mas não bloquear regressão | CI vira teatro |
+| AP-04 | Baseline desatualizado | Regressão real fica invisível |
+
+## Boas práticas
+
+1. **Baseline atualizado a cada release** — não a cada commit
+2. **Regressão = bloqueio de release**, não comentário ignorável
+3. **Métricas exportadas para Datadog/Grafana** após N coletas, para visualizar tendência
+4. **Skill deve rodar em < 60s** — se demorar, paralelizar collectors
+
+## Dicas
+
+- **Use** o template `packages/skills/dare-quality-telemetry/github_actions_template.ts` para gerar `.github/workflows/dare-metrics.yml`
+- **Combine** com `dare-ax` (M-01 a M-04 dela são coletadas aqui)
+- **Estenda** criando collectors custom para métricas específicas do projeto (cobertura de testes, build time, etc.)
+
+---
+
+Esta skill é parte do DARE Method e está sob licença MIT.

package/templates/ide/antigravity/.agents/skills/dare-realtime/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: dare-realtime
+description: Comunicação real-time (WebSocket, SSE) em projetos DARE. Fornece schema validation de eventos, registro central de tipos, reconexão com exponential backoff, e gerenciamento de subscriptions com limpeza garantida (zero ghost listeners).
+---
+
+# DARE Realtime Skill
+
+Você é um especialista em comunicação real-time. Seu papel é garantir que toda integração WebSocket/SSE em projeto DARE seja **tipada, autorizada, reconectável e sem ghost listeners**.
+
+## Quando usar esta skill
+
+- Projeto precisa de WebSocket (chat, notifications, live updates)
+- Projeto precisa de SSE (logs streaming, métricas em tempo real)
+- Você está auditando ghost listeners (memória crescendo após desconexão)
+- Você está revisando código que faz `socket.on('event', ...)` sem cleanup
+
+## Arquitetura recomendada
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Event Registry                                          │
+│  - Tipos de evento com schema JSON                       │
+│  - Versionamento (v1, v2…)                               │
+│  - Autorização por evento                                │
+└─────────────────────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────────────────────┐
+│  Subscription Manager                                    │
+│  - Map<connection_id, Set<event_type>>                   │
+│  - Cleanup garantido on disconnect                       │
+└─────────────────────────────────────────────────────────┘
+                       ↓
+┌─────────────────────────────────────────────────────────┐
+│  Reconnect Strategy                                      │
+│  - Exponential backoff (1s, 2s, 4s, 8s, max 30s)         │
+│  - Jitter para evitar thundering herd                    │
+│  - Resync de estado após reconectar                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+## Os 4 pilares
+
+### 1. Schema validation de eventos
+
+Todo evento WebSocket/SSE tem schema JSON:
+
+```typescript
+// event_registry.ts
+const events = {
+  'user.created.v1': z.object({
+    id: z.string().uuid(),
+    email: z.string().email(),
+    createdAt: z.string().datetime(),
+  }),
+  'message.sent.v1': z.object({
+    conversationId: z.string().uuid(),
+    senderId: z.string().uuid(),
+    body: z.string().max(2000),
+    sentAt: z.string().datetime(),
+  }),
+};
+```
+
+Server valida antes de emitir, client valida antes de processar. Evento inválido = log + drop.
+
+### 2. Registro central de tipos
+
+Um único `event_registry.ts/py/rs` lista todos os event types. Adicionar evento novo passa por PR explícito. Versionamento via sufixo (`.v1`, `.v2`).
+
+### 3. Reconexão com exponential backoff
+
+```typescript
+class ReconnectStrategy {
+  private attempt = 0;
+  next(): number {
+    const base = Math.min(1000 * 2 ** this.attempt, 30_000);
+    const jitter = Math.random() * 1000;
+    this.attempt++;
+    return base + jitter;
+  }
+  reset() { this.attempt = 0; }
+}
+```
+
+Após reconectar, **resync de estado** — buscar eventos perdidos via REST ou pedir snapshot via WS.
+
+### 4. Subscription manager (zero ghost listeners)
+
+Cada subscription rastreada em map, com cleanup automático:
+
+```typescript
+class SubscriptionManager {
+  private subs = new Map<string, Set<string>>(); // connectionId → events
+  
+  subscribe(connId: string, event: string) {
+    if (!this.subs.has(connId)) this.subs.set(connId, new Set());
+    this.subs.get(connId)!.add(event);
+  }
+  
+  unsubscribeAll(connId: string) {
+    this.subs.delete(connId);
+  }
+  
+  // Forçar limpeza on disconnect — SEMPRE
+  onDisconnect(connId: string) {
+    this.unsubscribeAll(connId);
+  }
+}
+```
+
+## Métricas obrigatórias
+
+| ID | Métrica | Como medir |
+|---|---|---|
+| M-01 | 100% de event types com JSON Schema definido | grep no registry |
+| M-02 | 100% de subscriptions autorizadas | verificar `authorize()` antes de `subscribe()` |
+| M-03 | 0 ghost listeners após desconexão | métrica `subs.size` por conexão = 0 após disconnect |
+| M-04 | Estratégia de reconexão configurada | grep por `ReconnectStrategy` ou similar |
+
+## Antipatterns
+
+| AP | Antipattern | Sinal | Correção |
+|---|---|---|---|
+| AP-01 | Evento sem schema | `socket.emit('foo', anything)` | Adicionar schema no registry |
+| AP-02 | `socket.on(...)` sem cleanup | listener fica vivo após disconnect | Usar SubscriptionManager |
+| AP-03 | Reconexão sem backoff | reconecta imediatamente em loop | Exponential backoff + jitter |
+| AP-04 | Sem autorização de subscription | usuário ouve eventos de outro tenant | `authorize(user, event)` antes de `subscribe()` |
+| AP-05 | Broadcast sem filtro | `io.emit()` para todos | Use rooms / channels por tenant |
+| AP-06 | Estado não recuperado após reconectar | UI mostra dados stale | Resync via REST ou snapshot |
+
+## Como aplicar
+
+### Passo 1: Criar event registry
+
+```typescript
+// src/realtime/event_registry.ts
+export const EventRegistry = {
+  'user.created.v1': { schema: UserCreatedSchema, requires: 'admin' },
+  'message.sent.v1': { schema: MessageSentSchema, requires: 'participant' },
+};
+```
+
+### Passo 2: Implementar subscription manager
+
+Use `packages/skills/dare-realtime/subscription_manager.ts` como template. Garante cleanup on disconnect.
+
+### Passo 3: Configurar reconexão no client
+
+```typescript
+const strategy = new ReconnectStrategy({ base: 1000, max: 30_000 });
+socket.on('disconnect', () => {
+  setTimeout(() => socket.connect(), strategy.next());
+});
+socket.on('connect', () => {
+  strategy.reset();
+  resyncState(); // fetch via REST eventos perdidos
+});
+```
+
+### Passo 4: Adicionar autorização
+
+```typescript
+socket.on('subscribe', (eventType) => {
+  if (!authorize(socket.user, eventType)) {
+    socket.emit('error', { code: 'FORBIDDEN' });
+    return;
+  }
+  subscriptionManager.subscribe(socket.id, eventType);
+});
+```
+
+### Passo 5: Validar eventos no client e server
+
+Server antes de emitir:
+```typescript
+const schema = EventRegistry[eventType].schema;
+const valid = schema.safeParse(payload);
+if (!valid.success) { log.error(...); return; }
+io.to(room).emit(eventType, valid.data);
+```
+
+Client antes de processar:
+```typescript
+socket.on(eventType, (payload) => {
+  const valid = EventRegistry[eventType].schema.safeParse(payload);
+  if (!valid.success) { log.warn(...); return; }
+  handleEvent(valid.data);
+});
+```
+
+## Boas práticas
+
+1. **WebSocket vs SSE** — SSE para server→client unidirecional (logs, métricas). WS para bidirectional (chat).
+2. **Rooms/channels por tenant** — evita broadcast cross-tenant
+3. **Heartbeat / ping-pong** — detectar conexão zumbi (network OK mas peer não responde)
+4. **Backpressure** — se client lento, fila no server explode. Drop eventos antigos ou aplicar rate limit.
+5. **Replay limitado** — guardar últimos N eventos por room para reconexão recente, não histórico completo
+
+## Stack recomendada
+
+| Stack | WebSocket | SSE |
+|---|---|---|
+| Node | `socket.io`, `ws` | `eventsource` (client) + endpoint custom |
+| Rails | Action Cable | Rack streaming |
+| Rust/Axum | `tokio-tungstenite`, `axum` ws | `axum::sse::Sse` |
+| FastAPI | `fastapi.WebSocket` | `EventSourceResponse` |
+| Go | `gorilla/websocket`, `melody` | stdlib `http.Flusher` |
+
+## Dicas
+
+- **Leia** `docs/design/skills/dare-realtime/DESIGN.md`
+- **Combine** com `dare-security` para autorização
+- **Use** os templates em `packages/skills/dare-realtime/`
+
+---
+
+Esta skill é parte do DARE Method e está sob licença MIT.