create-sdd-ai-stack 0.1.17

package/AGENTS.md

@@ -0,0 +1,164 @@
+# 🤖 LEIS ABSOLUTAS DO AGENTE IA (AGENTS.md)
+
+> 🛑 **VOCÊ É UM AGENTE AUTÔNOMO** sob Spec-Driven Development (SDD).
+> Sua memória falha em contexto longo. **Sua ÚNICA fonte da verdade são os arquivos de especificação deste repositório.** Se está aqui, vale. Se não está, não invente.
+
+> 📦 **Onde este arquivo mora:** na raiz do pacote `create-sdd-ai-stack`.
+> Quando instalado num projeto, ele fica em **`SDD/AGENTS.md`** e todos os caminhos abaixo são relativos a `SDD/`.
+> Por isso todos os links usam prefixo `SDD/`.
+
+---
+
+## 🎯 0. RESUMO EXECUTIVO (30 segundos)
+
+| Pergunta | Resposta |
+| --- | --- |
+| Stack padrão? | **Next.js 16** (App Router) |
+| Backend extra? | **Node.js** puro, só para worker/cron/webhook |
+| Onde eu leio as regras? | `SDD/` — comece por `SDD/AGENTS.md` (este arquivo) |
+| O que eu faço primeiro? | Ler `SDD/specs/PLAN.md` e pegar a **única** task `[-]` |
+| Quando paro? | Quando a task virar `[x]` e eu colar a evidência do terminal |
+| Posso editar regras? | **NÃO.** Ver [§6](#-6-regra-de-permissão-de-docs) |
+| Como commito? | Conventional Commits + identidade fixa. Ver `SDD/stacks/git.md` |
+
+---
+
+## 📚 1. MAPEAMENTO DE CONTEXTO (ordem obrigatória de leitura)
+
+Sempre que for acionado, leia nesta exata ordem:
+
+1. **`SDD/AGENTS.md`** (este arquivo) — leis e fluxo.
+2. **`SDD/specs/PLAN.md`** — a **única** tarefa pendente agora.
+3. **`SDD/APP.md`** + **`SDD/APP-STACK.md`** — o que é este app e qual a stack dele.
+4. **`SDD/ARCHITECTURE.md`** — arquitetura global.
+5. **`SDD/NEXT.md`** — regras da stack padrão (ou o doc da stack deste app, se `APP-STACK.md` apontar outro).
+6. **`SDD/DESIGN.md`** — regras de UI/UX (só se for mexer em UI).
+7. **`SDD/stacks/README.md`** — índice das regras por ferramenta (só se precisar).
+
+> ⚠️ **Regra de hiperfoco (TDAH):** leia **o mínimo necessário**. Não leia tudo "por garantia". Abra o doc da stack só quando a task exigir.
+
+---
+
+## 🗺️ 2. ROTEADOR DE REGRAS (onde está o quê)
+
+```text
+SDD/
+├── AGENTS.md          ← VOCÊ ESTÁ AQUI (leis + fluxo)
+├── APP.md             ← o que é este app (regras de negócio)
+├── APP-STACK.md       ← qual stack este app usa (ponteiro)
+├── ARCHITECTURE.md    ← arquitetura global (vertical slices)
+├── DESIGN.md          ← design system (tokens, tipografia, componentes)
+├── NEXT.md            ← Next.js 16  ⭐ STACK PADRÃO
+├── NODE.md            ← Node.js puro (worker, cron, fila)
+├── REACT.md           ← React (hooks, estado, composição)
+├── stacks/            ← regras por linguagem/ferramenta
+│   ├── typescript.md  tailwind.md  shadcn.md  testing.md
+│   └── database.md    ai.md        git.md     ci.md
+├── specs/             ← SDD operacional
+│   ├── PLAN.md        (a task AGORA)
+│   ├── BACKLOG.md     (ideias soltas, débito técnico)
+│   ├── ROADMAP.md     (visão macro)
+│   ├── history/phases/  (fases concluídas)
+│   └── tasks/         (TASK-PHASE-TASK.md)
+├── docs/
+│   ├── PRODUCT.md     changelog        PLANNING.md
+└── SKILLS/            ← automações (scripts) do projeto
+```
+
+| Preciso saber...            | Abra                          |
+| --------------------------- | ----------------------------- |
+| A próxima task              | `specs/PLAN.md`               |
+| As regras do Next.js        | `NEXT.md`                     |
+| Tokens de cor/fonte         | `DESIGN.md`                   |
+| Como commitar                | `stacks/git.md`               |
+| Como escrever teste          | `stacks/testing.md`           |
+| Regras de TypeScript         | `stacks/typescript.md`        |
+| Estrutura de pasta           | `ARCHITECTURE.md`             |
+| Qual stack este app usa      | `APP-STACK.md`                |
+
+---
+
+## 🧠 3. COMPORTAMENTO OBRIGATÓRIO
+
+1. **Proativo e criativo, mas disciplinado.** Sugira melhoria de arquitetura, mas **pergunte antes** de alterar regra.
+2. **Fim de ciclo = comemorar e perguntar.** Ao concluir uma fase: comemore, pergunte ao humano se segue, ou sugira o próximo desafio.
+3. **Não invente regra.** Se a resposta não está em `SDD/`, **pergunte**. Nunca "improvisar" arquitetura.
+4. **Falhou o teste? Pare.** Volte, corrija, rode de novo. **PROIBIDO avançar com teste vermelho.**
+5. **Tamanho de task:** o dev tem TDAH. Se a task levar > 1h, **quebre em duas** antes de começar.
+
+---
+
+## 🔄 4. FLUXO DE ENTREGA (o gated workflow)
+
+Ao encontrar sua task em `specs/PLAN.md`:
+
+1. **Refinar** — leia a task + o doc de regra relevante. Entenda 100% antes de escrever.
+2. **Instalar pacotes** — **NUNCA** rode `npm install` na raiz. Use `cd` explícito se houver sub-pastas.
+3. **Implementar** — só o necessário (máx 5 arquivos por passo). Use scripts de `SKILLS/` quando existirem.
+4. **Testar** — `typecheck` + `test:unit` + `test:e2e`. Crie teste de TODO tipo: unit, integração, E2E. Mokar dados para teste rápido.
+5. **Prova de vida anti-alucinação** — para marcar `[x]`, **cole o output verde do terminal** na resposta (comando + resultado + evidência Playwright). **Você está PROIBIDO de mentir sobre teste.**
+6. **Concluir** — marque `[x]` em `specs/PLAN.md` e **encerre a resposta**.
+
+### Loop de falha 🛑
+> Erro? Volte. Corrija. Teste de novo. **Teste vermelho = task não concluída.** Sem exceção, sem "deve funcionar".
+
+---
+
+## 🛠️ 5. SISTEMA DE SKILLS (automação)
+
+- Se um padrão se repete, **transforme em SKILL**: script em `SDD/SKILLS/<nome>/`.
+- Antes de codar na mão, verifique se já existe uma SKILL que faz isso.
+- Mantenha nomes descritivos para que **você mesmo** consiga descobrir e rodar.
+
+---
+
+## 🌿 6. REGRA DE PERMISSÃO DE DOCS
+
+| Ação | Permissão |
+| --- | --- |
+| Atualizar `specs/PLAN.md`, `specs/tasks/*`, `docs/changelog.md`, `docs/PRODUCT.md`, `docs/PLANNING.md` | ✅ **AUTOMÁTICO** (obrigatório após mudança) |
+| Criar task nova em `specs/tasks/` | ✅ Automático quando a fase pedir |
+| Editar `APP-STACK.md` para trocar a stack do app | ✅ Automático (é configuração do projeto) |
+| **Editar** `NEXT.md`, `NODE.md`, `REACT.md`, `DESIGN.md`, `ARCHITECTURE.md`, `AGENTS.md`, `stacks/*` | 🛑 **PROIBIDO sem pedir** ao humano primeiro |
+
+> Se identificar melhoria nessas arquiteturas, **PERGUNTE** antes de mudar. Elas são a lei do template.
+
+---
+
+## 📝 7. GIT, COMMIT E VERSIONAMENTO
+
+- **Gitflow + Conventional Commits + SemVer com tags.**
+- **Identidade fixa:** Marcelino Sandroni <marcelino.sandroni@gmail.com>.
+- **Padrão de mensagem:** `tipo(escopo): descrição curta. (Agent: <Ferramenta> - <Modelo>)`
+  - Ex.: `feat(chat): cria interface IVideo. (Agent: Cursor - Claude)`
+  - Tipos: `feat` `fix` `refactor` `test` `docs` `chore` `perf` `style` `build` `ci`.
+- Detalhes completos: `stacks/git.md`.
+
+### Limpeza de memória (fim de fase)
+Quando **todas** as tasks da fase no `specs/PLAN.md` estiverem `[x]`:
+1. Resuma a fase em `specs/history/phases/phase-N-finished.md`.
+2. Apague as tasks concluídas de `specs/tasks/`.
+3. Gere a tag SemVer: `git tag vX.Y.Z`.
+4. **Um** commit de arquivamento.
+5. Limpe o `specs/PLAN.md` e pergunte: **"Qual o próximo desafio, chefe?"**
+
+---
+
+## 🚨 8. ARMADILHAS CONHECIDAS (Next 16)
+
+Não caia nestas (detalhes em `NEXT.md` §11):
+- `params`/`searchParams`/`cookies()`/`headers()` são **async**.
+- `middleware.ts` foi renomeado para **`proxy.ts`** (função `proxy`). Arquivo antigo é ignorado em silêncio.
+- `revalidateTag(tag)` de 1 argumento **depreciado** → use `updateTag` em actions.
+- `next lint` **removido** → use Biome/ESLint direto.
+- `export const dynamic/revalidate` **não existem** com `cacheComponents` → use `'use cache'` + `cacheLife`.
+- Turbopack é o **padrão** do build.
+- Parallel routes exigem `default.js` explícito.
+
+---
+
+## 🧭 9. COMO ESTE PROJETO FOI MONTADO
+
+- Este repositório é o **template** (`create-sdd-ai-stack`). As regras vivem em `SDD/`.
+- Consumo: `npx create-sdd-ai-stack meu-app` (copia as regras + o template Next) **ou** `git submodule add ... SDD` (só as regras).
+- Detalhes: [`README.md`](./README.md).

package/APP-STACK.md

@@ -0,0 +1,31 @@
+# 🧠 APP-STACK (qual stack este app usa)
+
+> **Ponteiro de stack.** O agente lê o doc aqui e abre o arquivo de regras correspondente.
+> Trocar este arquivo é **automático** (é configuração do projeto). Trocar as regras em si, **não**.
+
+---
+
+## 🎯 Stack ativa
+
+| Papel | Stack | Documento de regras |
+| --- | --- | --- |
+| **App (frontend + backend)** | **Next.js 16** — App Router | [NEXT.md](./NEXT.md) ⭐ **STACK PADRÃO** |
+| **UI library** | shadcn/ui + Tailwind CSS v4 | [stacks/shadcn.md](./stacks/shadcn.md) · [stacks/tailwind.md](./stacks/tailwind.md) |
+| **Linguagem** | TypeScript (strict) | [stacks/typescript.md](./stacks/typescript.md) |
+| **Backend extra** | Node.js puro (workers, cron, filas) | [NODE.md](./NODE.md) |
+| **Banco de dados** | Prisma ORM | [stacks/database.md](./stacks/database.md) |
+| **Validação** | Zod | [stacks/typescript.md](./stacks/typescript.md) |
+| **Testes** | Vitest + Playwright | [stacks/testing.md](./stacks/testing.md) |
+| **IA / LLM** | (se o app usar) | [stacks/ai.md](./stacks/ai.md) |
+| **Deploy** | Vercel | [stacks/ci.md](./stacks/ci.md) |
+| **Versionamento** | Git + Conventional Commits | [stacks/git.md](./stacks/git.md) |
+
+---
+
+## 🔀 Como trocar a stack do app
+
+1. Edite a tabela acima com a stack real deste projeto.
+2. Se usar uma stack que não tem doc aqui, crie `SDD/stacks/<stack>.md` seguindo o padrão dos outros.
+3. **Não mexa** em `AGENTS.md` §1 (que aponta o doc padrão) sem pedir ao humano.
+
+> Enquanto `APP-STACK.md` apontar para `NEXT.md`, a stack padrão do template é Next.js.

package/APP.md

@@ -0,0 +1,46 @@
+# 🚀 [NOME DO SEU APP AQUI]
+
+> ⚠️ **FOCA AQUI:** Substitua esse bloco pela descrição real da aplicação. O que ela faz? Qual problema resolve? Quem é o usuário final? Direto ao ponto, sem enrolação.
+
+## 🏗️ Stack e Arquitetura
+
+Este projeto segue **Spec-Driven Development** com **Next.js 16** e **Vertical Slices**.
+
+**Leia antes de tocar em uma linha de código:**
+
+| Documento | Escopo |
+| --- | --- |
+| [🤖 AGENTS.md](./AGENTS.md) | **Leis do agente + fluxo de entrega (LEIA PRIMEIRO)** |
+| [🎯 specs/PLAN.md](./specs/PLAN.md) | A task que está sendo feita AGORA |
+| [🧠 APP-STACK.md](./APP-STACK.md) | Qual stack este app usa (ponteiro) |
+| [⚛️ NEXT.md](./NEXT.md) | Regras do Next.js 16 — **stack padrão** |
+| [🟢 NODE.md](./NODE.md) | Regras do Node.js puro (workers, cron, filas) |
+| [⚛️ REACT.md](./REACT.md) | Regras do React |
+| [🎨 DESIGN.md](./DESIGN.md) | Design system (tokens, tipografia, componentes) |
+| [🏗️ ARCHITECTURE.md](./ARCHITECTURE.md) | Arquitetura global (vertical slices) |
+| [🧱 stacks/](./stacks/README.md) | TypeScript, Tailwind, shadcn, testes, DB, IA, Git, CI |
+
+## 🛠️ Stack Principal
+
+- **App (fullstack):** Next.js 16 (App Router, Server Actions, Route Handlers)
+- **UI:** React 19.2 (Server Components por padrão) + Tailwind v4 + shadcn/ui
+- **Dados:** Prisma + [PostgreSQL / MySQL / SQLite]
+- **Validação:** Zod
+- **Testes:** Vitest (unit/integr) + Playwright (E2E)
+- **Backend extra (se houver):** Node.js puro para worker/cron/fila
+- **Deploy:** [Vercel / Node VPS / Railway]
+
+---
+
+## 📝 Detalhes Específicos do App
+
+*(Escreva AQUI as regras de negócio únicas, integrações e fluxos que só este app tem. **Não deixe em branco**.)*
+
+- **Integrações de Terceiros:** [Ex: OpenAI, Stripe, WhatsApp API]
+- **Features Principais:**
+  - [Ex: Geração de vídeo por IA]
+  - [Ex: Dashboard de métricas executivas]
+- **Regras Críticas de Negócio:**
+  - [Ex: O usuário só pode gerar 5 vídeos por dia na conta free]
+- **Entidades de Domínio:** [Liste as entidades principais e suas invariantes]
+- **Regras de Autorização:** [Ex: Admin vê tudo; membro só o próprio workspace]

package/ARCHITECTURE.md

@@ -0,0 +1,115 @@
+# 🏗️ ARQUITETURA GLOBAL
+
+> **Next.js 16, App Router, Vertical Slices.** Sem `client/` vs `server/` separado — o framework já é a fronteira.
+
+## 🧠 O princípio
+
+Uma **feature** (fatia vertical) é a unidade de mudança. Ela carrega **tudo** que aquele domínio precisa:
+
+```text
+src/features/chat/
+├── domain/          # Entidades, contratos (I*.ts) — ZERO dependência externa
+├── application/     # Use cases (lógica de negócio pura)
+├── infrastructure/  # Prisma, HTTP client, filas, storage
+├── container.ts     # Montagem de dependências (DI do slice)
+├── queries.ts       # Entrada de LEITURA
+├── actions.ts       # Entrada de ESCRITA (Server Actions)
+└── ui/              # Componentes do domínio
+```
+
+**Consequência prática:** para entender um requisito, você abre **uma** pasta. Nada se espalha.
+
+## 📂 Estrutura root
+
+```text
+meu-projeto/
+├── src/
+│   ├── app/          # ROTEAMENTO (só roteia, zero regra de negócio)
+│   ├── features/     # 🌟 SLICES DE DOMÍNIO
+│   ├── shared/       # Genérico compartilhado
+│   │   ├── ui/       # Design system (shadcn)
+│   │   ├── lib/      # Helpers puros
+│   │   ├── server/   # server-only: db, auth, env, logger
+│   │   └── hooks/    # Hooks transversais
+│   └── proxy.ts      # Network boundary (opcional)
+├── SDD/              # As regras (submodule) ← o que o agente lê
+├── tests/            # unit/ integration/ e2e/
+└── public/
+```
+
+## 🔀 Fluxo de uma requisição
+
+```text
+Browser
+  ↓
+proxy.ts (rede: redirect, rewrite)  ← NÃO é segurança
+  ↓
+app/…/page.tsx  (Server Component)
+  ↓
+features/x/queries.ts   (leitura, com 'use cache' se cabível)
+  ↓
+features/x/application/ (use case)
+  ↓
+features/x/infrastructure/ (Prisma / API externa)
+  ↓
+render (PPR: shell estático + conteúdo dinâmico)
+```
+
+```text
+Browser <form action={…}>
+  ↓
+app/…/page.tsx  (Server Action) — auth → zod → autorização → use case → cache
+  ↓
+revalidate / updateTag
+  ↓
+re-render do shell
+```
+
+## 🧩 Shared vs Feature — a régua de decisão
+
+| Pergunta                                   | Resposta                            |
+| ------------------------------------------ | ----------------------------------- |
+| "Isso é genérico e não é de um domínio?"  | `shared/`                           |
+| "Só este domínio usa?"                     | `features/<dominio>/`               |
+| "Precisa de DB/rede/segredo?"              | `infrastructure/` (ou `shared/server`) |
+| "É UI primitiva (Button, Dialog)?"         | `shared/ui/`                        |
+| "É UI com regra de negócio?"               | `features/<dominio>/ui/`            |
+
+**Proibido:** `features/a` importando `features/b`. Se precisar, extraia para `shared/` ou use evento de domínio.
+
+## 📏 Onde cada tipo de código mora
+
+| Tipo | Local | Por quê |
+| --- | --- | --- |
+| Regra de negócio | `features/x/application/` | Testável, isolada, sem Next |
+| Contrato de domínio | `features/x/domain/` | Zero dependência (inverte a direção) |
+| SQL / Prisma query | `features/x/infrastructure/` | Trocável sem tocar no domínio |
+| Server Action | `features/x/actions.ts` | Entrada de escrita, com auth+validação |
+| Query (leitura) | `features/x/queries.ts` | Entrada de leitura, com cache |
+| Componente de rota | `app/…/page.tsx` | Só layout + composição |
+| Config global (env, db, auth) | `shared/server/` | Ponto único de boot |
+| Token de design | `app/globals.css` | Fonte única do tema |
+
+## 🧪 Testabilidade
+
+A arquitetura existe para isso: **`application/` e `domain/` não importam Next nem Prisma.** Você instancia o use case com um repositório falso e testa em 5ms.
+
+```ts
+const useCase = new CreateExampleUseCase(fakeRepo);
+```
+
+## 🚫 Anti-padrões estruturais
+
+| ❌ | ✅ |
+| --- | --- |
+| `src/utils/`, `src/services/`, `src/models/` (pastas genéricas) | `features/<dominio>/` |
+| Lógica de negócio em `page.tsx` | `page.tsx` delega para use case |
+| `features/a` importando `features/b` | `shared/` ou evento |
+| `types/` global com tipo de domínio | `I*.ts` dentro do slice |
+| Prisma importado em Server Component | via `queries.ts` |
+| CSS inline / hex literal | tokens do [DESIGN.md](./DESIGN.md) |
+| API route para tudo | Server Action para mutação de UI |
+
+## 🧭 Complementary: Node.js
+
+O App Router cobre web. **Node.js puro** entra **só** para o que o App Router não faz: worker de fila, cron, consumer de webhook pesado, CLI de batch. Ver [NODE.md](./NODE.md).

package/DESIGN.md

@@ -0,0 +1,219 @@
+# 🎨 DESIGN SYSTEM — EXECUTIVE ENGINEERING
+
+> **Esta é a lei visual do projeto.** Se a UI não segue este documento, a UI está errada.
+> Tema: **DARK ONLY**. Sem modo claro. Sem branding genérico.
+
+---
+
+## 🧭 0. ROTEADOR
+
+| Você está fazendo...              | Leia              |
+| --------------------------------- | ----------------- |
+| Escolhendo cor/espaço/fonte      | §1 Tokens         |
+| Escrevendo/copiando CSS          | §2 Tokens         |
+| Montando layout/grid             | §5 Layout         |
+| Botão, card, chip, input         | §6 Componentes    |
+| Pensando em feedback/UX          | §7 UX             |
+
+---
+
+## 🎯 1. BRAND & STYLE
+
+Interseção entre **engenharia de sistemas distribuídos de alto nível** e **stewardship financeiro executivo**.
+
+- **Estética:** precisão de ferramenta de dev (Linear, Vercel) + disciplina tipográfica de publicação suíça e whitepapers financeiros (Stripe Press).
+- **Tom emocional:** execução de alta frequência somada a gravidade institucional. Calculado, calmo, inabalável.
+- **Tratamento visual:** austero, denso, mas impecavelmente legível.
+- **Surfaces:** ardósia profunda com tom obsidiana (nunca preto absoluto), micro-bordas de 1px, acentos surgical em neon lime e mint.
+- **Métricas de impacto financeiro** (R$ milhões salvos, latências, bilhões sob custódia) têm peso tipográfico de museu.
+- **Zero firula.** Estímulo visual além do necessário = falha.
+
+---
+
+## 🎨 2. TOKENS (FONTE DE VERDADE)
+
+> Tokens vivem em `src/app/globals.css` dentro do bloco `@theme` (Tailwind v4).
+> **Nunca** escreva hex literal em componente.
+
+### Cores
+
+| Token | Hex | Uso |
+| --- | --- | --- |
+| `surface` | `#111319` | Base de panels/cards |
+| `surface-base` | `#0A0D12` | Canvas raiz (Tier 0) |
+| `surface-raised` | `#11151C` | Cards e containers (Tier 1) |
+| `surface-overlay` | `#181E27` | Modais, dropdowns, code headers (Tier 2) |
+| `surface-container` | `#1D2025` | Containers neutros |
+| `surface-container-high` | `#272A30` | Containers elevados |
+| `surface-container-highest` | `#32353B` | Máximo contraste de container |
+| `surface-bright` | `#36393F` | Superfícies muito elevadas |
+| `on-surface` | `#E1E2EA` | Texto/icons sobre surface |
+| `text-primary` | `#F4F1EA` | Texto principal (off-white editorial quente) |
+| `text-secondary` | `#94A3B8` | Texto subsequente |
+| `text-muted` | `#56657A` | Texto terciário / decorativo |
+| `border-subtle` | `#1E2633` | Borda de card (Tier 1) |
+| `border-prominent` | `#2D384B` | Borda de overlay (Tier 2) |
+| `primary` | `#BAF336` | 🟢 **Lime neon** — ação executiva crítica, ROI, estado ativo |
+| `on-primary` | `#0A0D12` | Texto sobre lime |
+| `primary-container` | `#B4F230` | Lime em container |
+| `on-primary-container` | `#253600` | Texto sobre lime container |
+| `secondary` | `#45DFA4` | 🟢 **Mint** — estabilidade, SLA up, delta positivo |
+| `on-secondary` | `#003825` | Texto sobre mint |
+| `tertiary` | `#9CC5FD` | 🔵 **Slate blue** — badges de infra, estágios de pipeline, tags técnicas |
+| `on-tertiary` | `#003257` | Texto sobre tertiary |
+| `error` | `#FFB4AB` | Erro |
+| `on-error` | `#690005` | Texto sobre erro |
+| `error-container` | `#93000A` | Erro em container |
+| `outline` | `#8D937B` | Contorno/foco |
+| `outline-variant` | `#434935` | Variante de contorno |
+| `kpi-accent-glow` | `rgba(186,243,54,0.12)` | Glow de KPI lime |
+| `mint-accent-glow` | `rgba(52,211,153,0.12)` | Glow de KPI mint |
+
+> **Regra de acento:** APENAS 1 cor primária de sotaque por tela. Lime (`primary`) é a ação executiva. Mint (`secondary`) é status/positivo. Slate blue (`tertiary`) é taxonomy/infra. Nunca as três brigando.
+
+### Tipografia — matriz de 3 fontes
+
+| Família | Papel | Regra |
+| --- | --- | --- |
+| **Manrope** | Núcleo geométrico estrutural: headlines, body, números gigantes | Peso 400–800 |
+| **JetBrains Mono** | Instrumentação técnica: tags, paths, índices, commit, metadata | `letter-spacing: 0.06em` em CAPS |
+| **Playfair Display** | Nuance editorial financeira: quotes, framing estratégico | Só itálico/médio. sparingly. |
+
+Todas via `next/font/google` (zero layout shift, zero request externo). Ver [stacks/tailwind.md](./stacks/tailwind.md).
+
+#### Escala tipográfica
+
+| Token | Fonte | Tamanho / Peso / Line | Letter | Uso |
+| --- | --- | --- | --- | --- |
+| `display-hero` | Manrope | 64 / 800 / 72 | -0.035em | Hero desktop |
+| `display-hero-mobile` | Manrope | 38 / 800 / 44 | -0.025em | Hero mobile |
+| `metric-stat` | Manrope | 48 / 700 / 52 | -0.03em | KPI desktop |
+| `metric-stat-mobile` | Manrope | 32 / 700 / 36 | -0.02em | KPI mobile |
+| `headline-lg` | Manrope | 32 / 700 / 40 | -0.02em | Título de seção |
+| `headline-md` | Manrope | 24 / 600 / 32 | -0.015em | Título de card |
+| `headline-sm` | Manrope | 18 / 600 / 26 | -0.01em | Subtítulo |
+| `body-lg` | Manrope | 17 / 400 / 28 | — | Body principal |
+| `body-md` | Manrope | 15 / 400 / 24 | — | Body padrão |
+| `body-sm` | Manrope | 13 / 400 / 20 | — | Body denso |
+| `editorial-quote` | Playfair | 26 / 500 / 36 | -0.01em | Quote |
+| `code-inline` | JetBrains Mono | 13 / 500 / 18 | -0.01em | Código inline |
+| `label-mono` | JetBrains Mono | 11 / 600 / 16 | +0.06em | Label técnica (CAPS) |
+
+> Escala transiciona de monumental (desktop) a denso (mobile) sem clipping nem wrap ruim.
+
+### Raios (curvatura "Soft", disciplined)
+
+| Token | Valor | Uso |
+| --- | --- | --- |
+| `sm` | `0.125rem` | Micro-chip |
+| `DEFAULT` | `0.25rem` | Botão, input (estética CAD/IDE) |
+| `md` | `0.375rem` | Input médio, select |
+| `lg` | `0.5rem` | Card, data module |
+| `xl` | `0.75rem` | Panel grande |
+| `full` | `9999px` | **Só** badge de status/online |
+
+### Espaçamento (grid de 8pt, ritmo vertical)
+
+| Token | Valor | Uso |
+| --- | --- | --- |
+| `gutter` | `1.5rem` | Gutter mobile |
+| `gutter-desktop` | `2rem` | Gutter desktop |
+| `margin` | `1rem` | Margem mobile |
+| `margin-tablet` | `2rem` | Margem tablet |
+| `margin-desktop` | `3rem` | Margem desktop |
+| `space-xs` | `0.25rem` | Micro gap |
+| `space-sm` | `0.5rem` | Gap apertado (data grid) |
+| `space-md` | `1rem` | Gap padrão |
+| `space-lg` | `1.5rem` | Gap de seção |
+| `space-xl` | `2.5rem` | Gap amplo |
+| `space-2xl` | `4rem` | Respiro de seção (mobile) |
+| `space-3xl` | `6rem` | Respiro de seção (desktop) |
+
+---
+
+## 🏔 3. ELEVATION & DEPTH
+
+**Sem drop shadow pesado.** Profundidade = tiering + glass + micro-border.
+
+- **Tier 0 (Canvas):** `#0A0D12` + padrão de micro-dot grid `1px` (`rgba(255,255,255,0.03)`).
+- **Tier 1 (Cards):** `#11151C` com borda contínua `1px #1E2633`.
+- **Tier 2 (Overlay/Hover/Focus):** `#181E27` com borda nítida `#2D384B` + micro-glow localizado.
+- **Gradientes radiais:** `rgba(186,243,54,0.04)` e `rgba(52,211,153,0.03)` atrás de diagramas de arquitetura. Difusos, sem poluir leitura.
+- **Glassmorphism:** nav rails e status bars persistentes = `backdrop-filter: blur(12px)` + slate semi-transparente `rgba(10,13,18,0.82)` + hairline inferior `rgba(30,38,51,0.9)`.
+
+---
+
+## 📐 4. LAYOUT & SPACING
+
+- **Grid:** 12 colunas matemáticas, baseline vertical estrita de 8pt.
+- **Largura máxima:** `1320px`, centralizado, dentro de gutters de alto contraste.
+- **Ritmo de seção:** módulos maiores respiram com `space-3xl` (desktop) → `space-2xl` (mobile). Presença de portfólio de museu.
+- **Densidade:** micro-componentes (data grid, métrica, stack) usam padding apertado `space-sm`–`space-md`. Equilíbrio entre respiro e densidade.
+- **Breakpoints adaptativos:**
+  - **Mobile (<768px):** reflow 4 colunas, métrica empilhada, tier de arquitetura em largura total com borda separadora.
+  - **Tablet (768–1024px):** layout 8 colunas, cards de métrica em dupla, sidebar condensado.
+  - **Desktop (>1024px):** 12 colunas, canvas de arquitetura multi-tier, deep-dives lado a lado.
+
+---
+
+## 🧱 5. COMPONENTES
+
+### Botões
+
+| Variante | Visual | Regra |
+| --- | --- | --- |
+| **Primary (ação executiva/CTA)** | bg `#BAF336`, texto `#0A0D12`, Manrope 600 | Hover: bg `#C8F75A` + `box-shadow 0 0 16px rgba(186,243,54,0.3)`. Active: `scale(0.98)`. |
+| **Secondary (deep dive)** | bg `transparent`, borda `1px #1E2633`, texto `#F4F1EA` | Hover: borda `#94A3B8` + bg `rgba(255,255,255,0.04)`. |
+| **Ghost / Copy code** | JetBrains Mono 11px CAPS, transparente, ícone em container suave | Tooltip de confirmação instantâneo ao copiar. |
+
+### Executive KPI Metric Card
+
+- Mostra impacto financeiro ("R$ 24M/ano salvos", "100M msgs/dia", "R$ 100 bi em custódia").
+- Construção em duas partes: **header mono** (`label-mono`) com ponto de status pulsante → **estatística monumental** (`metric-stat`) → **subtexto anotado** com escopo técnico e ROI de negócio.
+- Borda interna `1px #1E2633` + glow de canto superior no hover em `#BAF336`.
+
+### Chips & Badges de Taxonomia (Tecnologia)
+
+- JetBrains Mono, 11px CAPS, padding `4px 8px`.
+- **Inativo:** bg `#11151C`, borda `#1E2633`, texto `#94A3B8`.
+- **Ativo/Destaque:** bg `rgba(186,243,54,0.08)`, borda `rgba(186,243,54,0.4)`, texto `#BAF336`.
+
+### Diagramas de Arquitetura / Fluxo
+
+- Containers de nó em ardósia escura, conectados por vetores de 1px.
+- Nó **ativo:** anel de status pulsante lime/mint. Nó inativo/legacy: `#56657A`.
+- Drawer de tooltip desliza da borda direita com snippets, benchmarks de latência e decisões arquiteturais.
+
+### Inputs & Campos de Terminal
+
+- Container minimalista, bg `#0A0D12`, borda `1px #1E2633`, placeholder `#56657A`.
+- Foco: hairline migra para `#BAF336` (sem outline grosso).
+
+### Project Showcase & Drawer de Recrutador
+
+- Cards com split: métricas de sistema à esquerda, arquitetura/stack interativa à direita.
+- Barra de scan rápido de metadata: Role, Team Size, Scale, Core Tech, Direct Fiscal Impact.
+- Drawer expansível com bullets: **Problem**, **Scale & Complexity**, **Architectural Decision**, **Measured Outcome**.
+
+---
+
+## 🧠 6. UX (Regras de interação)
+
+1. **Feedback imediato (dopamina):** clicou? loading IMEDIATO. Deu certo? toast de sucesso. Deu erro? toast de erro. **Zero ações sem resposta.**
+2. **Foco único:** uma tela = um objetivo. Nada de 50 formulários. Complexo → modal/wizard.
+3. **Micro-interações:** `hover:` em tudo que é clicável. O usuário precisa sentir a tela viva.
+4. **Acessibilidade real:** contraste que passa. Texto secundário não some. O que importa **grita**.
+5. **Animações** respeitam `prefers-reduced-motion`. Transições ≤ 200ms para feedback, ≤ 400ms para drawer/modal.
+
+---
+
+## 🚫 PROIBIÇÕES (resumo de uma linha)
+
+- ❌ Cor/rgba literal em componente (use tokens).
+- ❌ Modo claro (é dark only).
+- ❌ Lib de UI além de shadcn ([stacks/shadcn.md](./stacks/shadcn.md)).
+- ❌ Drop shadow pesado.
+- ❌ Pill shape fora de status/online.
+- ❌ >1 acento de cor competindo na mesma tela.
+- ❌ Sem `focus-visible` em nada interativo.
+- ❌ Grid que não é 12 colunas / max-width 1320px.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marcelino Sandroni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.