chore: initial monorepo scaffold + WDS Phase 1+2 artifacts

- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-27 14:34:20 +00:00
commit 17c08e6392
3631 changed files with 855518 additions and 0 deletions
--- a/design-artifacts/A-Product-Brief/dialog/decisions.md
+++ b/design-artifacts/A-Product-Brief/dialog/decisions.md
@@ -0,0 +1,768 @@
+# Decisões — Phase 1 (Project Brief)
+
+> Log de decisões-chave tomadas durante a Phase 1. Append-only.
+
+---
+
+## 2026-05-26 — Step 1a (Client Profile)
+
+### Organização
+- **JCS Sistemas** é PME estabelecida (software house), 11-50 pessoas, alta maturidade técnica, design ainda iniciante.
+- SAR é o **1º projeto da JCS com processo UX formal**.
+
+### People & decisão
+- **Julian** acumula 3 papéis: Product Owner + Tech Lead + único Champion.
+- **Autonomia total** para decidir escopo/prazo/design.
+- **Cultura fast-individual:** sem comitê, sem signoff externo, decisões saem rápido.
+
+### Driver
+- SAR **não é "consertar legado"**. É **upgrade de tier**: unificar força de vendas (app Android) + ERP (Desktop) num **SaaS web vendável**.
+- **Sucesso = JCS competitiva como SaaS de força de vendas regional/nacional.**
+- SAR funciona como **vitrine de marca JCS** — vai além de produto, é posicionamento.
+
+### Working style
+- Sem deadline rígido.
+- Sessões longas focadas no chat.
+- Velocidade > formalismo (mas qualidade > velocidade quando conflitam).
+
+### Implicações
+- Posso ser direto em recomendações (sem precisar embalar politicamente).
+- Steps 27-32 (Platform) vão ser **consolidação documental** via STACK.md, não descoberta.
+- Steps 1-12 (Brief estratégico) e 13-18 (Content) são onde há trabalho real.
+- Phase 2 (Trigger Map) precisa considerar **clientes-empresa potenciais** como persona implícita, além dos 3 perfis usuários (rep / supervisor / admin).
+
+---
+
+## 2026-05-26 — Step 2 (Vision)
+
+### Vision statement aprovada
+> SAR é a plataforma de força de vendas que dá clareza para o representante, ferramenta de decisão para o supervisor, e IA estratégica para o dono — entregue como SaaS web, vendável e escalável, posicionando a JCS Sistemas como fornecedora de software moderno para o mercado B2B brasileiro.
+
+### Decisões-chave reveladas
+1. **3 experiências distintas, não 3 telas iguais.** Rep, Supervisor e Dono usam o SAR de modos qualitativamente diferentes (operacional ↔ tático ↔ estratégico).
+2. **WhatsApp é canal nativo, não integração anexa.** Implica API WhatsApp Business no escopo desde o início.
+3. **IA estratégica para o dono é diferencial declarado.** Implica decidir cedo o escopo de IA (insights generativos? alertas? recomendações?).
+4. **Inteligência de carteira ativa** (inativos, ciclo, oportunidades) — não é "relatório", é parte do produto-base.
+5. **SaaS multi-tenant é o pulo qualitativo**, não "ter mais features que o legado". Distribuição/instalação é o gargalo que o web resolve.
+
+### Implicações para próximos steps
+- Step 3 (Positioning): diferenciais já mapeados (6 itens), prontos para virar positioning statement.
+- Step 7 (Target Users): rep / supervisor / dono (não "admin" do brand.md — o dono é uma persona estratégica distinta).
+- Step 9 (Competitive Landscape): SaaS força de vendas regional/nacional — Mercos, Promosoft, Workforce, etc.
+- Step 10 (Constraints): IA + WhatsApp + multi-tenant impõem escolhas técnicas e regulatórias (LGPD reforçada).
+
+### Lacuna documentada
+- "Cena concreta do dia típico" (pergunta #1) ficou em aberto, será retomada na Phase 2 (Trigger Map).
+
+---
+
+## 2026-05-26 — Step 3 (Positioning)
+
+### Target customer
+- 4 perfis válidos: Distribuidoras, Indústrias, RCAs, PMEs com vendas externas
+- **Sweet spot:** 5-50 representantes na rua (mid-SMB)
+
+### Categoria
+- Plataforma SaaS de Força de Vendas (SFA)
+
+### Dor central
+- **Donos e supervisores decidem no escuro** — não têm visibilidade em tempo real do que acontece na rua
+
+### Concorrência
+- Apps verticais: Mercos, Promosoft, MaxFV, Workforce, Mobits
+- ERPs com módulo: TOTVS, Sankhya, Senior
+- Stack improvisado: Excel + WhatsApp + ERP
+- Apps caseiros sob medida
+
+### Implicações estratégicas chave
+1. **Coexistência com ERPs como diferencial** — multi-tenancy BD-por-workspace facilita integração heterogênea por cliente
+2. **WhatsApp nativo e IA estão no MVP**, não em roadmap futuro
+3. **3 experiências distintas** é pilar de marca, não detalhe
+4. **"Visibilidade em tempo real" é promessa-mãe** — implica websockets/SSE no produto desde o lançamento
+5. **Pricing range** definido pelo sweet spot 5-50 reps (mid-SMB, não enterprise nem micro)
+
+### 4 estratégias de aquisição por origem
+- App vertical concorrente → ganho de IA + 3 experiências + WhatsApp
+- Módulo de ERP → coexistência, não migração
+- Stack improvisado → primeira ferramenta de verdade
+- App caseiro → fim do pesadelo de manutenção
+
+---
+
+## 2026-05-26 — Step 5 (Business Model)
+
+### Modelo escolhido
+- **B2B SaaS multi-tenant, per-seat, sales-led, com trial real**
+- Cobrança: **per-seat** (por rep ativo/mês)
+- Sales motion: **sales-led** (demo + proposta + acompanhamento comercial)
+- Trial: **14-30 dias** com dados reais (workspace sandbox)
+- Contrato: **híbrido** — mensal sem fidelização OU anual prepago com desconto (10-20%)
+
+### Ticket médio estimado (R$ 150/rep referência)
+- Pequeno (5-10 reps): R$ 750-1.500/mês → ARR R$ 9k-18k
+- Médio baixo (11-25): R$ 1.650-3.750/mês → ARR R$ 20k-45k
+- Médio alto (26-50): R$ 3.900-7.500/mês → ARR R$ 47k-90k
+
+### Implicações técnicas chave
+1. Precisa **active rep counter** no produto (define cobrança)
+2. Trial exige **provisioning automatizado** de workspace + seed opcional
+3. Billing suporta **cobrança mensal recorrente + cobrança anual única** (provider a decidir em Step 29 — Iugu/Pagar.me/Gerencianet/Stripe)
+4. Workspace sandbox de trial reusa arquitetura BD-por-workspace (ADR 0006) — não é caso especial
+
+### Implicações de marketing
+- **CTA principal do site:** "Agende demo", não "Sign up free"
+- **Trial é gated:** form → SDR qualifica → demo → liberação
+- **Pricing page** explícita no site
+
+### Lacunas conscientemente adiadas
+- Preço exato/rep (validar com mercado)
+- Setup fee / implantação paga (não decidido)
+- Add-ons premium (WhatsApp tier? IA tier?) — futuro
+
+---
+
+## 2026-05-26 — Step 6 (Business Customers)
+
+### Buyer persona — "O Dono Empresário B2B"
+- 35-60 anos, sócio-fundador ou herdeiro, gerencia "no peito"
+- Critério: **fé que vai funcionar**, não TCO planilhado
+- Convence: demo concreta + boca-a-boca + cases
+- Assusta: aprendizagem do time, complexidade, custo
+
+### Estrutura de decisão
+- **Decisor:** dono OU diretor comercial (varia por porte)
+- **Influenciadores que matam o deal:** supervisor de vendas + reps champions
+- **Ausentes:** financeiro, TI, jurídico (venda operacional-emocional, não técnico-financeira)
+
+### Canais de aquisição (4 ativos)
+- Indicação boca-a-boca + Google/SEO + feiras setoriais + parceiros (contadores, revendedores ERP)
+- Implica: programa de referral, blog SEO, calendário de feiras, página de parceiros
+
+### Ciclo por porte
+- Pequeno (5-10 reps): 2-4 semanas
+- Médio baixo (11-25): 1-2 meses
+- Médio alto (26-50): 2-4 meses (POC possível)
+
+### Implicações chave
+1. **Demo-friendliness obrigatória** — produto precisa brilhar em 5 min, sem hand-holding
+2. **Site precisa 3 páginas por papel** (`/para-donos`, `/para-supervisores`, `/para-representantes`)
+3. **Comparativos diretos** com Mercos/TOTVS no site (combate frontal)
+4. **WhatsApp visível na primeira tela** do produto (diferencial declarado)
+5. **JCS precisa de CRM próprio** para venda — possível dogfood (vender SAR com SAR)
+6. **Conteúdo SEO:** controle de rep externo, força de vendas para distribuidora, WhatsApp + B2B
+
+---
+
+## 2026-05-26 — Step 7 (Target Users)
+
+### 4 user personas confirmados
+1. **Rafael Representante (PRIMÁRIA — MVP focus)** — 30-50a, mobile-first, 70-90% do volume de uso
+2. **Sandra Supervisora** — 35-55a, desktop+mobile, "apertar parafusos diários"
+3. **Daniel Dono** — 40-65a, desktop/iPad, IA estratégica, overlap com buyer persona
+4. **Alice Admin (nova)** — 25-45a, desktop-only, pautas/promoções/tributação
+
+### Decisão crítica de design
+- **Mobile-first para Rafael, desktop-first para os outros 3.** SAR não é "responsivo único" — são paradigmas de UI distintos no mesmo produto.
+- App do Rafael deve funcionar com sinal 3G/4G ruim (offline-resiliente parcial)
+- Touch-friendly + dark mode desejável
+
+### Insights de produto (entram em Phase 3/4)
+- **Editor de campanhas/promoções no-code** vira diferencial declarado (foi mencionado como responsabilidade Alice)
+- **Assistente de tributação ICMS-ST** por NCM+UF — diferencial vs ERP-modules
+- **Auditoria/trilha de mudanças** em pautas, produtos, cadastros (Alice precisa, regulatório também)
+- **WhatsApp integrado** + **comissão em tempo real** + **funil kanban** são fundamentos do Rafael
+- **IA explicável** para Daniel (não black box; alertas com contexto)
+
+### Insight de venda (refina Step 6)
+- Demo precisa: **brilhar para Sandra** (influenciadora), **vender para Daniel** (decisor), **encantar Rafael** (champion)
+- Alice é benefício mostrado, não argumento de venda
+
+---
+
+## 2026-05-26 — Step 7a (Product Concept)
+
+### Concept estrutural canônico
+> **SAR é uma plataforma de 4 cockpits especializados (Rep / Supervisor / Dono / Admin) compartilhando um dado único em tempo real, atravessado por WhatsApp nativo e IA contextual.**
+
+### Metáfora canônica
+- "Equipe de Fórmula 1" — cada papel tem seu próprio dashboard, mas todos veem o mesmo carro em tempo real
+
+### 4 princípios de implementação
+1. **Cada cockpit tem UX/device-target próprios** (Rafael mobile-first, outros desktop-first)
+2. **Camada de dados única em tempo real** (Socket.IO + SSE, <2s entre cockpits)
+3. **WhatsApp e IA são fios horizontais**, não módulos isolados
+4. **Multi-tenancy BD-por-workspace** garante isolamento físico + facilita integração ERP heterogênea
+
+### Tensões deliberadas aceitas
+- Construir 4 UX paradigmas em vez de 1 responsivo (custo alto, diferencial alto)
+- Tempo real obrigatório (custo de infra, ganho de promessa)
+- WhatsApp/IA como pilares horizontais desde MVP (não roadmap)
+
+### Implicações arquiteturais
+- **Phase 6 (Design System) não é opcional** — tokens compartilhados + variantes por cockpit
+- Cada cockpit possível epic na PRD; atravessadores (WhatsApp/IA/real-time/multi-tenant) viram epics horizontais
+- Broadcast WebSocket sempre escopado a workspace (não global) — alinha com BD-por-workspace
+
+---
+
+## 2026-05-26 — Step 8 (Success Criteria)
+
+### North Star MVP
+- **1º cliente real paga e renova sem cancelar nos primeiros 3 meses após go-live**
+- Critério: retenção provada > tração massiva
+
+### Y1 comercial (12 meses pós-GA)
+- **10-20 clientes pagantes** (conservador) | NPS donos > 50 | ARR R$ 200k-600k
+
+### Timeline-chave
+- **MVP em produção com 1º cliente real: 3-4 meses** (a partir de 2026-05-26)
+- MVP validado: mês 6-7 (1º cliente renova)
+- 10 clientes pagantes: mês 12
+- Premissa: Julian + 1-2 devs adicionais
+
+### Targets críticos por camada
+- **Negócio JCS:** logo churn < 3%/mês · NPS > 50 · CAC payback < 12m · NRR > 110%
+- **Cliente:** +15-30% pedidos/rep/mês · 10-20% inativos recuperados · aprovação desconto < 30 min · DAU/MAU reps > 80%
+- **Comportamento usuário:** Rafael > 95% pedidos no SAR + DAU/MAU > 70% · Sandra > 90% aprovações pelo SAR · Daniel > 2x/sem IA · Alice > 80% campanhas no-code
+- **Qualidade:** p95 tela < 800ms · p95 pedido < 60s · uptime 99.5% · pedidos perdidos = 0 · workspace provisionado < 5 min
+
+### Implicação técnica chave
+- **Instrumentação de produto no MVP, não em Phase 2 de roadmap**:
+  - OTel + Pino + Grafana (já em STACK.md §09)
+  - Analytics de produto (PostHog/Amplitude/self-host)
+  - Módulo de feedback in-app para NPS
+
+### Riscos definidos
+- Rafael não adota → DAU/MAU < 50% em 60d
+- Sandra não confia → aprovações por WhatsApp > 30%
+- Daniel ignora IA → < 1x/semana
+- North star falha → cliente cancela em 3m
+- P0 imediato: qualquer pedido perdido por bug
+
+---
+
+## 2026-05-26 — Step 9 (Competitive Landscape)
+
+### 5 grupos de alternativa analisados
+1. Apps verticais (Mercos, Promosoft, MaxFV, Workforce, Mobits) — SAR ataca via 4 cockpits + IA + WhatsApp nativo
+2. ERPs com módulo (TOTVS, Sankhya, Senior, Bling, Tiny, Omie) — SAR ataca via **coexistência** (não migração)
+3. Stack improvisado (Excel + WhatsApp + ERP sem módulo) — SAR ataca via "primeira ferramenta de verdade"
+4. Apps caseiros — SAR ataca via roadmap contínuo + fim do pesadelo de manutenção
+5. **Do nothing** (50%+ dos prospects) — SAR ataca via choque "5-10% carteira/ano perdida silenciosamente"
+
+### 5 unfair advantages estruturais (alto moat, >2 anos para concorrente neutralizar)
+1. **Concept estrutural "4 cockpits"** — reescrita completa para copiar
+2. **Multi-tenancy BD-por-workspace (ADR 0006)** — arquitetura desde dia 0
+3. **Stack moderna JCS** — Node 24 + Nest 11 + Prisma 7 + React 19.2 (~3x velocidade vs PHP/Java/Delphi)
+4. **IA desenhada desde concept** — não bolt-on
+5. **Velocidade de iteração JCS** — equipe pequena + decisão fast-individual → iteração mensal vs anual
+
+### Vantagens não-sustentáveis (copiáveis em 6-24 meses)
+- WhatsApp nativo, editor no-code, UX moderna, real-time
+- **Defesa estratégica: a combinação estrutural** dos 5 itens resistentes, não feature individual
+
+### Posição estratégica alvo
+- **Vendas-first + baixo atrito de implantação** — quadrante semi-vazio do mapa competitivo
+
+### Implicações estratégicas
+1. **Demo ataca do-nothing primeiro**, não Mercos — urgência vende mais que comparativo
+2. **Coexistência com ERP é mensagem-chave** para Grupo 2
+3. **IA precisa ser explicável desde MVP** — black box não convence donos
+4. **WhatsApp via arquitetura plug-in** (não acoplado) — proteção contra mudanças Meta
+5. **Janela de 2-3 anos para entrincheirar** — velocidade do MVP (3-4 meses) é decisão estratégica
+6. **Foco em referenciabilidade** > tração massiva — primeiros 10 clientes viram cases públicos
+
+---
+
+## 2026-05-26 — Step 10 (Constraints)
+
+### ⚠️ Tensão estratégica explícita (flagueada)
+**Combo decidido:** concept ambicioso + MVP 3-4 meses + **solo founder mode** (Julian full-time até 1º cliente).
+**A matemática não fecha sem trade-off.**
+
+### Resolução proposta (refinar em Phase 3 PRD)
+**MVP mínimo defensível:**
+- ✅ Rep cockpit (Rafael) — obrigatório
+- ✅ Supervisor cockpit (Sandra) — obrigatório, simplificado
+- ✅ Multi-tenant BD-por-workspace — fundacional
+- ✅ WhatsApp — versão básica (notificações; conversa bidirecional pós-MVP)
+- 🟡 Dono cockpit (Daniel) — dashboard simples; **IA estratégica entra pós-MVP**
+- 🟡 Admin cockpit (Alice) — cadastros essenciais; **editor no-code de campanhas entra pós-MVP**
+
+**Premissa:** 1º cliente é referência interna/parceiro próximo, aceita limitações em troca de condições especiais. Quando renova (north star), Julian contrata 1-2 devs e completa.
+
+### Constraints fixos
+- **Timeline:** MVP 3-4 meses, janela mercado 2-3 anos
+- **Budget:** small-business, CAC payback < 12m
+- **Time:** **solo founder mode até 1º cliente** (Julian acumula tudo)
+- **Stack:** STACK.md v2.2 é fonte da verdade (RFC para mudanças)
+- **Brand:** brand.md (paleta JCS + Plus Jakarta + AntD 6.4 + topbar/sidebar + tom Apple)
+- **Regulatório:** LGPD by design (isolamento físico multi-tenant, redact, criptografia PII)
+
+### Constraints flexíveis (decisão pós-Brief)
+- Provider de pagamento (Step 29)
+- Provider de IA (Step 29)
+- WhatsApp Business API provider (Step 29)
+- Analytics de produto (Step 8 já flagueado)
+- Dark mode (desejável especialmente Rafael)
+
+### LGPD adicional para WhatsApp + IA
+- DPA com Meta e OpenAI/Anthropic obrigatório
+- Hashar dados antes de enviar para IA (sem nome/CPF/telefone real)
+- Opt-in explícito do contato final no WhatsApp
+
+---
+
+## 2026-05-26 — Step 10a (Platform Strategy)
+
+### Plataforma primária
+- **Web SaaS** (React 19.2 SPA + Vite 8 + Nginx + Cloudflare) — STACK.md
+- Sem app store; deploy = rolling docker-compose em VMs Proxmox
+
+### Device strategy por cockpit
+- **Rafael (Rep):** **PWA mobile-first** com foco primário em **iOS** (gap onde JCS não tem app native). Android secundário (existe legado, mas reps podem optar pelo PWA).
+- **Sandra (Supervisora):** Desktop + PWA mobile-light para consultas/aprovações rápidas.
+- **Daniel (Dono):** Desktop + **iPad first-class** (otimização dedicada).
+- **Alice (Admin):** Desktop-only.
+
+### Coexistência com app Android legado
+- **MVP:** SAR PWA + backend SAR construídos do zero. Android legado intocado.
+- **Pós-MVP (Y1+):** Adaptar app Android legado para consumir backend SAR (unificar fonte da verdade).
+- **Futuro (Y1-Y2):** Avaliar native iOS + native Android sobre backend SAR (Capacitor/React Native).
+
+### Offline strategy (Rafael)
+- **Nível:** Read + Write com sync
+- Lançamento de pedido offline → IndexedDB queue → Service Worker sync quando volta online
+- Conflict resolution: Last-write-wins para rascunho; pedido submetido imutável
+- Idempotency-Key por pedido (UUID local) protege contra duplicação no sync
+
+### Native features no MVP
+- ✅ Geolocation (check-in Rafael)
+- ✅ Web Push (Sandra aprovação, Rafael pedido aprovado) — exige PWA + VAPID
+- ✅ Share API (Rafael compartilha pedido via WhatsApp do celular dele)
+- ✅ Notification API desktop (Sandra)
+- 🟡 Pós-MVP: Camera, File System Access, Voice (este descartado por segurança rodoviária)
+
+### Acessibilidade
+- WCAG AA mínimo desde MVP
+
+### Implicação de execução
+- PWA exige investimento explícito ~1-2 semanas no MVP
+- iPad first-class implica testes regulares em iPad Safari durante Phase 4
+- Web Push backend reusa BullMQ jobs (alinha com STACK.md §11)
+
+---
+
+## 2026-05-26 — Step 11 (Tone of Voice)
+
+### 5 atributos canônicos
+1. **Direto** — sem floreio
+2. **Profissional sem ser frio** — sério, mas humano (não burocratês)
+3. **Confiante** — afirmativo, não tentativo
+4. **Específico** — números/dados sempre que possível
+5. **Empático nos momentos difíceis** — problema + caminho para resolver
+
+### Variações por cockpit (mesmos atributos, registros distintos)
+- Rafael: informal, frases curtas
+- Sandra: direto + decisivo
+- Daniel: executivo, foco em insight
+- Alice: técnico-preciso
+
+### Don'ts
+- Emoji em produção (brand clean Apple)
+- Caps lock para erros
+- Burocratês ("operação", "registro", "movimentação")
+- "Por favor"/"obrigado" excessivo
+- Anglicismos onde tem pt-BR (Submit→Enviar)
+- Frases dúbias ("Talvez", "Possivelmente")
+
+### Vocabulário canônico (padrão único)
+- Cliente · Representante/Rep · Orçamento · Pedido · Faturado · Visita · Carteira · Inativo · Painel · Aprovação
+
+### Implicação
+- Vocabulário vira tokens i18n centralizados (não strings espalhadas)
+- Phase 6 Design System inclui guia de microcopy
+- Prompt de IA generativa precisa incluir esses 5 atributos + vocabulário canônico
+
+---
+
+## 2026-05-26 — Step 12 (Create Product Brief) — BLOCK A COMPLETO
+
+### Product Brief synthesis
+- **Narrativa estratégica apresentada** como história coerente (não checklist)
+- **User confirmation:** confirmado sem ajustes
+- **Brief gerado:** `design-artifacts/A-Product-Brief/01-product-brief.md`
+
+### Conteúdo do brief canônico
+- Resumo estratégico
+- Vision + 3 experiências + 7 diferenciais
+- Positioning (framework Geoffrey Moore) + mapa estratégico
+- 4 personas (Rafael primária + Sandra + Daniel + Alice)
+- Buyer × User mapping
+- Business model (per-seat sales-led trial + contrato híbrido)
+- Buyer persona "Dono Empresário B2B"
+- Canais de aquisição (4) + ciclo por porte
+- Success criteria (North Star MVP + 4 camadas de métricas)
+- Competitive landscape (5 grupos + 5 unfair advantages + janela de mercado)
+- Constraints (tensão solo + 3-4 meses + concept ambicioso flagueada)
+- Platform strategy (PWA iOS + offline + native features)
+- Tone of voice (5 atributos + vocabulário canônico + don'ts)
+- Riscos + mitigações
+- Próximos passos (Blocks B, C, D, E)
+
+### Status do Block A
+- **CONCLUÍDO** — Steps 1, 1a, 2, 3, 5, 6, 7, 7a, 8, 9, 10, 10a, 11, 12 (14 steps)
+- Tempo decorrido: ~2-3 horas em uma sessão
+- Próximo: Block B (Content & Language) — Steps 13-18
+
+---
+
+## 2026-05-26 — Step 13 (Content Init) — BLOCK B INICIADO
+
+### Materiais herdados
+- `brand.md` — identidade visual + tom visual "Apple-inspired"
+- `01-product-brief.md` — Block A canônico
+- `dialog/tone-of-voice.md` — 5 atributos + vocabulário canônico (Step 11)
+
+### Q: Tem brand guidelines existentes?
+**A: Sim** — brand.md + tone-of-voice.md cobrem visual e microcopy. Block B vai expandir para:
+- Personalidade (Step 14)
+- Tom refinado (Step 15)
+- Idiomas (Step 16)
+- SEO (Step 17)
+- Content structure (Step 17a)
+- Documento final (Step 18)
+
+### Output inicializado
+- `design-artifacts/A-Product-Brief/02-content-language.md`
+
+---
+
+## 2026-05-26 — Step 14 (Personality)
+
+### Metáfora canônica
+- **"Consultor sênior brasileiro de vendas B2B"** — 40-50a, ex-rep que virou consultor, conhece a rua e o ERP, sem firula
+
+### 5 atributos de personalidade
+1. **Confiável** — não erra, não some
+2. **Especialista prático** — conhece o setor, fala como amigo, não acadêmico
+3. **Decidido** — diz o que é, aponta caminho
+4. **Discreto** — não atrapalha, Apple-inspired
+5. **Aliado** — do lado do usuário, não vigiando
+
+### Conexão por persona
+- Rafael: colega mais experiente
+- Sandra: assessor de confiança
+- Daniel: consultor estratégico
+- Alice: técnico-parceiro
+
+### O que NÃO é
+- Vendedor barulhento, burocrata, coach motivacional, espião, filósofo, jovem descolado
+
+---
+
+## 2026-05-27 — Step 15 (Tone refinement)
+
+### Posicionamento nos 4 espectros (1-5)
+- **Formality: 3** (levemente formal)
+- **Mood: 2** (sério-com-leveza)
+- **Complexity: 3** (vocabulário do setor + acessível)
+- **Energy: 2** (reservado, Apple-inspired calm)
+
+### Centro de gravidade
+"Levemente formal, sério-com-leveza, tecnicamente acessível, energia contida."
+
+### We Say / Don't Say expandidos
+- 5 categorias com 3 colunas (✅ SAR / ❌ formal demais / ❌ casual demais)
+- Cobre: cumprimentos · sucesso · erro · empty states · IA/sugestão
+
+---
+
+## 2026-05-27 — Step 16 (Languages)
+
+### Estratégia canônica
+- **pt-BR only no MVP, arquitetura i18n-ready**
+- en preparado no código (chaves i18n) mas sem tradução no MVP
+- es (LatAm) fora de escopo (requer adaptação fiscal por país)
+
+### IA generativa
+- **Sempre pt-BR** — prompts em pt-BR + validação de output (rejeitar respostas em en, fallback)
+- Vocabulário canônico naturalmente vira chaves i18n estruturadas
+
+### Localização (BR-only)
+- BRL · DD/MM/AAAA · 24h · fuso `America/Sao_Paulo` por workspace · telefone `+55 (XX) XXXXX-XXXX` · CEP/CNPJ/CPF padrão BR · sistema métrico
+
+### Implicação para STACK
+- Validators Zod para CPF/CNPJ/CEP/telefone BR
+- Date-fns/Day.js com locale pt-BR
+- `Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })`
+- Fuso por workspace no master-login
+
+---
+
+## 2026-05-27 — Step 17 (SEO Strategy)
+
+### Keywords nos 6 intents
+- Service/Solução · Problem · Comparison · Brand · Informational · Long-tail setor
+
+### Domínio
+- **A definir** — recomendação: `sarjcs.com.br` (brandable + JCS-link)
+
+### URL pattern
+- pt-BR: `<dominio>/<slug>` · en futuro: `<dominio>/en/<slug>`
+- Slug: lowercase, hífen, sem especiais, ASCII
+
+### Sitemap
+- `/` · `/funcionalidades/<cockpit|whatsapp|ia|carteira>` · `/para/<setor>` · `/comparativos/<concorrente>` · `/precos` · `/recursos/<blog|calculadora|kit>` · `/cases` · `/parceiros` · `/sobre` · `/contato` · `/app/`
+
+### Structured data
+- `Organization` (todas) · `SoftwareApplication` (home) · `Product`+`Offer` (preços) · `Article`+`Review` (cases) · `Article`+`BreadcrumbList` (blog) · `FAQPage`
+
+### Local SEO
+- Reivindicar Google Business Profile da JCS Sistemas
+- NAP consistente no footer
+
+### Implicação técnica
+- Vite + plugin React Helmet para meta dinâmico
+- JSON-LD para structured data (não microdata)
+- Sitemap.xml gerado por script no build
+- robots.txt + meta noindex em `/app/`
+
+---
+
+## 2026-05-27 — Step 17a (Content Structure)
+
+### Site Marketing (10 princípios)
+- Hero em <5s · vídeo não tour · prova social pesada · 3 jornadas por persona · setor dedicado · CTA único · pricing visible · comparativos acessíveis (não em destaque) · `/recursos/` separado · cases viram peça central com 3+ clientes
+
+### Produto / 4 cockpits (11 princípios)
+- Cada cockpit tem home própria · hierarquia por urgência · navegação por device (bottom nav rep / sidebar 260px outros) · max 3 níveis · WhatsApp+IA no caminho principal · empty states informativos · notificações só pra decisão · tempo real com micro-animação · admin fora do path · auditoria em cada entidade · onboarding discreto
+
+### Exclusões explícitas (8)
+- Tutorial agressivo · gamificação gritante · chat-com-cliente in-app · marketing email · NF/SPED · wallet · CMS blog · mobile-first para Daniel/Alice
+
+### Latitude Phase 4
+- Visão alta no produto, restrições claras de tom/estilo
+
+---
+
+## 2026-05-27 — Step 18 (Create Content Document) — BLOCK B COMPLETO
+
+### Output finalizado
+- `design-artifacts/A-Product-Brief/02-content-language.md` — documento canônico de comunicação
+
+### Conteúdo adicional ao doc
+- **Content Type Guidelines:** UI microcopy · Marketing · Informational · Notificações transacionais · WhatsApp programático · IA generativa
+- **Content Ownership** (MVP solo + Y1+ contratações)
+- **Writing Checklist** (13 itens; entra em todo PR de microcopy/artigo/email)
+- **Resumo executivo** (snapshot completo)
+
+### Status do Block B
+- **CONCLUÍDO** — Steps 13, 14, 15, 16, 17, 17a, 18 (7 steps)
+- Próximo: Block C (Visual Direction) — Steps 19-26 (fast-track via brand.md)
+
+---
+
+## 2026-05-27 — Step 19 (Inspiration Workshop) — BLOCK C INICIADO
+
+### 🌟 Insight estratégico chave revelado
+> "Não acho nada que tem no mercado de identidade como inspirador — mais uma das coisas que nos trouxe para esse projeto." (Julian)
+- Mercado B2B força de vendas BR é visualmente medíocre
+- **Estética moderna é parte do diferencial fundacional do SAR**, não detalhe
+- **Adicionar como 6º unfair advantage estrutural** no Brief (refinamento ao Step 9)
+
+### 4 referências externas confirmadas
+1. **Apple iCloud** — Apple-inspired clean canon
+2. **Linear** — SaaS B2B moderno, dense + clean, atalhos, dark mode
+3. **Stripe Dashboard** — densidade + acessibilidade, dados com contexto
+4. **Notion** — flexibilidade, empty states, hierarquia tipográfica
+
+### 7 padrões destilados (entram em Design Style)
+- Sidebar fixa + área limpa · Tipografia hierarquia · Único accent · Densidade respirável · Animações sutis · Dark mode · Empty states informativos
+
+### Referência por cockpit (alimenta Phase 4)
+- Rafael: Linear mobile + Apple Notes
+- Sandra: Linear + Stripe Dashboard
+- Daniel: Stripe Dashboard + Apple iCloud
+- Alice: Notion + Linear
+
+### Output
+- `dialog/inspiration-analysis.md`
+
+---
+
+## 2026-05-27 — Step 21 (Existing Brand)
+
+### Inventário
+- Logo SAR: PNG existe (`frontend/img/`) — refresh para SVG + variantes
+- Logo JCS: 4 PNGs colocados em `design-artifacts/_references/jcs-logo/` — refresh para SVG
+- Paleta JCS: canônica (brand.md), Keep as-is
+- Plus Jakarta Sans: canônica, Keep as-is + self-host produção
+- FA 6.4 + Chart.js + tokens radius/sombra: canônicos, Keep as-is
+- Layout topbar+sidebar: Keep + adaptar Rafael (mobile bottom nav)
+
+### Análise visual da logo JCS
+- "JCS." em bold JCS Blue + seta/swoosh no "C" (movimento, precisão)
+- "sistemas" em peso light, lowercase, mesmo azul
+- Layout horizontal clean — Apple-inspired confirmado
+
+### Análise visual da logo SAR
+- Ícone JCS Blue com gráfico de barras crescente em branco (metáfora analytics)
+- "SAR" em bold sans-serif cinza/preto
+- "FORÇA DE VENDAS" em letterspaced caps cinza médio
+- Hierarquia deliberada: SAR como produto distinto, JCS como marca-mãe
+
+### Afiliações declaradas
+- ✅ "Powered by JCS Sistemas" no footer/login/sobre
+- ✅ Selos LGPD compliant + futuras certificações
+- Nenhuma franquia, nenhuma associação setorial obrigatória
+
+### Brand constraints (não negociáveis)
+- JCS Blue `#004a99` único accent
+- Plus Jakarta única família
+- SAR coexiste visualmente com JCS sempre (parental link)
+- Tom Apple-inspired clean — sem decoração desnecessária
+
+---
+
+## 2026-05-27 — Step 22 (Visual References)
+
+### 9 categorias destiladas das 4 referências positivas
+- Layout · Cor · Tipografia · Densidade · Imagery · Efeitos · Estados · Dark mode · Mobile
+
+### 7 estilos a evitar (referências negativas)
+- Burocrata corporativo legado · apps verticais BR (Mercos/Promosoft) · SaaS "fofo" · Material Design pesado · BI 2010-2015 · sites BR "exuberantes" · tour interativo agressivo
+
+### 5 mood keywords canônicos
+- **Clean · Confident · Specific · Serene · Modern**
+
+### Frase âncora
+"clean, confident, specific, serene, modern — como um consultor sênior que apareceu na sua empresa e abriu o notebook"
+
+---
+
+## 2026-05-27 — Step 23 (Design Style)
+
+### 4 decisões canônicas
+1. **UI Visual Style:** Modern Flat + Minimal (Apple/Linear/Stripe/Notion family) — sem skeumorfismo, sem 3D, radius 12/20px, sombra sutil
+2. **Design Aesthetic:** Minimalism contemporâneo / Digital-native modern — post-Apple, sem ilustrações ornamentais
+3. **Color Direction:** Monochromatic + functional accents — JCS Blue protagonista, cool, light + dark mode, distribuição 60/30/10
+4. **Typography Direction:** Plus Jakarta Sans Geometric Humanist — tabular numerals em dashboards, hierarquia preliminar h1 32-40 / body 14-16 / caption 12-13
+
+---
+
+## 2026-05-27 — Step 24 (Layout & Effects)
+
+### Site Marketing
+- **Hero: Split** (texto + vídeo play-on-click)
+- Layouts variados por tipo de página (single column / card grid / side-by-side / 3-column tier)
+- Top nav sticky · hamburger mobile-only · mega menu em Funcionalidades/Para · CTA demo sempre visível
+
+### Produto — pattern por cockpit
+- **Rafael:** single column + cards verticais + bottom nav
+- **Sandra:** sidebar + grid de cards + tabelas (Linear-like dense+decisão)
+- **Daniel:** sidebar + **bento box** dashboard (Stripe-like KPIs)
+- **Alice:** sidebar + **table-first** + forms drawer lateral
+
+### Visual Effects (nível canônico)
+- Shadows: sutil (brand.md)
+- Animations: sutis funcionais 150-250ms ease-out
+- Parallax: **none** (gimmick em B2B)
+- Hover: sutil (background/opacity, sem transform 3D)
+- Loading: skeleton (não spinner)
+- Real-time: micro-animação 200ms, sem toast intrusivo
+- Focus rings WCAG AA + reduced motion respeitado
+
+### Performance targets
+- Lighthouse mobile > 90 · TTI Rafael 3G < 3s · FCP < 1.5s
+- Bundle inicial < 200KB gzipped por entry
+- Code-split por cockpit · WebP/AVIF + lazy + sharp · Service Worker para Rafael offline · vídeo hero sem autoplay
+
+---
+
+## 2026-05-27 — Step 25 (Imagery)
+
+### Estratégia canônica: **Apple-style produto-primário**
+- MVP usa **screenshots do produto + ilustrações minimíssimas**
+- **Sem stock humano** — sai do mainstream B2B saturado
+- Fotos reais entram pós-MVP quando houver cases/permissões
+
+### Photography style (quando aplicar)
+- Authentic/Documentary — pós-MVP em cases
+- **Product-focused — MVP** (screenshots reais)
+- Lifestyle moderado pós-MVP (sem "team smiling")
+- Polished/staged **NUNCA**
+
+### Anti-padrões absolutos
+- Executive shaking hands · diverse team smiling · UI hologram · gráficos 3D flutuando · senhor preocupado com planilha · cidade + barra sobreposta
+
+### Icons
+- FA 6.4 subset · **Regular/Outline padrão**, Solid só em estados · sistema 16/20/24px · cor inherit + JCS Blue em ações primárias · ícone SAR como signature visual
+
+### Illustrations
+- **Quase nenhuma no MVP** — Apple-clean prefere ausência
+- Permitido: empty states (line art mono JCS Blue) e erro 404/500
+- EVITAR: isométrico hipster · gradiente saturado · diversity blob people
+
+### Image guidelines
+- 16:9 / 4:3 / 1:1 ratios · alt obrigatório WCAG AA · WebP/AVIF + JPG fallback q80-85 · lazy load · srcset 1x/2x/3x · Cloudflare CDN · sharp pipeline
+
+---
+
+## 2026-05-27 — Step 26 (Create Visual Document) — BLOCK C COMPLETO
+
+### Visual DNA Summary
+```
+Style:       Modern Flat + Minimal (Apple/Linear/Stripe/Notion family)
+Aesthetic:   Minimalism contemporâneo / Digital-native modern
+Colors:      Monochromatic JCS Blue + functional accents · cool · light + dark mode · 60/30/10
+Typography:  Plus Jakarta Sans Geometric Humanist · tabular numerals
+Mood:        Clean · Confident · Specific · Serene · Modern
+Layout:      Split hero (site) · cards/grid/bento/table por cockpit
+Effects:     Sutis funcionais 150-250ms · sombra única brand.md · sem parallax
+Imagery:     Screenshots-only Apple-style · sem stock humano · FA outline
+Key element: 4 cockpits sobre dado único em tempo real (ícone do gráfico crescente da logo SAR como símbolo)
+```
+
+### Status do Block C
+- **CONCLUÍDO** — Steps 19, 20, 21, 22, 23, 24, 25, 26 (8 steps)
+- Documento canônico: `design-artifacts/A-Product-Brief/03-visual-direction.md`
+- Próximo: Block D (Platform Requirements) — fast-track via STACK.md (Steps 27-32)
+
+---
+
+## 2026-05-27 — Block D (Platform Requirements) — CONCLUÍDO ✅
+
+### Steps 27-32 batched
+- Step 27 (Init) · Step 28 (Tech Stack — espelho STACK.md v2.2) · Step 29 (Integrations) · Step 30 (Contact Strategy) · Step 31 (Multilingual & SEO) · Step 32 (Final synthesis)
+- Documento canônico: `design-artifacts/A-Product-Brief/04-platform-requirements.md`
+
+### Decisões fechadas no Step 29
+- **Pagamento:** Iugu (boleto/PIX/cartão + assinaturas recorrentes BR)
+- **WhatsApp:** Oficial Meta (WhatsApp Cloud API)
+- **Analytics produto:** PostHog self-host em Proxmox
+- **Email, Storage, Secrets, CDN, Obs:** já cobertos por STACK.md (Resend, MinIO, Vault, Cloudflare, Grafana+Sentry)
+
+### Decisão ABERTA — IA generativa
+- Julian quer estudar todas as opções (Anthropic / OpenAI / Local Ollama / Multi-provider)
+- **Resolução estratégica:** abstração multi-provider via Vercel AI SDK ou LiteLLM desde dia 1 — código fica provider-agnostic
+- **Default temporário:** Anthropic Claude (Sonnet/Opus) por explicabilidade e força em pt-BR, escondido atrás de interface JCS
+- Decisão definitiva: quando 1º cliente fechar e Julian tiver tempo para benchmark
+
+### Contact Strategy
+- **Form de demo** como CTA único (sem chat ao vivo no MVP)
+- 8 campos obrigatórios + 2 opcionais (qualifica origem + porte + ERP)
+- Anti-spam: hCaptcha/Turnstile (não Google reCAPTCHA — LGPD)
+- Rate limit 5/h email + 10/h IP
+- SDR JCS (Julian no início) responde em até 4h úteis
+
+### Multilingual & SEO técnico
+- pt-BR only MVP, i18n-ready
+- Domínio recomendado: `sarjcs.com.br`
+- JSON-LD structured data plan completo
+- noindex em `/app/` (produto privado)
+- Lighthouse > 90 mobile como CI gate
+
+### Maintenance
+- Solo founder mode até 1º cliente; depois +1-2 devs JCS
+- Documentação extensiva (CODING-RULES.md) como mitigação de bus factor