@snksergio/design-system 0.61.0 → 0.63.0

package/dist-lib/ai/roteiros/crud-builder/geracao.md

@@ -0,0 +1,113 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# CRUD Builder — Geração
+
+Só entre aqui após o gate aprovado. Ordem obrigatória:
+
+## 1. Puxar do registry (componentes + exemplo canônico)
+
+```bash
+npm run igreen:add -- data-table example-clientes
+# + example-finance  (se houver drawers de criar/editar/detalhe)
+# + outros componentes citados no blueprint (chip, avatar-ig, etc — o registry resolve deps)
+```
+
+## 2. LER antes de escrever (precedência de fontes)
+
+1. `src/examples/clientes/clientes-screen.tsx` — o molde real (colunas via `textColumn/currencyColumn/dateColumn/statusColumn/actionColumn`, `useMemo`, toolbar, paginação, seleção).
+2. `src/components/ui/DataTable/USAGE.md` + types ao lado — API exata.
+3. Pra drawers: `src/examples/finance/components/NovoClienteDrawer` e `.../FinanceDetailPanel`.
+
+Nunca gere props de memória — copie a forma do exemplo.
+
+## 3. Criar a página
+
+- Caminho/rota conforme o blueprint (`PAGES_DIR`/`REGISTRO`).
+- Wrapper: `<div className="flex flex-col h-full min-h-0 gap-gp-2xl">` → `<PageHeader .../>` → `<DataTable className="flex-1 min-h-0" .../>`.
+- `columns` em `useMemo`; server mode ⇒ `fetchData` em `useCallback`.
+
+### Regras de coluna (OBRIGATÓRIO — pega bugs comuns)
+
+1. **Filtro em TODAS as colunas de dados**: cada coluna ganha `enableColumnFilter: true` + `filterType` (text→`"text"`, number/currency/percentage→`"number"`, date→`"date"`, badge/status/select→`"select"`, multiSelect/tags→`"multiSelect"`). Só ficam de fora `actions` e render-custom sem valor. ⚠️ O funil/drawer de filtros só lista colunas com `enableColumnFilter` — marcar só 2 = bug "filtra só 2 colunas".
+2. **Coluna `actions` por ÚLTIMO**, `type: "actions"` (via `actionColumn`/`getActions`). É o **`type`** que dá as 3 garantias — vai pro fim (mesmo declarada no meio), **ancora à direita** (`pinned: "right"` é redundante) e **não entra no rateio** do autoFit. Coluna de botões montada na unha (`render` sem `type`) não recebe nenhuma das três: fica no meio da tabela e cresce no rateio. ⚠️ **NÃO passe `width`** (lib 0.42.0+): a largura é **derivada do nº de ações** — 1→44px, 2→74px, 3→104px, **4+ colapsam no "…"** (44px). Até a 0.41.x esta linha mandava espelhar `width: 64`; era inútil, porque o cálculo **ignorava `col.width`** nesta coluna. Agora vale, e 64px cabe **1** ícone. Split manual: `showInMenu: true` nos itens que devem ir pro menu (desliga o automático, sem limite de inline).
+3. **Prefira NÃO setar `width`** nas colunas de dados — `autoFit` (default ON) distribui pra preencher o container (sem 1ª coluna esticada, sem scroll). Nunca `autoFit: false` sem motivo. **(v0.22.0+)** `col.width` virou **base/piso** (não trava fixa): o autoFit usa como mínimo e ainda distribui a sobra proporcionalmente — setar `width` em várias colunas **não** deixa mais sobra à direita. Travar de fato = `width`+`maxWidth` iguais (ou `type` fixo). Título do header **nunca trunca** (a largura mínima já inclui o `headerName`).
+4. **Copiar valor** (`copyable`) — **infira, não espere que peçam**; ícone de copiar no **hover/foco** da célula + feedback "Copiado!" (~2s, `navigator.clipboard`). Critério: **o valor é um identificador que a pessoa cola em outro lugar**. ✅ documento (CPF/CNPJ/RG/IE), e-mail, telefone/WhatsApp, conta/agência/chave PIX, código de rastreio/protocolo/contrato/NF/pedido, token/hash, ID **externo**. ❌ nome de pessoa/empresa, status, data, valor monetário, quantidade, percentual, endereço em prosa. ⚠️ `id` sequencial curto (1, 2, 3) **não**; UUID/protocolo/NF **sim** — decide servir fora da tela, não a coluna se chamar "id". **Limites (verificados no código):** inerte em `actions`, na coluna de árvore e na célula em edição — marcar lá não dá erro, só não aparece; **`readMore` vence `copyable`** na mesma coluna (escolha um); copia o texto **formatado**, então numa coluna `currency` sai `R$ 1.234,56` e não `1234.56` — pro valor cru use `copyable: { value: (row) => String(row.x) }`. Texto/rótulo diferentes: `copyable: { value: (row) => "...", label: "Copiar conta" }`. **Declare no gate** as colunas em que você inferiu, pra o usuário recusar em lote — inferência silenciosa de recurso que ele não sabe que existe é surpresa, não conveniência.
+5. **Grab-to-scroll é NATIVO** (`grabToScroll` default `true`, v0.26.0+): toda tabela já rola lateral ao arrastar o corpo (mouse/pen, threshold ~6px, clique/seleção preservados). Não configure — só `grabToScroll={false}` pra desligar.
+6. **Filtro visível na tabela** (`showEmptyFilterChips`, v0.6.0+): pros filtros que o usuário mais usa (status, categoria, tipo, graduação…), passe `showEmptyFilterChips={["status", "categoria"]}` no `<DataTable>` → os chips nascem **vazios e clicáveis** já no load, sem abrir o menu de filtros. É o que faz o filtro **aparecer** na tela — sem isso o usuário não vê a afordância e acaba pedindo select na unha (⛔ **proibido** montar form/select acima da tabela — ver `.claude/rules/ds-components.md`). Status/segmento como eixo de navegação (poucos valores) → alternativa: **uma visão por valor** em `defaultViews` (ver item de visões abaixo). Regra de ouro: se a informação está numa coluna, **chip nativo primeiro**.
+
+**Formato de data.** `type: "date"` renderiza `14/03/2023` e `type: "datetime"` renderiza `14/03/2023 09:30` — **com ano** (lib 0.43.0+). Precisa de outro formato (mês escrito, relativo, ISO)? Passe **`valueFormatter`** na coluna: ele vence o formato do tipo e vale na célula, no export e no clipboard. **NÃO** escreva `render` próprio só pra formatar data. ⚠️ Até a 0.42.1 esses tipos mostravam a data **sem ano** e o `valueFormatter` não chegava na célula — se você viu `render` de data em código antigo, era contorno disso.
+
+
+### Padrões de CÉLULA (consistência finance — OBRIGATÓRIO)
+
+Espelhar `finance-screen.tsx` (puxe `example-finance`). **Componente do DS sempre antes de markup manual**:
+
+- **Coluna primária (nome)**: `isPrimary` + `render` com `<Avatar size="md">` + nome `text-body-sm font-medium` + secundária `text-caption-md text-fg-muted` (email/ID/doc) + ícone "abrir detalhe" (`<SquareArrowOutUpRight>` num `size-[24px] rounded-radius-sm border bg-bg-canvas shadow-sh-sm`) quando o row click abre painel.
+- **Status / badge**: `type: "badge"` + `render` com `<Chip variant="soft" size="sm" shape="pill">` (cor semântica). Nunca pill na unha com `<span>` estilizado.
+- **Avatar**: use **`avatar-ig`** (`@/components/ui/avatar-ig`), não o `avatar` (Radix puro, sem `colorHex`/`size`). `size="md"` na tabela (não `sm`). **Números/moeda/%**: `tabular-nums` + `type` (`currency`/`percentage`) + `align: "right"`. **Tags**: `type: "tags"` + `<Chip soft sm rounded>`. **Código/identificador/valor técnico** (chave de env, ID, hash, slug, path): preset **`text-code-sm`** — nunca `font-mono text-body-sm` + `tracking-*` na unha.
+
+### Detail panel (row click → painel)
+
+**Cite o bloco `dsgreen-paneldetail-1`** — a estrutura inteira já está resolvida e
+referenciável por ID (`npm run igreen:add -- dsgreen-paneldetail-1`, ou peça
+*"use a referência dsgreen-paneldetail-1"*).
+
+A referência anterior era "espelhe o `FinanceDetailPanel`", e ela funciona — o
+`example-finance` distribui esse arquivo. O bloco é melhor por dois motivos, não porque o
+outro esteja quebrado: **não exige puxar uma tela inteira** só pra ver um painel, e o arquivo
+dele traz **o porquê de cada decisão** (com as medições) em vez de só o resultado.
+
+**Sempre** `<FloatingPanel>`, nunca markup solto. O que o bloco carrega:
+
+- `titleSlot`: `<Avatar size="lg">` + nome (`text-body-md font-semibold`) + linha
+  `código · <Chip status>`. ⚠️ Se você usar `Panel` em vez de `FloatingPanel`, esse header é
+  impossível: lá `title`/`description` são **string**.
+- `headerActions`: 1–2 ações de ícone, **todas `variant="soft"`** (`secondary` neutro,
+  `success` contato, `critical` destrutivo). `ghost` no meio da fileira fica sem container e lê
+  como desabilitada ao lado do maximize/close, que o componente renderiza como `soft`.
+  `aria-label` obrigatório — botão de ícone não tem texto.
+- `bodyPadded={false}` + **agrupar por assunto** em `<FloatingPanelSection title>`.
+- 1ª seção = **métricas do registro**, em cards compactos (ícone + valor 18px + rótulo), 2 por
+  linha. ⛔ **Não use `Kpi`**: ele é card de dashboard (144px de altura por célula) e come a
+  primeira dobra do painel antes de qualquer campo.
+- Cada dado simples = **uma linha** `<FloatingPanelField label value/>`.
+- Dado que **não é** `label: valor` sai do Field: entidade com marca (banco, gestor) vira linha
+  de largura cheia com `Avatar`; vários valores viram `<Chip>`; e-mail/telefone viram
+  `mailto:`/`tel:` com cor de link.
+- `footer`: Fechar + ação primária.
+- ⛔ **Sem aba.** Se o corpo já é pilha de seções colapsáveis, o colapso **é** o mecanismo de
+  esconder — ter os dois faz o usuário procurar o dado em dois lugares.
+
+- **Tabela + Lista (toggle)**: se o usuário quer alternar entre tabela e uma **lista de cards** (não kanban), use `viewMode` + `listConfig={{ renderItem(row), paginated?, hierarchical?, getPath?, getMenuItems? }}` no próprio `<DataTable>` — mesma toolbar, toggle Tabela/Lista automático. NÃO monte um `<DataList>` paralelo + toggle na mão.
+  - **Lista flat paginada**: `listConfig.paginated: true` — a lista usa a MESMA paginação da tabela + mostra o footer. Default `false` (mostra todas, sem footer); ignorado em `hierarchical`. Use quando a lista flat puder ter muitas linhas.
+- ⛔ **No MÁXIMO 2 presets, e NUNCA um preset "Todos"/"Todas"**: `maxTabs` default é 3 e a aba **Default** (nativa, que já É a visão sem filtro) consome 1 slot — sobram 2. O excedente é cortado por `.slice(0, maxTabs - 1)` — em DEV o componente avisa no console qual visão foi engolida (v0.43.1), em produção não. Precisa de mais? `maxViewTabs={N + 1}` no `<DataTable>` (o `+1` é a Default) — mas 2 é o default por um motivo: barra de visões não é menu. Um preset "Todos" duplica a Default e gasta um slot com nada.
+- **Visões pré-definidas read-only (`allowCreateView={false}`, v0.23.0+)**: passe `defaultViews={[presetView({ id, name, filters?, sort?, viewMode? })]}` + `persistId` pras abas nativas da tela. `allowCreateView={false}` esconde o botão "+" (o usuário não salva visões próprias — só usa as suas). Default `true`. **viewMode "sticky"**: trocar de visão só muda Tabela↔Lista↔Kanban se o preset declarar `viewMode` explícito; sem isso, mantém a view que o usuário está vendo (só declare `viewMode` no preset que DEVE forçar uma view).
+  - Lista árvore **+ tabela árvore**: `hierarchical` + `getTreeDataPath` (tabela não pagina).
+  - **Tabela FLAT paginada + lista em ÁRVORE**: `hierarchical` + **`listConfig.getPath`** e NÃO passe `getTreeDataPath` (senão a tabela vira tree-data e perde paginação).
+- Drawers de criar/editar: espelhe `NovoClienteDrawer` (Panel + FormField + `gap-form-gap`), ligados via estado da página (igual ao `finance-screen.tsx`).
+- Tokens/spacing/typography conforme `.claude/rules/ds-design.md` + `DESIGN.md`.
+
+## 4. Registrar a rota
+
+No ponto que o usuário indicou (router / App). Página órfã = incompleto.
+
+## 5. Validar
+
+```bash
+npx tsc --noEmit   # abort se falhar — corrija antes do handoff
+```
+
+## 6. Handoff
+
+`CRUD_PRONTO: <Entidade>` + onde foi registrada + como rodar (`npm run dev`).
+Sugira ao usuário abrir a tela e conferir; ofereça ajustes finos (larguras de coluna, filtros).

package/dist-lib/ai/roteiros/crud-builder/roteiro.md

@@ -0,0 +1,89 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+
+# CRUD Builder (consumidor) — Router
+
+Você guia a criação de uma tela de tabela que consome `<DataTable>` **sem fugir
+do exemplo e da documentação do projeto**. NÃO inventa API de props, NÃO gera
+código de memória, NÃO toca em arquivo antes do gate aprovado.
+
+> **Kanban / board / funil / pipeline de vendas** caem AQUI: kanban é uma `viewMode`
+> do DataTable (mesmos dados/colunas/filtros, só muda a exibição). "Quero um kanban/
+> funil" → esta skill; a Fase 6 do interview configura as lanes pela coluna de
+> status/etapa. Funil = board agrupado por etapa. Ref. visual: `example-finance`.
+
+## Ambiente (este é um projeto CONSUMIDOR, copy-in)
+
+| Variável                 | Valor                                                                                                           |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `IMPORT_PATH`            | `@/components/ui/DataTable`, `@/components/ui/Button`, etc (copy-in via alias)                                  |
+| `EXEMPLO_CANÔNICO`       | `example-clientes` → `npm run igreen:add -- example-clientes` → ler `src/examples/clientes/clientes-screen.tsx` |
+| `DOC`                    | `src/components/ui/DataTable/USAGE.md` (após `igreen:add data-table`) + types ao lado                           |
+| `PAGES_DIR` / `REGISTRO` | perguntar ao usuário (onde mora a página + como registra rota)                                                  |
+
+Se o componente/exemplo ainda não está no disco, **puxe via `igreen:add`** antes de ler — nunca gere de memória.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/<Nome>`)
+> e leia o exemplo canônico direto em `<dsPath>/src/examples/clientes/clientes-screen.tsx` —
+> **NÃO** rode `igreen:add`. `PAGES_DIR`/`REGISTRO` continuam do projeto pai.
+
+## Fluxo — 3 estágios
+
+```
+/ds-create-crud
+   ▼ interview.md
+1. ENTREVISTA (fases 0-6)         — acumula escolhas, ZERO edição em disco
+   ▼ blueprint.md
+2. BLUEPRINT [GATE]               — preview consolidado + pré-validações → aguarda "aprovar"
+   ▼ generate.md
+3. GERAÇÃO                        — igreen:add → ler exemplo → criar página → registrar → tsc → handoff
+```
+
+Carregue cada sub-arquivo só no estágio correspondente: `interview.md` agora, `blueprint.md` ao fim da entrevista, `generate.md` só após o gate.
+
+## ⚠️ Precedência de fontes (anti-drift)
+
+```
+1. src/examples/clientes/clientes-screen.tsx  (exemplo real, vence tudo)
+2. src/components/ui/DataTable/USAGE.md + types ao lado
+3. Snippets desta skill
+4. Memória da IA  ← NUNCA confiar sozinha
+```
+
+Se USAGE.md divergir do exemplo/types, o exemplo + types vencem.
+
+## Guardrails (não-negociáveis)
+
+1. `columns` SEMPRE em `useMemo`; `fetchData` (server mode) SEMPRE em `useCallback` (senão loop de refetch).
+2. Operador de filtro válido pro filterType (multiSelect⇒`isAnyOf`, text⇒`contains`, date⇒`between`...).
+3. `virtualize: true` ⇒ paginação desligada + container com altura (`flex-1 min-h-0` num pai `h-full`).
+4. `groupBy`/kanban ativo ⇒ paginação desligada (avisar).
+5. Forms em drawers/modais usam `<FormField>` (nunca `<label>` cru) + `gap-form-gap`.
+6. Classes DS antes de Tailwind literal; zero hardcode de cor/tamanho (ver `.claude/rules/ds-design.md`).
+7. Wrapper da tela: `flex flex-col h-full min-h-0 gap-gp-2xl` (PageHeader → 16px → tabela). Ver `DESIGN.md`.
+8. Página registrada no roteador do usuário — página órfã = tarefa incompleta.
+9. `npx tsc --noEmit` limpo antes do handoff (abort-on-error).
+10. LER o exemplo canônico ANTES de gerar — nunca de memória.
+11. Ação destrutiva (excluir) ⇒ **confirmação via `AlertModal`** — nunca deletar direto.
+12. Sempre wire os 3 estados: `loading`/`renderLoading` (skeleton), `renderEmpty` (sem
+    registros + CTA _Adicionar_), `renderNoResults` (filtro sem match). **O default
+    embutido conta como wirado — desde que declarado no blueprint** (linha `Estados:`).
+    Faltou = incompleto: o que não vale é o estado nunca ter sido decidido.
+
+## Drawers (criar/editar/detalhe) — ligado ao CRUD
+
+Se o CRUD precisa de criar/editar/ver-detalhe, espelhe o padrão do `example-finance`:
+`NovoClienteDrawer` (criar/editar via `Panel` + `FormField`) e `FinanceDetailPanel`
+(detalhe via `FloatingPanel`). Puxe `example-finance`, leia esses componentes e
+reuse a estrutura — mesmo design de drawer do DS.
+
+## Handoff
+
+- Entrevista pronta → `BLUEPRINT_PRONTO: <Entidade> — aguardando gate`
+- Pós-geração → `CRUD_PRONTO: <Entidade>` (+ onde foi registrada)

package/dist-lib/ai/roteiros/dashboard-builder/blueprint.md

@@ -0,0 +1,47 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# Dashboard Builder (consumidor) — Blueprint + GATE
+
+Consolide a entrevista num preview de uma tela só e **pare** — ⛔ zero edição antes do "aprovar".
+
+## Preview a apresentar
+
+```
+PAINEL: <nome>  ·  rota <definir com o usuário>  ·  fonte: mock | API(<shape>)
+Wrapper: AppShell + PageHeader | puro     (chrome do print entregue? sim/não)
+
+⚠️ Inferido (não perguntei) — vete se discordar:
+  • <decisão> → <o que muda se vetar>       [ou: nenhuma]
+
+MAPA DE ROWS (top → bottom):
+  Row 1 — [hero/insight?]                         (opcional)
+  Row 2 — KPI-group "Painel do Líder" · N cols    (§1)  KPIs: <label · tom · delta(signed?)> …
+  Row 3 — <gráfico principal> (2/3) + <donut/resumo> (1/3)   (§2)
+  Row 4 — <ranking / fusão KPI+evolução?>         (§3)
+  Row 5 — <card dividido / mapa?>                 (§4)
+  Row 6 — <tabela | lista embutida?>              (§5/§6 → delega crud/list-builder)
+
+Primitivos (igreen:add): kpi · chart · panel · <data-table|data-list?> · example-dashboard (base)
+```
+
+## Pré-validações
+- [ ] É mesmo dashboard (2+ tipos de seção)? Senão → rotear pro builder certo.
+- [ ] Cada gráfico com tipo + séries; cabe no padrão (skill `charts`).
+- [ ] KPI delta: `signed` só onde sinal = bom/ruim; senão tom explícito.
+- [ ] Ícone: KPI-group = círculo; mini-stat/legenda = quadrado.
+- [ ] Tabela/lista embutida delega a crud/list-builder; distribuição correta.
+- [ ] Layout estreito não coloca cards lado-a-lado apertados; zero hardcode.
+
+## Gate
+Apresentar mapa de rows + pré-validações numa tela só. Aguardar `aprovar` → `generate.md`;
+`ajustar X` → re-montar; `cancelar` → abortar (zero edits). **Não tocar em arquivo antes do aprovar.**

package/dist-lib/ai/roteiros/dashboard-builder/entrevista.md

@@ -0,0 +1,62 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# Dashboard Builder (consumidor) — Entrevista (fases 0–6)
+
+Uma pergunta (ou grupo curto) por vez. Acumule as escolhas — **ZERO edição em disco**
+até o gate. Use `AskUserQuestion` pra escolhas fechadas; proponha um default sensato.
+As receitas de cada seção estão no `generate.md` (§1–§6) + no `example-dashboard`.
+
+## Fase 0 — Intent + fonte
+- Do que é o painel? (visão geral de quê, pra quem — ex.: painel do líder, resumo de
+  categoria, financeiro consolidado).
+- Dados: mock ou API? Se API, anote o shape → a geração cria mock tipado espelhando.
+- Período/segmentação no topo? (quase sempre → PeriodSelector no `actions` do PageHeader).
+
+- **Envelope (wrapper)** — verifique antes de perguntar: existe `AppShell`? A referência
+  mostra rail/menu/header? Chrome sem shell → ofereça `/ds-create-app` junto; recusado →
+  registre no blueprint o que do print fica de fora.
+
+## Fase 1 — KPIs rápidos ("Painel do Líder", §1)
+- Quais métricas rápidas? (label + valor + tom do ícone).
+- Delta? O sinal é literalmente bom/ruim → `signed`. Senão, tom explícito (tempo ↓ = success).
+- Quantas colunas (4–6)? → `<KpiGroup columns={N} divided>`.
+
+## Fase 2 — Gráficos (chart-cards, §2)
+- Quais gráficos? Tipo (barras/linha/área/pizza-donut), séries, o que comparam (ver skill `charts`).
+- Cada um num SectionCard (head título+subtítulo discreto). Big-number liderando? Legenda/metric-rows?
+- Donut com total no centro? 2 séries → verde+âmbar; pizza → rampa da marca.
+
+## Fase 3 — Ranking / fusão KPI+evolução (§3)
+- Ranking (reconhecimento, top do mês) ou linha de lista rica que funde identidade +
+  mini-KPIs em colunas + métrica headline com delta (ex.: cidades/licenciados por status)?
+- Se sim: mini-KPIs (label+ícone+tom), métrica headline à direita (delta Chip), identificador (rank/nome/sub).
+
+## Fase 4 — Card dividido em 2 / mapa (§4)
+- Seção que junta dados + visual lado a lado (ex.: barras por UF | mapa)? → card dividido (divisor no 2º painel).
+- Precisa de mapa? (SVG por região/UF + legenda). Anote regiões/UFs.
+
+## Fase 5 — Tabela / lista embutida (delega)
+- Termina com tabela (grade) ou lista (cards) de detalhe?
+- Tabela → geração delega a distribuição de colunas ao `crud-builder` (identidade → status →
+  categóricos → muted → moeda/data à direita; filtros nativos pré-aplicados).
+- Lista/kanban → delega ao `list-builder` (linha1 título+secundário, linha2 meta, status chip,
+  valor à direita; sem botão de ação).
+- Nenhuma → pula.
+
+## Fase 6 — Layout das rows
+- Ordem/agrupamento. Padrão: (1) hero/insight opcional · (2) KPI-group "Painel do Líder" faixa larga ·
+  (3) gráfico principal (2/3) + donut/resumo (1/3) · (4) qualidade/ranking/fusão · (5) listas/tabela.
+- Estreito → 1 card/row + coluna única. Rows 2–3 col via `grid grid-cols-1 lg:grid-cols-{2,3} gap-gp-2xl items-stretch`.
+
+## Fim
+Resumir em 1 frase + `BLUEPRINT_PRONTO: <Painel> (dashboard) — aguardando gate` → carregar `blueprint.md`.

package/dist-lib/ai/roteiros/dashboard-builder/geracao.md

@@ -0,0 +1,88 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# Dashboard Builder (consumidor) — Geração
+
+Só após o gate aprovado. Abort-on-error.
+
+## 1. Puxar + ler ANTES de montar (nunca de memória)
+
+```bash
+npm run igreen:add -- example-dashboard kpi chart panel
+# + data-table (se tabela embutida) / data-list (se lista embutida)
+```
+Ler `src/examples/dashboard/dashboard-screen.tsx` (referência runnable) + `Kpi/USAGE.md`
++ `Chart/USAGE.md`. Catálogo visual: **https://igreen-desingsystem-admin.vercel.app** (`#/dashboard-showcase`).
+**Prefira adaptar o example-dashboard** a montar do zero.
+
+## 2. Receitas canônicas (as 6 — resumo; o example-dashboard tem o código completo)
+
+**Shell**: `<div className="flex flex-col h-full min-h-0 gap-gp-2xl">` + `PageHeader`
+(actions = PeriodSelector) + rows.
+
+**§1 KPI-group "Painel do Líder"** (faixa de KPIs rápidos):
+```tsx
+<KpiGroup columns={N} divided>
+  <Kpi label="..." value="..." icon={<Icon />} tone="success|brand|info|warning|danger|neutral"
+       hint="..." delta={<KpiDelta value="+34" signed />} />
+</KpiGroup>
+```
+Tone colore SÓ o ícone (círculo `size-form-lg rounded-radius-full`); valor default (só KPI de
+alerta ganha cor). `signed` deriva verde/vermelho + seta do sinal; use tom explícito quando
+"subir" não é bom (tempo ↓ = success).
+
+**§2 Chart-card**: SectionCard (`flex flex-col gap-gp-2xl p-pad-3xl bg-bg-surface border
+border-border-subtle rounded-radius-xl shadow-sh-sm`) com head discreto (título `text-body-md
+font-medium`, subtítulo `text-body-xs text-fg-muted`, gap `gap-gp-2xs` (2px)) + `<ChartContainer
+className="h-[160px]">`. Cor só por token. Big-number liderando: `text-stat-lg
+leading-none tabular-nums` (30px/bold — o preset existe; NÃO hardcode `text-[30px]`). Legenda/metric-row: ícone-**quadrado** `size-comp-xl rounded-radius-base`
++ label/sub + valor à direita, sob `border-t border-border-subtle`.
+
+**§3 Fusão KPI+evolução / ranking** (linha rica): identidade (rank badge `size-comp-sm
+rounded-radius-full` + nome) · mini-KPIs em colunas (`hidden sm:flex gap-gp-6xl`, cada = quadrado
+`size-comp-lg rounded-radius-base` tonal + valor `text-body-md font-semibold tabular-nums` +
+label `text-caption-sm text-fg-muted`) · bloco headline à direita `ml-auto shrink-0 border-l
+border-border-subtle pl-gp-3xl` (valor `text-title-lg font-bold` + delta Chip `shape="rounded"`,
+seta 180° se negativo + micro-label `uppercase tracking-[0.04em]`).
+
+**§4 Card dividido em 2**: 1 surface SEM padding + `grid lg:grid-cols-2`; cada painel `p-pad-3xl`
+com ColHead; divisor no **2º painel**: `border-t border-border-subtle ... lg:border-l lg:border-t-0`.
+
+**§5 Tabela embutida** → delega ao `crud-builder`: ordem identidade → status → categóricos →
+muted → moeda/data à direita (`align:"right" tabular-nums`); primário `isPrimary`+`minWidth`+
+`font-medium`; status `Chip variant="soft" size="sm" shape="rounded"`; filtros nativos
+pré-aplicados (`defaultViews`/`presetView`), sem form solto acima.
+
+**§6 Lista/kanban embutida** → delega ao `list-builder`: linha1 título bold `body-md` + `·`
+secundário muted · linha2 meta muted `caption-md` (lugar · pessoa · data) · status Chip soft pill ·
+valor à direita fixo `font-semibold tabular-nums`. **Sem botão de ação na linha.**
+
+## 3. Registro
+Registrar a página no roteador do app (perguntar ao usuário onde/como). Página órfã = incompleto.
+
+## 4. Sequência (abort-on-error)
+1. `igreen:add` dos itens + ler o example-dashboard.
+2. Montar seção por seção (as § acima; adaptar o exemplo).
+3. Registrar rota.
+4. `npx tsc --noEmit` → erro: corrigir e repetir.
+5. (recomendado) rodar o app e conferir: KPI-group divided, gráficos com token, ranking com
+   `border-l`, card dividido, tabela/lista embutida, responsivo + dark.
+
+## 5. Checklist final
+- [ ] Compõe 2+ tipos de seção espelhando o example-dashboard
+- [ ] KPI-group divided + KpiDelta (signed só onde cabe); ícone círculo vs quadrado certo
+- [ ] Gráficos só com token; tabela/lista via crud/list-builder
+- [ ] Zero Tailwind literal com equivalente DS · zero hardcode
+- [ ] Registro completo · `npx tsc --noEmit` limpo
+
+## Handoff
+`DASHBOARD_PRONTO: <Painel>` (+ onde foi registrada)

package/dist-lib/ai/roteiros/dashboard-builder/roteiro.md

@@ -0,0 +1,88 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+
+# Dashboard Builder (consumidor) — Router
+
+Você guia a criação de uma tela de **dashboard/painel** que **compõe** os primitivos
+do DS (`Kpi`/`KpiGroup`/`KpiDelta`, `Chart`, `Panel`, `DataTable`, `DataList`) nos
+**padrões canônicos**. NÃO inventa API, NÃO gera de memória, NÃO toca em arquivo
+antes do gate.
+
+> Irmão do `crud-builder` (tabela) e do `list-builder` (lista). Dashboard não é um
+> componente — é **composição** de seções. Uma tabela/lista DENTRO do dashboard é
+> delegada ao crud/list-builder.
+
+## ⚠️ Desambiguação ANTES de tudo
+
+| Dashboard (ESTA skill) | Não é dashboard |
+|---|---|
+| **compõe** 2+ tipos de seção: KPIs + gráfico(s) + ranking/resumo numa "visão geral" | 1 tabela densa → `crud-builder` |
+| foco em métrica/tendência/comparação, pouca edição | 1 lista de cards standalone → `list-builder` |
+| ex: painel do líder, resumo de categoria, visão da rede | 1 gráfico isolado → skill `charts` |
+
+Só 1 grade/lista/gráfico → **PARAR** e rotear pro builder certo.
+
+## Ambiente (projeto CONSUMIDOR, copy-in)
+
+| Variável | Valor |
+| --- | --- |
+| `IMPORT_PATH` | `@/components/ui/Kpi`, `@/components/ui/Chart`, `@/components/ui/Panel`, etc (copy-in via alias) |
+| `EXEMPLO_CANÔNICO` | `example-dashboard` → `npm run igreen:add -- example-dashboard` → ler `src/examples/dashboard/dashboard-screen.tsx` |
+| `DOC` | `src/components/ui/Kpi/USAGE.md` + `Chart/USAGE.md` (após `igreen:add`) + types ao lado; catálogo visual hospedado `#/dashboard-showcase` |
+| `PAGES_DIR` / `REGISTRO` | perguntar ao usuário (onde mora a página + como registra rota) |
+
+Se o componente/exemplo não está no disco, **puxe via `igreen:add`** antes de ler.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/<Nome>`)
+> e leia o exemplo canônico direto em `<dsPath>/src/examples/dashboard/dashboard-screen.tsx` —
+> **NÃO** rode `igreen:add`. `PAGES_DIR`/`REGISTRO` continuam do projeto pai.
+
+## Fluxo — 3 estágios
+
+```
+/ds-create-dashboard
+   ▼ interview.md
+1. ENTREVISTA (fases 0-6)   — KPIs → gráficos → ranking/fusão → dividido/mapa → tabela/lista → layout; ZERO edição
+   ▼ blueprint.md
+2. BLUEPRINT [GATE]         — mapa de rows + pré-validações → aguarda "aprovar"
+   ▼ generate.md
+3. GERAÇÃO                  — igreen:add example-dashboard → ler → montar → registrar → tsc → handoff
+```
+
+Carregue cada sub-arquivo só no estágio: `interview.md` agora, `blueprint.md` ao fim
+da entrevista, `generate.md` só após o gate.
+
+## ⚠️ Precedência de fontes (anti-drift)
+
+```
+1. src/examples/dashboard/dashboard-screen.tsx (exemplo real — vence tudo)
+2. src/components/ui/Kpi/USAGE.md + Chart/USAGE.md + types ao lado
+3. Snippets/receitas desta skill (generate.md)
+4. Memória da IA  ← NUNCA confiar sozinha
+```
+
+## Guardrails (não-negociáveis)
+
+1. LER `example-dashboard` ANTES de montar — nunca de memória.
+2. **KPI rápido = "Painel do Líder"**: `<KpiGroup divided>` + `<Kpi>` + `<KpiDelta>`.
+   Tone colore SÓ o ícone (círculo); valor default (só KPI de alerta ganha cor).
+   Delta: `signed` só quando sinal = bom/ruim; senão `tone` explícito ("-12s" é melhora → success).
+3. Gráfico = SEMPRE `<ChartContainer>`, cor só por token (`--color-chart-1..5`); ver skill `charts`.
+4. Ranking/fusão + card dividido: divisor via `border-l`/`border-t` (nunca só gap);
+   ícone mini-stat = **quadrado** `size-comp-lg rounded-radius-base`, KPI-group = **círculo** `size-form-lg rounded-radius-full`.
+5. Tabela/lista embutida → delegar a `crud-builder`/`list-builder`; filtros nativos pré-aplicados, sem form solto acima.
+6. Classes DS antes de Tailwind literal; zero hardcode (ver `.claude/rules/ds-design.md`, `DESIGN.md`). Números grandes literais só onde não há preset.
+7. Shell: `flex flex-col h-full min-h-0 gap-gp-2xl` (PageHeader → 16px → rows). Estreito → 1 card/row.
+8. Página registrada no roteador do usuário — órfã = incompleto.
+9. `npx tsc --noEmit` limpo antes do handoff.
+
+## Handoff
+
+- Entrevista pronta → `BLUEPRINT_PRONTO: <Painel> (dashboard) — aguardando gate`
+- Pós-geração → `DASHBOARD_PRONTO: <Painel>` (+ onde foi registrada)

package/dist-lib/ai/roteiros/drawers/roteiro.md

@@ -0,0 +1,41 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+
+# drawers — Criar / Editar / Detalhe
+
+Padrão de drawer do DS, ligado ao CRUD/detalhe. Três variantes, mesma família visual.
+
+## Fluxo
+1. `npm run igreen:add -- example-finance` (traz os drawers + `Panel`, `FloatingPanel`, `FormField`).
+2. **Leia** os componentes-modelo:
+   - Criar/editar → `src/examples/finance/components/NovoClienteDrawer` e `.../EditarFinanceDrawer` (base: `Panel` + `FormField`).
+   - Ver detalhe → `src/examples/finance/components/FinanceDetailPanel` (base: `FloatingPanel`, não-modal).
+3. Adapte os campos/conteúdo ao caso. Ligue ao estado da página (igual `finance-screen.tsx`: `open`/`onOpenChange` + registro selecionado).
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/Panel`)
+> e leia os drawers-modelo direto em `<dsPath>/src/examples/finance/components/` —
+> **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+- **Criar/Editar** = `Panel` (drawer modal lateral) com form em `<FormField>` + `gap-form-gap`. Footer sticky com Cancelar/Salvar.
+- **Detalhe** = `FloatingPanel` (não-modal, não bloqueia a página; pode coexistir com a tabela). `shadow-sh-aside`.
+- Largura: `Panel` default é `size="md"` = **560px**. O token `max-w-drawer-md` (480px) é outra coisa — não confunda. Mobile (<1024px): vira Sheet full.
+- Nunca `<label>` cru; nunca `<button onClick>` como "card de seleção" (use label/FormField nativo).
+- Abrir detalhe no click da linha (`onRowClick`); abrir editar via ação da linha.
+
+Aplique `DESIGN.md` + regras. Handoff: `DRAWER_PRONTO: <criar|editar|detalhe> de <Entidade>`.
+
+## Aba dentro do drawer/painel
+
+`<Tabs fullWidth>` com a variante **default** (`segmented`) — nunca `line`. Estas superfícies
+são estreitas por construção (`Panel` 560px, `FloatingPanel` 320–720 e **redimensionável**),
+e ali o `line` vira um trilho curto que lê como fragmento. Sem `fullWidth` as abas ficam num
+canto. ⛔ Não escreva `w-full` no `TabsList` nem `flex-1` nos triggers: a prop faz as três
+camadas (root + list + triggers), e `w-full` só no list estica o container e agrupa as abas
+na esquerda.

package/dist-lib/ai/roteiros/list-builder/blueprint.md

@@ -0,0 +1,94 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# List Builder — Blueprint [GATE]
+
+## Pré-validações automáticas (ANTES de exibir)
+
+Corrigir silenciosamente (ou reportar se exigir decisão):
+
+1. **Excludências de escala** — `virtualized` + `enableDnD` → desligar DnD;
+   `virtualized` + `onLoadMore` → escolher um; `fillHeight` + `virtualized` →
+   `fillHeight` off. Anotar `← corrigido`.
+2. **branchHighlight** só com `layout="hierarchical"` — em outro layout, ignorar
+   e avisar.
+3. **Coerência de layout** — `grouped` tem `groups`; `hierarchical` tem itens com
+   `children` (ou `onLoadChildren`).
+4. **filterFields** — cada um tem `accessor`; `select` tem `options`. Operador de
+   view/filtro pré-aplicado válido pro `type` (multiSelect⇒`isAnyOf`,
+   select⇒`equals`, text⇒`contains`, number⇒`equals`, date⇒`between`,
+   boolean⇒`equals`).
+5. **Colisão de rota** — o id/rota proposto não pode já existir no router **deste
+   projeto**. Colisão → propor sufixo. (Onde ficam as rotas varia: React Router,
+   TanStack Router, file-based do Next… **pergunte** se não for óbvio pelo repo.)
+6. **Card** — `title` presente (slots) OU `renderItem` definido. Excluir
+   (destructive) tem `AlertModal` no plano (se houver form).
+
+## Formato do blueprint (apresentar TUDO de uma vez)
+
+```markdown
+## Blueprint — Lista <Entidade>
+
+**Página**: <Título> · id `<page-id>` · wrapper <ExamplePageLayout|AppShell|puro> · nav "List Components"
+**Dados**: <client|server> mode · fonte: <sample|interface|endpoint|manual> · ~<N> itens · id: `<campo>`
+
+### ⚠️ Decisões inferidas — vete se discordar
+
+Só o que o usuário NÃO disse e você decidiu sozinho (wrapper, tema, tipo de campo com
+confiança baixa…) — uma linha cada, com o que muda se ele vetar. Sem inferência →
+`nenhuma`; não apague a seção: é a ausência dela que faz a decisão passar aprovada
+em pacote junto com o resto.
+
+### Card (<slots|renderItem>)
+- leading: <avatar/ícone|—> · title: `<campo>` · subtitle: `<campo|—>`
+- meta: [<label:campo(align)>, ...] · trailing: <badge|—> · description: <campo|—>
+- (ou renderItem custom: <descrição do card rico>)
+- densidade <comfortable|compact> · menu por card [<Editar·Excluir>|—]
+
+### Layout
+<standard | grouped (groups: <id(cor)>...; DnD <on|off>; surface <on|off>)
+ | hierarchical (branchHighlight <none|block|active>; expand inicial <...>; lazy <on|off>)>
+
+### Toolbar
+título OU views[<abas>] · busca <on|off> · refresh <on|off> · moreActions [<...>]
+filterFields: [<id:label:type>, ...]
+
+### Seleção / escala
+selectable <on|off> + bulk [<actions>] · onItemClick <nada|detalhe|nav>
+escala: <nenhuma | virtualized (estimate <N>) | infinite (onLoadMore/hasMore/loadingMore)>
+fillHeight <on|off>
+
+### Estados
+loading <skeletonCount> · vazio <emptyState msg/CTA>
+
+### Arquivos
+- CRIAR  <PAGES_DIR><Nome>.tsx (~<N> linhas)
+- EDITAR <REGISTRO> (rota + entrada de navegação do SEU projeto — ver Fase 0)
+
+### Referências canônicas que serão lidas antes de gerar
+<lista da matriz do generate.md, só os cenários presentes>
+
+⛔ Nenhum arquivo será tocado antes da aprovação.
+Responda **aprovar** · **ajustar <o quê>** · **cancelar**.
+```
+
+## Protocolo do gate
+
+- Enunciar a **Assumption** central junto do blueprint (ex.: "o sample é
+  representativo; `status` tem exatamente os N valores mapeados") — é o que torna a
+  decisão reversível depois. **Não** há audit log a preencher neste projeto.
+- `aprovar` → carregar `generate.md` e executar.
+- `ajustar X` → re-montar → re-apresentar (novo gate).
+- `cancelar` → abortar; nota de cancelamento. Zero disco.
+
+Sinal junto com o preview: `BLUEPRINT_PRONTO: <Entidade> (lista) — aguardando gate`