DeskcommCRM/docs/index.md

type, project, status, last_updated, generated_by, confidence, audited_against

type	project	status	last_updated	generated_by	confidence	audited_against
index	DeskcommCRM	draft	2026-07-29	auditoria documental (Claude Code)	alta (inventário de arquivos é CONFIRMADO; agrupamento temático é INFERIDO)	origin/main @ 789dfa6 (v1.0.0, 2026-07-27)

Índice da documentação — DeskcommCRM

Mapa dos 154 arquivos .md de docs/, espalhados por 20 subpastas — medido em 2026-08-14, com as réguas ao lado: git ls-files 'docs/**/*.md' | wc -l e git ls-files 'docs/**/*.md' | sed 's|^docs/||;s|/.*||' | sort -u | wc -l. Os dois números estavam errados (149 e 24) e a segunda régua nem existia — é a mesma classe que audits/2026-08-14-afirmacoes-de-estado.md cataloga. Existe porque a documentação cresceu sem ponto de entrada: sem este índice, humano e agente não acham o que já foi decidido e reescrevem por cima.

Regra de precedência quando dois docs discordam: CLAUDE.md (doutrina) > docs/specs/ (contrato técnico) > docs/prd/ (intenção) > HANDOFF-*.md (estado de sessão) > README. Se achou divergência, corrija a fonte de menor precedência e registre.

---

1. Comece por aqui

Doc	Para quê
README.md	O que é, quickstart de 5 min, stack, roadmap. Também em EN / ES
VISION.md	Posicionamento, por que self-host, para quem
ARCHITECTURE.md	Arquitetura em 1 página
AGENTS.md	Contrato para agentes de código (qualquer ferramenta)
CLAUDE.md	Doutrina não-negociável. Convenções, anti-patterns, Definition of Done
CONTRIBUTING.md	Como contribuir
CHANGELOG.md	Mudanças por versão (SemVer). Quem roda VPS lê antes de update.sh — mudança que exige ação manual aparece sob "⚠️ Requer atenção"
docs/current-state.md	O que está pronto, incompleto e quebrado hoje
.agents/skills/	Guias do assistente — instalar, montar cliente por nicho, métricas, prompt, contribuir. Skills lidas por Claude Code, Codex, Cursor, OpenCode e Antigravity (não confundir com as Skills do agente de IA, na tela IA › Skills)

2. Produto e intenção

Doc	Conteúdo
prd/00-prd-master.md	PRD mestre — visão, escopo MVP, KPIs, restrições
prd/01-prd-platform-base.md	Auth, tenancy, RBAC, framework LGPD
prd/02-prd-customer-360.md	Customer 360 + identity resolution determinística
prd/03-prd-whatsapp-waha.md	Canal WhatsApp, anti-banimento, janela 24h
prd/04-prd-pipeline-attendance.md	Kanban, atendimento, tickets, handoff
prd/05-prd-ai-rag-handoff.md	IA conversacional, RAG por tenant, sentiment
prd/06-prd-nuvemshop-lgpd.md	Integração Nuvemshop + webhooks LGPD
business-rules/00-business-rules-catalog.md	Catálogo de regras de negócio — fonte da verdade fora do código
presentation/pitch-deck.md	Pitch

3. Contrato técnico (specs)

Detalham schema SQL e payloads exatos. Consulte antes de modelar qualquer coisa.

Spec	Domínio
specs/01	Plataforma base — tenancy, RLS, RBAC, API, audit
specs/02	Customer 360
specs/03	WAHA — fila outbound, warm-up, spinning, crons
specs/04	Pipeline e atendimento
specs/05	IA, RAG, gatilhos de handoff
specs/06	Nuvemshop + LGPD
specs/07	event_log, workers, claim atômico, backoff/DLQ
specs/08	Deploy e observabilidade
specs/09	Integração front/back
specs/10	Runtime dos AI Agents
specs/11	MCP server interno + catálogo de tools
specs/12	UI dos AI Agents
specs/13	Governança de atendimento (épico G1–G6)
specs/14	Contrato para agentes de IA externos
specs/15	Casos humanos (IA delega a humano)
specs/16	Três papéis do agente — Conversador / Operador / Segurança
specs/17	A conversa vira lead — o elo entre atendimento e CRM
specs/17	Índice de Atrito — medir o propósito (menor atrito p/ os dois lados), não a atividade
specs/18	Chamada de voz WhatsApp (WaCalls) — rascunho, sem sub-PRD dedicado
specs/extensoes-declarativas-v1.md	Extensões declarativas v1 — pacote JSON estrito, catálogo admitido pelo dono da instalação, ativação por organização, guia no hub CRM
integracao/webhooks-de-saida.md	Webhook de saída do lado de quem recebe: cabeçalhos, assinatura com carimbo de tempo, id de entrega, exemplos em Node e Python
specs/RECONCILIATION-LOG.md	Log de reconciliação entre specs

4. Doutrina e arquitetura

Doc	Conteúdo
doctrine/sistema-vivo.md	Doutrina do Sistema Vivo — a LEI. 7 invariantes + regra do tempo + Living System Checklist (item 13 do DoD)
doctrine/sistema-vivo/	Manual do Sistema Vivo — 8 capítulos plugáveis (princípio universal + aplicação de referência). O porquê de cada invariante, e como adotar a doutrina em outro sistema
doctrine/restricao-de-canal.md	Auto-restrição × hetero-restrição de canais externos; contrato de parâmetros derivado
doctrine/separacao-fala-e-operacao.md	Vocabulário interno nunca vaza para o cliente
doctrine/packaging.md	Doutrina de Packaging — a LEI. 8 invariantes + política de canais + checklist de release (item 15 do DoD)
doctrine/prova-em-par.md	Prova em Par — emenda ao item 12 do DoD. Caso de aceite que atravessa agente de IA mede tela + ferramenta com o mesmo texto cru, e só conta quando os dois concordam
doctrine/destrutivo-pede-confirmacao.md	Ação destrutiva pede confirmação que nomeia o alvo — dois botões gêmeos, o mesmo contrato
doctrine/extensoes.md	Doutrina de Extensões — a LEI. Núcleo × extensão pela pergunta "com zero ativações a operação comum continua inteira?" + 13 não-negociáveis, com as políticas do DEC-004 (item 18 do DoD)
specs/19	Console de Agência — operar N organizações clientes; unidade de cobrança decidida (retainer por cliente operado). Lei em doctrine/operacao-de-agentes.md
adr/0001-packaging-e-distribuicao.md	ADR do packaging: namespace, os 3 packages, e o que foi recusado
adr/0002-tabelas-de-modulo-num-banco-so.md	Aceita em 17/09/2026. Tabelas de módulo opcional: um banco só, public, criadas por função provisionadora fixa quando o módulo é instalado
adr/0003-perfil-declarativo-v2-portas-nomeadas-e-vitrine.md	Aceita em 17/09/2026. Perfil declarativo v2 das extensões: portas nomeadas e o metadado de loja no catálogo
adr/0004-cobranca-do-revendedor.md	Aceita em 29/09/2026. Cobrança do revendedor: o terceiro eixo de dinheiro — o dono da instalação cobra as empresas que atende; capacidade do núcleo com chave, desligada por padrão; revisa a condição 2 da ADR-0002 só para este caso
architecture/agent-turn.html	Diagrama do turno do agente (inbound → guardrails → outbound)
specs/pre-go-live-whatsapp.md	Modo de teste do WhatsApp por canal: lista de telefones, abertura ao público e compatibilidade com autorização por origem
specs/19	Console de Agência — operar N organizações clientes; unidade de cobrança decidida (retainer por cliente operado). Lei em doctrine/operacao-de-agentes.md
architecture/pre-go-live-whatsapp.architecture.json	Mapa do pré-go-live, configuração administrativa e gate compartilhado
architecture/extensoes-declarativas.architecture.json	Mapa vivo das extensões declarativas — admissão, download, recibos, ativação por organização e guia no CRM
architecture/teto-de-orcamento.architecture.json	Mapa vivo do teto de gasto com IA — quem alimenta o gate, o que a parada NÃO desfaz sozinha, e o laço de retorno (invariante 7)
release/teto-de-orcamento.md	Nota de release para quem opera uma VPS — o que muda, o que fazer (nada), a troca de rótulo de R$ para US$ e como ligar a proteção
research/architecture-diagrams.md	Diagramas de arquitetura
research/extensoes/	Plataforma de extensões — arquitetura aprovada, bancada concluída e primeira integração provada em tela; acompanha PROG-021
research/reference-synthesis.md	Arquitetura herdada da referência WAHA
research/followup-reference-mining.md	Pesquisa do motor de follow-up
threat-model.md	Superfície de ataque real do self-host
alertas-de-seguranca-triados.md	Razão de cada alerta descartado no painel do GitHub, e o que a varredura por classe achou que o scanner não vê

5. Design system

design-system/README.md é o ponto de entrada (v1.0, 5 escolhas visuais lockadas: paleta Sage, Atkinson Hyperlegible, densidade aerada, Phosphor duotone, IBM Plex Mono). Numerados 00–09: overview, tokens, paleta, tipografia, densidade, iconografia, componentes, motion, voice & tone, anti-patterns. Fluxo de tela em design-system/screen-flow/ (jornadas, clickflows, máquinas de estado, acessibilidade).

6. Operar e instalar

Doc	Conteúdo
SETUP.md	Guia completo de env vars e setup local
deploy-selfhost/README.md	Self-host genérico
deploy-hostgator/README.md	VPS HostGator (install.sh, backup.sh, reset-mfa.sh)
DEPLOY-CHECKLIST.md	Checklist de deploy
ATUALIZANDO.md	update.sh, restore.sh, healthcheck.sh
runbooks/deploy.md	Deploy em produção — os dois -f do compose, verificação pós-deploy
runbooks/remediar-worker-congelado.md	Incidente: o worker congelado — diagnóstico (diagnostico.sh), impacto medido e as duas rotas de remediação. Ainda não ensaiado
runbooks/ativar-packaging.md	Ativação da doutrina de packaging — os 3 passos que não cabem num PR (pacote público, check obrigatório, primeira release)
runbooks/custo-e-cota-do-supabase.md	“Meu Supabase estourou a cota” — como medir a origem do consumo, os dois intervalos da fila e as duas tabelas que só crescem
runbooks/waha-hostgator.md	Runbook do WAHA em produção
runbooks/cloudpanel.md	VPS que já tem CloudPanel/Nginx nas portas 80/443 — o modo proxy externo do kit, o endereço fixo para o Nginx do host e o 403 do webhook global
runbooks/ai-credentials-rotation.md	Rotação de credenciais de IA
../SECURITY.md	Política de reporte de vulnerabilidade

7. Testes e QA

Doc	Conteúdo
testing/user-journey-map.md	Mapa de jornadas vivo — casos, prioridade [P0], achados. Atualizar sempre
testing/HANDOFF-vps-qa.md	Receita do ambiente fresco estilo VPS
harness-audit.md	Auditoria do harness — 20 itens + nível de maturidade
audits/2026-08-14-afirmacoes-de-estado.md	393 afirmações de estado medidas contra a fonte, cada uma com o comando que a responde. É o retrato datado que sustenta as correções de doutrina desta data — releia a data antes de citar qualquer número dele
audits/2026-08-14-alinhamento-stable-v1.3.0.md	O que a tag v1.3.0 — que é o kit que roda na VPS, e não a main — de fato contém
../tests/e2e/README.md	Como rodar os E2E

8. Execução — planos, épicos, handoffs

Documentação de processo. Alta rotatividade; trate como estado, não como contrato.

Convenção: todo HANDOFF*.md vive em handoffs/, indexado pelo handoffs/README.md — encerrado ou não. Até setembro de 2026 valia "épico vivo mantém o HANDOFF na raiz", e a regra não segurou: 12 arquivos se acumularam na raiz e quatro carregavam identificador de produção num repositório público (#638). O gate que impede a volta é tests/unit/handoff-na-raiz-nao-volta.test.ts.

• handoffs/ — todo o arquivo de handoff, com o índice e a convenção em handoffs/README.md. Quantos: git ls-files 'docs/handoffs/HANDOFF*.md' | wc -l (20 em 2026-09-26), mais briefing, contrato e waves/
• stories/ — épicos e stories (epics/MASTER.md = plano por epic/wave)
• superpowers/ — plans/ e specs/ datados por onda, mais handoffs/
• growth/ — material de crescimento · brand/ — marca · white-label.md — instalação com marca própria, também em en e es (traduções seladas pelo hash do original; ver scripts/selar-traducao.ts)
• ../plan/ — backlog do gov-loop (features.json 31/31, phases.md, progress.md)
• ../loop/ — máquina do gov-loop (LOOP.md, CHECKPOINT.md, checkpoints/G1..G6-report.md + .approved)
• ../tasks/todo.md — workflow de construção original (Fase 0 → PRD → specs)

9. Grafo de conhecimento

graphify-out/ — grafo do repositório (7310 nós, 17705 arestas, 538 comunidades na última geração). Consulte via skill graphify antes de varrer código bruto. GRAPH_REPORT.md traz god nodes, hyperedges e comunidades. Gerado — não editar. ⚠️ Foi gerado contra uma árvore anterior à v1.0.0; regenere (/graphify .) antes de confiar em detalhe fino.

---

Lacunas conhecidas deste índice

• docs/vendaval-fusion-plan.md e docs/vendaval-vps-deploy-comandos.md referem-se a uma integração ("Vendaval") cujo status é A CONFIRMAR — o README não a lista mais em "Próximo", apesar de o gatilho (loop/checkpoints/G6.approved) existir.

• docs/diagrams/ não tem .md e não foi inventariado. docs/evidence/ é evidência visual (18 PNGs), não documentação de leitura.

• docs/architecture/ reúne mapas JSON e seus renders disponíveis. Consulte o catálogo de mapas e os arquivos do diretório; a contagem muda com as entregas. A doutrina exige representar peças novas e suas relações, e tests/unit/mapas-de-arquitetura.test.ts verifica a forma e os kinds do runtime. Esse gate não comprova, sozinho, que toda funcionalidade tem um mapa.

• docs/growth/ (3 docs) e docs/brand/ (1) não foram lidos em detalhe — classificados por nome de pasta, portanto INFERIDO.

• Acompanhamento administrativo por sessão — autoridade, somente leitura, saída e contratos OAuth.