# TROUBLESHOOTING.md — Erros, Correções e Lições da Léia

Este arquivo guarda as correções e cuidados aprendidos durante a instalação real da Léia. A ideia é que uma nova cópia já nasça mais madura, evitando problemas já conhecidos.

## 1. Áudio / Whisper / Transcrição

### Sintoma
A transcrição automática de áudio pode falhar com erro `429`.

### Causa provável
Rate limit ou instabilidade temporária da API de transcrição. Isso NÃO significa necessariamente erro de permissão do servidor.

### Correção
- Tentar novamente usando o script de transcrição liberado.
- Se falhar de novo com `429`, aguardar alguns segundos e tentar mais uma vez.
- Não confundir `Audio transcription failed (429)` com erro de `exec denied`.

### Regra operacional
Quando o erro for claramente do Whisper/API, não pedir aprovação de exec sem necessidade.

---

## 2. Exec / Allowlist / Aprovação

### Sintoma
Comando falha com:

```txt
exec denied: allowlist miss
```

### Causa
O comando ou o formato do comando não está permitido na allowlist do OpenClaw.

### Correções práticas
- Preferir comandos simples e diretos.
- Evitar heredoc quando possível.
- Evitar `bash -lc` se o ambiente bloquear.
- Usar scripts dentro de `/root/.openclaw/workspace/scripts/` quando for algo recorrente.
- Não repetir o mesmo comando bloqueado várias vezes.

### Exemplo real
Um comando Python com heredoc foi bloqueado. A correção foi usar `python3 -c` em uma linha simples.

---

## 3. Vercel não lê variável no comando direto

### Sintoma
Erro da Vercel:

```txt
You defined "--token", but its contents are invalid. Must not contain: "$"
```

### Causa
A variável `VERCEL_TOKEN` não foi expandida no ambiente daquele comando.

### Correção usada
Criar um script seguro dentro de `/root/.openclaw/workspace/scripts/`, carregar o `.env` dentro dele e executar o comando sem imprimir token.

Exemplo de script:

```bash
#!/usr/bin/env bash
set -euo pipefail
DOMAIN="$1"
PROJECT="$2"
set -a
. /root/.openclaw/.env
set +a
vercel domains add "$DOMAIN" "$PROJECT" --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE"
```

---

## 4. Cloudflare DNS

### Cuidados
- Para subdomínio em Vercel, usar CNAME para `cname.vercel-dns.com`.
- Para raiz em Vercel, usar A para `76.76.21.21`.
- Não mexer em `MX`, `TXT`, SPF, DKIM, DMARC ou email sem confirmação explícita.

### Regra importante
Antes de apagar um registro antigo em produção, avisar o dono, porque pode tirar o site antigo do ar.

---

## 5. Domínio emersoncrispim.com.br

### Estado conhecido
- `acessoaleia.emersoncrispim.com.br` aponta para a página do Kit da Léia.
- O site principal `emersoncrispim.com.br` pode ser substituído pela Vercel quando o site novo estiver pronto.
- Antes de apagar os registros antigos do site principal, avisar o Emerson.
- Email não deve ser tocado.

---

## 6. Segurança de tokens

### Regra
Mesmo que o dono autorize, não publicar tokens, senhas ou chaves reais em página pública, ZIP público ou repositório.

### Solução correta
Publicar `.env.example` com os nomes das variáveis e instruções. O `.env` real fica só no servidor.

---

## 7. Estrutura de memória

### Arquivos importantes
- `MEMORY.md` — índice.
- `memory/decisions.md` — decisões permanentes.
- `memory/projects.md` — projetos ativos.
- `memory/lessons.md` — lições aprendidas.
- `memory/pending.md` — pendências.
- `memory/people.md` — contatos.
- `memory/security-log.md` — eventos de segurança.

### Regra
Se importa, escreve em arquivo. O que não está escrito, pode se perder.

---

## 8. Deploy de páginas

### Processo padrão
1. Criar site em `/root/.openclaw/workspace/sites/NOME-DO-SITE/`.
2. Criar `index.html` e assets.
3. Rodar:

```bash
vercel-deploy.sh /root/.openclaw/workspace/sites/NOME-DO-SITE nome-do-site
```

4. Se precisar domínio customizado:
   - criar DNS no Cloudflare;
   - adicionar domínio no projeto Vercel;
   - validar HTTPS com `web_fetch` ou browser.

---

## 9. Regra de ouro operacional

Quando for uma ação externa, destrutiva, cara, pública ou que altera produção, pedir confirmação ou avisar no momento certo.

Quando for criar arquivo, organizar pasta, montar página local ou publicar algo já autorizado pelo dono, executar e validar.