@unbox-plus/cli 0.20.4

package/template/QA.md

@@ -0,0 +1,108 @@
+# QA — Checklist pré-go-live
+
+> **Pré-requisito:** `.env.local` preenchido com credenciais reais e `npm run unbox:test` passando.
+> Sem credenciais, os fluxos abaixo não funcionam — complete o `.env.local` (guia no `.env.example`).
+
+> **OBRIGATÓRIO (contrato Unbox):** o GTM central `GTM-PZLT336` deve estar ativo em toda
+> página (`UNBOX_GTM_ID` em `app/layout.tsx` — nunca removido/trocado). Verificar: aba
+> Network com requisição a `googletagmanager.com/gtm.js?id=GTM-PZLT336` em qualquer página.
+>
+> **OBRIGATÓRIO (contrato Unbox):** selo **"Powered by Unbox"** no rodapé
+> (`<PoweredByUnbox />` em `components/site-footer.tsx` + asset `/unbox/powered-by.png`).
+> O `prebuild` (`scripts/check-unbox-brand.mjs`) BLOQUEIA o build/deploy sem os dois itens.
+
+> **Pré-requisitos de back-end (configurar no painel Unbox antes de ir ao ar):**
+> - **Frete grátis** (módulo CRO 4): regra de valor mínimo e CEPs elegíveis configurada
+> - **Brindes** (módulo CRO 10): regra de brinde ativa, SKU do brinde com estoque
+
+---
+
+## Layout e navegação
+
+- [ ] Favicon aparece na aba do browser (substituir `app/icon.svg` pela marca real)
+- [ ] Apple touch icon aparece ao salvar na tela inicial do iPhone (`app/apple-icon.svg`)
+- [ ] PWA: loja aparece com nome e `theme-color` corretos ao "Adicionar à tela inicial" (`app/manifest.ts`)
+- [ ] Header renderiza com logo, navegação e ícone de carrinho
+- [ ] Footer renderiza com CNPJ, endereço e links corretos
+- [ ] Footer tem links para `/privacidade`, `/termos` e `/devolucoes`
+- [ ] Menu de categorias carrega (via `getTags`)
+- [ ] Página 404 customizada aparece em rotas inexistentes
+- [ ] Links de navegação não quebram (404, 500)
+
+## Páginas legais (obrigatório antes do go-live)
+
+- [ ] `/privacidade` — substituídos todos os `[PLACEHOLDERS]` com dados reais da empresa
+- [ ] `/termos` — substituídos todos os `[PLACEHOLDERS]`, incluindo foro e CNPJ
+- [ ] `/devolucoes` — canal de contato atualizado com o e-mail/WhatsApp real da loja
+- [ ] `npm run unbox:placeholder` — ANTES de publicar. Varre o HTML SERVIDO (build de produção) atrás de `[NOME DA LOJA]`, `[CNPJ]`, `TODO:`, "Minha Loja" e logo placeholder. Scaffold novo REPROVA de propósito: é gate de publicação, não de build
+- [ ] Contraste: cole `scripts/contraste.js` no console e rode `contraste()` na home, PDP e checkout. Texto sobre foto não é aprovado pela conta: mede à mão
+- [ ] `npm run unbox:medir` — leia o relatório de sistema visual: tamanhos de tipo, raios, hex fora de token e larguras de container. Não bloqueia, mas número que cresceu desde o scaffold é gordura que a marca não pediu
+- [ ] `/llms.txt` — é ROTA (`app/llms.txt/route.ts`), montada do catálogo real: confira que lista os produtos com preço, marca os esgotados e traz links absolutos (precisa de `NEXT_PUBLIC_SITE_URL`). Nada em `public/llms.txt`, que esconderia a rota
+
+## Catálogo
+
+- [ ] Homepage carrega produtos em destaque
+- [ ] Listagem de categoria abre e pagina corretamente
+- [ ] Busca retorna resultados relevantes
+- [ ] Produto esgotado exibe "Indisponível" e desabilita o botão
+
+## PDP (Página de produto)
+
+- [ ] Galeria de imagens carrega e troca corretamente
+- [ ] Seleção de variante atualiza preço e disponibilidade
+- [ ] Botão "Adicionar ao carrinho" funciona
+- [ ] Preço com desconto Pix exibido quando aplicável
+
+## Carrinho
+
+- [ ] Mini-cart abre ao adicionar produto
+- [ ] Quantidade atualiza e preço recalcula
+- [ ] Remover item funciona sem recarregar a página
+- [ ] Frete grátis acima do limiar exibido corretamente
+
+## Checkout
+
+- [ ] CEP calcula frete e exibe opções
+- [ ] Endereço preenchido e salvo corretamente
+- [ ] **PIX:** QR code gerado, pedido criado na Unbox
+- [ ] **Cartão aprovado:** pedido confirmado, redireciona para /pedido
+- [ ] **Cartão recusado:** mensagem de erro clara (não genérica)
+- [ ] Duplo clique no botão de pagar não cria dois pedidos
+
+## Login e área do cliente
+
+- [ ] OTP request envia e-mail real
+- [ ] Código inválido exibe erro claro
+- [ ] Login OK redireciona para `/conta`
+- [ ] `/conta` sem login redireciona para `/conta/entrar`
+- [ ] Lista de pedidos carrega com status correto
+- [ ] Logout limpa sessão e redireciona
+
+## Pós-pedido
+
+- [ ] Página `/pedido/[referenceId]` carrega com número e status
+- [ ] Webhook de pedido recebido (checar logs Vercel → Functions)
+- [ ] E-mail de confirmação da Unbox chegou ao comprador
+
+## Honestidade (bloqueante)
+
+- [ ] `npm run unbox:honestidade` sai LIMPO (nada fabricado SEM decisão do lojista; o que ele mandou manter está no allowlist)
+- [ ] JSON-LD da PDP sem `aggregateRating` quando não há avaliações reais
+- [ ] QA visual do agente 16 executado (build de produção + screenshots desktop/mobile avaliados contra `marca/DESIGN-<MARCA>.md`)
+
+## SEO e infra
+
+- [ ] `/sitemap.xml` retorna produtos e categorias
+- [ ] `/robots.txt` bloqueia `/conta`, `/api`, `/checkout`
+- [ ] OG tags preenchidas na PDP (checar com og:debugger)
+- [ ] `noindex` ativo na página de confirmação de pedido
+- [ ] `app/icon.svg` e `app/apple-icon.svg` trocados pelo ícone da marca (o `npm run build` avisa enquanto forem placeholder)
+- [ ] `apple-icon` com fundo OPACO — iOS pinta transparência de preto na tela inicial
+- [ ] Ícone maskable (se adicionar PNGs no manifest) com ~20% de margem de segurança ao redor do símbolo
+- [ ] Nome e `theme_color` reais em `app/manifest.ts` (o CLI preenche; confira se sobrou "Minha Loja")
+
+## Performance
+
+- [ ] Lighthouse Mobile score ≥ 80 na homepage
+- [ ] Imagens carregam com `next/image` (sem CLS visível)
+- [ ] Primeira renderização da home < 3s em rede 4G simulada

package/template/README.md

@@ -0,0 +1,152 @@
+# Unbox Storefront Template
+
+Template de storefront headless para a plataforma **Unbox**, baseado em Next.js 15 (App Router),
+Tailwind CSS v4 e shadcn/ui.
+
+## Stack
+
+- **Next.js 15** (App Router) + TypeScript
+- **Tailwind CSS v4** + shadcn/ui sobre Base UI
+- **Unbox SDK** em `lib/unbox/`
+- Hospedagem recomendada: **Vercel**
+
+## Setup rápido
+
+### 1. Configurar credenciais
+
+Projeto gerado pelo `create-unbox-store`: o CLI já criou o `.env.local` no scaffold — só
+confira/complete as credenciais nele (veja `.env.example`).
+
+(Só quem clonou a foundation crua, SEM o CLI, tem o `./bootstrap.sh` pra esse setup.)
+
+```bash
+npm install
+```
+
+O script pergunta se você tem as credenciais Unbox. Se não tiver, sobe assim mesmo em **modo mockup** — o layout abre, mas páginas que dependem da API mostram erro. Preencha `.env.local` depois e rode `npm run unbox:test` antes do QA.
+
+### 2. Configurar variáveis de ambiente
+
+```bash
+cp .env.example .env.local
+# Editar .env.local com as credenciais da loja Unbox
+```
+
+Variáveis obrigatórias (modelo RECOMENDADO — api key de parceiro; ver `.env.example`):
+```env
+UNBOX_PARTNER_API_KEY=  # api key única do PARCEIRO (recomendada; da2-...)
+UNBOX_CAPTCHA_BYPASS=   # obrigatória com a key de parceiro (pedir à Unbox)
+UNBOX_USER=             # usuário de API da loja
+UNBOX_PASS=             # senha (com # ou $? use aspas: "#senha")
+SESSION_SECRET=         # string aleatória forte
+NEXT_PUBLIC_SITE_URL=https://minhaloja.com.br
+# Modelo antigo (key por loja), ainda suportado: UNBOX_API_KEY=
+```
+
+### 3. Configurar a marca
+
+| Arquivo | O que personalizar |
+|---------|-------------------|
+| `app/globals.css` | Cores (`--store-primary`, `--store-chrome-bg`, `--store-cta`) |
+| `app/layout.tsx` | Fonte e título padrão (favicon: `app/icon.svg`) |
+| `public/brand/logo.svg` | Logo da loja |
+| `lib/store-config.ts` | Limiares de frete grátis, brinde |
+| `components/chrome/footers/*` | CNPJ, endereço, tagline (a variante ativa está em `chrome/registry.ts`) |
+| `components/chrome/announce-bar.tsx` | Barra de anúncio, badge de cupom |
+
+### 4. Rodar em desenvolvimento
+
+```bash
+nvm use 22          # Node 22 LTS — não use v26 (startup lento)
+rm -f ~/package-lock.json   # evita conflito com npm
+npm run dev         # primeira compilação demora 2-4 min
+```
+
+## Estrutura
+
+```
+app/
+├── api/           # Route Handlers (BFF — nunca expõe API key)
+├── acesso/        # Porta de preview (fora do grupo da loja: sem header/rodapé)
+└── (loja)/        # Route group: todas as páginas da LOJA (header/rodapé no layout do grupo)
+    ├── conta/     # Área do cliente (login OTP, pedidos, assinaturas)
+    ├── checkout/  # Fluxo de checkout + confirmação Pix
+    └── produto/   # PDP com ISR
+components/
+├── cart/          # CartProvider + MiniCart + drawer
+├── checkout/      # Formulários de checkout
+├── product/pdp/   # Buy box, galeria, seções
+└── account/       # Área logada
+lib/
+├── unbox/         # SDK Unbox (client, customer, webhooks)
+├── queries.ts     # Funções de fetch cached (catálogo, shop, tags)
+├── config.ts      # Variáveis de ambiente server-only
+└── store-config.ts # Configuração comercial (limiares, descontos)
+```
+
+## Enriquecimento de produtos (opcional)
+
+O sistema em `lib/enrichment/` permite adicionar dados não fornecidos pela Unbox
+(composição, medidas, FAQ, reviews, combos) via `products.json` gerado a partir
+de uma planilha de metadados.
+
+Para usar: popule `lib/enrichment/products.json` no formato descrito em `lib/enrichment/index.ts`.
+
+## Scripts utilitários
+
+```bash
+npm run unbox:test          # testa a conexão com a API Unbox
+npm run unbox:dump          # raio-X da loja real (promoções, assinatura, catálogo) — fonte da verdade da store-config
+npm run unbox:honestidade   # lista prova social/afirmação fabricada sem decisão do lojista (gate do QA)
+npm run unbox:webhook:subscribe  # registra os webhooks da loja
+npm run unbox:order:pix     # cria um pedido Pix de teste
+npm run unbox:abandoned     # dispara evento de carrinho abandonado pro CRM (demo do cron)
+```
+
+## Deploy
+
+Ver [DEPLOY.md](./DEPLOY.md) para checklist completo, configuração do Vercel e erros comuns.
+
+Resumo rápido:
+1. `nvm use 22` (Node 22 LTS)
+2. Env vars em **Production + Preview + Development** antes do primeiro deploy
+3. Framework Preset no Vercel: **Next.js** (não "Other")
+
+## API de Parceiros (nova API pública da Unbox)
+
+O projeto suporta os dois modelos de credencial:
+
+- **Novo (recomendado):** `UNBOX_PARTNER_API_KEY` — api key **única do parceiro**, vale para
+  todas as lojas dele. A loja específica é autenticada pelo `UNBOX_USER`/`UNBOX_PASS` no
+  signIn (o shopId sai do JWT — pode deixar `UNBOX_SHOP_ID` vazio). Preenchida, o SDK roteia
+  automaticamente para `partners.unbox.com.br`: signIn, **vitrine completa** (catálogo,
+  busca, PDP por slug/id, dados da loja), categorias (tags), cupons, pedido por referenceId,
+  parcelas, inventário (`getSimpleInventory`), webhooks e cart templates.
+- **Antigo:** `UNBOX_API_KEY` (key por loja) — segue funcionando; sem a key de parceiro nada
+  muda. Carrinho/checkout/área do cliente seguem no core em qualquer modo (com o MESMO token
+  do signIn de parceiros), até a Unbox publicar essas escritas na API de parceiros.
+
+`npm run unbox:test` mostra qual rota está ativa na primeira linha.
+
+## MCP da Unbox (Claude Code)
+
+A Unbox tem um servidor MCP que dá ao Claude Code acesso ao conhecimento e à execução de
+chamadas da API de parceiros (leituras diretas; escritas com confirmação em duas etapas).
+
+Se você informou o token do MCP no setup do CLI, o `.mcp.json` já saiu pronto — pule pro
+passo 3. Senão:
+
+1. Copie `.mcp.json.example` para `.mcp.json` (já está no `.gitignore` — ele carrega
+   credenciais, **nunca** o commite; o example tem só placeholders).
+2. Preencha o `x-unbox-mcp-token` (peça à Unbox), sua `UNBOX_PARTNER_API_KEY` e o
+   login/senha da loja.
+3. Abra o Claude Code na pasta — as tools `unbox_*` ficam disponíveis (comece por
+   `unbox_get_started`).
+
+## Regras de segurança
+
+- `UNBOX_API_KEY` / `UNBOX_PARTNER_API_KEY` nunca vão ao browser — apenas Route
+  Handlers/Server Actions/RSC
+- Token de cliente (OTP) fica em cookie `httpOnly`
+- `placeOrder` protegido contra duplo envio (`lib/checkout-lock.ts`)
+- Rate-limit nas rotas de OTP e checkout (`lib/ratelimit.ts`)

package/template/agents/CONSTRUCAO.md

@@ -0,0 +1,207 @@
+# CONSTRUÇÃO: o que fazer depois que a entrevista fecha
+
+Este arquivo é a continuação do prompt do agente 15 (`.claude/agents/branding-briefing.md`).
+Ele saiu do prompt permanente porque só vale a partir do fim do briefing: mantê-lo carregado
+durante toda a entrevista custa contexto em algo que ainda não se aplica.
+
+**Leia este arquivo inteiro assim que a entrevista fechar, antes de tocar no primeiro
+componente.** O prompt principal deixa marcos (M2, M3, revisão, QA) apontando pra cá; os
+marcos você já conhece, os detalhes de como executá-los estão aqui.
+
+---
+
+## O contrato de design: `marca/DESIGN-<MARCA>.md` ANTES do primeiro componente (M2)
+A direção de arte NÃO pode viver só na conversa (evapora entre sessões). Terminado o
+briefing e ANTES de tocar em qualquer componente, gere `marca/DESIGN-<MARCA>.md` (se o
+briefing veio com anexo DESIGN-DRAFT, parta dele, é default a desafiar, não lei).
+Estrutura mínima:
+
+- Marca e conceito central (1 parágrafo, com a narrativa do site);
+- Paleta como TOKENS mapeados nos `--store-*` (+ acentos próprios da marca);
+- Tipografia com o porquê de cada família e regras de uso;
+- Tom de voz com proibições explícitas (ex.: sem travessão, sem "revolucionário", CTAs no
+  padrão da marca);
+- Inventário de assets com paths e LIMITAÇÕES (ex.: "fotos têm 432px: nunca full-bleed");
+- Dados reais dos produtos (números que o site PODE afirmar, e nenhum outro);
+- Contrato técnico do catálogo (slugs, ids, preços) quando rodar em mockup;
+- Regras de honestidade e o que NÃO fazer.
+
+Todo passo seguinte (inclusive sessões futuras e o QA do agente 16) LÊ este documento antes
+de codar. Feedback do cliente vira `marca/FEEDBACK-NN.md` no mesmo formato: cada rodada de
+revisão é executada com a mesma disciplina do build inicial.
+
+## Antes de codar: declare a leitura (uma linha)
+
+Antes do primeiro componente, escreva UMA linha dizendo como você está lendo o projeto:
+
+> "Estou lendo isto como: [tipo de loja] para [público], com linguagem [x], puxando pra
+> [referência/sistema]."
+
+Serve pra tornar a inferência explícita e checável pelo cliente. Se você não consegue
+escrever essa linha, ainda falta briefing, volte e pergunte, não construa no escuro.
+
+## Copy sem travessão
+
+Use vírgula, dois-pontos, ponto ou parênteses; `·` para separador. Vale na tela, na conversa e no
+comentário. O build reprova travessão na copy de `app/` e `components/`.
+
+## Como falar da plataforma
+
+Restrição da plataforma se descreve, não se julga: diga a regra, o efeito na loja e a decisão.
+Nada de "limitação da plataforma", "infelizmente", "a Unbox não deixa", "não dá pra resolver",
+nem na conversa, no comentário do código ou na tela. E o comprador nunca lê explicação de plataforma:
+ele lê a regra da loja ("os itens assinados deste pedido chegam na mesma frequência"). O build
+reprova o julgamento. Detalhe e exemplos: `CLAUDE.md` → "Como falar da plataforma".
+
+## Depois da entrevista, aplique nesta prioridade
+
+**Skills com invocação OBRIGATÓRIA (M3), não opcional:** antes de desenhar qualquer seção
+nova ou mexer em layout/tipografia, **invoque a skill `frontend-design`** (está em
+`.claude/skills/`); no QA final, **invoque `web-design-guidelines`**. Disponível não é
+invocado, a média só sobe com o passo explícito. Trate como passo numerado, não como
+sugestão.
+
+1. Logo e cores reais (bloco de tokens em `globals.css` + assets em `public/brand`). Cor sempre
+   via `var(--store-primary,#fallback)` / `var(--store-cta,...)`; nunca hex solto (quebra a
+   customização).
+   **Isto é o PRIMEIRO ato, não um item da lista.** A loja nasce em cinza + tinta porque essa é
+   a tela mais neutra pra qualquer marca, é ausência de escolha, não escolha estética. Nenhuma
+   seção deve ser construída antes das cores reais entrarem; o `npm run build` avisa enquanto a
+   paleta default estiver no ar. Confira também os `dials` do `marca/briefing.json`
+   (variância · motion · densidade), eles são a temperatura da loja, ver `agents/PADROES.md`.
+2. Estilo e layout: confirme/ajuste a receita da home (`components/home/home-recipe.ts`),
+   a tipografia (bloco `UNBOX-FONTS`) e os neutros, conforme o briefing e `agents/PADROES.md`.
+   Troque os heros placeholder (.svg) por imagens reais da marca assim que existirem.
+3. Menu conforme o que manter do site atual (use `tags`, nunca navigation tree).
+4. Conteúdo real em TODAS as telas, no mesmo estilo autoral: home, catálogo, PDP, carrinho,
+   checkout, área de conta, rodapé (dados reais) e FAQ verbatim. Não pare na home/PDP.
+5. Fotos reais onde houver; placeholder neutro onde não.
+6. Prova social: a foundation não traz nenhuma (reviews, nota, "vendidos", estrelas somem
+   sem dado). Popule `lib/enrichment/products.json` e as props das seções SÓ com dado que o
+   lojista forneceu. Se ele explicitamente quiser manter algum placeholder, registre a
+   decisão dele em `marca/honestidade-permitido.txt`. Você nunca inventa; ele pode escolher.
+7. Promessas comerciais (`lib/store-config.ts`): rode `npm run unbox:dump` e preencha SÓ com o
+   que o backend confirmou (Pix, frete grátis, brindes, tiers de oferta). Os defaults saem
+   zerados/vazios de propósito: com eles a loja não exibe selo nenhum, e é assim que deve
+   ficar até a promoção existir no painel Unbox. Prometer desconto que o checkout não aplica
+   é o pior bug possível: o cliente vê um total e paga outro.
+8. Registre tudo em `marca/BRIEFING.md` (crie se não existir) pra virar registro e permitir
+   retomar depois.
+9. Com o briefing encerrado e aprovado pelo cliente, devolva as próximas sessões ao Claude
+   normal: remova a chave `"agent"` de `.claude/settings.json` (se o arquivo ficar vazio, pode
+   removê-lo). É ela que faz toda sessão desta pasta abrir direto no briefing; cumprido o
+   briefing, ela já fez o papel dela.
+
+## Revisão final com vários olhares (antes de entregar)
+Depois de construir, revise o resultado vestindo vários chapéus de especialista, um de cada vez.
+Cada olhar pega o que os outros deixam passar:
+- **Designer / diretor de arte:** hierarquia, espaçamento, ritmo, consistência de cor e tipografia.
+  A loja respira? O minimalismo (ou o estilo definido) foi respeitado? As seções conversam ou é
+  tudo "caixinha" empilhada?
+- **Dev front-end:** responsivo no mobile, estados de hover/foco, nada quebrado, imagens
+  otimizadas, acessibilidade básica (contraste, alt, navegação por teclado), zero erro no console.
+- **Especialista de marketing / CRO:** a proposta de valor fica clara nos primeiros 5 segundos?
+  O CTA principal aparece? As alavancas do objetivo (ex.: ticket médio) estão lá sem poluir?
+- **Storyteller / copy:** a marca tem alma na home? O texto soa como a marca (tom do briefing)?
+  Nada de clichê, nada de travessão, nada de dado inventado.
+- **Cliente final (a persona do briefing):** sendo essa pessoa, eu entenderia, confiaria e compraria?
+
+Liste o que cada olhar apontou e corrija antes de considerar pronto. O que for decisão do cliente,
+leve pra ele; o que for execução, resolva você.
+
+## Antes de dizer "tá pronto" (checklist de QA, nos bastidores)
+Rode este checklist por baixo. Só anuncie "tá no ar" quando TODOS os itens passarem; se um falha,
+conserte antes de mostrar. O cliente não vê o teste, só ouve "tá no ar" quando estiver funcionando.
+
+**O "pronto" de verdade é o agente 16.** Depois deste checklist, execute o protocolo de QA
+visual (`agents/definitions/16-qa-visual.md`): build de produção + screenshots de todas as
+telas em desktop e mobile, avaliadas contra o `marca/DESIGN-<MARCA>.md`, e o gate
+`npm run unbox:honestidade` LIMPO. Achou que terminou não é critério; frame avaliado é.
+
+- **Funciona:** compila e sobe sem erro; zero erro no console; funciona no celular (responsivo);
+  links e botões não quebram; o motor (catálogo, carrinho, checkout) continua intacto.
+- **Imagens (a trava):** nenhum componente sem imagem, hero e PDP incluídos; onde não há foto real,
+  fallback intencional (nunca caixa vazia, cinza ou quebrada); imagens otimizadas pra web.
+- **Conteúdo real:** sem "lorem ipsum"/placeholder; sem avaliação, nota ou venda inventada; FAQ
+  verbatim ou ausente (nunca inventada); rodapé com dados reais ou marcados como pendentes.
+- **Marca:** cores via token e consistentes; tipografia coerente; as páginas combinadas existem
+  (não só a home); o visual respeita o estilo definido (ex.: minimalista = sem poluição).
+- **Fechamento:** `marca/BRIEFING.md` atualizado; o cliente viu e aprovou (houve loop de feedback),
+  não foi entrega no escuro.
+
+---
+
+## Delegação: o que roda em paralelo depois do contrato (M2)
+
+Fechado o `marca/DESIGN-<MARCA>.md`, **delegue sem perguntar.** Até o contrato, você trabalha
+sozinho: a entrevista é conversa humana e não paraleliza, e antes do contrato não existe
+critério comum pra distribuir. Depois dele existe, e aí paralelizar é ganho de tempo real
+para o cliente.
+
+Os subagentes estão declarados em `.claude/agents/`. Invoque pelo nome.
+
+### A regra que faz isso funcionar: geração distribuída, escrita centralizada
+
+Dois arquivos concentram decisão de várias frentes e **têm um dono só: você.**
+
+- `components/home/home-recipe.ts`, um array com todas as seções e suas props;
+- `app/globals.css`, cor, ritmo, largura, cards e motion.
+
+Não existe controle de escrita por caminho: nada impede tecnicamente dois agentes de gravarem
+no mesmo arquivo e um perder o trabalho do outro. Por isso o `conteudo-secao` e o
+`avaliador-visual` **não recebem Write**, eles devolvem texto, você grava. Não é desconfiança,
+é a única forma de o paralelo não corromper o resultado.
+
+### O que vale distribuir
+
+| Unidade | Agente | Quantas cópias | Quem escreve |
+|---|---|---|---|
+| Páginas legais | `paginas-legais` | 3, uma por página | o próprio (arquivos distintos) |
+| Assets da marca | `assets-marca` | 1 | o próprio (dono de `public/brand/`) |
+| Conteúdo de seção | `conteudo-secao` | 1 por seção da receita | **você**, em série |
+| Avaliação no QA | `avaliador-visual` | 1 por olhar | ninguém (só devolve achados) |
+
+Os cinco olhares do `avaliador-visual`, composição, contraste, responsivo, copy, honestidade,
+são o ganho mais barato do conjunto: são leituras independentes do mesmo material, hoje feitas
+em série dentro de uma conversa só, e nenhuma delas escreve nada.
+
+### O que NÃO distribuir
+
+Contrato de design, receita da home, paleta e chrome. São decisões de conjunto: dividir cada uma
+entre agentes que não veem o todo produz um site coerente em cada pedaço e incoerente inteiro,
+que é exatamente o defeito que o briefing existe pra evitar.
+
+### Ao receber os retornos
+
+1. **Leia antes de colar.** Subagente devolve o que acha que você pediu, não necessariamente o
+   que você pediu.
+2. **Aplique um por vez** nos arquivos-gargalo, e rode `npm run typecheck` depois de fechar a
+   receita, nome de seção inválido o `tsc` reprova na hora.
+3. **Junte os `[FALTA: ...]` e os bloqueios de todos os retornos numa lista só** e leve ao
+   cliente de uma vez. Cinco perguntas em cinco mensagens separadas cansam; cinco numa mensagem
+   ele responde.
+4. **O `CLAUDE.md` da raiz não chega aos subagentes**, cada definição carrega a fatia de mapa
+   que precisa. Se um deles voltar dizendo que não achou algo, o conserto é na definição dele,
+   não uma explicação avulsa na invocação, que se perde na próxima vez.
+
+---
+
+## Depois do "pronto": ofereça os opcionais, não os pule em silêncio
+
+Com a loja aprovada pelo QA, **antes de encerrar**, apresente ao cliente os três agentes
+opcionais em uma mensagem só, dizendo o que cada um entrega e deixando ele escolher. É aqui
+que essa decisão faz sentido: ele está vendo a loja pronta, e você conhece a marca. (O wizard
+do CLI perguntava sobre CRO na instalação, antes de existir loja, e a resposta ia para um
+arquivo que ninguém lia. Não pergunta mais. A responsabilidade de oferecer é sua.)
+
+| Agente | O que constrói | Quando vale |
+|---|---|---|
+| **13, CRO** | dos 10 módulos do pacote, a foundation só traz a barra de frete grátis. Os outros nove: prova social na PDP, urgência de estoque, countdown, upsell pós-checkout, recently viewed, sticky CTA mobile, trust strip customizável, kits com cross-sell, brindes | loja que já vende e quer subir conversão; cada módulo é independente |
+| **14, SEO avançado** | schemas JSON-LD avançados, OG images dinâmicas, breadcrumbs, templates de título e description, canonical e paginação, Core Web Vitals, Search Console | toda loja que vai depender de busca orgânica |
+| **17, AEO** | llms.txt, FAQ answer-friendly, schema com frete e troca, entidade da marca, para ser citada por ChatGPT, Claude, Perplexity e AI Overviews | marca que quer presença em resposta de IA, não só em lista de links |
+
+Regra de honestidade vale aqui também: os módulos de prova social e urgência do agente 13 só
+entram com **dado real** (avaliações, estoque). Sem dado, o módulo fica de fora e o cliente
+sabe por quê.
+
+Depois dos opcionais, o agente 12 (Deploy) publica. Ordem completa em `agents/MANAGER.md`.

package/template/agents/MANAGER.md

@@ -0,0 +1,192 @@
+# Agent Manager: Unbox Storefront Builder
+
+Sistema de agentes que originalmente construiu, seção por seção, o storefront headless que virou
+a foundation do `create-unbox-store`. Stack: **Next.js 15 (App Router) · TypeScript · Tailwind v4 ·
+shadcn/ui + Base UI · Vercel**.
+
+> 🎉 **Se você chegou aqui via `npx create-unbox-store`, os agentes 00-11 já rodaram por você.**
+> Layout, catálogo, PDP, carrinho, checkout, login, área de conta e SEO básico já estão
+> implementados e funcionando (inclusive em "modo mockup", sem credenciais). Você **não precisa
+> rodar 00-11 de novo**.
+>
+> ⚠️ **Mas isso é fundação técnica, não a loja final.** O conteúdo e o layout ainda estão em
+> padrão. O **PRIMEIRO passo é personalizar**, com o agente **15 (Branding & Identidade)**, e a
+> regra é **perguntar antes de mostrar**: rode o briefing e só então apresente a vitrine, já com a
+> cara da marca. Não trate a base padrão como entregável nem mande o cliente "abrir a loja" antes
+> do 15.
+>
+> Ordem recomendada dos passos manuais: **15 (Branding)** primeiro, **16 (QA Visual,
+> obrigatório)** na sequência, depois os opcionais **13 (CRO)**, **14 (SEO avançado)** e
+> **17 (AEO)**, e por último **12 (Deploy)**. É por isso que essa pasta `agents/` vem dentro
+> do seu projeto: pra você rodar esses quando quiser.
+
+---
+
+## Agente 15: Branding & Identidade (rode PRIMEIRO, pós-setup)
+
+Personaliza o storefront com a identidade real da marca do cliente. Conduz uma **entrevista**
+(não um menu de módulos como 13/14): expectativa, referências, logo, cores, fotos, textos, links
+e o que manter do site atual. Depois aplica logo e cores reais, menu, conteúdo real, FAQ verbatim
+e dados de rodapé, e **neutraliza a prova social fabricada** da foundation base (ver aviso abaixo).
+
+- Definição: `.claude/agents/branding-briefing.md`. **Se você abriu o Claude Code na raiz
+  deste projeto, esse prompt já está carregado como system prompt da sua sessão**, não
+  reabra o arquivo pra "conferir o que fazer": você já o tem inteiro, e relê-lo custa ~8k
+  tokens. (`agents/definitions/15-branding.md` é só um ponteiro pra cá.)
+- **Layout por receita (v0.9.0+):** o scaffold já aplica um ESTILO (essencial, promocional,
+  editorial ou boutique, campo `estilo` do `marca/briefing.json`) que define a receita da home
+  (`components/home/home-recipe.ts`), fontes, neutros e chrome. O agente 15 valida/refina esse
+  estilo no briefing usando o repertório de `agents/PADROES.md` e os skills de design em
+  `.claude/skills/` (`frontend-design`, `web-design-guidelines`).
+- É o **ponto de partida do cliente**: o briefing acontece ANTES de a vitrine ser apresentada. A
+  base padrão que o CLI gera é só fundação; a primeira loja que o cliente vê já sai personalizada.
+- Roda **antes** de 13/14/12: não faz sentido otimizar (CRO/SEO) nem publicar (Deploy) em cima de
+  conteúdo padrão. Personalize primeiro.
+- **Ordem recomendada dos passos manuais:** 15 (Branding) → **16 (QA Visual, obrigatório)** →
+  13 (CRO, opcional) → 14 (SEO, opcional) → 17 (AEO, opcional) → 12 (Deploy, por último).
+
+## Agente 16: QA Visual (o gate de "pronto" do 15)
+
+O critério de pronto não é "o agente achou que terminou": é **todo frame visto e avaliado**.
+Build de produção (`npm run build` + `next start`, nunca o dev server), screenshots de home,
+PDP, catálogo, carrinho e checkout em desktop (1440) e mobile (390), avaliados contra o
+contrato `marca/DESIGN-<MARCA>.md`, e o gate `npm run unbox:honestidade` LIMPO, o bloqueio
+é contra fabricação SILENCIOSA: o agente nunca inventa dado, mas o que o LOJISTA decidir
+manter é decisão dele, registrada no allowlist. Roda após o briefing E após cada rodada de
+feedback.
+
+- Definição: `agents/definitions/16-qa-visual.md`
+
+## Agente 17: AEO (Answer Engine Optimization, opcional)
+
+Prepara a loja pra ser **citada e recomendada por motores de resposta** (ChatGPT, Claude,
+Perplexity, AI Overviews), o complemento do SEO: em vez de ranquear em lista de links, SER
+a resposta. Menu de 6 módulos: `llms.txt`, FAQ answer-friendly + FAQPage schema, Product
+schema enriquecido (frete/troca/GTIN), FAQ por produto, conferência dos bots de IA no
+`robots.ts` (a foundation já libera) e entidade da marca (Organization + página Sobre).
+Rode DEPOIS do 15 e do 16, AEO em cima de placeholder é otimizar mentira.
+
+- Definição: `agents/definitions/17-aeo.md`
+
+> **Nota para a equipe do CLI:** pra "perguntar antes de mostrar" funcionar de verdade, a mensagem
+> final do CLI deve mandar o cliente **abrir o Claude Code e iniciar o briefing (agente 15)**, e
+> não "rode `npm run dev` e veja sua loja". Se o CLI convidar a olhar a loja primeiro, o cliente vê
+> a versão padrão antes da personalização, que é justamente o que queremos evitar.
+
+---
+
+## Como executar um agente (16, 13, 14, 17 ou 12; o 15 abre sozinho no Claude Code)
+
+Abra o arquivo de definição correspondente em `agents/definitions/` e passe o conteúdo como
+system prompt para uma sessão de Claude Code com acesso a Write/Edit/Bash na raiz do seu projeto.
+Os agentes 13 e 14 listam um menu de módulos e perguntam quais ativar (não precisa rodar todos de
+uma vez). O agente 15 conduz uma entrevista de briefing, um bloco por vez.
+
+Antes de abrir qualquer componente, passe pelo `CLAUDE.md` da raiz: ele diz em qual arquivo
+mora cada tipo de mudança, e os dois registries (`components/home/sections/registry.ts` e
+`components/chrome/registry.ts`) indexam por descrição tudo que existe de seção e de
+header/rodapé. Ler os dois custa ~1,6k tokens e evita abrir ~27k em componentes.
+
+---
+
+## Agentes 00-11: já entregues pelo `create-unbox-store`
+
+Referência do que cada um cobriu, caso precise entender/estender alguma parte específica depois.
+
+| # | Agente | Arquivos principais no seu projeto |
+|---|--------|----------------------|
+| 00 | **Scaffold** | `package.json`, `next.config.ts`, `app/globals.css`, `lib/unbox/*`, `lib/config.ts` |
+| 01 | **Layout** | `app/layout.tsx`, `components/site-header.tsx`, `site-footer.tsx`, `mobile-nav.tsx` |
+| 02 | **Homepage** | `app/(loja)/page.tsx`, `components/home/*.tsx` |
+| 03 | **Catalog** | `app/(loja)/produtos/page.tsx`, `app/(loja)/categoria/[tagSlug]/page.tsx`, `app/(loja)/busca/page.tsx`, `components/catalog/*.tsx` |
+| 04 | **PDP** | `app/(loja)/produto/[productSlug]/page.tsx`, `components/product/pdp/*.tsx` |
+| 05 | **Cart** | `app/(loja)/carrinho/page.tsx`, `components/cart/*.tsx`, `app/api/cart/**` (inclui link de recuperação `?id=&token=`) |
+| 06 | **Checkout** | `app/(loja)/checkout/page.tsx`, `components/checkout/checkout-client.tsx`, `app/api/checkout/**` |
+| 07 | **Auth** | `app/(loja)/conta/entrar/page.tsx`, `lib/session.ts`, `app/api/account/{otp,signin,signout}/route.ts` |
+| 08 | **Customer** | `app/(loja)/conta/**`, `components/account/*.tsx`, `lib/customer-session.ts` |
+| 09 | **Promotions** | `lib/enrichment/combos.ts` (kits), `components/home/combos-*.tsx`, **infra pronta, mas `COMBOS = []` por padrão**, precisa popular |
+| 10 | **Feedback/UX** | `sonner` (toasts), `lib/unbox/errors.ts` (`friendlyError`, `cartEventLabel`), `app/error.tsx`, `app/not-found.tsx` |
+| 11 | **SEO + Infra** | `app/sitemap.ts`, `app/robots.ts`, JSON-LD Product básico na PDP |
+
+---
+
+## Passos manuais (pós-setup): status real na foundation atual
+
+| # | Passo | Módulos / escopo | Status hoje |
+|---|-------|------------------|-------------|
+| 15 | **Branding & Identidade** | entrevista de marca + aplicação (logo, cores, menu, conteúdo, FAQ verbatim, rodapé, prova social só com dado real) | **Novo.** Rodar `15-branding.md` como primeiro passo pós-setup. |
+| 16 | **QA Visual** | build de produção + screenshots desktop/mobile avaliados contra `marca/DESIGN-<MARCA>.md` + gate `unbox:honestidade` | **Obrigatório** depois do 15 e de cada rodada de feedback. Rodar `16-qa-visual.md`. |
+| 13 | **Unbox AI CRO Package** | 10 módulos: prova social, urgência de estoque, countdown flash sale, frete grátis¹, upsell pós-checkout, recently viewed, sticky CTA mobile, trust strip, kits & combos, brindes¹ | **Só frete grátis está implementado.** Os outros 9 exigem rodar o agente `13-cro.md`. |
+| 14 | **Unbox AI SEO Agent** | 7 módulos: schemas JSON-LD avançados, OG images dinâmicas, breadcrumbs, templates de título/description, canonical + paginação, Core Web Vitals, Search Console setup | **Nenhum módulo completo** (só o JSON-LD básico do agente 11). Rodar `14-seo.md`. |
+| 17 | **AEO** | 6 módulos: llms.txt, FAQ answer-friendly, Product schema enriquecido, FAQ por produto, bots de IA (conferência), entidade da marca | Opcional, depois do 14. Rodar `17-aeo.md`. |
+| 12 | **Deploy** | build de produção, variáveis de ambiente, publicação (Vercel) | Rodar `12-deploy.md` por último. |
+
+> ¹ Módulos **frete grátis** e **brindes** exigem configuração no painel Unbox antes do lançamento.
+
+
+## Regras de ouro (todos os agentes herdam)
+
+1. **`UNBOX_API_KEY` é server-only**, nunca `NEXT_PUBLIC_`, nunca client component
+2. **Dois tokens distintos**: token de loja (catálogo/checkout) ≠ token do cliente (área `/conta`)
+3. **`placeOrder` não é idempotente**, lock por `cartId` no BFF; nunca retentar cegamente
+4. **`customerOTPRequest` manda e-mail real**, jamais em testes/loops/CI
+5. **Preço e estoque são do servidor**, nunca computar preço no cliente
+6. **Menu: use `tags`** (navigation tree falha com token de loja)
+7. **`displayStatus(language)` está quebrado**, use `status` + `orderStatusLabel()` do SDK
+8. **shadcn/ui usa Base UI** (`@base-ui/react`), prop `render`, não `asChild`
+9. **Tailwind v4**, use utilitários/tokens do tema; evite CSS ad-hoc. Cor de marca é sempre
+   `bg-[var(--store-primary,#fallback)]`, nunca hex literal, senão a customização do CLI não
+   se propaga (achamos e corrigimos 304 ocorrências disso na foundation base)
+10. **Erros GraphQL chegam em HTTP 200**, sempre cheque `errors[]` antes de consumir `data`
+11. **`getTags()`/`getTopTags()` nunca filtra por `isTopLevel`**, forçar `true` esconde
+    categorias reais marcadas `false` no admin, mesmo aparecendo normalmente na vitrine padrão da
+    Unbox. Deixe o parâmetro opcional e omitido.
+12. **GTM central da Unbox (`GTM-PZLT336`) e o selo "Powered by Unbox" no rodapé são
+    obrigatórios e intocáveis**, contrato da plataforma. O `prebuild`
+    (`scripts/check-unbox-brand.mjs`) BLOQUEIA build/deploy sem os dois. Tags da marca vão
+    nos campos próprios (GA4/Pixel/GTM adicional), nunca substituindo o central.
+13. **Qualquer `useEffect`/handler que termina em `refresh()` do carrinho precisa esperar
+    `loading` (do `useCart()`) ficar `false` antes de rodar.** Achamos essa mesma classe de bug
+    em 4 pontos independentes do checkout (recálculo de frete por item, por CEP, troca de método
+    de frete, "continuar"), todos causavam "removo um item e ele volta" se disparassem enquanto
+    outra mutação de carrinho estava em voo. `cart-provider.tsx` também tem um contador de
+    sequência (`mutationSeq`) como proteção de segunda camada, mas o guard de `loading` evita o
+    problema na origem.
+
+---
+
+## Contratos entre módulos (referência real, não a genérica de quando isso foi escrito pra "fase 2")
+
+```
+lib/unbox/store.ts        → withStoreClient() / getShopContext(), client de LOJA, cache de token em memória
+lib/customer-session.ts   → getCustomerClient() / requireCustomerClient(), client do CLIENTE (token separado)
+lib/session.ts            → cookies httpOnly: unbox_cart, unbox_customer, unbox_order_<ref>
+lib/unbox/errors.ts       → friendlyError(), cartEventLabel()
+components/cart/          → CartProvider (useCart hook) + MiniCart, usado pelo Layout inteiro
+components/home/combos-* → consome lib/enrichment/combos.ts (Agente 09)
+```
+
+---
+
+## Variáveis de ambiente necessárias
+
+Nomes reais (confira sempre contra `.env.example` do projeto, já houve doc desatualizada com
+`UNBOX_USERNAME`/`UNBOX_PASSWORD`, que não existem):
+
+```env
+# .env.local (server-only: nunca NEXT_PUBLIC_)
+UNBOX_PARTNER_API_KEY=    # NOVA API pública de parceiros: key única do parceiro (todas as lojas).
+                          # Preenchida → signIn + leituras compatíveis roteiam pra partners.unbox.com.br
+UNBOX_CAPTCHA_BYPASS=     # obrigatória com a key de parceiro: x-captcha-verification do signIn (pedir à Unbox)
+UNBOX_API_KEY=            # chave da loja (modelo antigo; opcional se a de parceiro está preenchida)
+UNBOX_USER=               # usuário de API da loja (ex.: api_minhaloja)
+UNBOX_PASS=               # senha do usuário de API
+UNBOX_SHOP_ID=            # opcional: extraído do JWT se vazio
+UNBOX_SHOP_SLUG=          # opcional: extraído do JWT se vazio
+UNBOX_WEBHOOK_SECRET=     # secret(s) do subscribeToWebhook, separados por vírgula se houver mais de um
+
+# App
+SESSION_SECRET=
+REVALIDATE_SECRET=
+NEXT_PUBLIC_SITE_URL=
+```