@unbox-plus/cli 0.20.4

package/template/scripts/vocabulario.py

@@ -0,0 +1,264 @@
+#!/usr/bin/env python3
+"""Cobertura do vocabulário gráfico — a medida do degrau 1 da escada.
+
+POR QUE ISTO EXISTE
+"Cara de AI" não é falta de capricho: é variedade sem sistema. O olho lê repetição
+como intenção e variedade como acidente. Em TRÊS marcas diferentes, a virada de "podia
+ser de qualquer um" para "tem dono" veio do mesmo movimento — um punhado de marcas
+gráficas próprias, repetidas em toda seção:
+
+    Bicafé    .pilula .selo .micro .numeral .regua   ("é barato e é o que faz o site
+                                                       ter dono")
+    Zé Tona   código de cor por tampa em TODO componente que lista produto
+    Oddie     o estilo adesivo com contorno
+
+E o defeito que este script pega não é a AUSÊNCIA do vocabulário — é ele existir e não
+ter sido distribuído. Medido na Pipó em 04/09/2026:
+
+    pipo-rotulo         24 usos    <- voz tipográfica: distribuída
+    pipo-display        16 usos
+    pipo-filete          1 uso     <- filete dourado 44x2px: a marca da casa
+    pipo-roda            1 uso        usada UMA vez cada
+    pipo-pop             1 uso
+    pipo-parallax        0 usos    <- definida e nunca usada
+
+Uma linha dourada numa seção é decoração. A mesma linha em nove seções é assinatura.
+
+O QUE ELE MEDE
+1. o vocabulário declarado (classes `.<prefixo>-*` no CSS da marca)
+2. quantas vezes cada uma é de fato usada, e quais estão mortas
+3. COBERTURA POR SEÇÃO: quantas seções da receita carregam pelo menos uma marca da casa
+   — uma seção sem nenhuma é uma seção que poderia estar em qualquer loja
+4. cobertura por página (home / catálogo / produto / carrinho), que é onde a assinatura
+   costuma parar: o vocabulário chega na home e não atravessa para as internas
+
+USO
+    vocabulario.py <dir-do-projeto> [--prefixo pipo] [--cobertura 0.7] [--minimo 3]
+
+CÓDIGOS DE SAÍDA
+    0  o vocabulário está distribuído
+    1  existe vocabulário, mas ele não cobre a loja
+    2  O GATE NÃO RODOU (caminho errado, sem CSS, ou nenhuma classe de marca encontrada)
+
+O 2 é o mesmo do escala.py: gate que varre o vazio e diz "limpo" aprova sem ter olhado.
+"""
+import re
+import sys
+import pathlib
+from collections import Counter
+
+# Ancorado na RAIZ do projeto de proposito: `marca/` (briefing) se ignora, mas
+# `components/marca/` e onde vivem os componentes de marca — foi la que a primeira
+# versao deste script perdeu a `pipo-roda` e a declarou morta.
+IGNORAR_RAIZ = {"node_modules", ".next", ".git", "shots", "reviews", "public", "marca"}
+
+# Classes utilitárias do próprio framework não são vocabulário de marca: elas resolvem
+# layout, não identidade. Quem assina a página é o filete, a roda, o selo — não o
+# container da seção.
+SUFIXO_UTILITARIO = re.compile(r"-(secao|tela|trilho|container|grid|wrap|layout|sr)$")
+
+RE_CLASSE_CSS = re.compile(r"^\.([a-z][a-z0-9]*)-([a-z0-9-]+)\s*(?:,|\{|::|:)", re.M)
+
+# Nem toda marca da casa e uma classe CSS. Na Pipo, a chuva de pipoca e a roda
+# tipografica sao COMPONENTES em components/marca/ — a primeira versao deste script
+# so contava classes e reportou o vocabulario como muito menos distribuido do que
+# ele esta: a chuva aparece em 8 lugares, nao em 1.
+DIR_COMPONENTES_MARCA = "components/marca"
+RE_COMPONENTE = re.compile(r"export\s+(?:default\s+)?function\s+([A-Z][A-Za-z0-9]*)")
+
+
+def arquivos(raiz, exts):
+    for p in raiz.rglob("*"):
+        if p.suffix.lower() not in exts:
+            continue
+        rel = p.relative_to(raiz).parts
+        if rel and rel[0] in IGNORAR_RAIZ:
+            continue
+        yield p
+
+
+def descobrir_vocabulario(raiz, prefixo=None):
+    """Lê o CSS e devolve (prefixo, {classe: descricao curta})."""
+    css = list(arquivos(raiz, {".css"}))
+    if not css:
+        return None, {}
+
+    achadas = Counter()
+    por_prefixo = {}
+    for p in css:
+        t = p.read_text(encoding="utf-8", errors="ignore")
+        for m in RE_CLASSE_CSS.finditer(t):
+            pre, resto = m.group(1), m.group(2)
+            achadas[pre] += 1
+            por_prefixo.setdefault(pre, set()).add(f"{pre}-{resto}")
+
+    if prefixo is None:
+        # O prefixo da casa é o que tem mais classes distintas — `pipo-`, `bic-`, `ze-`.
+        # Prefixos de framework (tw, sm, md) não chegam perto em variedade.
+        candidatos = sorted(por_prefixo.items(), key=lambda kv: -len(kv[1]))
+        if not candidatos or len(candidatos[0][1]) < 3:
+            return None, {}
+        prefixo = candidatos[0][0]
+
+    return prefixo, sorted(por_prefixo.get(prefixo, set()))
+
+
+def componentes_de_marca(raiz):
+    """Componentes exportados de components/marca/ — marcas da casa que nao sao classe."""
+    base = raiz / DIR_COMPONENTES_MARCA
+    nomes = set()
+    if base.is_dir():
+        for p in base.rglob("*.tsx"):
+            nomes |= set(RE_COMPONENTE.findall(p.read_text(encoding="utf-8", errors="ignore")))
+    return sorted(nomes)
+
+
+def usos(raiz, classes, comps=()):
+    """Conta uso de cada marca (classe OU componente) e mapeia arquivo -> marcas."""
+    contagem = Counter()
+    por_arquivo = {}
+    base_marca = (raiz / DIR_COMPONENTES_MARCA).resolve()
+    for p in arquivos(raiz, {".tsx", ".jsx"}):
+        # a definicao do componente nao conta como uso dele
+        dentro_da_definicao = str(p.resolve()).startswith(str(base_marca))
+        t = p.read_text(encoding="utf-8", errors="ignore")
+        presentes = set()
+        for c in classes:
+            n = len(re.findall(r"\b" + re.escape(c) + r"\b", t))
+            if n:
+                contagem[c] += n
+                presentes.add(c)
+        if not dentro_da_definicao:
+            for c in comps:
+                n = len(re.findall(r"<" + re.escape(c) + r"\b", t))
+                if n:
+                    contagem[c] += n
+                    presentes.add(c)
+        if presentes:
+            por_arquivo[p] = presentes
+    return contagem, por_arquivo
+
+
+def secoes_da_receita(raiz):
+    for nome in ("components/home/home-recipe.ts", "components/home/home-recipe.tsx"):
+        p = raiz / nome
+        if p.exists():
+            t = p.read_text(encoding="utf-8", errors="ignore")
+            return re.findall(r"\bsection:\s*[\"']([^\"']+)[\"']", t)
+    return []
+
+
+def arquivo_da_secao(raiz, nome):
+    for cand in (
+        raiz / "components/home/sections" / f"{nome}.tsx",
+        raiz / "components/home" / f"{nome}.tsx",
+    ):
+        if cand.exists():
+            return cand
+    return None
+
+
+PAGINAS = {
+    "home": ["components/home"],
+    "catálogo (PLP)": ["components/catalog", "app/(loja)/produtos"],
+    "produto (PDP)": ["components/product", "app/(loja)/produto"],
+    "carrinho": ["components/cart", "app/(loja)/carrinho"],
+}
+
+
+def main():
+    args = sys.argv[1:]
+    if not args:
+        sys.exit(__doc__)
+    raiz = pathlib.Path(args[0]).resolve()
+    prefixo = args[args.index("--prefixo") + 1] if "--prefixo" in args else None
+    alvo_cob = float(args[args.index("--cobertura") + 1]) if "--cobertura" in args else 0.7
+    minimo = int(args[args.index("--minimo") + 1]) if "--minimo" in args else 3
+
+    if not raiz.is_dir():
+        print(f"ERRO: {raiz} nao e um diretorio — o gate NAO RODOU", file=sys.stderr)
+        sys.exit(2)
+
+    prefixo, classes = descobrir_vocabulario(raiz, prefixo)
+    if not classes:
+        print(
+            "ERRO: nenhum vocabulario de marca encontrado no CSS — o gate NAO RODOU.\n"
+            "      Ou a loja nao tem vocabulario proprio (que ja e o achado do degrau 1),\n"
+            "      ou o prefixo precisa vir em --prefixo.",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    comps = componentes_de_marca(raiz)
+    contagem, por_arquivo = usos(raiz, classes, comps)
+
+    # marcas gráficas = o vocabulário menos os utilitários de layout, mais os componentes
+    marcas = [c for c in classes if not SUFIXO_UTILITARIO.search(c)] + list(comps)
+    mortas = [c for c in marcas if contagem[c] == 0]
+    unicas = [c for c in marcas if contagem[c] == 1]
+
+    print(f"Vocabulario grafico: {len(classes)} classes `{prefixo}-*` + {len(comps)} componentes de marca\n")
+    for c in sorted(marcas, key=lambda x: -contagem[x]):
+        n = contagem[c]
+        estado = "MORTA " if n == 0 else ("uso unico" if n == 1 else "")
+        print(f"  {c:<28}{n:>4} usos   {estado}")
+
+    ok = True
+
+    # ── cobertura por seção da home ───────────────────────────────────────────
+    secoes = secoes_da_receita(raiz)
+    if secoes:
+        sem_marca = []
+        for s in secoes:
+            f = arquivo_da_secao(raiz, s)
+            if f is None:
+                continue
+            if not (por_arquivo.get(f, set()) & set(marcas)):
+                sem_marca.append(s)
+        cobertas = len(secoes) - len(sem_marca)
+        frac = cobertas / len(secoes) if secoes else 0
+        print(f"\nCobertura da home: {cobertas}/{len(secoes)} secoes carregam ao menos uma marca da casa")
+        if sem_marca:
+            print("  sem nenhuma marca (poderiam estar em qualquer loja):")
+            for s in sem_marca:
+                print(f"    - {s}")
+        if frac < alvo_cob:
+            print(f"  ABAIXO DO ALVO ({frac:.0%} < {alvo_cob:.0%})")
+            ok = False
+    else:
+        print("\n(sem receita de home encontrada — cobertura por secao nao medida)")
+
+    # ── cobertura por página ──────────────────────────────────────────────────
+    print("\nCobertura por pagina:")
+    for pagina, dirs in PAGINAS.items():
+        marcas_ali = set()
+        for d in dirs:
+            base = raiz / d
+            if not base.exists():
+                continue
+            for f, cs in por_arquivo.items():
+                try:
+                    f.relative_to(base)
+                except ValueError:
+                    continue
+                marcas_ali |= cs & set(marcas)
+        estado = "" if len(marcas_ali) >= minimo else f"  <- abaixo de {minimo}"
+        print(f"  {pagina:<18}{len(marcas_ali):>3} marcas distintas{estado}")
+        if len(marcas_ali) < minimo:
+            ok = False
+
+    if mortas or unicas:
+        print()
+        if mortas:
+            print(f"  {len(mortas)} marca(s) MORTA(S): " + ", ".join(mortas))
+            ok = False
+        if unicas:
+            print(f"  {len(unicas)} marca(s) de USO UNICO: " + ", ".join(unicas))
+            print("    uma marca usada uma vez e decoracao; usada em toda secao e assinatura.")
+            ok = False
+
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/template/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/tools/LEIA-ME.md

@@ -0,0 +1,39 @@
+# tools/ — utilitários de desenvolvimento do CLI
+
+Nada aqui é publicado: o `package.json` só empacota `bin`, `src` e `template`.
+
+- `tokenize-neutrals.mjs` / `tokenize-radius.mjs` — scripts de migração usados uma vez na
+  tokenização da foundation (v0.6).
+- `workflow-storefront.legado.js` — orquestrador multiagente da era "construir um storefront
+  do zero, sem o CLI". **Saiu do `template/` na v0.15.0** por três motivos: o próprio
+  `agents/MANAGER.md` já dizia que ele não se aplica a quem usa o CLI; ele custava ~11k tokens
+  de contexto se o agente o abrisse por engano, com "Regras de Ouro" divergentes das do
+  MANAGER; e as linhas 13-15 tinham caminhos absolutos da máquina do desenvolvedor, que
+  viajavam para dentro do projeto de todo cliente.
+
+  Fica aqui como referência: o padrão dele (agentes em paralelo que NÃO escrevem em disco,
+  devolvem `{path, content}` por schema, e um passo serial grava) é o que a fase multiagente
+  do briefing deve adotar.
+
+## `notion-doc.mjs` — a página do Notion
+
+Gera o conteúdo da página **create-unbox-store — CLI de geração de loja**, em
+`Documentações → Lojas Store` do Notion de tecnologia:
+
+`https://app.notion.com/p/3cbf44e324da8125a0afd7fbe6916247`
+
+```bash
+node tools/notion-doc.mjs
+```
+
+A versão sai do `package.json` e o changelog é extraído do `README.md` — as duas únicas
+fontes da verdade, então a página não pode divergir do pacote. A prosa de apresentação é
+curada dentro do script (uma página para o time não é um despejo do README); as entradas
+`### vX.Y.Z` viram toggles, e a era "Beta" fica condensada em uma linha por versão dentro de
+um toggle único, com o texto integral seguindo no README.
+
+**Depois de todo release:** rode o comando e substitua o conteúdo da página com a saída. O
+próprio topo da página diz isso, para quem chegar por lá não editar o changelog à mão.
+
+O link fica aqui e não no `README.md` de propósito: aquele README viaja dentro do zip
+entregue ao cliente, e não deve apontar para o Notion interno da Unbox.

package/tools/check-template-neutro.mjs

@@ -0,0 +1,111 @@
+// ═══════════════════════════════════════════════════════════════════════════════════════
+// GATE DE NEUTRALIDADE DO TEMPLATE — roda no `prepack`, e o pack FALHA se reprovar.
+//
+// Por que existe: a foundation nasceu de uma loja de temperos e, por duas varreduras, ainda
+// entregava loja de outro ramo com "polvilhe sobre o alimento", "escolha o molho", aba
+// nutricional com traços e selo "Sem glúten" inventado. As varreduras anteriores olharam COR
+// e NOME DE CLIENTE; o que vazava era VOCABULÁRIO DE DOMÍNIO. Este gate olha isso.
+//
+// Por que aqui e NÃO no projeto gerado: uma loja de alimento pode e deve dizer "polvilhe"
+// depois do briefing. O que não pode é a FOUNDATION dizer. Então a checagem é no repositório
+// do CLI, antes de empacotar — e nunca viaja para o cliente.
+//
+// Escopo: código e docs que o agente lê ou o cliente vê. Comentário conta: comentário
+// ensina o agente a escrever igual.
+// ═══════════════════════════════════════════════════════════════════════════════════════
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RAIZ = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const TEMPLATE = path.join(RAIZ, "template");
+const EXTS = new Set([".ts", ".tsx", ".md", ".json", ".css", ".svg", ".txt", ".mjs"]);
+const IGNORAR_DIRS = new Set(["node_modules", ".next", "qa"]);
+
+// [regex, por quê]. Só termos SEM uso legítimo numa foundation neutra. "alimento",
+// "nutricional", "glúten" ficam de fora de propósito: aparecem em código CONDICIONAL correto
+// ("tabela nutricional só se for alimento") e o gate não pode punir isso.
+const PROIBIDOS = [
+  [/\bbadia\b|\bblessy\b|\bzetona\b|\bzétona\b|\boddie\b/i, "nome de cliente"],
+  [/polvilh/i, "instrução de uso de tempero"],
+  [/\btemperos?\b|\btempere\b|\btemperad[oa]s?\b/i, "vocabulário de tempero"],
+  [/\bespeciarias?\b|\bcondimentos?\b/i, "vocabulário de tempero"],
+  [/p[aá]prica|or[eé]gano|cominho|a[cç]afr[aã]o|chimichurri|lemon pepper|sriracha|garlic|alho em p[oó]/i, "produto de tempero"],
+  [/\bmolhos?\b(?! de contato)/i, "produto de alimentação"],
+  [/marinad[ao]s?|churrasco|festa junina/i, "contexto de alimentação"],
+  [/\bsabor(es)?\b/i, "copy de alimentação ('mais sabor')"],
+  [/porção 1 ?g\b/i, "porção de tempero cravada"],
+  [/Cliente [A-C]\. .*(tempero|prato|receita de)/i, "depoimento de alimentação"],
+];
+
+// Trechos permitidos: a explicação do próprio bug, em comentário, precisa poder citar a
+// palavra uma vez. Mantém a lista CURTA — todo item aqui é uma exceção que alguém revisou.
+const PERMITIDOS = [
+  "tools/",                                  // este diretório
+  "README.md::### v0.15",                    // changelog descreve o bug
+];
+
+const achados = [];
+function varrer(dir) {
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, ent.name);
+    if (ent.isDirectory()) { if (!IGNORAR_DIRS.has(ent.name)) varrer(p); continue; }
+    if (!EXTS.has(path.extname(ent.name))) continue;
+    const rel = path.relative(RAIZ, p);
+    const linhas = fs.readFileSync(p, "utf8").split("\n");
+    linhas.forEach((linha, i) => {
+      for (const [re, motivo] of PROIBIDOS) {
+        if (!re.test(linha)) continue;
+        const chave = `${rel}::${linha.trim().slice(0, 30)}`;
+        if (PERMITIDOS.some((ok) => rel.startsWith(ok) || chave.startsWith(ok))) continue;
+        achados.push({ rel, n: i + 1, motivo, texto: linha.trim().slice(0, 110) });
+        break;
+      }
+    });
+  }
+}
+varrer(TEMPLATE);
+
+// ── Travessão no texto que o CLI IMPRIME ─────────────────────────────────────
+// O template tem gate próprio (scripts/check-unbox-brand.mjs). Aqui pega o outro lado: as
+// perguntas, avisos e mensagens do wizard, e os cabeçalhos que o CLI escreve dentro do projeto.
+// Comentário de código fica de fora: é nota de engenharia, não texto para quem lê a tela.
+function semComentario(linha, dentroDeBloco) {
+  let out = "", aspas = null, bloco = dentroDeBloco;
+  for (let i = 0; i < linha.length; i++) {
+    const c = linha[i], prox = linha[i + 1];
+    if (bloco) { if (c === "*" && prox === "/") { bloco = false; i++; } continue; }
+    if (aspas) {
+      if (c === "\\") { out += c + (prox ?? ""); i++; continue; }
+      if (c === aspas) aspas = null;
+      out += c; continue;
+    }
+    if (c === '"' || c === "'" || c === "`") { aspas = c; out += c; continue; }
+    if (c === "/" && prox === "/") break;
+    if (c === "/" && prox === "*") { bloco = true; i++; continue; }
+    out += c;
+  }
+  return { texto: out, bloco };
+}
+for (const arquivo of ["bin/cli.js", "src/theme.js", "src/presets.js", "src/colors.js"]) {
+  const caminho = path.join(RAIZ, arquivo);
+  if (!fs.existsSync(caminho)) continue;
+  let bloco = false;
+  fs.readFileSync(caminho, "utf8").split("\n").forEach((linha, i) => {
+    const r = semComentario(linha, bloco);
+    bloco = r.bloco;
+    if (r.texto.includes("\u2014")) {
+      achados.push({ rel: arquivo, n: i + 1, motivo: "travessão no texto impresso pelo CLI", texto: linha.trim().slice(0, 110) });
+    }
+  });
+}
+
+if (achados.length) {
+  console.error(`\n✗ PACK BLOQUEADO — a foundation tem ${achados.length} resíduo(s) de domínio:\n`);
+  for (const a of achados) console.error(`   ${a.rel}:${a.n}  [${a.motivo}]\n      ${a.texto}`);
+  console.error("\n  A foundation é neutra: nada de vocabulário de um ramo específico, nem em comentário.");
+  console.error("  E o texto que o CLI imprime não usa travessão: vírgula, dois-pontos, ponto ou \"·\".");
+  console.error("  Loja de alimento escreve isso DEPOIS, no briefing. Corrija e rode de novo.\n");
+  process.exit(1);
+}
+console.log("✓ Foundation neutra (sem vocabulário de domínio nem nome de cliente)");

package/tools/notion-doc.mjs

@@ -0,0 +1,191 @@
+// ═══════════════════════════════════════════════════════════════════════════════════════
+// GERADOR DA PÁGINA DO NOTION — node tools/notion-doc.mjs
+//
+// Emite o conteúdo da página "create-unbox-store — CLI de geração de loja" em Notion-flavored
+// Markdown, pronto pra ser passado ao update-page do MCP do Notion.
+//
+// Existe pra que "manter a página atualizada" seja um comando, não um trabalho manual que
+// ninguém lembra de fazer no dia do release. A versão vem do package.json e o changelog é
+// extraído do README.md — as duas únicas fontes da verdade. Rode depois de todo release e
+// atualize a página com a saída.
+//
+// A prosa de apresentação é curada aqui (uma página de Notion para o time não é um despejo
+// do README). O changelog é mecânico: toda entrada "### vX.Y.Z" do README vira um toggle.
+// ═══════════════════════════════════════════════════════════════════════════════════════
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const RAIZ = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(fs.readFileSync(path.join(RAIZ, "package.json"), "utf8"));
+const readme = fs.readFileSync(path.join(RAIZ, "README.md"), "utf8");
+const VERSAO = pkg.version;
+
+// ── Changelog: extrai as entradas "### vX" / "### Beta vX" do README ────────────────────
+function extrairChangelog() {
+  const linhas = readme.split("\n");
+  const ini = linhas.findIndex((l) => l.trim() === "## Changelog");
+  if (ini === -1) throw new Error("seção '## Changelog' não encontrada no README.md");
+
+  const entradas = [];
+  let atual = null;
+  for (const linha of linhas.slice(ini + 1)) {
+    const m = linha.match(/^### (.+)$/);
+    if (m) {
+      if (atual) entradas.push(atual);
+      atual = { titulo: m[1].trim(), corpo: [] };
+    } else if (atual) {
+      atual.corpo.push(linha);
+    }
+  }
+  if (atual) entradas.push(atual);
+  return entradas;
+}
+
+// Markdown do README → Notion-flavored. As diferenças que importam:
+//  • parágrafo quebrado em várias linhas vira UMA linha (no Notion, \n encerra o bloco);
+//  • item de lista com continuação indentada é juntado no mesmo item;
+//  • o resto (negrito, código inline, links) é compatível.
+function paraNotion(corpo) {
+  const out = [];
+  for (const bruta of corpo) {
+    const linha = bruta.replace(/\s+$/, "");
+    if (!linha.trim()) { out.push(""); continue; }
+    const ehItem = /^\s*[-*]\s+/.test(linha);
+    const ehTitulo = /^#{1,6}\s/.test(linha);
+    const ehCodigo = /^\s*```/.test(linha);
+    const continuacao = /^\s+\S/.test(linha) && !ehItem && !ehCodigo;
+    if ((continuacao || (!ehItem && !ehTitulo && !ehCodigo)) && out.length && out[out.length - 1]) {
+      // continua o bloco anterior em vez de abrir um novo
+      const ant = out[out.length - 1];
+      if (!/^\s*```/.test(ant)) { out[out.length - 1] = ant + " " + linha.trim(); continue; }
+    }
+    out.push(ehItem ? "- " + linha.replace(/^\s*[-*]\s+/, "") : linha.trim());
+  }
+  return escaparAngulos(out.join("\n").replace(/\n{3,}/g, "\n\n").trim());
+}
+
+// O Notion lê "<algo>" fora de crase como bloco/tag XML. Escapa só o que está solto —
+// dentro de crase (código inline e blocos) o conteúdo é literal e não pode ser tocado.
+function escaparAngulos(texto) {
+  const partes = texto.split(/(```[\s\S]*?```|`[^`\n]*`)/g);
+  return partes.map((p, i) => (i % 2 ? p : p.replace(/</g, "\\<").replace(/>/g, "\\>"))).join("");
+}
+
+const entradas = extrairChangelog();
+// Detalhe integral só na era da arquitetura atual (v0.12.13+, quando o versionamento foi
+// unificado). O histórico anterior vira uma linha por versão dentro de um toggle: ninguém lê
+// 35 changelogs completos, e o texto integral continua no README do pacote.
+const DETALHADAS = entradas.findIndex((e) => /^Beta v/.test(e.titulo));
+const corte = DETALHADAS === -1 ? entradas.length : DETALHADAS;
+
+const detalhadas = entradas.slice(0, corte).map((e, i) => {
+  const corpo = paraNotion(e.corpo);
+  const marca = i === 0 ? " · atual" : "";
+  return `### ${e.titulo}${marca} {toggle="true"}\n` +
+    corpo.split("\n").map((l) => (l ? "\t" + l : "")).join("\n");
+}).join("\n");
+
+// Uma linha por versão antiga: título + primeira frase do corpo.
+const antigas = entradas.slice(corte).map((e) => {
+  const texto = paraNotion(e.corpo)
+    .split("\n").map((l) => l.replace(/^-\s*/, "").trim()).filter(Boolean)[0] ?? "";
+  let resumo = texto.split(/(?<=\.)\s/)[0].slice(0, 170).replace(/[\s:—-]+$/, "");
+  if (resumo.length >= 170) resumo += "…";
+  return `- **${e.titulo}** — ${resumo}`;
+}).join("\n");
+
+const changelog = detalhadas + `
+
+<details>
+<summary>Histórico anterior (${entradas.length - corte} versões, era "Beta")</summary>
+` + antigas.split("\n").map((l) => "\t" + l).join("\n") + `
+\t
+\tO texto integral de cada uma está no \`README.md\` dentro do pacote.
+</details>`;
+
+// ── A página ────────────────────────────────────────────────────────────────────────────
+const pagina = `<callout icon="📦" color="blue_bg">
+	**Versão atual: v${VERSAO}** — entregue como \`CLI - Unbox v${VERSAO}.zip\`, que contém \`create-unbox-store.tgz\` e o README completo.
+	O nome do tarball é sempre \`create-unbox-store.tgz\`, **sem versão** — a versão fica dentro do pacote. Zips antigos traziam a versão no nome do arquivo e isso gerava erro de \`npx\` quando o comando não batia com o nome real.
+</callout>
+
+<callout icon="🔄" color="gray_bg">
+	Esta página é gerada a partir do \`README.md\` e do \`package.json\` do CLI. Para atualizá-la depois de um release, rode \`node tools/notion-doc.mjs\` no repositório do CLI e substitua o conteúdo com a saída. Não edite o changelog aqui à mão: ele será sobrescrito.
+</callout>
+
+## O que é
+
+CLI de dependência zero (só \`prompts\`) que gera um **storefront Next.js 15 completo**, integrado com a API headless da Unbox, já com a marca do cliente aplicada: layout, fontes, neutros, cores e nome da loja.
+
+O que sai do CLI é **fundação**, não loja pronta. A personalização de verdade acontece logo depois, no briefing de marca conduzido pelo Claude Code — e é de propósito: o cliente é entrevistado **antes** de ver qualquer coisa, para não ancorar a expectativa dele no padrão.
+
+## Como usar
+
+Único pré-requisito da máquina: **Node.js** ([nodejs.org](https://nodejs.org), botão LTS). Coloque o \`create-unbox-store.tgz\` na pasta onde quer criar o projeto e rode:
+
+\`\`\`bash
+npx --package=./create-unbox-store.tgz create-unbox-store
+\`\`\`
+
+<callout icon="⚠️" color="yellow_bg">
+	Use sempre a forma com \`--package=\`. O \`npx ./create-unbox-store.tgz\` sem ela dá erro de permissão em algumas versões do npm.
+</callout>
+
+O CLI pergunta 12 coisas: nome do projeto e da loja, cor primária e de CTA, site e Instagram da marca, objetivo em uma frase, **estilo visual** (Essencial, Promocional, Editorial ou Boutique), credenciais da Unbox, tipo de checkout, o segredo de captcha (só com key de parceiro) e se roda \`npm install\`. Tudo menos as credenciais fica em \`marca/briefing.json\`, para o agente de marca não reperguntar.
+
+Sem credenciais em mãos, responda "não": o projeto sobe em **modo mockup** com o layout completo e sem dados reais. Preenche o \`.env.local\` depois.
+
+### O passo seguinte não é \`npm run dev\`
+
+\`\`\`bash
+cd <nome-do-projeto>
+claude
+\`\`\`
+
+O Claude Code abre direto no briefing de marca e conduz a personalização. Encerrado o briefing, o próprio agente remove a chave que força esse modo e as sessões seguintes voltam ao normal.
+
+### Sem interação (CI ou testes)
+
+\`\`\`bash
+npx --package=./create-unbox-store.tgz create-unbox-store minha-loja --yes --no-install
+\`\`\`
+
+Use \`--estilo <essencial|promocional|editorial|boutique>\` para escolher o preset sem interação.
+
+## O que o projeto gerado traz
+
+Next.js 15 (App Router) + Tailwind v4 + shadcn/ui sobre Base UI, com catálogo, carrinho, checkout, área do cliente (login por OTP, pedidos, assinaturas, endereços), páginas legais, PWA e SEO básico já implementados. \`DEPLOY.md\` e \`QA.md\` dentro do projeto trazem o checklist de publicação na Vercel.
+
+O projeto também vem com um \`CLAUDE.md\` que mapeia "quero mudar X, mexo em Y", e com \`agents/MANAGER.md\`, que descreve a ordem dos passos: **15 (Branding) primeiro**, depois os opcionais 13 (CRO) e 14 (SEO), e por último 12 (Deploy).
+
+### Portões de qualidade
+
+| Comando | O que faz |
+| --- | --- |
+| \`npm run typecheck\` | o gate mais barato, rode primeiro |
+| \`npm run build\` | dispara o prebuild de marca (bloqueia sem o selo Powered by Unbox ou sem o GTM) |
+| \`npm run unbox:honestidade\` | promessa comercial ou prova social sem lastro |
+| \`npm run unbox:receita\` | variedade da composição da home (mede, não bloqueia) |
+| \`npm run unbox:qa\` | screenshots do QA com emulação de dispositivo |
+| \`npm run unbox:dump\` | imprime o catálogo e as promoções **reais** da loja |
+
+## Antes de publicar — decisões que não são do CLI
+
+A fundação traz placeholders que funcionam mas **precisam de uma decisão consciente**. O CLI não resolve isso sozinho de propósito: seria tomar a decisão no lugar de quem publica.
+
+1. **Prova social: a foundation não traz nenhuma.** Sem avaliação real em \`lib/enrichment/products.json\`, a loja não mostra nota, estrelas, contagem nem depoimento (o bloco some, não cai em placeholder). Decida antes de publicar: popular com dados reais ou publicar sem prova social. O agente de Branding pede esse material no briefing; o \`unbox:honestidade\` lista qualquer número ou promessa que entrar sem lastro.
+2. **CRO: 1 de 10 módulos na fundação.** Só a barra de frete grátis vem pronta. Os outros nove são do agente 13, que o briefing oferece ao terminar (o wizard não pergunta mais sobre isso).
+3. **SEO avançado: o básico está, os 7 módulos não.** JSON-LD de produto, Organization + WebSite/SearchAction, imagem Open Graph gerada e canonical por página já vêm. Breadcrumbs, FAQ schema, OG por produto e templates de título/description são do agente 14.
+4. **Kits e combos vêm vazios.** A seção só aparece depois que alguém popular os kits reais.
+
+<callout icon="🧭" color="gray_bg">
+	A regra que orienta tudo isso: **um campo vazio declarado é melhor que um campo plausível inventado.** Quando falta material real, o certo é registrar a pendência, não preencher com algo verossímil. É no briefing e na fundação que um valor plausível vira lei sem ninguém questionar.
+</callout>
+
+## Changelog
+
+${changelog}
+`;
+
+process.stdout.write(pagina);