@unbox-plus/cli 0.20.4

package/template/agents/definitions/11-seo-infra.md

@@ -0,0 +1,159 @@
+# Agente 11 — SEO + Infraestrutura
+
+> ⚠️ **Doc de plano (histórico).** A implementação entregue pela foundation difere em nomes e
+> caminhos de arquivo citados abaixo. O mapa REAL de arquivos por área é a tabela "Agentes
+> 00-11" do `agents/MANAGER.md` — em conflito, valem o MANAGER e o código.
+
+## Escopo
+SEO técnico: sitemap dinâmico, robots.txt, metadados estruturados, JSON-LD e helpers de metadata.
+
+## Dependências
+- Agente 00 (Scaffold) — `lib/metadata.ts` base
+
+## Arquivos proprietários
+
+| Arquivo | Descrição |
+|---------|-----------|
+| `app/sitemap.ts` | Sitemap dinâmico com produtos + categorias |
+| `app/robots.ts` | robots.txt com bloqueio de /conta e /api |
+| `lib/metadata.ts` | Helpers buildMetadata, buildCategoryMetadata, buildProductJsonLd |
+| `app/(loja)/pedido/[referenceId]/page.tsx` | Confirmação de pedido (noindex) |
+
+## lib/metadata.ts (completo)
+
+```ts
+import type { Metadata } from "next"
+
+const SITE = process.env.NEXT_PUBLIC_SITE_NAME ?? "Loja"
+const URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://seudominio.com.br"
+
+export function buildMetadata(
+  product: { title: string; pageTitle?: string; metaDescription?: string; description?: string; imageUrls?: string[]; slug: string },
+  canonical?: string,
+): Metadata {
+  const title = product.pageTitle ?? product.title
+  const description = product.metaDescription ?? product.description?.replace(/<[^>]+>/g, "").slice(0, 160)
+  const image = product.imageUrls?.[0]
+  const url = canonical ?? `${URL}/p/${product.slug}`
+  return {
+    title: `${title} | ${SITE}`,
+    description,
+    alternates: { canonical: url },
+    openGraph: {
+      title, description, url, type: "website",
+      images: image ? [{ url: image, alt: title, width: 800, height: 800 }] : [],
+    },
+    twitter: {
+      card: "summary_large_image", title, description,
+      images: image ? [image] : [],
+    },
+    robots: { index: true, follow: true },
+  }
+}
+
+export function buildCategoryMetadata(tag: {
+  name: string; displayTitle?: string; description?: string; slug: string
+}): Metadata {
+  const title = tag.displayTitle ?? tag.name
+  return {
+    title: `${title} | ${SITE}`,
+    description: tag.description,
+    alternates: { canonical: `${URL}/c/${tag.slug}` },
+  }
+}
+
+export function buildProductJsonLd(product: {
+  title: string; description?: string; imageUrls?: string[];
+  variants?: Array<{ sku?: string | null }>
+  isSoldOut: boolean; pricing?: Array<{ price: number | null }>
+}) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: product.title,
+    description: product.description?.replace(/<[^>]+>/g, ""),
+    image: product.imageUrls ?? [],
+    sku: product.variants?.[0]?.sku,
+    offers: {
+      "@type": "Offer",
+      availability: product.isSoldOut
+        ? "https://schema.org/OutOfStock"
+        : "https://schema.org/InStock",
+      price: product.pricing?.[0]?.price ?? 0,
+      priceCurrency: "BRL",
+    },
+  }
+}
+```
+
+## app/sitemap.ts — paginação correta
+
+```ts
+// Iterar catálogo completo com paginação (não buscar tudo com first grande)
+let offset = 0
+for (;;) {
+  const page = await client.getCatalog({ first: 100, offset })
+  // processar page.nodes
+  if (!page.pageInfo?.hasNextPage) break
+  offset += 100
+}
+```
+
+## app/robots.ts
+
+```ts
+import type { MetadataRoute } from "next"
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      {
+        userAgent: "*",
+        allow: "/",
+        disallow: ["/conta/", "/checkout", "/pedido/", "/api/", "/busca?"],
+      },
+    ],
+    sitemap: `${process.env.NEXT_PUBLIC_SITE_URL}/sitemap.xml`,
+  }
+}
+```
+
+## Variáveis NEXT_PUBLIC seguras
+
+```ts
+// PERMITIDOS como NEXT_PUBLIC (não são credenciais):
+NEXT_PUBLIC_SITE_NAME=Minha Loja
+NEXT_PUBLIC_SITE_URL=https://seudominio.com.br
+
+// PROIBIDOS como NEXT_PUBLIC:
+// NEXT_PUBLIC_UNBOX_API_KEY  ← NUNCA
+// NEXT_PUBLIC_UNBOX_SHOP_ID  ← evitar (não é credencial mas não precisa ser público)
+```
+
+## Página de confirmação de pedido
+
+```tsx
+// app/(loja)/pedido/[referenceId]/page.tsx
+export const metadata: Metadata = {
+  robots: { index: false, follow: false }  // noindex — evitar indexar URLs de pedido
+}
+
+async function getOrder(referenceId: string) {
+  const client = await getUnboxClient()
+  // buscar por referenceId — ver SDK
+  return client.getOrderByReferenceId(referenceId)
+}
+
+// Status: orderStatusLabel(order.status) — NUNCA displayStatus(language)
+// Rastreio: tracking.trackingCode (não trackingUrl no contexto cliente)
+```
+
+## Performance — checklist
+
+```
+- getCatalog para homepage: unstable_cache({ revalidate: 300 })
+- getProductBySlug (PDP): export const revalidate = 3600
+- getTags: unstable_cache({ revalidate: 3600 })
+- getShop/shopSales: unstable_cache({ revalidate: 300 })
+- Sitemap: sem cache explícito (Next.js revalida conforme revalidate da rota)
+- Imagens: next/image com sizes corretos para evitar oversized downloads
+```

package/template/agents/definitions/12-deploy.md

@@ -0,0 +1,173 @@
+# Agente 12 — Deploy (Vercel)
+
+## Escopo
+Preparar e executar o primeiro deploy da loja no Vercel: Node version, env vars nos três
+ambientes (Production / Preview / Development) e configuração do projeto.
+
+**REGRA DE OURO DO PRIMEIRO DEPLOY: sem git, sem GitHub.** O `vercel` sobe a pasta local
+direto, e a conta Vercel pode ser criada com email (na tela de login, ignorar o "Continue
+with GitHub"). NUNCA peça pro lojista criar conta GitHub ou inicializar git pra ver a loja
+no ar — isso é atrito desnecessário. Git/GitHub é um opcional de CI/CD pra DEPOIS da loja
+publicada, e só se o cliente quiser.
+
+## Dependências
+- Todos os outros agentes concluídos
+- `.env.local` preenchido com as credenciais reais da loja
+- Conta Vercel (login por email serve)
+
+## O que este agente faz
+
+1. Garante Node 22 LTS (`nvm use 22`)
+2. Remove lock file global que conflita com npm
+3. Valida conexão com a API Unbox antes de subir
+4. Cria projeto no Vercel e sobe as env vars
+5. Configura Framework Preset como **Next.js**
+6. Executa o primeiro deploy de produção (upload direto, sem repositório)
+7. (Opcional, se o cliente pedir) conecta GitHub pra redeploy automático
+
+---
+
+## Passo a passo
+
+### 1. Ambiente local
+
+```bash
+nvm install 22 && nvm use 22   # Node 22 LTS obrigatório (v26 causa startup lento)
+rm -f ~/package-lock.json      # evita conflito com npm install
+npm install
+npm run unbox:test             # valida credenciais antes de qualquer coisa
+```
+
+### 2. Vercel — entrar e linkar o projeto
+
+```bash
+npx vercel login   # abre o browser; login por email funciona (não precisa GitHub)
+npx vercel link    # cria novo projeto na conta (ou linka um existente)
+```
+
+Durante o `vercel link`, responder:
+- **Set up and deploy?** → No (vamos configurar antes)
+- **Link to existing project?** → depende (Yes se já existe, No para criar)
+
+### 3. Env vars — CRÍTICO
+
+Adicionar **todas** as variáveis **nos 3 ambientes** (Production + Preview + Development) antes do
+primeiro build. Sem elas o build falha com `UnboxError: signin HTTP 403`.
+
+#### Via CLI (recomendado — selecionar todos os 3 ambientes no prompt):
+
+```bash
+npx vercel env add UNBOX_PARTNER_API_KEY   # modelo recomendado (ou UNBOX_API_KEY, por loja)
+npx vercel env add UNBOX_CAPTCHA_BYPASS    # obrigatório com a key de parceiro (placeOrder/OTP)
+npx vercel env add UNBOX_USER
+npx vercel env add UNBOX_PASS
+npx vercel env add SESSION_SECRET
+npx vercel env add NEXT_PUBLIC_SITE_URL
+npx vercel env add NEXT_PUBLIC_SITE_NAME
+# opcionais mas recomendados:
+npx vercel env add UNBOX_WEBHOOK_SECRET
+npx vercel env add REVALIDATE_SECRET
+```
+
+> Quando o CLI perguntar "Which environments?", escolher **Production, Preview, Development** (todos).
+
+#### Ou via dashboard:
+
+> Settings → Environment Variables → Add
+
+Para cada variável, marcar os checkboxes: **Production ✅ Preview ✅ Development ✅**
+
+| Variável | Obrigatório | Descrição |
+|---|---|---|
+| `UNBOX_PARTNER_API_KEY` | ✅ (recomendado) | Key única do parceiro; dispensa `UNBOX_API_KEY` |
+| `UNBOX_CAPTCHA_BYPASS` | ✅ com key de parceiro | Segredo do header x-captcha-verification (sem ele: CAPTCHA_MALFORMED_ERROR no pagamento) |
+| `UNBOX_API_KEY` | ✅ se não houver key de parceiro | Chave de API da loja (modelo antigo) |
+| `UNBOX_USER` | ✅ | Usuário de API |
+| `UNBOX_PASS` | ✅ | Senha de API |
+| `SESSION_SECRET` | ✅ | String aleatória forte (≥ 32 chars) |
+| `NEXT_PUBLIC_SITE_URL` | ✅ | URL pública (`https://minhaloja.com.br`) |
+| `NEXT_PUBLIC_SITE_NAME` | ✅ | Nome da loja (título, OG, manifest, JSON-LD) |
+| `UNBOX_SHOP_ID` | — | Extraído do JWT se vazio |
+| `UNBOX_SHOP_SLUG` | — | Extraído do JWT se vazio |
+| `UNBOX_WEBHOOK_SECRET` | — | Secret dos webhooks |
+| `REVALIDATE_SECRET` | — | Protege `/api/revalidate` |
+| `NEXT_PUBLIC_GA_ID` | — | GA4 measurement ID |
+| `NEXT_PUBLIC_META_PIXEL_ID` | — | Meta Pixel ID |
+| `META_CAPI_TOKEN` | — | Meta Conversions API token |
+
+### 4. Framework Preset — CRÍTICO
+
+> Settings → Build & Development Settings → Framework Preset → **Next.js**
+
+**Nunca deixar como "Other"** — o Vercel não configura o build command correto e o deploy falha.
+
+### 5. Primeiro deploy
+
+```bash
+npx vercel --prod
+```
+
+Upload direto da pasta local; a URL de produção sai no final. Sem repositório envolvido.
+
+### 6. Opcional (só se o cliente pedir): redeploy automático via GitHub
+
+Com a loja já no ar, quem quiser que todo push em `main` redeploye sozinho:
+
+```bash
+# .gitignore já está correto no template — não alterar
+git init
+git add .
+git commit -m "chore: initial storefront"
+git remote add origin <repo-url>
+git push -u origin main
+```
+
+E no dashboard: Settings → Git → conectar o repositório.
+
+> `git add -A` pode travar em repos grandes. O `.gitignore` já exclui `node_modules/` e `.next/`.
+
+---
+
+## Erros comuns
+
+| Erro | Causa | Solução |
+|---|---|---|
+| `UnboxError: signin HTTP 403` | Env vars ausentes | Adicionar em todos os 3 ambientes e fazer Redeploy |
+| Build falha silenciosamente | Framework Preset "Other" | Settings → Build → alterar para **Next.js** |
+| `npm ERR!` no install | `~/package-lock.json` global | `rm -f ~/package-lock.json` |
+| Startup lento (> 5 min) em dev | Node.js v26 | `nvm use 22` |
+| `Project already exists` | Nome duplicado na conta | Usar nome diferente (ex: `minhaloja-app`) |
+| Prerender error na home | API inacessível durante build | Checar credenciais + `npm run unbox:test` |
+
+---
+
+## Redeploy após mudar env vars
+
+Após alterar variáveis no dashboard:
+
+1. Deployments → último deploy → **Redeploy**
+
+Ou pela CLI:
+
+```bash
+npx vercel --prod
+```
+
+(Quem conectou GitHub também pode só dar `git push origin main`.)
+
+---
+
+## QA pré-go-live
+
+Após o deploy, rodar o checklist em `QA.md` **com credenciais reais**.
+
+> Sem `.env.local` preenchido e `npm run unbox:test` passando, os fluxos de carrinho,
+> checkout e login não funcionam — o QA só vale com a API conectada.
+
+## Saída esperada
+
+- Projeto no Vercel configurado e com todas as env vars
+- Framework Preset = Next.js
+- Primeira URL de produção retornada pelo `npx vercel --prod` (sem git/GitHub envolvidos)
+- Confirmação de que a home carrega sem erros (prerender passou)
+- QA.md executado e sem itens pendentes

package/template/agents/definitions/13-cro.md

@@ -0,0 +1,275 @@
+# Agente 13 — Unbox AI CRO Package
+
+## Objetivo
+
+Ativar os módulos de otimização de conversão (CRO) escolhidos pelo usuário. Cada módulo é independente — ative apenas os que fazem sentido para a loja atual.
+
+---
+
+## Apresentação ao usuário
+
+Ao iniciar este agente, exiba o menu abaixo e pergunte quais módulos ativar:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Unbox AI CRO Package — Módulos disponíveis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  [1] Prova Social no PDP
+      Avaliações reais em destaque (badge "X compraram hoje" só com contador do backend)
+      ⚙️  Requer: reviews reais em lib/enrichment/products.json. NÃO existe valor mockup:
+          sem dado, o módulo fica bloqueado (regra do CLAUDE.md e gate unbox:honestidade)
+
+  [2] Urgência de Estoque
+      "Restam X unidades" quando stock ≤ threshold configurável
+      ⚙️  Requer: campo de estoque na API Unbox (productStock)
+
+  [3] Countdown Flash Sale
+      Banner com temporizador regressivo para ofertas com prazo
+      ⚙️  Requer: definir data/hora de fim da promoção
+
+  [4] Barra de Frete Grátis
+      Progress bar no carrinho: "Faltam R$X para frete grátis"
+      ⚙️  Requer: definir threshold de frete grátis (ex: R$149)
+
+  [5] Upsell Pós-Checkout
+      Seção "Você também vai gostar" na página de pedido confirmado
+      ⚙️  Requer: lógica de recomendação (por categoria ou manual)
+
+  [6] Recently Viewed
+      Histórico de produtos vistos (localStorage, sem backend)
+      ⚙️  Sem dependências — funciona sem credenciais
+
+  [7] Sticky CTA Mobile
+      Botão "Adicionar ao carrinho" fixo no scroll do PDP (mobile)
+      ⚙️  Sem dependências
+
+  [8] Trust Strip Customizável
+      Ícones de confiança editáveis: entrega, troca, pagamento seguro
+      ⚙️  Sem dependências — apenas editar os textos
+
+  [9] Kits & Combos com Cross-sell
+      Seção de kits na home com produtos complementares
+      ⚙️  Requer: definir os combos em lib/enrichment/combos.ts
+
+  [10] Brindes (Gift with Purchase)
+       Exibe brinde desbloqueado quando carrinho atinge valor mínimo
+       ⚠️  Requer configuração no back-end Unbox ANTES do lançamento
+       ⚙️  Requer: regra de brinde ativa no painel + SKU do brinde
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ⚠️  Módulos 4 e 10 dependem de configuração no back-end
+      antes de ir ao ar. Veja a seção "Pré-requisitos de back-end".
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Opções: "all", números separados por vírgula (ex: 1,4,7), ou "none"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Aguarde a resposta antes de qualquer implementação.
+
+---
+
+## Módulos — especificação técnica
+
+### [1] Prova Social no PDP
+
+**Arquivo:** `components/product/pdp/social-proof.tsx`
+
+**Contador de compras ("X pessoas compraram hoje"): BLOQUEADO.** A API pública da loja não
+expõe volume de vendas por SKU e o enrichment não tem campo pra isso (`lib/enrichment/index.ts`).
+Um número "configurável" ou "hardcoded por SKU" é fabricação, e o `unbox:honestidade` derruba o
+build (`\d+ pessoas compraram`, `compraram nas últimas 24h`). Só implemente se o lojista fornecer
+um contador REAL (integração própria), e registre a fonte no `marca/DESIGN-<MARCA>.md`.
+
+O que este módulo faz HOJE: destacar as avaliações reais do produto (`reviews` do enrichment)
+logo abaixo do preço no `buy-box.tsx`: nota média + 1 depoimento curto + link pra seção completa.
+Sem reviews, o bloco não existe.
+
+---
+
+### [2] Urgência de Estoque
+
+**Arquivo:** `components/product/pdp/stock-urgency.tsx`
+
+```tsx
+// Exibe "Restam 8 unidades" quando o estoque REAL <= THRESHOLD
+const THRESHOLD = 15; // configurável
+```
+
+Inserir no `buy-box.tsx`, abaixo do seletor de quantidade.
+
+**Dependência API:** o catálogo público NÃO expõe quantidade (`productStock` não existe; só
+`isSoldOut`). Quantidade real vem de `simpleInventory` na API de parceiros (`agents/COVERAGE.md`),
+via `withStoreClient` no servidor. Sem esse dado, o módulo fica BLOQUEADO: contador que "desce
+sozinho" ou threshold sem estoque real é fabricação.
+
+---
+
+### [3] Countdown Flash Sale
+
+**Arquivo:** `components/home/flash-sale-banner.tsx`
+
+```tsx
+// Banner full-width com countdown regressivo
+// Configurar: SALE_END_DATE (ISO string) e mensagem da oferta
+const SALE_END_DATE = "2025-12-31T23:59:59-03:00"; // TODO: atualizar
+```
+
+Inserir na home, entre o hero e os combos. Condicionado: se `Date.now() < SALE_END_DATE`, exibe; caso contrário, não renderiza (null).
+
+---
+
+### [4] Barra de Frete Grátis
+
+⚠️ **A foundation JÁ tem isso** — régua de frete grátis no mini-cart, checkout, buy-box e
+header, todos lendo `FREE_SHIPPING_THRESHOLD` de `lib/store-config.ts` (que nasce `null` =
+nada renderiza até existir regra real; ver `npm run unbox:dump`). Este módulo NÃO cria
+componente novo nem segundo limiar: se a régua não aparece, o motivo é o threshold `null` —
+preencha a store-config com a regra REAL. Só crie UI adicional (ex.: barra no topo da página
+de carrinho) consumindo o MESMO `FREE_SHIPPING_THRESHOLD`, nunca um número hardcoded.
+
+---
+
+### [5] Upsell Pós-Checkout
+
+**Arquivo:** `components/order/upsell-section.tsx`
+
+```tsx
+// Recomendações na página de pedido confirmado
+// Fonte: últimos produtos vistos (localStorage) ou lista manual
+```
+
+Inserir em `app/(loja)/pedido/[referenceId]/page.tsx` (confirmação de pedido).
+
+---
+
+### [6] Recently Viewed
+
+**Arquivo:** `lib/recently-viewed.ts` + `components/product/recently-viewed.tsx`
+
+```ts
+// localStorage: salva array de slugs visitados (max 8)
+// Hook: useRecentlyViewed()
+```
+
+- Salvar no `useEffect` do PDP (client component).
+- Exibir no carrinho e na home como seção "Vistos recentemente".
+- **Sem dependências externas** — funciona com qualquer storeToken.
+
+---
+
+### [7] Sticky CTA Mobile
+
+**Arquivo:** `components/product/pdp/sticky-cta.tsx`
+
+```tsx
+// Visível apenas em mobile (md:hidden)
+// Aparece após scroll passar o botão principal (IntersectionObserver)
+// Posição: fixed bottom-0, acima da nav bar (bottom-[84px])
+```
+
+Inserir no layout do PDP (`app/(loja)/produto/[productSlug]/page.tsx`).
+
+---
+
+### [8] Trust Strip Customizável
+
+⚠️ **A foundation JÁ tem trust strips** — `components/home/sections/trust-strip.tsx` (escura)
+e `trust-bar.tsx` (clara), registradas no `registry.ts` e documentadas no `agents/PADROES.md`.
+Este módulo customiza os ITENS das existentes via receita: `props.items: [{ icon?, text }]`
+(ícones em `TRUST_ICONS`, `trust-bar.tsx`). Sem `items`, as duas seções NÃO renderizam: os
+selos são promessas do lojista ("entrega em 24h", "garantia de 1 ano"), não da foundation.
+
+**Arquivo (só se precisar de variante nova):** `components/home/sections/` + registro no registry
+
+```tsx
+// Array configurável de itens: { icon, label, sub }
+const TRUST_ITEMS = [
+  { icon: "Truck",    label: "Entrega rápida",      sub: "Prazo conforme CEP" },
+  { icon: "RotateCcw", label: "Troca sem burocracia", sub: "Até 7 dias após recebimento" },
+  { icon: "Shield",   label: "Pagamento seguro",     sub: "SSL + antifraude" },
+  { icon: "Award",    label: "Produto original",     sub: "Nota fiscal inclusa" },
+];
+```
+
+Reutilizável: inserir no PDP, na home e/ou no checkout.
+
+---
+
+### [9] Kits & Combos com Cross-sell
+
+**Arquivo:** `lib/enrichment/combos.ts` (já existe, vazio por padrão)
+
+```ts
+// Preencher com os combos da loja:
+export const COMBOS: ComboDef[] = [
+  {
+    id: "kit-essencial",
+    name: "Kit Essencial",
+    description: "Os mais vendidos juntos",
+    items: [{ family: "FAMILIA_A" }, { family: "FAMILIA_B" }],
+  },
+];
+```
+
+Os dados vivem em `lib/enrichment/combos.ts` (`COMBOS` + `resolveCombos`, chamado em `app/(loja)/page.tsx`; a seção da home é `kits`)
+
+---
+
+### [10] Brindes (Gift with Purchase)
+
+**Arquivo:** `components/cart/gift-indicator.tsx`
+
+```tsx
+// Exibe brinde desbloqueado quando carrinho atinge valor mínimo.
+// A lógica de elegibilidade e o SKU do brinde vêm da API Unbox
+// (campo `gifts` retornado no payload do carrinho).
+//
+// ⚠️  PRÉ-REQUISITO DE BACK-END — configurar no painel Unbox:
+//   1. Criar regra de brinde (mínimo de valor, SKU do produto brinde)
+//   2. Garantir que o SKU do brinde está com estoque ativo
+//   Sem isso, o componente renderiza vazio — nunca exibe brinde falso.
+```
+
+**Comportamento:**
+- Carrinho abaixo do mínimo: `"Adicione mais R$X e ganhe [nome do brinde]"` com progress bar
+- Carrinho acima do mínimo: `"🎁 Brinde desbloqueado: [nome do brinde]!"` em destaque
+- Sem regra configurada no back: componente não renderiza (null)
+
+Inserir no `app/(loja)/carrinho/page.tsx`, abaixo da barra de frete grátis (módulo 4) se ativo, senão no topo do sumário.
+
+**Dependência API:** `cart.gifts[]` — array de brindes elegíveis retornado pela Unbox API.
+
+---
+
+## Pré-requisitos de back-end
+
+> Estes módulos exibem dados que vêm do painel Unbox. **Configurar antes do lançamento da loja.**
+
+| Módulo | O que configurar no painel Unbox |
+|--------|----------------------------------|
+| **[4] Barra de Frete Grátis** | Regra de frete grátis: valor mínimo do pedido, CEPs/regiões elegíveis |
+| **[10] Brindes** | Regra de brinde: valor mínimo, SKU do produto brinde, estoque ativo |
+
+Sem essas configurações, os componentes renderizam vazios (não inventam dados). Isso é intencional — nunca exibir promoção que não existe.
+
+---
+
+## Fluxo do agente
+
+1. **Apresentar menu** e aguardar escolha.
+2. **Confirmar escopo:** listar módulos selecionados e suas dependências.
+3. **Perguntar configurações** específicas de cada módulo (ex: threshold de frete, data do flash sale).
+4. **Implementar** um módulo por vez, em ordem numérica.
+5. **Para cada módulo:** criar/editar arquivo → inserir no componente pai → confirmar sem erros de TypeScript.
+6. **Ao final:** listar TODOs de configuração que ainda precisam de dados reais (ex: `SALE_END_DATE`, combos, reviews).
+
+---
+
+## Regras
+
+- **Nunca ativar módulo sem perguntar.** O template base é intencionalmente simples.
+- **Módulos são opcionais e independentes** — remover um não quebra os outros.
+- Usar os **brand tokens** (`--store-primary`, `--store-cta`) para cores, nunca hardcodar hex.
+- Módulos sem dependência de API (6, 7, 8) podem ser ativados mesmo em modo mockup.
+- Módulos com dependência (1, 2, 3, 4, 5, 9) devem exibir aviso se `.env.local` não estiver configurado.