@unbox-plus/cli 0.20.4

package/template/agents/definitions/17-aeo.md

@@ -0,0 +1,257 @@
+# Agente 17 — AEO (Answer Engine Optimization)
+
+## Objetivo
+
+Preparar o storefront para ser **citado e recomendado por motores de resposta** (ChatGPT,
+Claude, Perplexity, Google AI Overviews). Complementa o SEO clássico (agentes 11 e 14):
+enquanto SEO otimiza pra ranquear em lista de links, AEO otimiza pra loja SER a resposta —
+dados estruturados completos, conteúdo que responde perguntas diretamente e acesso liberado
+aos crawlers de IA.
+
+**Pré-requisitos:** a foundation já traz `app/sitemap.ts`, `app/robots.ts` (com os bots de
+IA liberados) e JSON-LD Product inline em `app/(loja)/produto/[productSlug]/page.tsx`. Se o
+agente 14 (SEO) já rodou, **leia o que ele fez antes de editar** — os módulos 3 e 6 estendem
+os mesmos arquivos. Rode DEPOIS do briefing (15) e do QA visual (16): AEO em cima de
+conteúdo placeholder é otimizar mentira.
+
+---
+
+## Apresentação ao usuário
+
+Ao iniciar este agente, exiba o menu abaixo e pergunte quais módulos ativar:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Unbox AI AEO Agent — Módulos disponíveis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  [1] llms.txt
+      JÁ EXISTE como rota (app/llms.txt/route.ts), montada do catálogo real:
+      produtos com preço, esgotados marcados, categorias e políticas. O que
+      falta é a APRESENTAÇÃo da marca (o que ela faz, para quem, diferenciais):
+      preencha NEXT_PUBLIC_SITE_DESCRIPTION e estenda lib/llms-txt.ts. Não
+      recrie o arquivo em public/: lá ele esconderia a rota e nasceria velho.
+      produtos-chave (nome, preço, link) e políticas —
+      gerada do catálogo, mesma fonte do sitemap
+      ⚙️  Sem dependências
+
+  [2] FAQ answer-friendly + FAQPage schema
+      Resposta direta de 40-60 palavras no 1º parágrafo
+      de cada pergunta + JSON-LD FAQPage
+      ⚙️  Requer: FAQ REAL da marca (verbatim — nunca inventar)
+
+  [3] Product schema enriquecido
+      shippingDetails, hasMerchantReturnPolicy, SKU/GTIN
+      quando houver — estende o JSON-LD da PDP
+      ⚙️  Requer: políticas reais de frete/troca da loja
+
+  [4] FAQ por produto na PDP
+      Bloco "Perguntas sobre este produto" + FAQPage por PDP,
+      derivado da ficha técnica real do produto
+      ⚙️  Requer: ficha técnica/atributos reais no catálogo
+
+  [5] Política de bots de resposta (conferência)
+      A foundation JÁ libera GPTBot, ClaudeBot, PerplexityBot
+      etc. — conferir/estender a lista em app/robots.ts
+      ⚙️  Sem dependências (decisão reversível da marca)
+
+  [6] Entidade da marca
+      Organization schema completo (sameAs com todas as redes)
+      + página Sobre estruturada para citação
+      ⚙️  Requer: links reais das redes (briefing/rodapé)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Opções: "all", números separados por vírgula (ex: 1,5,6), ou "none"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Aguarde a resposta antes de qualquer implementação.
+
+---
+
+## Módulos — especificação técnica
+
+### [1] llms.txt
+
+**Arquivo:** `app/llms.txt/route.ts` (novo)
+
+Rota que devolve `text/plain` no padrão [llms.txt](https://llmstxt.org): um sumário da loja
+em Markdown, pensado pra um LLM consumir em uma leitura. Gerar dinamicamente da MESMA fonte
+do sitemap (catálogo via `withStoreClient()`; em modo mockup, `lib/enrichment/products.json`
+— não pode quebrar o build sem credenciais):
+
+```ts
+// app/llms.txt/route.ts
+export async function GET() {
+  const body = [
+    `# ${nomeDaLoja}`,
+    ``,
+    `> ${descricaoDaLoja}`, // 1-2 frases: o que a loja vende e para quem (do briefing)
+    ``,
+    `## Categorias`,
+    ...tags.map((t) => `- [${t.name}](${URL}/categoria/${t.slug})`),
+    ``,
+    `## Produtos principais`,
+    ...produtos.slice(0, 20).map(
+      (p) => `- [${p.title}](${URL}/produto/${p.slug}) — R$ ${preco(p)}`
+    ),
+    ``,
+    `## Políticas`,
+    `- [Trocas e devoluções](${URL}/devolucoes)`,
+    `- [Termos](${URL}/termos)`,
+  ].join("\n");
+  return new Response(body, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+}
+```
+
+Confira os caminhos REAIS das páginas de política desta loja antes de linkar (a foundation
+traz `/devolucoes`, `/termos`, `/privacidade`; o briefing pode ter criado outras).
+
+⚠️ **A foundation já traz um `public/llms.txt` ESTÁTICO de partida** — e em Next.js o
+arquivo em `public/` vence o route handler: a rota nova nunca responderia. Ao criar a rota
+dinâmica, **apague `public/llms.txt`** no mesmo commit (uma fonte de verdade só). Se
+preferir manter o estático, atualize-o à mão e NÃO crie a rota.
+
+### [2] FAQ answer-friendly + FAQPage schema
+
+**Arquivos:** onde o FAQ da loja vive — na foundation, o bloco de FAQ da PDP
+(`components/product/pdp/interactive.tsx`, `FaqList`) e/ou a página institucional que o
+briefing tiver criado.
+
+Answer engines extraem respostas curtas e autocontidas. Reestruture cada item pra que o
+**primeiro parágrafo responda a pergunta em 40-60 palavras**, sem depender do contexto ao
+redor ("Sim, trocamos em até 7 dias (CDC). Basta..." e não "Conforme mencionado acima...").
+Detalhes vêm depois do parágrafo de resposta.
+
+JSON-LD na página (sempre via `JSON.stringify`):
+
+```ts
+const faqSchema = {
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  mainEntity: faq.map((item) => ({
+    "@type": "Question",
+    name: item.pergunta,
+    acceptedAnswer: { "@type": "Answer", text: item.respostaDireta },
+  })),
+};
+```
+
+**Regra dura:** o conteúdo vem do FAQ REAL da marca (site atual ou briefing), verbatim no
+sentido — pode reescrever a FORMA pra ficar direto, nunca inventar pergunta ou resposta.
+Sem FAQ real → módulo não roda, vira pendência.
+
+### [3] Product schema enriquecido
+
+**Arquivo:** `app/(loja)/produto/[productSlug]/page.tsx` (estender o objeto `jsonLd`
+existente — **leia antes**; o QA de honestidade já condicionou o `aggregateRating` a
+avaliações reais, não regrida isso).
+
+Answer engines pesam muito frete e política de troca ao recomendar onde comprar. Adicionar
+à `Offer`:
+
+```ts
+offers: {
+  "@type": "Offer",
+  // ...campos existentes (price, availability, url)
+  shippingDetails: {
+    "@type": "OfferShippingDetails",
+    shippingDestination: { "@type": "DefinedRegion", addressCountry: "BR" },
+    // deliveryTime só se a loja tiver prazo padrão REAL declarado
+  },
+  hasMerchantReturnPolicy: {
+    "@type": "MerchantReturnPolicy",
+    applicableCountry: "BR",
+    returnPolicyCategory: "https://schema.org/MerchantReturnFiniteReturnWindow",
+    merchantReturnDays: 7, // CDC: 7 dias de arrependimento; ajuste se a política real for maior
+    returnMethod: "https://schema.org/ReturnByMail",
+    returnFees: "https://schema.org/FreeReturn", // só se for verdade
+  },
+},
+sku: p.sku ?? undefined,
+gtin13: p.gtin ?? undefined, // só quando o campo existir no catálogo
+```
+
+Valores de política **têm que refletir a política real** (páginas legais/briefing/decisão
+registrada do lojista). Na dúvida, o mínimo legal (7 dias CDC) e um TODO pro humano
+confirmar.
+
+### [4] FAQ por produto na PDP
+
+**Arquivos:** `components/product/pdp/product-faq.tsx` (novo) + inserção na PDP + FAQPage
+JSON-LD por produto.
+
+Bloco "Perguntas sobre este produto" com 3-5 perguntas derivadas **da ficha técnica real**
+(peso, medidas, uso, cuidados — o que existir em `lib/enrichment/products.json` ou nos
+atributos do catálogo). Exemplo honesto: "Qual o peso do produto?" → resposta com o dado
+real.
+
+- JSON-LD FAQPage no nível da PDP com essas perguntas.
+- **Nunca inventar** resposta que o dado não sustenta; produto sem ficha suficiente fica
+  sem o bloco (renderiza null).
+
+### [5] Política de bots de resposta (conferência)
+
+**Arquivo:** `app/robots.ts`
+
+A foundation JÁ libera os crawlers de IA (lista `AI_AGENTS`: GPTBot, OAI-SearchBot,
+ChatGPT-User, ClaudeBot, Claude-Web, anthropic-ai, PerplexityBot, Perplexity-User,
+Google-Extended, Applebot-Extended, Amazonbot, meta-externalagent, CCBot) com os mesmos
+`disallow` de conta/carrinho/checkout/pedido/api. Neste módulo: confira que ninguém removeu
+a lista, acrescente bots novos que surgirem, e registre no commit que a permissão é decisão
+reversível da marca. Regra por userAgent específico SUBSTITUI a genérica — os `disallow`
+precisam estar replicados em cada regra (a foundation já faz).
+
+### [6] Entidade da marca
+
+**Arquivos:** `app/(loja)/page.tsx` (Organization + WebSite JÁ existem: estenda com sameAs/logo, não duplique) +
+página Sobre.
+
+Answer engines montam um "cartão" da marca cruzando fontes. Ajude:
+
+```ts
+const orgSchema = {
+  "@context": "https://schema.org",
+  "@type": "Organization",
+  name: nomeDaLoja,
+  url: siteUrl,
+  logo: `${siteUrl}/brand/logo.svg`,
+  description: descricaoDaMarca, // 1 frase, do briefing
+  sameAs: [instagramUrl /* todas as redes REAIS do rodapé/briefing */],
+};
+```
+
+Se o agente 14 (módulo 1) já criou um Organization schema, **estenda** o existente com
+`description` e `sameAs` completos — nunca duplique o bloco.
+
+Página **Sobre**: garanta que existe (crie em `app/(loja)/sobre/page.tsx` se o briefing
+tiver o conteúdo) e que o primeiro parágrafo define a marca de forma autocontida (quem é, o
+que vende, desde quando, diferencial) — é o parágrafo que um answer engine cita. Conteúdo
+do briefing (Entendimento da Marca / Posicionamento); nada inventado.
+
+---
+
+## Fluxo do agente
+
+1. **Apresentar o menu** e aguardar a escolha.
+2. **Verificar pré-requisitos:** `app/robots.ts` e `app/sitemap.ts` existem; ler o que os
+   agentes 11/14 já implementaram (e o que o QA de honestidade já condicionou no JSON-LD).
+3. **Implementar em ordem numérica** — módulos independentes entre si.
+4. **Ao final:** listar o que foi implementado, com os TODOs que exigem confirmação humana
+   (política de troca real, GTIN, redes sociais faltantes) — pendências no formato do
+   briefing (bloqueiam o go-live, não o build).
+
+---
+
+## Regras
+
+- **Você nunca inventa dado** (regra de ouro da loja): FAQ verbatim; políticas de
+  frete/troca reais; ficha técnica real. O que não houver, não entra — vira pendência
+  listada. Decisão de manter algo sem fonte é do LOJISTA, registrada
+  (`marca/honestidade-permitido.txt`).
+- **Nunca duplicar** schema que 11/14 já emitem — leia os arquivos antes de editar.
+- `<script type="application/ld+json">` sempre via `JSON.stringify()` (XSS com interpolação
+  direta).
+- `llms.txt` e `robots.ts` devem funcionar em modo mockup (catálogo de exemplo) sem quebrar
+  o build — rode `npm run build` ao final.
+- Textos em português do Brasil, no tom de voz do briefing (sem travessão na copy).

package/template/app/(loja)/busca/page.tsx

@@ -0,0 +1,72 @@
+import type { Metadata } from "next";
+import Link from "next/link";
+import { CaretRight } from "@phosphor-icons/react/dist/ssr";
+import { getCatalog, getTopTags } from "@/lib/queries";
+import { PAGE_SIZE } from "@/lib/catalog";
+import { buildTagMap, mapCatalogItems } from "@/lib/catalog-map";
+import { ProductGrid } from "@/components/catalog/product-grid";
+import { Pager } from "@/components/catalog/pager";
+import { EmptyState } from "@/components/empty-state";
+import { SearchBox } from "@/components/search-box";
+import { mockupOr } from "@/lib/mockup";
+import { DataLayerReady } from "@/components/analytics/data-layer-ready";
+
+export const metadata: Metadata = { title: "Busca", robots: { index: false } };
+
+type SP = { q?: string; page?: string };
+
+export default async function BuscaPage({ searchParams }: { searchParams: Promise<SP> }) {
+  const sp = await searchParams;
+  const q = (sp.q ?? "").trim();
+  const page = Math.max(1, parseInt(sp.page ?? "1", 10) || 1);
+  const offset = (page - 1) * PAGE_SIZE;
+
+  const [catalog, tags] = await Promise.all([
+    q
+      ? mockupOr(getCatalog({ first: PAGE_SIZE, offset, searchText: q }), ({ nodes: [], totalCount: 0 } as any), "busca/getCatalog")
+      : Promise.resolve({ nodes: [], totalCount: 0 } as any),
+    mockupOr(getTopTags(), [], "busca/getTopTags"),
+  ]);
+
+  const items = mapCatalogItems(catalog.nodes ?? [], buildTagMap(tags as any[]));
+  const total = catalog.totalCount ?? 0;
+  const totalPages = Math.max(1, Math.ceil(total / PAGE_SIZE));
+  const hrefForPage = (p: number) => `/busca?q=${encodeURIComponent(q)}${p > 1 ? `&page=${p}` : ""}`;
+
+  return (
+    <div className="store-layout full-bleed bg-white text-[var(--store-ink)]">
+      <DataLayerReady pageType="search" />
+      <div className="mx-auto max-w-[1240px] px-4 py-7 sm:px-6">
+        {/* breadcrumb */}
+        <div className="flex items-center gap-2 text-[13px] font-medium text-[var(--store-muted)]">
+          <Link href="/" className="no-underline hover:text-[var(--store-ink)]">Início</Link>
+          <CaretRight className="text-[11px]" />
+          <span className="font-semibold text-[var(--store-ink)]">Busca</span>
+        </div>
+
+        <h1 className="font-display mt-4 text-[28px] font-extrabold leading-[1.12]">Buscar produtos</h1>
+        <SearchBox defaultValue={q} className="mt-4 max-w-xl" />
+
+        <div className="mt-7">
+          {!q ? (
+            <EmptyState title="Digite o que procura" description="Busque pelo nome do produto ou categoria." />
+          ) : items.length === 0 ? (
+            <EmptyState title={`Nada encontrado para “${q}”`} description="Tente outros termos ou explore o catálogo completo.">
+              <Link href="/produtos" className="font-display inline-flex h-11 items-center rounded-xl bg-[var(--store-primary,#18181B)] px-5 text-[14px] font-bold text-white no-underline transition-colors hover:bg-[var(--store-primary-dark,#09090B)]">
+                Ver todos os produtos
+              </Link>
+            </EmptyState>
+          ) : (
+            <>
+              <p className="mb-4 text-sm text-[var(--store-muted)]">
+                <b className="text-[var(--store-ink)]">{total}</b> resultado(s) para “{q}”
+              </p>
+              <ProductGrid items={items} />
+              <Pager page={page} totalPages={totalPages} hrefForPage={hrefForPage} />
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/app/(loja)/carrinho/oferta/page.tsx

@@ -0,0 +1,57 @@
+// Passo 2 do funil (/carrinho/oferta): o cliente distribui a quantidade escolhida entre os
+// produtos, escolhe a frequência de envio (assinatura REAL da política da loja, se houver)
+// e segue pro checkout. Tela split sem o chrome do site. Produtos e preços do catálogo.
+import type { Metadata } from "next";
+import { Suspense } from "react";
+import { getCatalog, getTopTags, getShopData } from "@/lib/queries";
+import { buildTagMap, mapCatalogItems } from "@/lib/catalog-map";
+import { ProductPicker, type PickerSubscription } from "@/components/landing/product-picker";
+import { mockupOr } from "@/lib/mockup";
+
+export const revalidate = 300;
+export const metadata: Metadata = { title: "Monte seu pedido", robots: { index: false } };
+
+const isCombo = (s: string) => /kit|combo/i.test(s);
+
+export default async function CarrinhoOfertaPage() {
+  const [catalog, tags, shop] = await Promise.all([
+    mockupOr(getCatalog({ first: 100 }), ({ nodes: [] as any[] }), "carrinho-oferta/getCatalog"),
+    mockupOr(getTopTags(), [], "carrinho-oferta/getTopTags"),
+    mockupOr(getShopData(), null, "carrinho-oferta/getShopData"),
+  ]);
+  const nodes = (catalog.nodes ?? []) as any[];
+  const items = mapCatalogItems(nodes, buildTagMap(tags as any[]));
+
+  // Mesma seleção da landing: combos → ofertas → destaques (o herói vem primeiro).
+  let list = items.filter((it) => it.categories.some(isCombo));
+  if (list.length < 2) {
+    const deals = items.filter((it) => it.oldPrice != null);
+    list = deals.length >= 2 ? deals : items.slice(0, 8);
+  }
+  list = list.slice(0, 8);
+
+  // Assinatura: política REAL da loja + produtos que permitem recorrência.
+  const recurrableIds = nodes
+    .map((n: any) => n.product ?? n)
+    .filter((p: any) => p?.recurrenceAllowed)
+    .map((p: any) => String(p.productId));
+  const policy = (shop as any)?.recurringOrdersPolicy;
+  const subscription: PickerSubscription | null =
+    policy?.enabled && (policy.allowedFrequencies?.length ?? 0) > 0 && recurrableIds.length > 0
+      ? {
+          percentOff: policy.pricingPolicy?.type === "PERCENTAGE_OFF" ? policy.pricingPolicy.value : null,
+          frequencies: (policy.allowedFrequencies ?? []).map((f: any) => ({ id: f._id, title: f.title })),
+        }
+      : null;
+
+  return (
+    <Suspense>
+      <ProductPicker
+        products={list}
+        shopName={(shop as any)?.name ?? "Nossa loja"}
+        subscription={subscription}
+        recurrableIds={recurrableIds}
+      />
+    </Suspense>
+  );
+}

package/template/app/(loja)/carrinho/page.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import * as React from "react";
+import Link from "next/link";
+import Image from "next/image";
+import { useRouter } from "next/navigation";
+import { Trash2, Tag, ArrowRight } from "@/lib/icons";
+import { useCart } from "@/components/cart/cart-provider";
+import { QuantityStepper } from "@/components/quantity-stepper";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Badge } from "@/components/ui/badge";
+import { Separator } from "@/components/ui/separator";
+import { EmptyState } from "@/components/empty-state";
+import { formatBRL } from "@/lib/format";
+import { goToCheckout } from "@/lib/checkout-nav";
+import { trackViewCart, trackPageType } from "@/lib/analytics";
+
+export default function CarrinhoPage() {
+  const router = useRouter();
+  const { cart, updateQty, remove, applyCoupon, removeCoupon, appliedCoupon, loading } = useCart();
+  const [code, setCode] = React.useState("");
+  const items = cart?.items ?? [];
+  const hasDiscount = !!appliedCoupon || (!!cart?.summary.discountTotal && cart.summary.discountTotal !== "R$0,00");
+
+  // dataLayerReady(cart) + view_cart — uma vez por carregamento com item dentro.
+  const trackedRef = React.useRef(false);
+  React.useEffect(() => {
+    if (trackedRef.current || !cart?.items?.length) return;
+    trackedRef.current = true;
+    const list = cart.items.filter((i) => !i.isBonus).map((i) => ({ id: i.productId, name: i.title, variant: i.variantTitle, price: i.unitPrice, quantity: i.quantity }));
+    trackPageType("cart", list);
+    trackViewCart(list, cart.summary.totalAmount);
+  }, [cart]);
+
+  if (!cart || items.length === 0) {
+    return (
+      <EmptyState title="Seu carrinho está vazio" description="Que tal explorar nossos produtos?">
+        <Button nativeButton={false} render={<Link href="/produtos" />}>Ver produtos</Button>
+      </EmptyState>
+    );
+  }
+
+  return (
+    <div>
+      <h1 className="mb-6 text-2xl font-bold">Seu carrinho</h1>
+      <div className="grid gap-8 lg:grid-cols-[1fr_340px]">
+        {/* Itens */}
+        <ul className="divide-y rounded-xl border">
+          {items.map((it) => (
+            <li key={it.id} className="flex gap-4 p-4">
+              <div className="relative h-20 w-20 shrink-0 overflow-hidden rounded-md bg-muted">
+                {it.thumbnail ? (
+                  <Image src={it.thumbnail} alt={it.title} fill sizes="80px" className="object-cover" />
+                ) : (
+                  <div className="flex h-full items-center justify-center text-[10px] text-muted-foreground">sem foto</div>
+                )}
+              </div>
+              <div className="flex flex-1 flex-col">
+                <div className="flex items-start justify-between gap-3">
+                  <div>
+                    <p className="font-medium">{it.title}</p>
+                    {it.variantTitle && <p className="text-sm text-muted-foreground">{it.variantTitle}</p>}
+                    <div className="mt-1 flex flex-wrap gap-1.5">
+                      {it.isRecurring && (
+                        <Badge variant="outline">
+                          Assinatura{cart.recurringFrequencyTitle ? ` · ${cart.recurringFrequencyTitle}` : ""}
+                        </Badge>
+                      )}
+                      {it.isBonus && <Badge>🎁 Brinde</Badge>}
+                    </div>
+                  </div>
+                  <div className="text-right">
+                    <p className="font-medium tabular-nums">{it.isBonus ? "Grátis" : it.displayUnitPrice}</p>
+                    {!it.isBonus && <p className="text-xs text-muted-foreground">cada</p>}
+                  </div>
+                </div>
+                {!it.isBonus && (
+                  <div className="mt-3 flex items-center justify-between gap-3">
+                    <div className="flex items-center gap-2">
+                      <QuantityStepper value={it.quantity} onChange={(q) => updateQty(it.id, q)} disabled={loading} />
+                      <Button variant="ghost" size="sm" onClick={() => remove(it.id)} disabled={loading}>
+                        <Trash2 /> Remover
+                      </Button>
+                    </div>
+                    {it.quantity > 1 && (
+                      <span className="text-sm font-medium tabular-nums">{formatBRL(it.unitPrice * it.quantity)}</span>
+                    )}
+                  </div>
+                )}
+              </div>
+            </li>
+          ))}
+        </ul>
+
+        {/* Resumo */}
+        <aside className="h-fit rounded-xl border p-5">
+          <h2 className="mb-3 font-semibold">Resumo</h2>
+
+          {/* Cupom */}
+          <form
+            className="mb-4"
+            onSubmit={async (e) => {
+              e.preventDefault();
+              if (code.trim() && (await applyCoupon(code.trim()))) setCode("");
+            }}
+          >
+            {hasDiscount ? (
+              <div className="flex items-center justify-between rounded-md bg-muted px-3 py-2 text-sm">
+                <span className="flex items-center gap-1.5">
+                  <Tag className="size-3.5" /> {appliedCoupon?.code ?? "Desconto aplicado"}
+                </span>
+                {appliedCoupon?.discountId && (
+                  <button type="button" className="text-muted-foreground hover:text-destructive" onClick={() => removeCoupon()}>
+                    remover
+                  </button>
+                )}
+              </div>
+            ) : (
+              <div className="flex gap-2">
+                <Input value={code} onChange={(e) => setCode(e.target.value)} placeholder="Cupom de desconto" aria-label="Cupom" />
+                <Button type="submit" variant="outline" disabled={loading || !code.trim()}>Aplicar</Button>
+              </div>
+            )}
+          </form>
+
+          <Separator className="my-3" />
+          <dl className="space-y-1.5 text-sm">
+            <Row label="Subtotal" value={cart.summary.itemTotal} />
+            {cart.summary.discountTotal && cart.summary.discountTotal !== "R$0,00" && (
+              <Row label="Desconto" value={`- ${cart.summary.discountTotal}`} accent />
+            )}
+            <Row label="Frete" value={cart.summary.shippingTotal ?? "calculado no checkout"} />
+          </dl>
+          <Separator className="my-3" />
+          <div className="flex items-center justify-between text-base font-semibold">
+            <span>Total</span>
+            <span>{cart.summary.total ?? "—"}</span>
+          </div>
+
+          <Button className="mt-4 w-full" size="lg" onClick={() => goToCheckout(router)}>
+            Finalizar compra <ArrowRight />
+          </Button>
+          <Button variant="ghost" className="mt-2 w-full" nativeButton={false} render={<Link href="/produtos" />}>
+            Continuar comprando
+          </Button>
+        </aside>
+      </div>
+    </div>
+  );
+}
+
+function Row({ label, value, accent }: { label: string; value?: string; accent?: boolean }) {
+  return (
+    <div className="flex justify-between">
+      <dt className="text-muted-foreground">{label}</dt>
+      <dd className={`tabular-nums ${accent ? "font-medium text-[var(--store-primary)]" : ""}`}>{value ?? "—"}</dd>
+    </div>
+  );
+}

package/template/app/(loja)/categoria/[tagSlug]/layout.tsx

@@ -0,0 +1,31 @@
+// ═══ POR QUE ESTE LAYOUT EXISTE (não é organização de código) ═══
+// Ele valida a existência da categoria e chama notFound() ANTES da página. Sem isso a
+// rota devolvia HTTP 200 com a tela de 404 dentro — um soft-404, que faz o Google
+// indexar página vazia, valida rota quebrada em qualquer checagem por status e
+// contamina destino de 301 e canonical.
+//
+// A causa não é óbvia: o notFound() da page.tsx SEMPRE esteve lá e não adiantava. O
+// loading.tsx deste segmento envolve a página num <Suspense>; o shell fica pronto na
+// hora e é enviado com 200, e quando o notFound() acontece o status já foi. O layout
+// renderiza ACIMA dessa fronteira, então aqui o 404 ainda pode ser emitido.
+// Medido: mesma página, só trocando a presença do loading.tsx → 404 vira 200.
+//
+// getTopTags é React cache(): chamar aqui e na página não duplica requisição.
+import { notFound } from "next/navigation";
+import { getTopTags } from "@/lib/queries";
+import { mockupOr } from "@/lib/mockup";
+
+export default async function CategoriaLayout({
+  children,
+  params,
+}: {
+  children: React.ReactNode;
+  params: Promise<{ tagSlug: string }>;
+}) {
+  const { tagSlug } = await params;
+  // mockupOr: falha da API com credenciais RELANÇA — nunca vira 404 cacheado.
+  const tags = await mockupOr(getTopTags(), [], `categoria/${tagSlug}`);
+  const alvo = decodeURIComponent(tagSlug);
+  if (!(tags as { slug?: string }[]).some((t) => t.slug === alvo)) notFound();
+  return <>{children}</>;
+}

package/template/app/(loja)/categoria/[tagSlug]/loading.tsx

@@ -0,0 +1,17 @@
+import { CatalogGridSkeleton } from "@/components/catalog/grid-skeleton";
+
+export default function Loading() {
+  return (
+    <div>
+      <div className="mb-3 h-5 w-56 animate-pulse rounded bg-muted" />
+      <div className="mb-5 flex flex-wrap items-center justify-between gap-3">
+        <div className="space-y-2">
+          <div className="h-7 w-48 animate-pulse rounded bg-muted" />
+          <div className="h-4 w-24 animate-pulse rounded bg-muted" />
+        </div>
+        <div className="h-9 w-40 animate-pulse rounded-md bg-muted" />
+      </div>
+      <CatalogGridSkeleton count={8} />
+    </div>
+  );
+}

package/template/app/(loja)/categoria/[tagSlug]/page.tsx

@@ -0,0 +1,49 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { getCatalog, getTopTags } from "@/lib/queries";
+import { buildTagMap, buildCategories, mapCatalogItems } from "@/lib/catalog-map";
+import { CatalogClient } from "@/components/catalog/catalog-client";
+import { mockupOr } from "@/lib/mockup";
+import { DataLayerReady } from "@/components/analytics/data-layer-ready";
+
+export const revalidate = 300;
+
+async function findTag(slug: string, tags: any[]) {
+  const decoded = decodeURIComponent(slug);
+  return (tags as any[]).find((t) => t.slug === decoded);
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ tagSlug: string }> }): Promise<Metadata> {
+  const { tagSlug } = await params;
+  const tags = await mockupOr(getTopTags(), [], "categoria/getTopTags");
+  const tag = await findTag(tagSlug, tags as any[]);
+  if (!tag) return { title: "Categoria" };
+  return { title: tag.displayTitle || tag.name, description: tag.description ?? undefined, alternates: { canonical: `/categoria/${encodeURIComponent(tag.slug)}` } };
+}
+
+export default async function CategoryPage({ params }: { params: Promise<{ tagSlug: string }> }) {
+  const { tagSlug } = await params;
+  const [catalog, tags] = await Promise.all([
+    mockupOr(getCatalog({ first: 100 }), ({ nodes: [] as any[] }), "categoria/getCatalog"),
+    mockupOr(getTopTags(), [], "categoria/getTopTags"),
+  ]);
+  const tag = await findTag(tagSlug, tags as any[]);
+  if (!tag) notFound();
+
+  const tagMap = buildTagMap(tags as any[]);
+  const itens = mapCatalogItems(catalog.nodes ?? [], tagMap);
+  // EDITOR: a categoria REAPROVEITA o container "catalogo" de /produtos (mesma faixa de confiança, mesmo
+  // cabeçalho de kits, mesmo aviso de lista vazia) sem mandar na ordem dele: `layout={false}` faz o
+  // manifesto desta página sair com `semLayout`, e o painel explica que a ordem se edita em /produtos.
+  return (
+    <>
+    <DataLayerReady pageType="category" products={itens.slice(0, 12).map((i) => ({ id: i.productId, name: i.title, price: i.price }))} />
+    <CatalogClient
+      items={itens}
+      categories={buildCategories(tags as any[])}
+      initialCategory={tag.displayTitle || tag.name}
+      layout={false}
+    />
+    </>
+  );
+}