@snksergio/design-system 0.61.0 → 0.63.0

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

@@ -0,0 +1,188 @@
+> **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 — Entrevista
+
+## ⛔ Perguntas obrigatórias (NUNCA pular, mesmo inferindo)
+
+1. **Shape do card (Fase 2)** — mesmo inferindo, APRESENTAR o mapa de slots
+   (leading/title/subtitle/meta/...) e **confirmar em lote**. Nunca gerar com o
+   card só inferido sem o usuário ver/confirmar.
+2. **Views (Fase 4)** — **OFERECER e explicar o valor**: _"abas com filtros
+   pré-configurados (ex.: Admins, Ativos) — troca de recorte num clique. Quer
+   alguma?"_ Default = nenhuma, mas só após perguntar.
+
+Princípios:
+
+- **Fases agrupadas com defaults explícitos** — cada pergunta mostra o default;
+  "ok/Enter" aceita.
+- **Modo expresso** — o usuário pode dizer "aceita os defaults daqui pra frente".
+- **Dados podem ser incompletos** — fonte sem payload → slots viram hipóteses a
+  confirmar (nunca gerar silenciosamente).
+- `AskUserQuestion` quando enumerável; prosa quando aberto.
+
+---
+
+## Fase 0 — Entidade + fonte de dados (obrigatória)
+
+1. **Entidade**: singular/plural (ex: "Membro/Membros") + 1 frase de domínio.
+2. **Fonte de dados** — uma de:
+   - **(a) Sample JSON colado** ← preferido (inferência valor+nome).
+   - **(b) Interface TypeScript** (inferência nome+tipo).
+   - **(c) Descrição de endpoint** (inferência só por nome → confiança baixa).
+   - **(d) Listagem manual** (`campo: tipo`).
+3. **Client vs server mode**:
+   - API pagina/filtra no servidor e devolve `total`? → **server**
+     (`mode="server"` + `onQueryChange` + `total`; DataList NÃO filtra local).
+   - Dataset completo de uma vez (ou mock)? → **client** (default).
+4. **Volume estimado** (decide proposta de escala na Fase 6). Default "< 1.000".
+5. **Campo id único** — todo item precisa `id`. Default `id`.
+
+---
+
+## Fase 1 — Página e shell (agrupada)
+
+| Pergunta               | Default                                                                |
+| ---------------------- | ---------------------------------------------------------------------- |
+| Título da página       | plural da entidade                                                     |
+| Descrição (1-2 frases) | gerada do domínio, confirmar                                           |
+| **Wrapper**            | ver abaixo                                                             |
+| Rota (kebab-case)      | derivada do nome — **verificar colisão no router deste projeto**       |
+| Onde entra na nav      | perguntar (menu lateral? submenu? qual grupo?)                        |
+
+**Wrapper — 3 opções:**
+
+- **(a) `ExamplePageLayout`** (default neste repo) — standalone, padrão dos
+  `List*Preview`. Props `category/title/description/code/children`. Dá altura
+  definida pro preview (pré-requisito de `fillHeight`/virtualização).
+- **(b) `AppShell` + `PageHeader`** — tela "real". Perguntar drawer de criação /
+  DetailDrawer no item click. Forms seguem L-023 (`FormField`) + L-024 (`gap-form-gap`).
+- **(c) Componente puro** — consumer (PAGES_DIR/REGISTRO do ambiente).
+
+---
+
+## Fase 2 — Card (shape) — confirmação em lote
+
+O DataList passa cada item pro `List`, que monta o card por **slots** OU por
+**`renderItem`** (card rico). Decidir qual:
+
+### 2a. Slots (caso comum) — mapear campos → slots
+
+Apresentar UM mapa e confirmar em lote:
+
+```
+| slot       | campo / conteúdo            | nota |
+|------------|-----------------------------|------|
+| leading    | <avatar/ícone>              | opcional |
+| title      | <campo>                     | OBRIGATÓRIO |
+| subtitle   | <campo>                     | opcional (ex: email) |
+| description | <campo>                    | opcional (line-clamp 2) |
+| meta[]     | <label:campo (align)>, ...  | colunas à direita (ROLE/STATUS/VISTO) |
+| trailing   | <badge/chip/contagem>       | opcional |
+```
+
+Inferência de slot por nome (PT+EN): `name/nome/title` → title · `email` →
+subtitle · `status/role/papel` → meta (com dot ou chip) · `avatar/photo/foto` →
+leading. `meta[].value` pode ser texto ou um chip/StatusDot — confirmar.
+
+### 2b. renderItem (card rico) — quando MUITOS campos / layout custom
+
+Se o item tem layout próprio (ex: pedido com header+meta+footer, progresso,
+avatar-stack) → `renderItem={(item) => <Card .../>}`. Espelhar
+`ListRichPreview.tsx`. O wrapper (card/hover/click/menu) continua do List.
+
+| Item                           | Default                                       |
+| ------------------------------ | --------------------------------------------- |
+| Densidade                      | `comfortable` (ou `compact`)                  |
+| Menu por card (`getMenuItems`) | oferecer Editar/Excluir (Excluir destructive) |
+
+---
+
+## Fase 3 — Layout (agrupada)
+
+| Layout                 | Quando                      | Extras a perguntar                                                                                                                                                      |
+| ---------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **standard** (default) | lista plana                 | —                                                                                                                                                                       |
+| **grouped**            | seções por status/categoria | `groups` (id/label/color) · `enableDnD` (arrastar entre/dentro → `onMove`/`onReorder`) · `groupSurface`                                                                 |
+| **hierarchical**       | árvore (pai→filho)          | itens com `children` · `defaultExpandedIds` · **`branchHighlight`**: `none` (conectores) / `block` (painéis) / `active` (ramo do último aberto) · lazy `onLoadChildren` |
+
+`branchHighlight` só em hierarchical. DnD só em standard/grouped (excludente com virtualização).
+
+---
+
+## Fase 4 — Toolbar (agrupada)
+
+A toolbar do DataList é enxuta (reusa o TableToolbar): visões(abas)/título ·
+refresh · busca · filtro(drawer) · ⋯. Sem colunas/toggle de visão.
+
+> ⛔ **Anti-pattern — NUNCA gerar form/selects soltos ACIMA da lista.** Intenção de
+> "adicionar filtro" (select de status em cima, campo de período, "filtrar por X") →
+> **sugira o padrão certo** (o DataList já filtra reativo, com chips clicáveis/editáveis):
+>
+> - **Filtro por campo** (status/categoria/tipo/data…) → declare em `filterFields`. Quer
+>   abrir já filtrado? **pré-aplique** via `views` ou `filterModel` → abre com o **chip
+>   aplicado**, editável, reativo. Pode pré-setar **vários** de uma vez.
+> - **toolbarActions é SÓ pra caso pequeno e simples que NÃO reage com campo** (ex.:
+>   data/período, escopo) — **label curta**, **máx ~2**. Se mexe com os campos, é grande,
+>   ou são muitos → **NÃO use o toolbar.**
+> - **Muitos filtros, ou ligados a campo** → SEMPRE os nativos **pré-aplicados** (chips no
+>   load) + drawer "Filtros". Nunca empilhar selects.
+>
+> Regra de ouro: **filtro é recurso do DataList (reativo), não UI montada na unha.**
+
+| Item               | Pergunta                                                                                                                                                                                            | Default                                     |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| Título OU views    | título à esquerda, ou abas de visão?                                                                                                                                                                | título (plural)                             |
+| Busca              | `searchable` (cobre title/subtitle/description + accessors)                                                                                                                                         | on                                          |
+| **filterFields**   | quais campos filtram? cada um: `{ id, label, type, accessor, options? }`                                                                                                                            | inferir dos campos select/status; confirmar |
+| **Views (abas)**   | presets `{ id, label, query:{search, filterModel} }` — OFERECER (ver obrigatória)                                                                                                                   | nenhuma                                     |
+| Refresh            | `onRefresh`                                                                                                                                                                                         | on                                          |
+| **toolbarActions** | ações custom no toolbar (`button`/`dropdown`/`input`, ex.: seletor de período/mês). Inline no desktop; **colapsam no ⋯ no mobile**. Oferecer quando o usuário pedir um seletor/botão extra na barra | off                                         |
+| moreActions (⋯)    | itens extras?                                                                                                                                                                                       | off                                         |
+
+`filterFields.type` ∈ text/select/boolean/number/date. Chips de filtro aplicado
+aparecem automaticamente (ToolbarApplied). Filtro abre o MESMO drawer da tabela.
+
+---
+
+## Fase 5 — Seleção, bulk e click
+
+| Item          | Pergunta                                                                       | Default           |
+| ------------- | ------------------------------------------------------------------------------ | ----------------- |
+| `selectable`  | checkbox por card + bulk bar                                                   | off               |
+| `bulkActions` | `{ label, icon?, onClick(ids), destructive? }[]` (ex: Editar/Arquivar/Excluir) | se selectable on  |
+| `onItemClick` | nada / abrir detalhe / navegar                                                 | nada (standalone) |
+
+Excluir (destructive) em drawer/form ⇒ confirmação via `AlertModal`.
+
+---
+
+## Fase 6 — Escala (excludentes)
+
+| Opção               | Quando                                       | Props                                                            |
+| ------------------- | -------------------------------------------- | ---------------------------------------------------------------- |
+| Nenhuma (default)   | < ~1.000 itens                               | —                                                                |
+| **Virtualização**   | listas grandes (só `standard`) — desliga DnD | `virtualized` (+ `estimateItemSize`)                             |
+| **Infinite scroll** | paginar ao rolar                             | `onLoadMore` + `hasMore` + `loadingMore` (+ skeleton automático) |
+
+Em tela dedicada (`ExamplePageLayout`), propor `fillHeight` + `className="flex-1
+min-h-0"` (toolbar fixa, só a lista rola). Não combinar `fillHeight` com `virtualized`.
+
+---
+
+## Encerramento
+
+Consolidar TODAS as escolhas num objeto de decisões (em memória — nada em disco),
+carregar `blueprint.md` e montar o preview do gate.
+
+Sinal: `BLUEPRINT_PRONTO: <Entidade> (lista) — aguardando gate`

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

@@ -0,0 +1,63 @@
+> **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 — Geração (consumidor)
+
+Só entre aqui após o gate aprovado. Ordem obrigatória:
+
+## 1. Puxar do registry (componente + exemplo canônico)
+
+```bash
+npm run igreen:add -- data-list example-mapa-rede
+# + outros componentes citados no blueprint (chip, page-header, floating-panel,
+#   alert-modal, etc — o registry resolve as deps automaticamente)
+```
+
+`data-list` traz junto `list`, `table-toolbar`, `data-table` (via registryDependencies).
+
+## 2. LER antes de escrever (precedência de fontes)
+
+1. `src/examples/mapa-rede/mapa-rede-screen.tsx` — o molde real (DataList
+   `layout="hierarchical"` + `branchHighlight` + `renderItem` do card + `fillHeight`
+   - painel de detalhe `FloatingPanel` + `AlertModal`).
+2. `src/components/ui/DataList/USAGE.md` + `src/components/ui/List/USAGE.md` + types ao lado — API exata.
+3. Pra card rico / outros layouts (standard/grouped/DnD): adapte a forma do exemplo.
+
+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 .../>`
+  → `<DataList fillHeight className="flex-1 min-h-0" .../>`.
+- Card via **slots** (`leading/title/subtitle/meta/trailing`) OU `renderItem` (card rico).
+- Layout `standard`/`grouped`(+`enableDnD`)/`hierarchical`(+`branchHighlight`) conforme blueprint.
+- `filterFields` com `accessor: (item) => valor`; views (abas); seleção/bulk; escala
+  (`virtualized` XOR `onLoadMore`) — um por vez.
+- Painel de detalhe / modais (se houver): espelhe `ConsultorDetailPanel` (FloatingPanel) e
+  o `AlertModal` do exemplo, ligados via estado da página.
+- 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
+
+`LIST_PRONTO: <Entidade>` + onde foi registrada + como rodar (`npm run dev`).
+Sugira ao usuário abrir a tela e conferir; ofereça ajustes finos (card, filtros, layout).

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

@@ -0,0 +1,91 @@
+> **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.
+
+
+# List Builder (consumidor) — Router
+
+Você guia a criação de uma tela de **lista de cards** que consome `<DataList>`
+**sem fugir do exemplo e da documentação**. NÃO inventa API de props, NÃO gera
+código de memória, NÃO toca em arquivo antes do gate aprovado.
+
+## ⚠️ Desambiguação ANTES de tudo (anti-erro)
+
+Muita gente chama tabela de "lista". Se você chegou aqui direto sem o front-door,
+confirme em 1 pergunta que o caso é mesmo lista de cards — senão a pessoa cria errado:
+
+| Lista de cards (ESTA skill)                                             | Tabela/grade (→ `crud-builder`)                                    |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| cada item é um **card**; poucos campos em destaque (avatar/título/meta) | colunas × linhas; muitos campos por registro                       |
+| visual, hierarquia/agrupamento/DnD, feed, organograma                   | comparar/ordenar/filtrar **por coluna**, editar célula, somatórios |
+| ex: membros, tarefas, organização (árvore), rede, atividades            | ex: clientes, financeiro, pedidos com muitas colunas               |
+
+Caso for tabela → **PARAR** e usar `crud-builder` (`/ds-create-crud`).
+
+## Ambiente (este é um projeto CONSUMIDOR, copy-in)
+
+| Variável                 | Valor                                                                                                                   |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `IMPORT_PATH`            | `@/components/ui/DataList`, `@/components/ui/List`, etc (copy-in via alias)                                             |
+| `EXEMPLO_CANÔNICO`       | `example-mapa-rede` → `npm run igreen:add -- example-mapa-rede` → ler `src/examples/mapa-rede/mapa-rede-screen.tsx`     |
+| `DOC`                    | `src/components/ui/DataList/USAGE.md` + `src/components/ui/List/USAGE.md` (após `igreen:add data-list`) + 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/mapa-rede/mapa-rede-screen.tsx` —
+> **NÃO** rode `igreen:add`. `PAGES_DIR`/`REGISTRO` continuam do projeto pai.
+
+## Fluxo — 3 estágios
+
+```
+/ds-create-list  (ou /ds-create-screen → desambiguação → aqui)
+   ▼ 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/mapa-rede/mapa-rede-screen.tsx  (exemplo real, vence tudo)
+2. src/components/ui/DataList/USAGE.md + src/components/ui/List/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. `virtualized` e `enableDnD` são **mutuamente exclusivos**; `virtualized` e
+   `onLoadMore` (infinite-scroll) **não combinam** — escolha um.
+2. `branchHighlight` (`block`/`active`) só faz efeito em `layout="hierarchical"`.
+3. `filterFields` declara `accessor: (item) => valor` (NÃO column def); `select`
+   precisa `options`. Operador de view/filtro válido pro tipo (multiSelect⇒isAnyOf,
+   select⇒equals, text⇒contains, number⇒equals, date⇒between, boolean⇒equals).
+4. `fillHeight` em tela dedicada ⇒ pai com altura + `className="flex-1 min-h-0"`
+   (toolbar/chips/bulk fixos, só a lista rola). Não usar com `virtualized`.
+5. `layout="grouped"` exige `groups`; `hierarchical` exige itens com `children`.
+6. Card via slots OU `renderItem` (não os dois). Forms (criar/editar em drawer)
+   usam `<FormField>` + `gap-form-gap`.
+7. Classes DS antes de Tailwind literal; zero hardcode de cor/tamanho (ver `.claude/rules/ds-design.md`).
+8. Wrapper da tela: `flex flex-col h-full min-h-0 gap-gp-2xl` (PageHeader → 16px → lista). Ver `DESIGN.md`.
+9. Página registrada no roteador do usuário — página órfã = tarefa incompleta.
+10. `npx tsc --noEmit` limpo antes do handoff (abort-on-error).
+11. LER o exemplo canônico ANTES de gerar — nunca de memória.
+
+## Handoff
+
+- Entrevista pronta → `BLUEPRINT_PRONTO: <Entidade> (lista) — aguardando gate`
+- Pós-geração → `LIST_PRONTO: <Entidade>` (+ onde foi registrada)

package/dist-lib/ai/roteiros/module-replicator/roteiro.md

@@ -0,0 +1,56 @@
+> **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/`.
+
+# module-replicator — Replicar família de telas (segmento)
+
+Quando um app tem **módulos espelhados** (ex.: várias verticais/segmentos com a
+mesma estrutura de telas), replica a família trocando só o que varia.
+
+## ⚠️ Antes de copiar: copiar OU parametrizar?
+
+Copiar N vezes = N cópias pra manter (todo bug/ajuste ×N). **Se as telas são
+idênticas em estrutura e só mudam dados/rótulos**, o melhor costuma ser
+**parametrizar** — 1 componente dirigido por config de segmento:
+
+```tsx
+const SEGMENTOS = { energia: {...}, telecom: {...}, seguros: {...} };
+function SegmentoDashboard({ seg }: { seg: SegKey }) { /* lê SEGMENTOS[seg] */ }
+```
+
+Ofereça as duas ao usuário: **(a) parametrizar** (recomendado se ≥3 clones ou
+manutenção conjunta) ou **(b) replicar arquivos** (ok pra 1-2 e quando os
+segmentos devem divergir depois). Só siga pra cópia se ele escolher (b).
+
+## Fluxo (replicar arquivos — opção b)
+
+1. **Identifique o módulo-fonte**: as telas/arquivos + o contexto de nav dele
+   (`nav-data`) + as rotas (`routes`).
+2. **Separe o que VARIA** (dataset/mock, rótulos/títulos, id/ícone/cor do contexto,
+   hrefs `#/<segmento>/...`) do que é **ESTRUTURAL** (layout, colunas, componentes,
+   spacing) — o estrutural fica **idêntico**.
+3. **Copie** as telas → novo segmento; troque só o que varia (1 arquivo de mock por
+   segmento, mesma shape/tipos).
+4. **Registre** o novo contexto em `nav-data` + as entradas no mapa de rotas
+   (ver skill `app-builder`). Hrefs únicos por segmento.
+5. `npx tsc --noEmit` limpo.
+
+## Gotchas do tipo
+
+- **Nunca altere a ESTRUTURA na cópia** — se divergir, vira manutenção ×N e perde o
+  sentido de "família". Só dados/rótulos/ícone/cor/href mudam.
+- **Mock**: um arquivo por segmento com a MESMA shape (reuse os tipos). Não duplique tipos.
+- **Nav/rotas**: `id`/label/icon/color do contexto únicos; hrefs `#/<segmento>/<tela>`;
+  1 linha por tela no mapa de rotas (não if-chain).
+- Se depois um segmento precisar de tela exclusiva, aí sim diverge só aquela.
+
+Aplique `DESIGN.md`. Handoff: `MODULO_PRONTO: <segmento> (N telas)` + rotas.

package/dist-lib/ai/roteiros/page-detail/roteiro.md

@@ -0,0 +1,32 @@
+> **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.
+
+
+# page-detail — Página de detalhamento
+
+Página de leitura/inspeção de um registro: cabeçalho + abas + cards de seção.
+
+## Fluxo
+1. `npm run igreen:add -- example-order-detail` (traz a tela + `Tabs`, `Card`, `Chip`, `PageHeader`).
+2. **Leia** `src/examples/order-detail/order-detail-screen.tsx` + USAGE dos componentes.
+3. Adapte as abas/seções/campos ao registro do usuário.
+4. Registre a rota. `npx tsc --noEmit` limpo.
+
+> **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/shadcn/tabs`)
+> e leia o exemplo direto em `<dsPath>/src/examples/order-detail/order-detail-screen.tsx` —
+> **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+- Estrutura: `PageHeader` (título + badges de status + ações) → `Tabs` (visão geral / detalhes / atividade / comentários / anexos) → cards de seção (`section-card`).
+- `Tabs` tem a variant `line` (underline) além da default segmented — use `line` pra navegação de abas de detalhe/ficha; segmented pra alternância de conteúdo curto.
+- Layout 2 colunas (conteúdo + painel lateral do cliente/meta) num grid responsivo; empilha no mobile.
+- Badges de status via `Chip`/`Badge` com cor semântica (`success`/`warning`/...).
+- Wrapper de página: `flex flex-col h-full min-h-0 gap-gp-2xl`.
+- Campos label/valor: rótulo `text-caption` em `fg-muted`, valor `text-body`.
+
+Se a tela também edita inline ou abre drawer de edição → ver skill `drawers`. Aplique `DESIGN.md`. Handoff: `DETAIL_PRONTO: <Entidade>` + rota.

package/dist-lib/ai/roteiros/page-edit/roteiro.md

@@ -0,0 +1,31 @@
+> **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.
+
+
+# page-edit — Tela de edição/cadastro
+
+Tela de formulário (criar/editar). Não gere de memória — puxe e adapte o exemplo.
+
+## Fluxo
+1. `npm run igreen:add -- example-edit-page` (traz a tela + `FormField`, `Button`, etc).
+2. **Leia** `src/examples/edit-page/edit-page-screen.tsx` + `src/components/ui/FormField/USAGE.md`.
+3. Adapte os campos ao caso do usuário (mantendo a estrutura de seções/steps).
+4. Registre a rota onde o usuário indicar. `npx tsc --noEmit` limpo.
+
+> **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/FormField`)
+> e leia o exemplo direto em `<dsPath>/src/examples/edit-page/edit-page-screen.tsx` —
+> **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+- **Sempre `<FormField>`** (FormFieldInput/Select/Textarea/Switch) — nunca `<label>` cru (peso/cor/dark-mode divergem). Spacing entre campos = `gap-form-gap` (20px).
+- Validação inline via `errorMessage` no FormField; helper via `helperText`.
+- Multi-step: padrão `StepNav` lateral do example-edit-page (estado `activeStep` + refs de seção).
+- Wrapper de página: `flex flex-col h-full min-h-0 gap-gp-2xl`; PageHeader com ações Cancelar/Salvar.
+- Ações: Salvar = `<Button color="primary" variant="filled">`; Cancelar = `secondary outline`.
+
+Aplique `DESIGN.md` + `.claude/rules/ds-design.md`. Handoff: `EDIT_PRONTO: <Entidade>` + rota.

package/dist-lib/ai/roteiros/screen-composer/roteiro.md

@@ -0,0 +1,95 @@
+> **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.
+
+
+# screen-composer — Página composta (estado compartilhado)
+
+Não é um tipo de peça — é a **cola** entre peças. Cada peça vem de um builder
+(crud/list/dashboard/drawers); aqui você monta o layout e **cabeia o estado que
+elas compartilham**. A receita completa está logo abaixo, em "Os 2 padrões".
+
+## Quando esta skill (vs os builders diretos)
+
+- 1 peça só (uma tabela, uma lista, um dashboard) → vá direto no builder.
+- **2+ peças que reagem entre si** (master-detail e/ou cross-filter) → **aqui**.
+
+## Fluxo
+
+1. **Decomponha** a página: quais peças (tabela / lista / KPIs+gráfico / detalhe /
+   filtro global) e quais **interações** (clicar→detalhe? controle→filtra tudo?).
+2. **Monte cada peça** pelo builder certo (crud/list/dashboard) OU puxe o exemplo
+   composto: `npm run igreen:add -- example-finance` (master-detail: tabela +
+   detail panel + drawers) / `example-order-detail`. **Leia** o exemplo.
+3. **Cabeie o estado no nível da PÁGINA** — ver "Os 2 padrões" abaixo.
+4. `npx tsc --noEmit` limpo.
+
+## Os 2 padrões (cobrem quase toda página composta)
+
+Estado que 2+ peças compartilham **não mora em cada peça**: sobe pro componente da
+página (single source of truth) e desce por props.
+
+### Master-detail — clicar num item abre o detalhe
+
+```tsx
+function ClientesPage() {
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const selected = selectedId ? findById(selectedId) : null;
+  return (
+    <div className="flex h-full min-h-0 gap-gp-2xl">
+      <DataTable
+        rows={rows}
+        columns={cols}
+        onRowClick={(row) => setSelectedId(row.id)}   // grade → estado
+        className="flex-1 min-h-0"
+      />
+      {/* ao LADO = FloatingPanel/painel fixo · POR CIMA = Drawer/Sheet */}
+      <DetailPanel item={selected} onClose={() => setSelectedId(null)} />
+    </div>
+  );
+}
+```
+
+Nunca duplique a linha no detalhe — passe só o `id`/objeto selecionado.
+
+### Cross-filter — um controle alimenta várias peças
+
+```tsx
+function PainelPage() {
+  const [periodo, setPeriodo] = useState<Periodo>("mes");
+  const data = useMemo(() => filtrar(base, periodo), [periodo]);  // 1 fonte
+  return (
+    <div className="flex flex-col gap-gp-2xl">
+      <PageHeader actions={<PeriodSelector value={periodo} onChange={setPeriodo} />} />
+      <KpiGroup>{/* lê `data` */}</KpiGroup>
+      <ChartCard data={data} />
+      <DataTable rows={data.rows} columns={cols} />
+    </div>
+  );
+}
+```
+
+- **Um** `useMemo` deriva o dataset; todas as peças leem dele (não refazem fetch).
+- Filtro por **coluna** continua nativo/pré-aplicado (chips) — ver `ds-components.md`.
+  O cross-filter aqui é o **escopo global** (período/segmento), no `PageHeader.actions`.
+- Os dois combinam: `selectedId` e `periodo` convivem no mesmo nível.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> NÃO rode `igreen:add` — leia os exemplos em `<dsPath>/src/examples/` e importe via `importBase`.
+
+## Gotchas do tipo
+
+- **Single source of truth**: estado que 2+ peças compartilham SOBE pra página, não
+  fica duplicado em cada peça. Peça isolada mantém o seu.
+- **Master-detail**: passe só `id`/objeto seleto pro detalhe (nunca remonte a linha).
+  Ao lado = `FloatingPanel`/painel fixo; por cima = `Drawer`/`Sheet`.
+- **Cross-filter**: um `useMemo(filtrar(base, filtro))` alimenta KPIs+gráfico+tabela;
+  não refaça fetch por peça. Filtro por COLUNA continua nativo/pré-aplicado (L-051);
+  o cross-filter é o escopo global (período/segmento), no `PageHeader.actions`.
+- **Layout**: shell `flex flex-col gap-gp-2xl` (ou `flex gap` p/ master-detail lado a lado);
+  `fillHeight`/`flex-1 min-h-0` nas peças que rolam.
+- Conteúdo/estilo de cada peça = responsabilidade do builder dela; aqui é só layout + estado.
+
+Aplique `DESIGN.md`. Handoff: `SCREEN_PRONTO: <página>` + rota.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snksergio/design-system",
-  "version": "0.61.0",
+  "version": "0.63.0",
   "//distribuicao": "Canal PRIMARIO = registry shadcn (copy-in) + CLI @snksergio/create-design-system; sobe sozinho no merge (Vercel). Canal SECUNDARIO = este pacote npm (@snksergio/design-system), publicado por passo MANUAL do mantenedor, entao costuma ficar atras do registry. SECUNDARIO descreve a ORDEM DE PUBLICACAO, nao o nivel de suporte: NAO e depreciado, e desde a 0.37.0 entrega 41 dos 42 componentes ui/ no barrel raiz + os 41 primitivos shadcn no subpath ./shadcn (so TabelaTeste, demo interno, fica de fora). Publish so pelo Passo 7 do .claude/skills/ds-dev/release.md (valida com `npm run lib:verify`, pede o token, publica, revoga). Ver DISTRIBUICAO.md.",
   "description": "iGreen Design System — internal library for SaaS CRM, admin panels and dashboards. React 19 + Tailwind v4 + Shadcn + Radix.",
   "license": "UNLICENSED",
@@ -19,8 +19,10 @@
     "dist-lib/chunks/**",
     "dist-lib/src/**",
     "dist-lib/tokens/**",
+    "dist-lib/ai/**",
     "README.md"
   ],
+  "//ai-bundle": "dist-lib/ai/ é o pacote de conteúdo pra IA fora do Claude Code (roteiros, regras, exemplos, guias, manifesto com versão+commit). É LIDO POR CAMINHO, não importado — por isso só o manifest.json tem entrada em exports, como âncora resolvível e verificada pelo lib-verify; os outros 60+ arquivos seguem o precedente de dist-lib/fonts/**, que está em files sem export e o gate aprova. Enumerar 60 markdowns em exports seria ruído, e wildcard não é verificado (ver //exports-theme-marcas). Gerado no closeBundle do vite.lib.config.ts.",
   "engines": {
     "node": ">=20.0.0"
   },
@@ -44,6 +46,7 @@
       "import": "./dist-lib/shadcn.mjs",
       "require": "./dist-lib/shadcn.cjs"
     },
+    "./ai/manifest.json": "./dist-lib/ai/manifest.json",
     "./theme.css": "./dist-lib/theme.css",
     "./theme/brand-blue.css": "./dist-lib/theme/brand-blue.css",
     "./theme/brand-green.css": "./dist-lib/theme/brand-green.css",