# Download CWW - CrânIA WhatsApp Web

Versão desta página revisada: `26.7.9a`.

CWW é CrânIA WhatsApp Web: a ponte local entre WhatsApp Web e agentes de IA.

## Escopo Deste Guia

Este guia existe para:

- validar requisitos mínimos;
- preparar o ambiente;
- baixar o pacote oficial;
- instalar o CWW localmente;
- executar o bootstrap inicial;
- iniciar a instância com segurança;
- validar o primeiro smoke test.

Este guia não é o manual completo de operação.

Depois da instalação:

- `config.md` é o manual técnico para a IA operar, configurar e evoluir a ferramenta;
- `skills/cww.md` é o mapa para a IA ensinar o usuário a operar junto com a IA no formato correto.

## Para Começar Com Agente

Instale o Codex, Antigravity, Claude Code ou Copilot e cole:

```text
Você é um agente de instalação do Ecossistema CrânIA.
Leia e siga as instruções de instalação em
https://crania.ia.br/download-CWW.md

Objetivo:
- instalar o CWW em modo local e seguro;
- perguntar: "deseja instalar na porta padrão 2001, ou deseja informar uma porta?";
- preparar o ambiente completo antes de colocar o CWW para rodar;
- validar sistema, arquitetura, Node.js, npm, navegador, porta livre, pasta e instalação antiga;
- tratar Node.js mínimo `22.x` e `npm` global como requisito do CWW básico;
- tratar Python mínimo `3.11` como opcional no CWW básico e necessário apenas para áudio local, documentos ou integrações extras;
- se faltar Node no Windows, validar a plataforma e preferir instalador oficial `.msi`; em máquina `x64`, preferir `x64`; instalar globalmente, nunca só no perfil do usuário;
- baixar, instalar e validar sem abrir o CWW antes da hora;
- não rodar o CWW antes de `cww bootstrap`, `cww doctor` e registro mínimo em `manage/README.md`;
- iniciar o CWW no Windows com `launch hidden` por padrão;
- tratar serviço Windows como opção avançada, não como caminho padrão;
- usar CListen/CSay online como áudio recomendado do pacote atual, ou deixar `TRANSCRIPT=OFF` e `NARRATE=OFF` se o usuário não quiser voz;
- instalar junto a skill `skills/cww.md` para orientar o uso com a IA;
- se houver instalação antiga, oferecer migração antes de sobrescrever qualquer coisa;
- explicar quando pedir elevação, usuário ou senha.
```

Esse documento foi escrito para agentes. A pessoa usuária deve conseguir copiar o prompt, colar no cliente de IA escolhido e deixar o agente conduzir a instalação.

## Ordem Obrigatória

Fase 1: preparar o ambiente.

- escolher porta e pasta base;
- validar Node.js, npm, navegador e porta;
- localizar instalação antiga, se houver;
- fazer backup de `.env`, `storage`, `session`, `runtime`, `log` e `manage` quando for atualização;
- baixar ZIP oficial publicado nesta página;
- instalar CLI;
- rodar `bootstrap`;
- rodar `doctor`;
- registrar `manage/README.md`;
- resolver pendências obrigatórias.

Fase 2: colocar para rodar.

- iniciar com `launch hidden`, `run.bat` ou serviço, conforme decisão registrada;
- abrir `http://127.0.0.1:<porta>/`;
- aceitar termos;
- parear QR Code;
- validar `/health`, `/status` e `/mcp`.

Se a Fase 1 falhou, não execute a Fase 2.

## Download

Pacote atual:

- versão: `26.7.9a`
- ZIP: https://crania.ia.br/static/downloads/cww-bundle-26.7.9a-20260709-135042.zip

O ZIP contém runtime compilado, CLI, documentação, `skills/cww.md`, scripts operacionais, `manifest.txt` e exemplos de `.env`. Ele não contém `.env` real, sessão de WhatsApp, storage, cache, `node_modules` ou chave privada.

## Pré-Requisitos

Obrigatórios:

- Node.js mínimo `22.x`, instalado globalmente;
- `npm` global;
- Google Chrome ou Microsoft Edge;
- porta `2001` livre, salvo escolha diferente.

Node.js `22.x` e `npm` global são requisito de funcionamento do CWW básico. Sem isso, não trate falha de instalação, QR, MCP ou storage como mero detalhe de configuração.

Opcionais recomendados:

- Python mínimo `3.11`, instalado globalmente, quando a instalação decidir usar áudio local, documentos ou integrações extras;
- Python é opcional no CWW básico e obrigatório apenas para áudio local, leitura de documentos e integrações locais extras;
- `ffmpeg` e `ffprobe` só entram quando a configuração técnica pedir áudio local depois;
- no Windows, validar a arquitetura antes de baixar instaladores; em máquina `x64`, preferir instalador oficial `.msi` `x64`;
- instalar Node e Python globalmente para a máquina, nunca apenas no perfil do usuário.

Áudio recomendado do pacote atual:

- transcrição online por CListen;
- narração online por CSay;
- detalhes de endpoints, tokens vigentes e modo `OFF` ficam no `config.md` do pacote.

## Porta, Pastas E Estrutura Base

Pergunta inicial obrigatória:

```text
deseja instalar na porta padrão 2001, ou deseja informar uma porta?
```

Se a pessoa confirmar, use `2001`. Se pedir outra porta, use a mesma porta em todos os comandos, registros e URLs.

Pastas sugeridas:

- Windows: `C:\crania\cww`
- Linux: `/opt/crania/cww`
- tools gerais: pasta irmã de `cww`, por exemplo `C:\crania\tools`
- base de conhecimento autorizada: `manage/files` dentro do próprio CWW

Estrutura esperada:

```text
C:\crania\cww
C:\crania\cww\package
C:\crania\cww\manage
C:\crania\cww\manage\files
C:\crania\tools
```

Regra importante:

- o CWW é pacote portátil;
- não dependa de caminhos absolutos da máquina de desenvolvimento;
- derive storage, sessão, runtime e logs a partir da base local escolhida;
- não crie `storage` fora da base escolhida em instalação local comum.

## Preflight Obrigatório

### Windows

Rode antes de baixar ou iniciar o CWW:

```powershell
$Port = 2001
$Base = "C:\crania\cww"
$Package = Join-Path $Base "package"
$Zip = Join-Path $Base "cww-bundle-26.7.9a-20260709-135042.zip"

Write-Host "Sistema:"
Get-ComputerInfo | Select-Object OsName, OsArchitecture, WindowsVersion

Write-Host "Node/npm:"
node --version
npm --version

Write-Host "Navegador:"
Get-Command chrome.exe -ErrorAction SilentlyContinue
Get-Command msedge.exe -ErrorAction SilentlyContinue

Write-Host "Porta:"
Get-NetTCPConnection -LocalPort $Port -ErrorAction SilentlyContinue

Write-Host "Pasta base:"
New-Item -ItemType Directory -Force -Path $Base | Out-Null
Get-Item $Base
```

Aceite mínimo do preflight Windows:

- `node --version` responde `v22.x`;
- `npm --version` responde sem erro;
- Chrome ou Edge existe;
- a porta escolhida não está ocupada;
- a pasta base existe e é gravável.

### Linux

Rode antes de baixar ou iniciar o CWW:

```bash
PORT=2001
BASE=/opt/crania/cww
PACKAGE="$BASE/package"
ZIP="$BASE/cww-bundle-26.7.9a-20260709-135042.zip"

uname -a
node --version
npm --version
command -v google-chrome || command -v chromium || command -v microsoft-edge || true
ss -ltnp | grep ":${PORT} " || true
sudo mkdir -p "$BASE"
sudo chown "$USER":"$USER" "$BASE"
test -w "$BASE"
```

Aceite mínimo do preflight Linux:

- `node --version` responde `v22.x`;
- `npm --version` responde sem erro;
- existe Chrome, Chromium ou Edge quando o fluxo precisar abrir WhatsApp Web local;
- a porta escolhida está livre;
- a pasta base existe e é gravável pelo usuário que vai operar o CWW.

## Instalação Windows

Abra PowerShell normal e execute:

```powershell
$Port = 2001
$Base = "C:\crania\cww"
$Package = Join-Path $Base "package"
$Zip = Join-Path $Base "cww-bundle-26.7.9a-20260709-135042.zip"

New-Item -ItemType Directory -Force -Path $Base | Out-Null
Set-Location $Base
Invoke-WebRequest `
  -Uri "https://crania.ia.br/static/downloads/cww-bundle-26.7.9a-20260709-135042.zip" `
  -OutFile $Zip
Expand-Archive $Zip -DestinationPath $Package -Force
Set-Location $Package
npm.cmd install -g .
cww.cmd --help
cww.cmd bootstrap --port $Port --data-root $Base --write
cww.cmd doctor --port $Port
```

Se `doctor` apontar erro obrigatório, pare e corrija antes de abrir o CWW.

Depois do `doctor`, registre a instalação:

```powershell
$Manage = Join-Path $Base "manage"
New-Item -ItemType Directory -Force -Path $Manage | Out-Null
@"
# CWW local

- base: $Base
- pacote: $Package
- porta: $Port
- modo padrão: launch hidden
- serviço Windows: não instalado
- observação: caminhos derivados da base local.
"@ | Set-Content -Encoding UTF8 (Join-Path $Manage "README.md")
```

Só então inicie:

```powershell
cww.cmd launch --port $Port --hidden --open
```

Se `cww.ps1` for bloqueado por `ExecutionPolicy`, use `cww.cmd`. Não mude a política global do PowerShell só para ganhar uma discussão besta com o Windows.

Serviço Windows é opção avançada. O padrão é `launch hidden`. Se o usuário pedir serviço, trate isso depois da instalação básica validada.

## Instalação Linux

```bash
PORT=2001
BASE=/opt/crania/cww
PACKAGE="$BASE/package"
ZIP="$BASE/cww-bundle-26.7.9a-20260709-135042.zip"

sudo mkdir -p "$BASE"
sudo chown "$USER":"$USER" "$BASE"
cd "$BASE"
curl -L -o "$ZIP" \
  https://crania.ia.br/static/downloads/cww-bundle-26.7.9a-20260709-135042.zip
unzip -o "$ZIP" -d "$PACKAGE"
cd "$PACKAGE"
npm install -g .
cww --help
cww bootstrap --port "$PORT" --data-root "$BASE" --write
cww doctor --port "$PORT"
```

Se `doctor` apontar erro obrigatório, pare e corrija antes de abrir o CWW.

Depois do `doctor`, registre a instalação:

```bash
mkdir -p "$BASE/manage"
cat > "$BASE/manage/README.md" <<EOF
# CWW local

- base: $BASE
- pacote: $PACKAGE
- porta: $PORT
- modo padrão: execução manual ou serviço Linux, conforme decisão registrada.
- observação: caminhos derivados da base local.
EOF
```

Só depois instale serviço Linux, se esse for o modo escolhido:

```bash
sudo cww service install --port "$PORT" --linux
systemctl status "cww@$PORT.service"
```

## Versão E Atualização

O CWW depende de WhatsApp Web, navegador, Node.js e bibliotecas locais. Essas peças mudam. Quando o WhatsApp muda, ele pode quebrar pareamento, envio, leitura, mídia, sessão ou automações.

Regra prática:

- consulte `https://crania.ia.br/cww` periodicamente;
- confira o detalhe da versão em `https://crania.ia.br/download-CWW.md`;
- antes de atualizar, faça backup de `.env`, `storage`, `session`, `runtime`, `log` e `manage`;
- antes de baixar e substituir o bundle, notifique o usuário sobre a versão atual e a versão alvo;
- troque o bundle somente com autorização explícita do usuário;
- depois de atualizar, rode `doctor`, `/health`, `/status` e `/mcp`;
- registre no `manage/README.md` a versão anterior, a versão nova, a data, o motivo e o resultado.

Periodicidade sugerida:

- uso pessoal ou teste: verificar versão a cada mês;
- uso operacional em empresa: verificar versão semanalmente;
- erro novo depois de semanas funcionando: verificar versão antes de depurar negócio.

## Depois Da Instalação

Use os arquivos certos para o momento certo:

- `config.md`: configuração técnica, `.env`, `config.json`, endpoints, Bearer, OpenAI, áudio, sync, serviço, diagnóstico e recursos avançados;
- `skills/cww.md`: bootstrap operacional com a IA, formato de mensagens para WhatsApp, confirmação humana explícita antes de `send`, autoatendimento e uso de `manage/files`.

Padrão inicial recomendado:

- se a máquina tiver até `8 GB` de RAM, a IA deve informar o usuário e preferir áudio online por padrão;
- acima de `8 GB`, a IA pode sugerir áudio local como opção, não como imposição;
- detalhes de áudio, tokens vigentes e requisitos extras ficam em `config.md`.

## Recuperação De Sessão

Se o WhatsApp Web quebrar depois do QR Code, a tela pedir refresh, o endpoint de
status parecer fora do ar ou aparecer `ERR_CACHE_READ_FAILURE`, não reinstale o
CWW como primeiro impulso. Use a limpeza de sessão pela home:

1. Clique em `Descarregar Aplicação`.
2. Aguarde a aplicação ficar descarregada.
3. Clique em `Limpar Sessão`.
4. Clique em `Carregar Aplicação`.
5. Abra o QR Code e pareie novamente.

Essa limpeza remove sessão/cache local e runtime volátil da instância. Ela
preserva storage, histórico baixado, logs, `config.json`, `.env` e arquivos de
gestão. Se o motor ainda estiver carregado, a limpeza deve ser recusada; primeiro
descarregue a aplicação.

## Contato E Mentoria

Para mentoria, configurações avançadas, apoio de arquitetura ou uso profissional do ecossistema:

- Fábio Souza: `(11) 96120-2670`

## Smoke Test

Valide:

```bash
cww doctor --port 2001
```

Com o CWW em execução:

```text
http://127.0.0.1:2001/health
http://127.0.0.1:2001/status
http://127.0.0.1:2001/mcp
```

Aceite mínimo:

- `/health` responde;
- `/status` mostra a versão instalada;
- `/mcp` responde JSON-RPC;
- `/terms` aparece antes do QR;
- QR só é pareado depois da ciência dos termos.