@pixeleducacao/curso-openclaw 2026.5.8

package/assets/skills/starter/wizard-conectar/evals/evals.json

@@ -0,0 +1,196 @@
+{
+  "skill": "wizard-conectar",
+  "version": "1.0",
+  "description": "4 cenários cobrindo: caminho completo, parcial (Brave já existe), aluno só quer Brave, .env já commitado por engano",
+  "scenarios": [
+    {
+      "id": "caminho-completo",
+      "name": "Aluno conecta as 3 integrações",
+      "description": "Estado limpo. Aluno gera Brave + GitHub, instala Chromium, ativa backup.",
+      "setup": {
+        "env_state": ".env só com OPENAI_API_KEY",
+        "memory_flags": {
+          "autonomia_liberada": true,
+          "workspace_organizado": true,
+          "onboarding_current_step": 5
+        }
+      },
+      "interaction_flow": [
+        {
+          "user": "[despachado]",
+          "expected_agent_behavior": [
+            "checa autonomia_liberada=true (ok)",
+            "Princípio 11 — lê .env, detecta Brave/GitHub ausentes",
+            "narra promessa (Brave + GitHub + Chromium opcional)",
+            "começa por Brave"
+          ]
+        },
+        {
+          "user": "BSAkXXXXXXXX",
+          "expected_agent_behavior": [
+            "valida via curl Brave Search API (200)",
+            "backup do .env (Princípio 1)",
+            "salva BRAVE_SEARCH_API_KEY",
+            "passa pra GitHub Token"
+          ]
+        },
+        {
+          "user": "ghp_XXXXXXXX",
+          "expected_agent_behavior": [
+            "valida via curl GitHub user API (200)",
+            "extrai username",
+            "salva GITHUB_TOKEN",
+            "pergunta sobre Chromium"
+          ]
+        },
+        {
+          "user": "instala",
+          "expected_agent_behavior": [
+            "explica que browser já vem incluído no Managed (não precisa instalar)",
+            "valida com openclaw browser status",
+            "confirma disponível"
+          ],
+          "must_not": [
+            "inventar comando 'openclaw browser install chromium' (não existe)",
+            "pedir aluno colar comando no terminal (não há comando pra colar)"
+          ]
+        },
+        {
+          "user": "[browser disponível confirmado]",
+          "expected_agent_behavior": [
+            "ativa backup-workspace-github (despacha skill)",
+            "espera skill terminar",
+            "confirma 4 conectados",
+            "pergunta-âncora"
+          ]
+        },
+        {
+          "user": "revogo a chave e gero nova",
+          "expected_agent_behavior": [
+            "valida resposta",
+            "menciona aula D2",
+            "marca conectado=true, brave/github/chromium/backup todos true",
+            "atualiza onboarding_current_step=6"
+          ]
+        }
+      ],
+      "success_criteria": [
+        "BRAVE_SEARCH_API_KEY + GITHUB_TOKEN no .env validados",
+        "Chromium instalado",
+        "backup-workspace-github ativo (cron criado, push feito)",
+        "conectado=true",
+        "onboarding_current_step=6",
+        ".env no .gitignore"
+      ]
+    },
+    {
+      "id": "parcial-brave-ja-existe",
+      "name": "Aluno já tem BRAVE_SEARCH_API_KEY no .env",
+      "description": "Princípio 11 detecta e pula pedido de Brave. Pede só GitHub.",
+      "setup": {
+        "env_state": ".env tem BRAVE_SEARCH_API_KEY válida (testada)",
+        "memory_flags": {
+          "autonomia_liberada": true
+        }
+      },
+      "interaction_flow": [
+        {
+          "user": "[despachado]",
+          "expected_agent_behavior": [
+            "lê .env, acha Brave + valida",
+            "narra '✓ Achei Brave já configurada, validei, OK'",
+            "pula direto pra pedido de GitHub Token",
+            "NÃO pede Brave nova"
+          ],
+          "must_not": [
+            "pedir aluno gerar Brave nova",
+            "duplicar BRAVE_SEARCH_API_KEY no .env"
+          ]
+        }
+      ],
+      "success_criteria": [
+        "Brave NÃO foi pedida (Princípio 11 funcionou)",
+        "GitHub foi pedido normalmente",
+        "Brave key original preservada"
+      ]
+    },
+    {
+      "id": "so-quer-brave",
+      "name": "Aluno topa só Brave, GitHub depois",
+      "description": "Aluno não quer GitHub agora. Wizard avisa do tradeoff e respeita.",
+      "setup": {
+        "env_state": ".env limpo",
+        "memory_flags": {}
+      },
+      "interaction_flow": [
+        {
+          "user": "[após Brave configurada]",
+          "expected_agent_behavior": ["pede GitHub Token"]
+        },
+        {
+          "user": "github fica pra depois, pode pular",
+          "expected_agent_behavior": [
+            "explica tradeoff (sem backup automático, depende só do snapshot do Managed)",
+            "respeita escolha",
+            "marca github_token_active=false, backup_active=false",
+            "pula Chromium também (ou pergunta?)",
+            "pergunta-âncora",
+            "confirma que pode reativar com 'ativa github' depois"
+          ],
+          "must_not": [
+            "insistir em GitHub depois de aluno ter declinado claramente"
+          ]
+        }
+      ],
+      "success_criteria": [
+        "Brave ativa, GitHub e backup pendentes",
+        "aluno foi informado do tradeoff",
+        "conectado=true (parcial — só Brave) em MEMORY"
+      ]
+    },
+    {
+      "id": "env-commitado-deteccao-defensiva",
+      "name": "Workspace tem .env commitado por engano antes do passo 5",
+      "description": "Antes de salvar GITHUB_TOKEN, wizard verifica histórico git e alerta se .env vazou.",
+      "setup": {
+        "env_state": ".env tem chaves antigas E foi commitado em algum momento",
+        "memory_flags": {
+          "autonomia_liberada": true
+        }
+      },
+      "interaction_flow": [
+        {
+          "user": "[despachado, após Brave OK]",
+          "expected_agent_behavior": ["pede GitHub Token"]
+        },
+        {
+          "user": "ghp_XXXXX",
+          "expected_agent_behavior": [
+            "ANTES de salvar, roda `git log -- .env` no workspace",
+            "detecta que .env aparece em commits anteriores",
+            "ALERTA crítico: '.env foi commitado em {N} commits anteriores. Suas chaves OpenAI/Brave podem estar públicas no histórico.'",
+            "instrui aluno a revogar IMEDIATAMENTE OPENAI_API_KEY e BRAVE_SEARCH_API_KEY no console de cada provider",
+            "instrui sobre git filter-branch ou BFG repo cleaner",
+            "NÃO salva o GITHUB_TOKEN até aluno confirmar entendimento do risco"
+          ],
+          "must_not": [
+            "salvar token e seguir como se nada (chaves antigas continuam vazadas)"
+          ]
+        },
+        {
+          "user": "entendi, revoguei as chaves antigas, gerei novas, tô limpo",
+          "expected_agent_behavior": [
+            "salva GITHUB_TOKEN",
+            "garante .env no .gitignore",
+            "segue fluxo normal (Chromium + backup)"
+          ]
+        }
+      ],
+      "success_criteria": [
+        ".env vazado foi detectado ANTES de adicionar mais chaves",
+        "aluno foi alertado e tomou ação corretiva",
+        "GITHUB_TOKEN salvo só após aluno confirmar limpeza"
+      ]
+    }
+  ]
+}

package/assets/skills/starter/wizard-whisper-quick/SKILL.md

@@ -0,0 +1,349 @@
+---
+name: wizard-whisper-quick
+status: ATIVO
+category: starter
+owner: aluno
+version: 1.2
+mode: guided
+estimated_time: 5min (ou 30s se já configurado)
+model_compatible: [gpt-5, gpt-5.5, claude-sonnet-4, claude-opus-4, gemini-pro]
+description: Use when student types "configura whisper" / "ativa áudio" / "quero mandar áudio", OR when dispatched by onboarding-checklist as passo 0 (pré-passo opcional). Configures OpenAI API key in .env so student can send voice messages on Telegram instead of typing. Detects existing key first (Princípio 11/.env first), validates with API call, asks only if missing. Ends with smoke test (student sends audio, agent transcribes).
+---
+
+# Wizard Whisper Quick — Passo 0 (Pré-passo opcional)
+
+## Promessa
+
+Aluno termina esse passo conseguindo **mandar áudio em vez de digitar** no Telegram. Eu transcrevo na hora e respondo. Quem tá no celular dirigindo, andando, fazendo café — fala em vez de teclar.
+
+Sem ele, aluno passa a jornada inteira digitando. Com ele, passa falando. Mudança grande na primeira impressão.
+
+## Quando disparar
+
+**Trigger automático:**
+- `onboarding-checklist` despacha como passo 0 antes da jornada principal
+
+**Trigger explícito (standalone):**
+- "configura whisper"
+- "ativa áudio"
+- "quero mandar áudio"
+- "configura openai"
+
+**NÃO disparar se:**
+- `whisper_configured=true` em `MEMORY.md` E última validação foi há menos de 7 dias
+- Aluno explicitamente pulou no passo 0 (`whisper_skipped=true` em `MEMORY.md`)
+
+## Princípio 11 — Detecção antes de pedir
+
+**Antes de qualquer pergunta**, executar checagem em 3 camadas:
+
+```
+1. Lê .env: existe OPENAI_API_KEY?
+2. Se existe, valida com call de teste à API:
+   curl -s https://api.openai.com/v1/models \
+        -H "Authorization: Bearer $OPENAI_API_KEY" | head -c 200
+3. Se retorna lista de models (200 OK): chave válida
+   Se retorna 401: chave inválida/revogada
+   Se outro erro: investiga
+```
+
+### 4 estados detectáveis
+
+| Estado | Ação |
+|---|---|
+| **Chave existe e válida** | Marca `whisper_configured=true`, narra "✓ Achei sua chave OpenAI no .env, validei, funcionando", pula direto pro smoke test |
+| **Chave existe mas inválida** | Explica erro específico (revogada/expirada/sintaxe), pede chave nova |
+| **Chave não existe no .env** | Pede ao aluno (fluxo normal abaixo) |
+| **`.env` não existe** | Cria `.env` na raiz do workspace + pede chave |
+
+## Fluxo principal (quando precisa pedir chave)
+
+### 1. Narrar o que vai acontecer
+
+```
+"Antes da gente começar a jornada principal, vou configurar uma coisa
+que destrava você no celular: transcrição de áudio.
+
+Sem isso, você responde tudo digitando. Com isso, manda áudio e eu
+entendo. No celular ou no carro, vira diferença grande.
+
+Pra ativar, preciso de uma chave da OpenAI (a empresa do ChatGPT).
+Custa centavos por mês de uso (~R$2-5 pra uso pessoal médio).
+
+**Você quer ajuda pra pegar essa chave, ou já tem ela fácil aí?**
+
+→ Se já tem: só me manda aqui que eu salvo no lugar certo.
+→ Se quer ajuda: te guio passo-a-passo (cadastro OpenAI → cartão → gera chave). Pega 5min.
+→ Se não quiser agora: manda 'pulo' que a gente vai direto pro passo 1 (você ativa depois com 'configura whisper')."
+```
+
+Esperar resposta:
+- Se aluno mandar a chave direto (começa com `sk-proj-` ou `sk-`): pular pro passo 3 (validar) — não precisa instruir geração.
+- Se aluno mandar "ajuda" / "preciso ajuda" / "como pegar": ir pro passo 2 (instruir geração passo-a-passo).
+- Se aluno mandar "pulo" / "depois" / "deixa pra depois": marcar `whisper_skipped=true` e devolver controle pra `onboarding-checklist`.
+- Outras respostas ambíguas ("já tenho" sem mandar a chave): pedir pra mandar a chave.
+
+### 2. Instruir como gerar chave
+
+```
+"Pra gerar a chave OpenAI:
+
+PARTE 1 — se você NUNCA usou OpenAI API antes:
+
+1. Abre https://platform.openai.com/signup (cria conta — pode usar
+   o mesmo email do ChatGPT Plus, mas a API é separada)
+2. Confirma o email (chega em 1min)
+3. Vai em https://platform.openai.com/billing
+4. Clica 'Add payment method' → adiciona cartão
+5. Adiciona crédito inicial ($5 mínimo recomendado — dura ~6 meses
+   pra uso pessoal médio de Whisper)
+6. Sem isso, qualquer chave que você gerar vai retornar 429 (sem saldo)
+
+PARTE 2 — gerar a chave:
+
+1. Abre https://platform.openai.com/api-keys (logado)
+2. Clica 'Create new secret key' (canto superior direito)
+3. Nome sugerido: 'openclaw-{seu-agente}' (ex: 'openclaw-atlas')
+4. Permissions: 'All' (default tá bom)
+5. Clica 'Create secret key'
+6. COPIA a chave que aparece (começa com 'sk-proj-' ou 'sk-')
+
+⚠️ Atenção segurança:
+- A OpenAI mostra a chave UMA vez só. Fechou janela = tem que gerar outra.
+- ANTES de colar aqui no Telegram: confirma que esse chat é só seu
+  (não é grupo). Chave em chat público = vazada.
+- Se desconfiar de qualquer coisa, revoga a chave em
+  platform.openai.com/api-keys (botão 'Revoke') e gera nova.
+
+Pode mandar a chave."
+```
+
+### 3. Validar a chave que aluno colou
+
+Quando aluno mandar a chave, **antes de salvar**:
+
+```bash
+# Testa com call simples ao endpoint /v1/models
+curl -s https://api.openai.com/v1/models \
+     -H "Authorization: Bearer {chave_recebida}" \
+     -o /tmp/openai-test.json -w "%{http_code}"
+```
+
+| Resposta | Ação |
+|---|---|
+| 200 | Chave válida, prossegue |
+| 401 | "Essa chave veio com erro 401 — autenticação falhou. Provável que você copiou só parte dela. Pode mandar de novo?" |
+| 429 | "A chave funciona, mas a conta tá sem crédito. Adiciona $5 em platform.openai.com/billing e tenta de novo." |
+| Outros | "Erro inesperado: {código}. Manda no grupo @cursoopenclaw que ajudo a debugar." |
+
+### 4. Salvar no .env (formato canônico)
+
+Antes de salvar, aplicar **Princípio 1** (backup):
+
+```
+Existe .env já?
+  - Se SIM: backup em ~/backups/pre-wizard-whisper-{YYYY-MM-DD-HHMM}/.env
+  - Se NÃO: cria .env do zero
+```
+
+Adicionar/atualizar linha no `.env`:
+
+```bash
+OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxx
+```
+
+**Importante:**
+- Nome canônico exato: `OPENAI_API_KEY` (não `openai-key`, `OPENAI_TOKEN`, etc).
+- Se já existir linha `OPENAI_API_KEY=...`, substitui (não duplica).
+- Garantir que `.env` tá em `.gitignore` (se workspace tem git inicializado).
+
+Confirmar ao aluno:
+
+```
+"✓ Chave salva em .env como OPENAI_API_KEY.
+✓ Adicionei .env no .gitignore (se ainda não estava).
+
+Próxima vez que algum wizard precisar dessa chave, ele acha sozinho.
+Você não vai precisar mandar de novo."
+```
+
+### 5. Smoke test (pergunta-âncora embutida)
+
+```
+"Rapidão antes de fechar este passo: pra confirmar que tá tudo certo,
+manda agora um áudio curto dizendo qualquer coisa — 'oi', 'tô testando',
+'gravando aqui'. Eu transcrevo e te mostro."
+```
+
+Quando aluno mandar áudio, transcreve via Whisper:
+
+```bash
+curl -s https://api.openai.com/v1/audio/transcriptions \
+     -H "Authorization: Bearer $OPENAI_API_KEY" \
+     -H "Content-Type: multipart/form-data" \
+     -F file=@{caminho_audio} \
+     -F model=whisper-1
+```
+
+Mostra transcrição:
+
+```
+"✓ Transcrevi: \"{texto}\"
+
+Funcionando. A partir de agora pode mandar áudio em qualquer momento —
+eu entendo igual texto. Pode misturar áudio + texto na mesma conversa
+sem problema.
+
+Se quer aprofundar como configurar OpenAI API e gerenciar custos,
+a aula é a *A0* — manda 'aula A0'.
+
+E se ficou alguma dúvida que eu não cobri, dois caminhos no grupo:
+- resposta rápida 24/7: chama @Openclawzinho (bot IA) no tópico Suporte
+- ajuda humana: pergunta nos outros tópicos
+https://t.me/cursoopenclaw
+
+Marquei o passo 0 como feito. Bora pro passo 1 (configurar a personalidade do seu agente)?"
+```
+
+### 6. Atualizar MEMORY.md
+
+Marcar flag e logar decisão:
+
+```markdown
+## Flags
+whisper_configured: true
+
+## Decisões da jornada
+- {data}: Configurou OpenAI API key. Smoke test áudio passou. Transcrição OK.
+```
+
+Atualizar `onboarding_current_step: 1`.
+
+### 7. Devolver controle pra onboarding-checklist
+
+Wizard termina. `onboarding-checklist` retoma e mostra checklist atualizada.
+
+## Caminho alternativo: chave já configurada
+
+Quando detecção (passo 0 do fluxo) acha chave válida:
+
+```
+"✓ Detectei que sua chave OpenAI já está configurada no .env.
+Validei agora — funcionando.
+
+Mesmo assim, vou fazer um smoke test pra ter certeza que Whisper tá ok:
+
+Manda um áudio curto pra mim agora. Pode ser qualquer coisa."
+```
+
+A partir daí, fluxo padrão (transcreve, mostra, marca como feito).
+
+**Por que validar mesmo já tendo:** chave pode estar lá mas com saldo zerado, sem permissão pra Whisper, ou de uma conta diferente. Smoke test valida end-to-end em 30s.
+
+## Caminho alternativo: aluno pula
+
+Se aluno mandar "pulo" antes de gerar chave:
+
+```
+"Beleza, pulei o passo 0. Você pode ativar áudio depois mandando
+'configura whisper' a qualquer momento, ou no passo 5 (Conectar)
+junto com as outras chaves.
+
+Marquei como pulado. Bora pro passo 1?"
+```
+
+Marca `whisper_skipped=true` em `MEMORY.md` e devolve controle pra `onboarding-checklist`.
+
+## Critérios de sucesso
+
+- [ ] `OPENAI_API_KEY` no `.env` E validada (call de teste retornou 200)
+- [ ] `.env` existe no `.gitignore` (proteção contra commit acidental)
+- [ ] Smoke test áudio completou (aluno mandou áudio, agente transcreveu, mostrou texto)
+- [ ] `whisper_configured=true` em `MEMORY.md`
+- [ ] `onboarding_current_step=1` (avançou)
+- [ ] Pergunta-âncora respondida (smoke test = a pergunta-âncora desse passo)
+
+OU (se pulou):
+
+- [ ] `whisper_skipped=true` em `MEMORY.md`
+- [ ] Aluno avisado que pode reativar via "configura whisper"
+
+## Erros comuns
+
+- **Aluno colou chave inválida (típico erro de copy-paste):** explicar erro específico (401 = autenticação, 429 = sem saldo) ao invés de "deu errado". Aluno volta pro platform.openai.com com clareza do que verificar.
+- **Aluno colou chave do ambiente errado** (ex: chave de uma org sem crédito, ou chave revogada num projeto): smoke test pega isso. Pedir nova.
+- **Aluno mandou áudio mas Whisper falhou:** quase sempre é problema de formato/tamanho do áudio. Telegram converte automaticamente, mas se aluno mandou anexo de outro lugar, pode dar erro. Investigar.
+- **`.env` não tá em `.gitignore`:** falha catastrófica se aluno commitar. Sempre validar antes de salvar chave.
+- **Aluno fica preso na criação da conta OpenAI:** link direto + screenshot do botão "Create new secret key" ajuda. Próxima versão: incluir screenshot inline.
+
+## Aplicação dos princípios defensivos
+
+Esta skill herda os princípios universais da `onboarding-checklist`. Ver: [`../onboarding-checklist/references/principios-defensivos.md`](../onboarding-checklist/references/principios-defensivos.md).
+
+### Aplicação específica
+
+- **Princípio 1 (backup antes de sobrescrever):** se `.env` já existe, faz backup timestamped antes de adicionar/modificar `OPENAI_API_KEY`.
+- **Princípio 2 (confirmação humana):** pede confirmação antes de salvar a chave no `.env` ("Vou salvar essa chave em ~/.env como OPENAI_API_KEY. Confirma?").
+- **Princípio 4 (narrar antes de fazer):** explica o que vai acontecer (gerar chave OpenAI, custo, smoke test) antes de pedir aluno fazer.
+- **Princípio 5 (atualizar MEMORY ao concluir):** marca `whisper_configured=true` ou `whisper_skipped=true`.
+- **Princípio 9 (parar se algo der errado):** se chave falhar validação 3x seguidas, parar e oferecer ajuda do grupo (não fica num loop infinito).
+- **Princípio 11 (detectar antes de pedir):** lê `.env` primeiro. Se já tem chave válida, NÃO pede de novo. Apenas valida e segue pro smoke test.
+- **Princípio ".env first":** chave OpenAI segue padrão universal (nome canônico `OPENAI_API_KEY`, leitura prioritária do `.env`).
+
+## Modo A vs Modo B (apresentação)
+
+A lógica é a mesma. Só muda o jeito de apresentar:
+
+**Modo A (aula-por-aula):**
+```
+"Bora pro Módulo 0 — Whisper.
+A aula correspondente é a A0 (Visão geral + créditos OpenAI).
+Recomendo assistir antes pra entender por que a OpenAI cobra
+diferente pra OAuth e API."
+[segue fluxo]
+```
+
+**Modo B (wizard direto):**
+```
+"Antes da gente começar, uma coisa rápida que destrava você:
+áudio. Posso configurar pra você mandar áudio em vez de digitar?"
+[segue fluxo conversacional, sem mencionar passo/aula]
+```
+
+Por baixo, mesmo fluxo de detecção/validação/salvamento/smoke test.
+
+## Comando "exemplo" neste contexto
+
+Se aluno pedir "exemplo" durante esse wizard, NÃO tem template Amora correspondente (chave API é só código). Resposta padrão:
+
+```
+"Pra esse passo não tenho exemplo do Bruno — chave OpenAI é só
+código numérico, não tem 'jeito' de fazer.
+
+Se você travou em algo específico (não sabe onde clicar, conta nova,
+cartão), me conta o que tá pegando que eu te ajudo."
+```
+
+## Referências
+
+### Internas
+- Princípios universais: [`../onboarding-checklist/references/principios-defensivos.md`](../onboarding-checklist/references/principios-defensivos.md) (Princípios 1, 2, 4, 5, 9, 11)
+- Comando "pulo": [`../onboarding-checklist/references/comandos-canonicos.md`](../onboarding-checklist/references/comandos-canonicos.md) (comando 2)
+- Pergunta-âncora padrão: [`../onboarding-checklist/references/mapa-aulas.md`](../onboarding-checklist/references/mapa-aulas.md) (passo 0)
+
+### Externas
+- OpenAI API keys: https://platform.openai.com/api-keys
+- OpenAI billing: https://platform.openai.com/billing
+- OpenAI Whisper docs: https://platform.openai.com/docs/guides/speech-to-text
+- Custos Whisper: $0.006/min de áudio (~R$3 por 100min — uso pessoal médio)
+
+## Status
+
+✅ ATIVO desde v1 do Starter Kit (02/05/2026).
+
+## Roadmap
+
+- v1.1: Screenshot inline mostrando exatamente onde clicar em platform.openai.com (reduz fricção de aluno leigo)
+- v1.2: Smoke test multi-idioma (validar que aluno em PT-BR funciona perfeito)
+- v1.3: Detecção de saldo OpenAI restante (pré-aviso quando aluno tá com $1 de crédito)
+- v2: Suporte alternativo a Groq Whisper (gratuito, rate-limited) pra aluno sem cartão