Rafael MelgaçoandClaude Opus 5
0750e10010
Varredura de "afirmações de estado": toda frase que afirma como o mundo ESTÁ e
que portanto pode ter envelhecido. 393 afirmações medidas contra a fonte em 11
grupos de documento, cada uma com o comando que a responde. 166 confirmadas, 227
com problema, 4 vereditos VERDADEIRA derrubados por um passe adversarial.
E a primeira coisa que a varredura derrubou foi uma frase que EU escrevi hoje.
## O pior achado, e é meu
O runbook dizia "**Desde a 1.3.0**, o agente completa o pin sozinho — em até 5
minutos". Falso. O `completar_pin_ausente` entrou em `81b3bd5d` (2026-08-14),
POSTERIOR à v1.3.0 (2026-08-13), e a v1.3.0 continua sendo a tag mais recente:
$ git show v1.3.0:hostgator-setup-kit/_common.sh | grep -c completar_pin_ausente
0
Nenhuma instalação existente tem esse comportamento. E o `update.sh` faz
`git checkout "$TARGET_TAG"` — o kit que roda na VPS é o da TAG, não o da `main`.
Quem atendesse um cliente lendo aquela linha diria "espere cinco minutos que se
resolve", e nada aconteceria, para sempre.
O erro é exatamente o que esta sessão passou o dia caçando: **provei presença na
main e afirmei comportamento na versão publicada.** A mesma frase estava no
CHANGELOG, e pior — dentro da seção `## [1.3.0]`, não em `[Não lançado]`. As duas
corrigidas, e a entrada foi para onde pertence.
## O segundo: o aviso que declarava não-provado o que o documento prova
O topo do runbook dizia "ainda não coberto: app contra Supabase real, sessão de
WhatsApp pareada". O §P4 do MESMO arquivo, 340 linhas abaixo, documenta as duas
coisas na produção. Faltava uma palavra — "pelo ENSAIO" — e sem ela o primeiro
parágrafo que qualquer leitor vê mandava refazer trabalho já feito.
## Três documentos mandavam o leitor agir errado
- **`triagem/TRIAGEM.md`**: "Obrigatórios no merge: verify, build-and-size,
invariants" — três de cinco, faltando `e2e` e `imagens-ok`. É o arquivo que
DEFINE a triagem, e o CLAUDE.md registra que medir contra a régua errada é o
modo de falha número um dela. Agora traz o comando, não a lista.
- **`docs/deploy-hostgator/README.md`**: mandava o comprador leigo instalar um
autenticador e esperar um QR de MFA "no primeiro login". Com o MFA opcional, o
`bootstrap-owner.ts` grava `mfa_required: false` e essa tela não aparece — o
leigo concluiria que a instalação falhou. É o guia P0 de primeira impressão.
- **`ARCHITECTURE.md`**: "MFA TOTP forçado pra admin/super-admin", a regra antiga.
O CLAUDE.md já tinha a nova; a porta de entrada linkada pelo README, não.
## A régua de RAM: duas parcelas medidas, uma herdada
"~150 MB por número de WhatsApp" aparece em SETE documentos que se citam entre si
e **nunca foi medido neste projeto** — vem da síntese do curso WAHA (2026-05). Fui
medir na produção: o contêiner `waha` inteiro em **304,5 MiB com uma sessão
pareada**, contra `mem_limit` de 1280. Um ponto não decompõe baseline e sessão.
A parcela agora está marcada como herdada, com o comando para quem quiser medir.
**O tier recomendado não muda** — a régua dos 4 GB é a soma da stack em operação,
não o WAHA isolado, e os materiais comerciais não foram tocados.
## Segurança: corrigi o fato, não rebaixei o risco
O `docs/threat-model.md` afirma que não há limite de tentativa em login, signup e
aceite de convite. `lib/auth/rate-limit.ts` existe desde 13/08 e cobre os quatro
pontos, com limites nomeados. **Não rebaixei o T1**: isso pede reauditoria com
teste contra instância viva, que o próprio `confidence` do documento diz nunca ter
havido. Corrigi os fatos e marquei a reauditoria como devida.
Uma sub-afirmação sobrevive à letra e morre no espírito, e ficou registrada: a
sonda do doc (`grep lockout|failed_attempts`) devolve ZERO ainda hoje — mas
`rate-limit.ts:158` conta falha de login POR CONTA. A sonda é cega para a defesa
que existe.
## O gate novo, e ele nasceu vermelho pelo motivo certo
`documentacao-aponta-para-o-que-existe.test.ts` vigia a classe inteira nos 36
documentos de AUTORIDADE: link relativo morto, path em crase que não existe, e
frase de pendência que sobreviveu à pendência.
Escopo deliberado: `docs/stories/`, `docs/handoffs/` e `docs/specs/` ficam de fora
— são planejamento, e incluí-los faria o gate nascer com 384 violações e ser
desligado na primeira semana. Nos 36 de autoridade havia UMA, e ela é honesta (o
runbook cita o script e declara que ele não existe): congelada com justificativa.
Ele nasceu vermelho e estava certo — pegou sozinho duas notas de pendência que a
varredura tinha achado e eu ainda não corrigira, em CONTRIBUTING.md e na doutrina.
Quatro sabotagens, cada uma derrubando exatamente 1 dos 4 — inclusive a do escopo
vazio, porque um gate que varre zero arquivo passa verde. Sabotei DEPOIS de deixar
o controle verde: na primeira tentativa o controle já falhava, e as sabotagens não
provavam nada. E `git add -N` antes, porque `git checkout` não restaura arquivo
que o git ainda não conhece — a sabotagem do escopo ficou aplicada e só apareceu
no run seguinte.
## O que NÃO entra aqui
227 achados; apliquei os de gravidade alta cuja consequência é alguém agir errado.
Os de gravidade média e baixa — sobretudo contagens que envelheceram em
`docs/current-state.md` e `docs/harness-audit.md` — ficam listados no relatório,
não corrigidos. Aplicar 227 correções de texto num commit seria trocar prosa velha
por prosa não verificada.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RKm2XcTcfgi1vdMcDYSRWa
Como subir o seu DeskcommCRM na HostGator (passo a passo, sem enrolação)
Este guia leva você do zero — sem servidor, sem nada — até o seu CRM no ar, com WhatsApp conectado e IA respondendo. Não precisa saber programar. Se travar em algum passo, o assistente do Claude Code faz por você (veja o Caminho fácil).
⏱️ Tempo estimado: 20 a 40 minutos, a maior parte esperando o domínio "propagar". 💰 Custo: o software é grátis. Você paga só a hospedagem (VPS) e, se quiser, a IA por uso.
Visão geral (o que vamos montar)
Seu domínio → Servidor VPS (HostGator) → DeskcommCRM rodando
│
├─ o CRM (site + painel)
├─ o WhatsApp (conectado por QR)
└─ os robôs de IA
Banco de dados: Supabase (grátis) · IA: Anthropic (paga por uso)
Antes de começar, você vai precisar de 3 contas
| O quê | Onde | Custo |
|---|---|---|
| Servidor VPS | HostGator (links abaixo) | pago (mensal) |
| Banco de dados | supabase.com | grátis |
| IA | console.anthropic.com | pago por uso |
Crie a conta do Supabase e da Anthropic agora (leva 2 min cada). O VPS a gente contrata no passo 1.
Passo 1 — Contrate o servidor (VPS) na HostGator
O DeskcommCRM roda num VPS com Docker. A opção mais fácil é um VPS que já vem com Docker instalado:
- 👉 VPS com GatorClaw — recomendado, Docker pronto
- 👉 VPS com OpenClaw — Docker pronto
- 👉 VPS com n8n — Docker pronto
- 👉 VPS padrão — funciona também (a gente instala o Docker)
- 👉 Servidor Dedicado — só se você atende MUITO volume
Plano recomendado: VPS NVMe 4 (2 vCPU / 4 GB / 100 GB NVMe) — é exatamente o mínimo que o runbook de produção declara. A stack sobe num NVMe 2, mas opera no limite. (Não precisa dos planos grandes — o CRM vem "pré-montado", o servidor não fica compilando nada).
Ao contratar, a HostGator te envia por e-mail o IP do servidor, um usuário
(geralmente root) e uma senha. Guarde isso.
Não tem domínio ainda? Você pode registrar um junto com a HostGator na contratação.
Passo 2 — Entre no servidor
No seu computador, abra o Terminal (no Windows: "PowerShell"; no Mac: "Terminal") e digite, trocando pelo IP que a HostGator te mandou:
ssh root@SEU-IP-AQUI
Ele vai pedir a senha (ao digitar, não aparece nada na tela — é normal). Deu certo? Você está "dentro" do servidor.
Se aparecer "Docker não encontrado" mais pra frente, instale com:
curl -fsSL https://get.docker.com | sh
Agora libere as portas do site (sem isso o cadeado de segurança/SSL não funciona).
⚠️ Antes de ativar o firewall, confira em que porta você está conectado por SSH. Se
for a padrão (22), use o comando abaixo como está. Se a HostGator te deu uma porta
diferente (ex.: 2222, 22022), troque o 22 pela sua porta — senão o firewall te
tranca pra fora do servidor.
ufw allow 22,80,443/tcp && ufw --force enable
Se a HostGator tiver um firewall no painel dela, libere as portas 80 e 443 lá também. Este é o motivo nº 1 de o site não abrir depois de instalar.
Passo 3 — Crie o banco de dados (Supabase, grátis)
- Entre em supabase.com → New project.
- Escolha a região South America (São Paulo) e uma senha forte para o banco (guarde).
- Espere o projeto ficar pronto (~2 min).
- No menu Settings → API, copie e guarde 3 coisas:
- Project URL (algo como
https://xxxx.supabase.co) - anon public key
- service_role key (secreta!)
- Project URL (algo como
- Em Settings → Database, na seção Connection string, clique em Session pooler (⚠️ NÃO use a "Direct connection") e copie a URL no modo URI.
Por que Session pooler, e não a conexão direta? A conexão "direct" do Supabase é só IPv6 — e quase todo VPS (incluindo os da HostGator) tem só IPv4, então ela não conecta e a instalação trava. O Session pooler aceita IPv4 e é grátis (você não precisa do add-on pago "IPv4 dedicado"). A URL correta se parece com:
postgresql://postgres.SEUPROJETO:SUASENHA@aws-1-<região>.pooler.supabase.com:5432/postgresSe a senha do banco tiver caracteres especiais (
@,#, etc.), o Supabase mostra um aviso pra "percent-encode" — o instalador já lida com isso; copie a URL como o painel mostra.
Pronto — você tem as 4 informações do banco.
Passo 4 — Aponte seu domínio para o servidor
⏳ Faça este passo primeiro, de preferência 1 dia antes. O domínio leva de minutos a horas pra "propagar", e o SSL só é emitido depois que ele apontar pra cá. Deixar isso pra última hora é o que mais atrasa a instalação.
No painel onde você comprou o domínio (HostGator ou outro), crie um registro A:
| Campo | Valor |
|---|---|
| Tipo | A |
| Nome/Host | crm (ou @ pra usar o domínio raiz) |
| Aponta para | o IP do servidor (passo 1) |
Isso faz crm.seudominio.com.br levar ao seu servidor. Pode levar de alguns minutos
a algumas horas pra "valer" (propagar) — o instalador confere isso e te avisa.
Passo 5 — Instale o CRM
Agora escolha um dos dois caminhos:
Caminho fácil: o Claude Code faz por você
-
Conecte no servidor por SSH e abra o Claude Code lá dentro (na VPS, não no seu PC).
-
Escreva pra ele exatamente isto:
"Clone https://github.com/melgarafael/DeskcommCRM e me instale o DeskcommCRM seguindo o
hostgator-setup-kit/install.sh. Me pergunte as chaves uma por uma e resolva os erros você mesmo." -
Ele baixa o projeto sozinho, lê as instruções de instalação e conduz tudo — pedindo o domínio, as chaves do Supabase e da Anthropic, e o e-mail/senha do admin uma de cada vez, e resolvendo qualquer tropeço.
Não precisa baixar nem enviar nenhum arquivo
.zip: o projeto é público e o Claude Code baixa direto do GitHub, sempre na versão mais recente.
Caminho manual: um comando
No servidor, baixe o projeto e rode o instalador:
git clone https://github.com/melgarafael/DeskcommCRM.git
cd DeskcommCRM
bash hostgator-setup-kit/install.sh
O instalador pergunta o que precisa e monta tudo: gera as senhas técnicas, cria o banco, cria o seu usuário admin, sobe o CRM e confere se ficou no ar.
Passo 6 — Primeiro acesso
- Abra
https://crm.seudominio.com.brno navegador. O cadeado de segurança (SSL) leva cerca de 1 minuto pra aparecer no primeiro acesso — se der erro de segurança, espere um pouco e recarregue. - Entre com o e-mail e senha que você definiu na instalação.
- Pronto — você já está dentro. Não há mais nenhum passo obrigatório antes de usar o sistema.
Segurança em 2 etapas (opcional, e recomendada). O CRM não pede isso no primeiro login — você liga quando quiser, em Configurações › Segurança. Vai precisar de um app como Google Authenticator ou Authy no celular: escaneia o QR e digita o código de 6 dígitos. Depois de ligado, o código passa a ser pedido em todo login.
Este guia já disse que o CRM pedia isso logo no primeiro acesso. Não pede — e quem esperasse a tela aparecer concluiria que a instalação deu errado. O QR que você vai ver a seguir é outro: é o do WhatsApp, no Passo 7.
Passo 7 — Conecte o WhatsApp
No onboarding, o CRM mostra um QR code. No celular:
- Abra o WhatsApp → Aparelhos conectados → Conectar um aparelho.
- Aponte a câmera pro QR na tela.
Pronto — as mensagens do seu número começam a cair no CRM.
Use o número que você quer atender pelo CRM. Recomendamos um número dedicado ao atendimento (não o seu pessoal).
Passo 8 — Coloque a IA pra trabalhar (opcional)
Na área de Agentes de IA, cole a sua chave da Anthropic e configure o robô (nome, tom de voz, base de conhecimento). A IA passa a sugerir e responder dentro das regras que você definir.
Deu tudo certo? Cuide do seu CRM
| Quero... | Comando (no servidor, dentro da pasta do projeto) |
|---|---|
| Ver se está tudo no ar | bash hostgator-setup-kit/healthcheck.sh |
| Atualizar pra versão nova | bash hostgator-setup-kit/update.sh |
| Fazer backup (faça sempre!) | bash hostgator-setup-kit/backup.sh |
| Esqueci a senha | bash hostgator-setup-kit/reset-password.sh seu@email.com |
| Perdi o app do autenticador | bash hostgator-setup-kit/reset-mfa.sh seu@email.com |
Backup é sério: o plano grátis do Supabase não faz backup sozinho. Rode o
backup.shde vez em quando (ou agende no servidor pra rodar todo dia).
Travou? Problemas comuns
| Sintoma | O que fazer |
|---|---|
| Site não abre / erro de segurança | O domínio ainda não apontou pro servidor, ou faltou liberar as portas. Rode ufw allow 80,443,22/tcp e espere o domínio propagar. |
| A página fica recarregando/erro | Faltou alguma chave. Rode docker compose -f docker-compose.prod.yml logs app e procure a linha que diz qual variável falta. |
| WhatsApp não conecta | Veja docker compose -f docker-compose.prod.yml logs waha. Confirme que o número não está conectado em outro computador. |
Em qualquer travamento, você pode voltar ao Claude Code e pedir ajuda — ele lê os erros do servidor e resolve.
Por que HostGator?
O DeskcommCRM foi desenhado pra rodar redondo na infraestrutura da HostGator. Além do VPS, você pode centralizar aí:
- Registro de domínio para o seu CRM;
- Servidor Dedicado quando o volume crescer.
Todos os links deste guia são oficiais da HostGator.