@softize/opus 12.10.0 → 13.0.0

package/src/ui/meta.ts

@@ -1,433 +1,425 @@
 /**
  * @softize/opus/ui/meta — o mapa CENTRAL de `meta` de todos os componentes.
  *
- * O componente portado é byte-fiel ao shadcn (sem `meta` co-localizado, pra re-sincronizar
+ * O componente portado é byte-fiel ao shadcn (sem `meta` co-localizado, para re-sincronizar
  * limpo); o metadado de descoberta (whenToUse/ancestry) mora AQUI, fora do arquivo. Quem
  * precisa do meta em RUNTIME — a doc de UI (DocBrowser), o manifesto, ferramentas — importa
  * este subpath explicitamente (`@softize/opus/ui/meta`); o barrel de runtime (react.tsx) não
  * o re-exporta de propósito (metadado de build-time, fora do bundle dos apps).
  */
-import type { ComponentMeta } from './index.ts'
+import type { ComponentMeta } from "./index.ts";
 
 /** Todos os metas, chaveados pelo nome canônico (kebab). Fonte única — zero duplicação. */
 export const componentMeta = {
-  'ask': {
-    name: 'ask',
-    ancestry: 'opus',
+  content: {
+    name: "content",
+    ancestry: "opus",
     whenToUse:
-      'Elicitação estruturada controlada para 1–4 perguntas `AskQuestion`: opções single/multi em pills, texto livre opcional, validação e submit de `AskAnswer[]`. Não faz transporte, persistência nem integração automática com ChatEvent; o consumidor controla `answers`/`onChange` e conecta `onSubmit` ao canal apropriado.',
+      "Organize uma região nomeada dentro de uma página ou de outra superfície. Use as propriedades de Content no caso comum e componha seus slots quando precisar controlar a estrutura. Para o cabeçalho principal da tela, use Page.",
   },
-  'alert': {
-    name: 'alert',
-    ancestry: 'opus',
+  ask: {
+    name: "ask",
+    ancestry: "opus",
     whenToUse:
-      'Aviso INLINE no fluxo da página (o erro do login, o "sincronizado" da lista) — `role="alert"`, então o leitor de tela anuncia sozinho. Forma CURTA (o caso comum): `<Alert title description icon variant />` numa linha; composição (`AlertTitle`/`AlertDescription`) só quando o conteúdo é rico (parágrafos, link, ação). `variant` default/destructive/success/warning; quando informado, o ícone recebe realce tonal nativo. Pra INTERROMPER cobrando decisão, use `confirm()`; pra recado passageiro, `toast`.',
+      "Colete respostas para uma a quatro perguntas estruturadas, com opções de escolha única, múltipla ou texto livre. O consumidor controla as respostas e conecta o envio ao canal apropriado; Ask não faz transporte nem persistência.",
   },
-  'badge': {
-    name: 'badge',
-    ancestry: 'shadcn',
+  alert: {
+    name: "alert",
+    ancestry: "opus",
     whenToUse:
-      'Rótulo curto de status/categoria. `variant` pra intenção (default/secondary/destructive/outline) ou tom de status (success/warning/info/danger, fill tingido). Não-interativo — pra clique, use Button ou `asChild` num <a>. Valor de dicionário com papel declarado usa DictionaryValue em vez de escolher a variante à mão.',
+      "Aviso inline no fluxo da página — `context` declara neutral/info/success/warning/danger e `variant` escolhe subtle/outline (ADR 0006). Forma curta: `<Alert title description icon context />`; para conteúdo rico, componha AlertMedia + AlertHeader (AlertTitle e AlertDescription) + AlertActions. A mídia mantém uma moldura tonal quadrada, mesmo com descrição multilinha. O texto comunica o significado sem depender só da cor. Para interromper cobrando decisão, use `dialog.confirm()`; para recado passageiro, `toast`.",
   },
-  'empty-value': {
-    name: 'empty-value',
-    ancestry: 'opus',
+  badge: {
+    name: "badge",
+    ancestry: "shadcn",
     whenToUse:
-      'Representação padrão de valor ausente (`null`, `undefined`, string vazia ou só espaços): em célula compacta (`compact`) mostra o travessão e reserva “Não informado” à leitura assistiva; em texto corrido mostra o rótulo. `label` troca o significado da ausência no domínio (“Nunca enviado”, “Sem vencimento”). `0` e `false` são valores, nunca ausência. Colunas de ActionList e DetailField já a usam; renderer customizado reutiliza em vez de repetir a condicional.',
+      "Rótulo curto de status/categoria. `context` declara neutral/primary/info/success/warning/danger; `variant` escolhe solid/subtle/outline (ADR 0006). Não-interativo — para clique, use Button ou `asChild` em um <a>. Valor de dicionário com papel declarado usa DictionaryValue em vez de escolher contexto ou variante na tela.",
   },
-  'dictionary-value': {
-    name: 'dictionary-value',
-    ancestry: 'opus',
+  "empty-value": {
+    name: "empty-value",
+    ancestry: "opus",
     whenToUse:
-      'Valor de um `t.dict` com a apresentação que o dicionário declarou (ADR 0003): `classification` vira Badge outline, `status`/`stage` viram Badge tonal pelo `tone` da entrada, `plain` ou sem papel vira texto. Ícone só quando a entrada declara `icon` do catálogo; tooltip só quando `description` acrescenta ao rótulo. O texto está sempre presente. Overrides explícitos por `presentation`, `variant`, `icon`, `tooltip` e `fallback`; não inferir badge, cor ou ícone a partir do nome do dicionário. Colunas de ActionList cujo campo é dicionário já usam este renderer.',
+      "Mostre valores ausentes de forma consistente e acessível. O modo compacto usa um travessão visual e preserva “Não informado” para leitores de tela; `label` permite declarar uma ausência específica do domínio. Zero e falso continuam sendo valores.",
   },
-  'dot': {
-    name: 'dot',
-    ancestry: 'opus',
+  "dictionary-value": {
+    name: "dictionary-value",
+    ancestry: "opus",
     whenToUse:
-      'Sinal compacto de estado quando o contexto ou o nome acessível já explica o significado. `variant` segue a intenção semântica (default/secondary/destructive/outline/success/warning/info). Passe `label` quando a cor comunicar informação; sem label, o ponto é decorativo. Para texto visível, use Badge.',
+      "Apresente um valor de `t.dict` conforme a semântica declarada no próprio dicionário. Classificações, status, estágios e valores simples recebem tratamentos previsíveis sem inferências pelo nome; use as propriedades de apresentação apenas para exceções explícitas.",
   },
-  'detail': {
-    name: 'detail',
-    ancestry: 'opus',
+  dot: {
+    name: "dot",
+    ancestry: "opus",
     whenToUse:
-      'Dados somente leitura em pares chave/valor. Compõe DetailGroup > DetailField com semântica de lista de definições; `columns` controla a grade, `orientation` posiciona chave e valor, `variant="framed"` aplica moldura e `dividers` acrescenta somente as divisórias internas. Para entrada, validação e erro, use Field; para uma coleção pesquisável, use ActionList.',
+      "Sinal compacto de estado. `context` declara neutral/primary/info/success/warning/danger e `variant` escolhe solid/outline. Passe `label` quando a cor reforçar informação; sem label, o ponto é decorativo. Para texto visível, use Badge.",
   },
-  'dock': {
-    name: 'dock',
-    ancestry: 'opus',
+  detail: {
+    name: "detail",
+    ancestry: "opus",
     whenToUse:
-      'Barra de ferramentas ancorada a uma superfície de trabalho — canvas, editor, preview —, quando um cabeçalho empilharia mais uma faixa de chrome sobre a trilha. Compõe Dock > DockGroup > DockAction; o estado da superfície (salvamento, versão) fica no SurfaceStatus, que flutua num canto e não pertence à barra. `position` escolhe a aresta; a divisória entre grupos é do componente. Requer TooltipProvider na raiz. Para ações de uma PÁGINA, use as `actions` do Page; para um conjunto de toggles exclusivos, ToggleGroup.',
+      'Dados somente leitura em pares chave/valor. Compõe DetailGroup > DetailField com semântica de lista de definições; `columns` controla a grade, `orientation` posiciona chave e valor e alinha uma coluna compartilhada de rótulos no modo horizontal, `variant="framed"` aplica moldura e `dividers` acrescenta somente as divisórias internas. Para entrada, validação e erro, use Field; para uma coleção pesquisável, use ActionList.',
   },
-  'button': {
-    name: 'button',
-    ancestry: 'shadcn',
+  dock: {
+    name: "dock",
+    ancestry: "opus",
     whenToUse:
-      'Ação clicável. `variant` define intenção (default/secondary/outline/ghost/destructive/link), `size` define altura (default/sm/lg · icon/icon-sm/icon-xs para os casos só-ícone, 2.25/2/1.5rem) e `shape="pill"` troca somente a geometria, sem alterar cor ou hierarquia. `busy` mostra spinner e desabilita. `asChild` renderiza como outro elemento.',
+      "Ancore ferramentas a uma superfície de trabalho, como canvas, editor ou prévia. Agrupe ações relacionadas com DockGroup e mantenha o estado da superfície em SurfaceStatus. Para ações da página, use Page; para opções exclusivas, use ToggleGroup.",
   },
-  'card': {
-    name: 'card',
-    ancestry: 'shadcn',
+  button: {
+    name: "button",
+    ancestry: "shadcn",
     whenToUse:
-      'Superfície da casa (bg-card + text-card-foreground + borda + rounded-xl, flat). Box simples: `<Card className="p-4">…</Card>`. Estruturado: Card > CardHeader(CardTitle/CardDescription) + CardContent + CardFooter — o padding mora nos slots (como o Dialog). Divergência declarada vs shadcn: sem shadow e sem flex/gap forçados (o upstream brigava com card-box simples).',
+      "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala; `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup.",
   },
-  'chat': {
-    name: 'chat',
-    ancestry: 'opus',
+  card: {
+    name: "card",
+    ancestry: "shadcn",
     whenToUse:
-      'Chat da casa (lista de mensagens + composer) que gerencia a conversa por dentro (estado/loading/auto-scroll; Enter envia, Shift+Enter quebra linha). A inteligência vem da prop `send` — resposta inteira (Promise<string>) OU streaming (AsyncIterable<ChatEvent>: texto incremental, indicador vivo do tool, artefato via renderArtifact). No Opus, o backend liga em `runtime.aiFor(base).run(...)` ou `.runStream(...)`. Estado vazio por `greeting` (frase) ou `empty` (nó composto com os slots de Empty). Dê altura ao container (ex.: `h-full`).',
+      "Agrupe conteúdo relacionado em uma superfície delimitada. Use Card diretamente para um bloco simples ou componha cabeçalho, corpo e rodapé quando houver hierarquia e ações. CardContent permanece apenas como alias temporário de compatibilidade.",
   },
-  'checkbox': {
-    name: 'checkbox',
-    ancestry: 'shadcn',
+  "metric-card": {
+    name: "metric-card",
+    ancestry: "opus",
     whenToUse:
-      'Caixa de marcação booleana (Radix). Controlado por `checked`/`onCheckedChange`. Parear com Label. Pra escolha única de várias opções, use Select/RadioGroup.',
+      "Medida resumida com rótulo, valor em destaque e descrição opcional. `context` realça semanticamente somente o ícone; aceita ação relacionada e estado de carregamento. O consumidor calcula e formata o valor; para conteúdo geral ou estrutura livre, use Card.",
   },
-  'icon-picker': {
-    name: 'icon-picker',
-    ancestry: 'opus',
+  chat: {
+    name: "chat",
+    ancestry: "opus",
     whenToUse:
-      'Seletor de ícone: gatilho com o ícone corrente + lista buscável (mesma receita Popover+Command do Select buscável). O value é o NOME do ícone (kebab-case) — renderize com a mesma paleta (iconPickerIcons[name] ?? fallback). Paleta default curada (~40, lucide); vocabulário próprio via prop icons. Pra personalização de item criado pelo usuário (relatório, projeto, pasta).',
+      "Monte uma conversa completa com mensagens, composição, carregamento e rolagem automática. A propriedade `send` aceita resposta integral ou streaming de eventos; use Composer quando precisar apenas da entrada de texto. Defina uma altura para o contêiner.",
   },
-  'command': {
-    name: 'command',
-    ancestry: 'shadcn',
+  checkbox: {
+    name: "checkbox",
+    ancestry: "shadcn",
     whenToUse:
-      'Lista filtrável com teclado (cmdk) — base de command-palettes. Use CommandDialog pra palette modal (⌘K). Pra escolha simples, use o Select direto.',
+      "Caixa de marcação booleana (Radix). Controlado por `checked`/`onCheckedChange`. Parear com Label. Para escolha única de várias opções, use Select/RadioGroup.",
   },
-  'composer': {
-    name: 'composer',
-    ancestry: 'opus',
+  "icon-picker": {
+    name: "icon-picker",
+    ancestry: "opus",
     whenToUse:
-      'A caixa de escrever da casa (o composer do Chat, extraído): textarea numa pílula elevada, Enter envia / Shift+Enter quebra linha, enviar dentro. Use SOZINHO quando há entrada de texto mas não um chat — ex.: o composer de criação de sessão do Maestro (sem histórico). Com `actions`, ganha uma barra embaixo pra seletores discretos à esquerda (app, agente, contexto…) — o mesmo lugar onde o Maestro põe app/task e a GB poria o agente. Sem `actions`, é a linha única de sempre. Controlado (`value`/`onChange`/`onSubmit`); `submitDisabled` gateia além de vazio/busy. Pra um chat completo (mensagens + este composer), use Chat.',
+      "Permita escolher um ícone por uma lista pesquisável. O valor é o nome do ícone em kebab-case; use a mesma paleta ao renderizá-lo e forneça `icons` quando o produto precisar de um vocabulário próprio.",
   },
-  'content-header': {
-    name: 'content-header',
-    ancestry: 'opus',
+  command: {
+    name: "command",
+    ancestry: "shadcn",
     whenToUse:
-      'Cabeçalho semântico de uma seção de conteúdo: título, descrição, meta e ações na mesma composição. Use `variant="section"` dentro de páginas e painéis; `Page` já fornece o cabeçalho principal e não deve receber outro ContentHeader equivalente. O `level` controla a hierarquia do heading sem alterar a hierarquia visual.',
+      "Lista filtrável com teclado (cmdk) — base de command-palettes. Use CommandDialog para palette modal (⌘K). Para escolha simples, use o Select direto.",
   },
-  'copyable': {
-    name: 'copyable',
-    ancestry: 'opus',
+  composer: {
+    name: "composer",
+    ancestry: "opus",
     whenToUse:
-      'Clicar-pra-copiar com feedback: copia `value` pro clipboard e o ícone vira check por ~1.5s. Sem filhos é um botão-ícone (toolbar/célula); com filhos, o rótulo visível + o ícone. Pra IDs, tokens, slugs, URLs. No-op silencioso se o clipboard não existir (contexto inseguro/SSR).',
+      "Receba texto para envio sem montar uma conversa completa. Enter envia, Shift+Enter quebra a linha e `actions` acrescenta uma faixa para seletores relacionados. O componente é controlado; use Chat quando também precisar de mensagens e estado da conversa.",
   },
-  'dialog': {
-    name: 'dialog',
-    ancestry: 'shadcn',
+  "content-header": {
+    name: "content-header",
+    ancestry: "opus",
     whenToUse:
-      'Janela modal com overlay e trap de foco (Radix). O DialogContent é a superfície PURA (sem padding); o espaço mora nos slots: DialogHeader (fixo) > DialogTitle/Description, DialogBody (rola; opcional) e DialogFooter (faixa de ação; opcional). `showCloseButton={false}` no DialogContent esconde o "X" (modal que exige ação). Pra menu de ações, use Menu; pra ancorado sem modal, Popover.',
+      "Estruture o cabeçalho de um Content com título, descrição, metadados e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia.",
   },
-  'input': {
-    name: 'input',
-    ancestry: 'shadcn',
+  copyable: {
+    name: "copyable",
+    ancestry: "opus",
     whenToUse:
-      'Campo de texto de uma linha. Aceita todos os atributos nativos de <input> (type, placeholder, disabled). `icon` (ícone leading, identidade) e `trailing` (ação no fim — limpar, mostrar senha) são adornos por PROP, as mesmas do Select (adorno de campo é prop, não composição). Pra rótulo, parear com Label; pra addon rico (botão no fim, prefixo de texto, múltiplos), InputGroup.',
+      "Copie identificadores, tokens, slugs ou URLs com confirmação visual. Sem filhos, Copyable funciona como botão de ícone; com filhos, mantém um rótulo visível. Em ambientes sem acesso à área de transferência, a ação não produz efeito.",
   },
-  'label': {
-    name: 'label',
-    ancestry: 'shadcn',
-    whenToUse: 'Rótulo acessível de um campo. `htmlFor` aponta pro id do controle. Parear com Input/Textarea/Select.',
-  },
-  'markdown': {
-    name: 'markdown',
-    ancestry: 'opus',
+  dialog: {
+    name: "dialog",
+    ancestry: "opus",
     whenToUse:
-      'Renderiza markdown como HTML semântico (motor markdown-it — o MESMO da doc; o parser de regex saiu em 7.1.0). `html: false`: tag no fonte é escapada, então serve pra texto de gente e de modelo. A tipografia vem do `prose` mapeado nos tokens da casa (theme.css) — não passe classe de tipografia por fora; o 1º/último bloco já não empurram a caixa em volta. Pra código com destaque e cópia, CodeBlock.',
+      "Abra conteúdo ou uma tarefa em uma janela modal com foco contido. Use o modo padrão quando a superfície puder ser dispensada e `mode=\"alert\"` quando exigir resposta explícita. Para o caso imperativo comum, use `dialog.alert`, `dialog.confirm`, `dialog.prompt` ou `dialog.choose`. Distribua conteúdo próprio entre cabeçalho, corpo rolável e rodapé de ações.",
   },
-  'menu': {
-    name: 'menu',
-    ancestry: 'opus',
+  input: {
+    name: "input",
+    ancestry: "shadcn",
     whenToUse:
-      'O menu de AÇÕES da casa: lista flutuante ancorada num gatilho (Radix DropdownMenu). Compõe Menu > MenuTrigger (`asChild` funde no Button) + MenuContent > (MenuItem, MenuCheckboxItem, MenuRadioGroup>MenuRadioItem, MenuLabel, MenuSeparator, MenuShortcut, MenuSub>MenuSubTrigger+MenuSubContent). `variant="destructive"` no item para a ação que apaga. É o único menu (5.0.0): ContextMenu, Menubar e NavigationMenu saíram — mesmo papel com outro gatilho, zero uso. Pra ESCOLHER um valor, use Select; pra busca por teclado, Command; pra conteúdo livre ancorado, Popover.',
+      "Receba texto em uma única linha com os atributos nativos de `input`. Use `icon` para identidade e `trailing` para uma ação no fim do campo; associe uma Label. Quando precisar combinar múltiplos adornos ou controles na mesma moldura, use InputGroup.",
   },
-  'popover': {
-    name: 'popover',
-    ancestry: 'shadcn',
+  label: {
+    name: "label",
+    ancestry: "shadcn",
     whenToUse:
-      'Painel flutuante ancorado num gatilho, sem modal (Radix). Pra conteúdo livre (form curto, detalhes). Use PopoverHeader/PopoverTitle/PopoverDescription pra estruturar. Pra lista de ações, use Menu; pra modal, Dialog.',
+      "Rótulo acessível de um campo. `htmlFor` aponta para o id do controle. Parear com Input/Textarea/Select.",
   },
-  'select': {
-    name: 'select',
-    ancestry: 'opus',
+  markdown: {
+    name: "markdown",
+    ancestry: "opus",
     whenToUse:
-      'Seletor para escolhas em lista. Recebe `options` no formato { value, label, hint?, content?, group? }, sem JSX por item. Os modos são definidos por `searchable`, `multiple`, `onSearch` e `native`. `variant="default"` funciona como campo de formulário; `outline` envolve o conteúdo com borda; `ghost` o envolve sem borda. `size` segue a régua inline (default 2.25rem/sm 2rem), e `shape="pill"` altera somente a geometria. Também aceita `icon`, `trailing`, `triggerLabel` e `clearable`.',
-  },
-  'separator': {
-    name: 'separator',
-    ancestry: 'shadcn',
-    whenToUse: 'Linha divisória entre seções/itens (Radix). `orientation` horizontal|vertical. Decorativa por padrão (a11y).',
+      "Renderize Markdown como HTML semântico com a tipografia do tema. HTML recebido no texto é escapado, por isso o componente pode apresentar conteúdo de pessoas ou modelos com segurança. Para código com destaque e cópia, use CodeBlock.",
   },
-  'skeleton': {
-    name: 'skeleton',
-    ancestry: 'shadcn',
-    whenToUse: 'Placeholder pulsante de carregamento. Dê o tamanho via className (h-4 w-32). Pra estado de loading antes do conteúdo chegar.',
+  menu: {
+    name: "menu",
+    ancestry: "opus",
+    whenToUse:
+      'O menu de ações da casa: lista flutuante ancorada em um gatilho (Radix DropdownMenu). Compõe Menu > MenuTrigger + MenuContent e seus itens. `context="danger"` sinaliza item com consequência perigosa; `destructive` permanece alias de migração. Para escolher um valor, use Select; para busca por teclado, Command; para conteúdo livre ancorado, Popover.',
   },
-  'spinner': {
-    name: 'spinner',
-    ancestry: 'shadcn',
-    whenToUse: 'Loading girando (ação em andamento: botão, fetch). Pra placeholder com forma de conteúdo, use Skeleton.',
+  popover: {
+    name: "popover",
+    ancestry: "shadcn",
+    whenToUse:
+      "Painel flutuante ancorado em um gatilho, sem modal (Radix). Para conteúdo livre (form curto, detalhes). Use PopoverHeader/PopoverTitle/PopoverDescription para estruturar. Para lista de ações, use Menu; para modal, Dialog.",
   },
-  'table': {
-    name: 'table',
-    ancestry: 'shadcn',
+  select: {
+    name: "select",
+    ancestry: "opus",
     whenToUse:
-      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). `variant="plain"` vem sem borda externa; `variant="framed"` aplica a moldura canônica, recorta o scroll e destaca o cabeçalho. Pra listagem tabular — pro pattern de search use ActionList.',
+      "Ofereça escolhas a partir de uma lista declarada em `options`. Habilite pesquisa, seleção múltipla, busca remota ou controle nativo conforme a necessidade; use RadioGroup quando poucas opções precisarem permanecer visíveis.",
   },
-  'tabs': {
-    name: 'tabs',
-    ancestry: 'shadcn',
+  separator: {
+    name: "separator",
+    ancestry: "shadcn",
     whenToUse:
-      'Abas pra alternar entre painéis de conteúdo (Radix). Compõe Tabs > (TabsList > TabsTrigger + TabsContent), pareando `value` do trigger com o do content. `variant` na TabsList: `default` (pill) ou `line` (barra sublinhada, ancorada na borda da lista). `size` no Tabs (default h-9 / sm h-8 — o par do sm de Button/Select, pra fileira densa); a altura pode ser substituída em `TabsList`. `orientation` (horizontal/vertical).',
+      "Linha divisória entre seções/itens (Radix). `orientation` horizontal|vertical. Decorativa por padrão (a11y).",
   },
-  'textarea': {
-    name: 'textarea',
-    ancestry: 'shadcn',
+  skeleton: {
+    name: "skeleton",
+    ancestry: "shadcn",
     whenToUse:
-      'Campo de texto multilinha. Aceita os atributos nativos de <textarea> (rows, placeholder, disabled). Cresce com o conteúdo via `field-sizing-content`.',
+      "Reserve a forma aproximada do conteúdo enquanto ele carrega. Defina dimensões com `className`; para uma espera sem forma conhecida, use Spinner.",
   },
-  'toast': {
-    name: 'toast',
-    ancestry: 'shadcn',
+  spinner: {
+    name: "spinner",
+    ancestry: "shadcn",
     whenToUse:
-      'Notificação efêmera (sonner). Monte `<Toaster />` 1x no root e dispare com `toast.success/error/message(...)`. Pra mensagem persistente inline, use Alert.',
+      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. Para reservar a forma do conteúdo, use Skeleton.",
   },
-  'tooltip': {
-    name: 'tooltip',
-    ancestry: 'shadcn',
+  table: {
+    name: "table",
+    ancestry: "shadcn",
     whenToUse:
-      'Dica curta no hover/foco de um elemento (Radix). Envolver a árvore num TooltipProvider. Só texto auxiliar — nunca pôr ação ou conteúdo essencial aqui.',
+      'Tabela de dados. Compõe Table > (TableHeader > TableRow > TableHead, TableBody > TableRow > TableCell). `variant="plain"` vem sem borda externa; `variant="framed"` aplica a moldura canônica, recorta o scroll e destaca o cabeçalho. Para listagem tabular — para o pattern de search use ActionList.',
   },
-  'truncate': {
-    name: 'truncate',
-    ancestry: 'opus',
+  tabs: {
+    name: "tabs",
+    ancestry: "shadcn",
     whenToUse:
-      'Texto truncado com tooltip SÓ quando transborda (medição do overflow, re-medida em resize) — substitui a composição `block truncate` + `title` sempre presente, que mostra dica até em texto que não corta. `tooltip` sobrepõe o conteúdo da dica (default: os children); `fade` troca as reticências por um esmaecimento até a borda, ligado pela mesma medição. Requer TooltipProvider na raiz. Pra célula de tabela, nome de arquivo, URL — qualquer linha única que pode estourar.',
+      "Alterne entre painéis relacionados no mesmo nível de navegação. Cada TabsTrigger aponta para um TabsContent pelo mesmo `value`; TabsList controla o tratamento visual e Tabs define orientação e escala.",
   },
-  'accordion': {
-    name: 'accordion',
-    ancestry: 'shadcn',
+  textarea: {
+    name: "textarea",
+    ancestry: "shadcn",
     whenToUse:
-      'Lista de seções empilhadas que abrem/fecham (Radix). `type` single (um painel por vez — combine com `collapsible` pra permitir fechar todos) ou multiple (vários abertos). Cada AccordionItem precisa de `value`; o chevron já vem no AccordionTrigger. Pra alternar conteúdo lado a lado, use Tabs; pra um único bloco recolhível solto, use Collapsible.',
+      "Campo de texto multilinha. Aceita os atributos nativos de <textarea> (rows, placeholder, disabled). Cresce com o conteúdo via `field-sizing-content`.",
   },
-  'alert-dialog': {
-    name: 'alert-dialog',
-    ancestry: 'opus',
+  toast: {
+    name: "toast",
+    ancestry: "shadcn",
     whenToUse:
-      'Diálogo modal que INTERROMPE pra cobrar decisão e NÃO fecha clicando fora (`role="alertdialog"`) — a confirmação destrutiva. Desenho ÚNICO e compacto (6.0.0: a prop `size` saiu, o largo não existe mais). Compõe AlertDialog > AlertDialogTrigger (asChild) + AlertDialogContent > AlertDialogHeader(AlertDialogMedia? + AlertDialogTitle/Description) + AlertDialogFooter(Cancel/Action). ATENÇÃO: Action e Cancel do Radix FECHAM ao clicar — pra ação async que só some no sucesso, use Button no footer. Na prática você quase nunca monta isto à mão: `confirm()` já faz, e o DeleteButton/ActionTrigger vêm prontos.',
+      "Comunique um resultado temporário sem interromper o fluxo. Monte Toaster uma vez na raiz e dispare a notificação pela API `toast`; ações seguem a ordem declarada e a última recebe destaque primário. Para uma mensagem persistente no contexto da página, use Alert.",
   },
-  'aspect-ratio': {
-    name: 'aspect-ratio',
-    ancestry: 'shadcn',
+  tooltip: {
+    name: "tooltip",
+    ancestry: "shadcn",
     whenToUse:
-      'Trava a proporção de um bloco (Radix) — a largura vem do pai e a altura é derivada de `ratio` (16/9 pra vídeo/preview, 1 pra quadrado, 4/3 clássico). Use pra mídia, thumbnails e previews de worktree não pularem o layout enquanto carregam. Borda/rounded/overflow-hidden moram no AspectRatio; o filho preenche com h-full w-full object-cover. Pra largura fixa em si, é o contêiner que decide, não este componente.',
+      "Ofereça uma dica curta ao passar o ponteiro ou focar um elemento. Envolva a árvore em TooltipProvider e mantenha ações ou conteúdo essencial fora do tooltip.",
   },
-  'avatar': {
-    name: 'avatar',
-    ancestry: 'shadcn',
+  truncate: {
+    name: "truncate",
+    ancestry: "opus",
     whenToUse:
-      'Retrato de uma pessoa ou agente (Radix). AvatarImage (src/alt) + AvatarFallback (iniciais ou ícone) — o fallback cobre o carregamento e a falha da imagem. `size` sm/default/lg. AvatarBadge é o selo de status no canto (tinja o fundo). Pra a pilha de membros, envolva os Avatar num AvatarGroup e feche o excedente com AvatarGroupCount ("+N").',
+      "Trunque uma linha de texto e mostre a dica somente quando houver transbordamento. Use `tooltip` para substituir o conteúdo da dica e `fade` para trocar as reticências por um esmaecimento. Requer TooltipProvider na raiz.",
   },
-  'breadcrumb': {
-    name: 'breadcrumb',
-    ancestry: 'shadcn',
+  accordion: {
+    name: "accordion",
+    ancestry: "shadcn",
     whenToUse:
-      'Trilha de navegação hierárquica (workspace → repositório → sessão): mostra onde o usuário está e o caminho de volta. `BreadcrumbLink` pros níveis navegáveis, `BreadcrumbPage` pro atual (não clicável), `BreadcrumbSeparator` entre eles e `BreadcrumbEllipsis` pra colapsar trilhas longas. Pra alternar painéis no mesmo nível, use Tabs.',
+      "Lista de seções empilhadas que abrem/fecham (Radix). `type` single (um painel por vez — combine com `collapsible` para permitir fechar todos) ou multiple (vários abertos). Cada AccordionItem precisa de `value`; o chevron já vem no AccordionTrigger. Para alternar conteúdo lado a lado, use Tabs; para um único bloco recolhível solto, use Collapsible.",
   },
-  'button-group': {
-    name: 'button-group',
-    ancestry: 'shadcn',
+  "aspect-ratio": {
+    name: "aspect-ratio",
+    ancestry: "shadcn",
     whenToUse:
-      'Junta botões (e Select) num bloco coeso — bordas internas colapsadas e cantos arredondados só nas pontas. `orientation` define o eixo e `shape="pill"` arredonda as extremidades externas sem reabrir a junção interna. ButtonGroupText adiciona rótulo/prefixo; ButtonGroupSeparator corta visualmente entre ações.',
+      "Preserve a proporção de mídias, miniaturas e prévias enquanto a largura muda ou o conteúdo carrega. A largura vem do contêiner e `ratio` determina a altura; borda, arredondamento e recorte pertencem ao AspectRatio.",
   },
-  'calendar': {
-    name: 'calendar',
-    ancestry: 'shadcn',
+  avatar: {
+    name: "avatar",
+    ancestry: "shadcn",
     whenToUse:
-      'Grade de datas (react-day-picker) pra escolher um dia ou um intervalo. `mode` define a seleção (single/multiple/range) e o formato de `selected`/`onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês/ano (pular pra um período distante); `numberOfMonths` mostra meses lado a lado; `disabled` (Matcher) corta datas. Pra exibir num popover de campo, ancore no Popover.',
+      "Represente uma pessoa ou agente por imagem, iniciais ou ícone de fallback. AvatarBadge acrescenta um estado no canto; AvatarGroup reúne participantes e AvatarGroupCount resume o excedente.",
   },
-  'carousel': {
-    name: 'carousel',
-    ancestry: 'shadcn',
+  breadcrumb: {
+    name: "breadcrumb",
+    ancestry: "shadcn",
     whenToUse:
-      'Trilho de slides deslizáveis (embla). Compõe Carousel > CarouselContent > CarouselItem + CarouselPrevious/CarouselNext; o `basis` do item controla quantos cabem na vista. `orientation` (horizontal/vertical), `opts` repassa o embla (loop, align), `setApi` expõe a instância. Pra lista paginada de dados, use Table; pra navegação entre painéis, Tabs.',
+      "Trilha de navegação hierárquica (workspace → repositório → sessão): mostra onde o usuário está e o caminho de volta. `BreadcrumbLink` para os níveis navegáveis, `BreadcrumbPage` para o atual (não clicável), `BreadcrumbSeparator` entre eles e `BreadcrumbEllipsis` para colapsar trilhas longas. Para alternar painéis no mesmo nível, use Tabs.",
   },
-  'collapsible': {
-    name: 'collapsible',
-    ancestry: 'shadcn',
+  calendar: {
+    name: "calendar",
+    ancestry: "shadcn",
     whenToUse:
-      'Seção que abre e fecha (Radix): um CollapsibleTrigger revela ou esconde o CollapsibleContent. Compõe Collapsible > (CollapsibleTrigger + CollapsibleContent) — o Trigger já é o `<button>`. `defaultOpen` pro modo não controlado; `open`/`onOpenChange` pro controlado (ex.: girar o chevron); `disabled` trava o gatilho. Pra alternar entre vários painéis, use Tabs; pra menu de ações ancorado, Menu.',
+      'Grade de datas (react-day-picker) para escolher um dia ou um intervalo. `mode` define a seleção (single/multiple/range) e o formato de `selected`/`onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês/ano (pular para um período distante); `numberOfMonths` mostra meses lado a lado; `disabled` (Matcher) corta datas. Para exibir em um popover de campo, ancore no Popover.',
   },
-  'drawer': {
-    name: 'drawer',
-    ancestry: 'opus',
+  carousel: {
+    name: "carousel",
+    ancestry: "shadcn",
     whenToUse:
-      'O painel que desliza de uma borda da tela (Radix Dialog: overlay + trap de foco + ESC), pra detalhe/edição lateral sem trocar de tela. Compõe Drawer > DrawerTrigger + DrawerContent (side="right|left|top|bottom") > (DrawerHeader > DrawerTitle/DrawerDescription, conteúdo, DrawerFooter); DrawerClose fecha, `asChild` funde no Button. É o port do `sheet` do shadcn com o nome que o ecossistema React usa — o `drawer` do registry (vaul, com gesto de arrastar) foi removido em 4.0.0: mesmo papel, zero uso. Pra modal centrado, Dialog; pra menu de ações, Menu.',
+      "Trilho de slides deslizáveis (embla). Compõe Carousel > CarouselContent > CarouselItem + CarouselPrevious/CarouselNext; o `basis` do item controla quantos cabem na vista. `orientation` (horizontal/vertical), `opts` repassa o embla (loop, align), `setApi` expõe a instância. Para lista paginada de dados, use Table; para navegação entre painéis, Tabs.",
   },
-  'empty': {
-    name: 'empty',
-    ancestry: 'shadcn',
+  collapsible: {
+    name: "collapsible",
+    ancestry: "shadcn",
     whenToUse:
-      'Região disponível para receber ou criar conteúdo: moldura tracejada centrada com `EmptyHeader` (mídia + `EmptyTitle` + `EmptyDescription`) e `EmptyContent` pras ações. Para lista ou tabela carregada sem registros, use DataState ou ActionList, que preservam a moldura sólida da estrutura. `EmptyMedia variant` icon (quadrado muted) ou default (sem fundo). Pra erro inline use Alert; pra carregamento, Skeleton.',
+      "Seção que abre e fecha (Radix): um CollapsibleTrigger revela ou esconde o CollapsibleContent. Compõe Collapsible > (CollapsibleTrigger + CollapsibleContent) — o Trigger já é o `<button>`. `defaultOpen` para o modo não controlado; `open`/`onOpenChange` para o controlado (ex.: girar o chevron); `disabled` trava o gatilho. Para alternar entre vários painéis, use Tabs; para menu de ações ancorado, Menu.",
   },
-  'field': {
-    name: 'field',
-    ancestry: 'shadcn',
+  drawer: {
+    name: "drawer",
+    ancestry: "opus",
     whenToUse:
-      'O esqueleto de um campo de formulário: rótulo, controle, descrição e erro compostos com espaçamento consistente. Field empilha (orientation vertical) ou põe o controle ao lado (horizontal/responsive, bom pra toggle); FieldLabel (htmlFor↔id), FieldDescription (ajuda) e FieldError (mensagem só quando há erro, ou uma lista de errors) preenchem. Agrupe campos relacionados num FieldSet > FieldLegend + FieldGroup, com FieldSeparator entre eles; FieldContent + FieldTitle dão o bloco texto quando o controle não é um <label>. É layout — o estado e a validação ficam no seu form (ou no ActionForm, que já monta tudo isto).',
+      "Mostre detalhes ou edição a partir de uma borda da tela, sem trocar de página. Estruture cabeçalho, corpo e rodapé dentro de DrawerContent e escolha a borda com `side`. Para uma janela centralizada, use Dialog; para ações ancoradas, use Menu.",
   },
-  'input-group': {
-    name: 'input-group',
-    ancestry: 'shadcn',
+  empty: {
+    name: "empty",
+    ancestry: "shadcn",
     whenToUse:
-      'Campo composto: cola ícones, texto e botões a um InputGroupInput/InputGroupTextarea numa única moldura (foco e erro propagam pro grupo todo). `shape="pill"` aplica a geometria arredondada à moldura. InputGroupAddon ancora adornos; InputGroupText é rótulo inerte; InputGroupButton é o botão embutido. Pra agrupar botões soltos, use ButtonGroup.',
+      "Apresente uma região disponível para receber ou criar conteúdo, com mensagem e ações de próximo passo. Para uma lista ou tabela sem registros, use DataState ou ActionList; para erro, use Alert.",
   },
-  'input-otp': {
-    name: 'input-otp',
-    ancestry: 'shadcn',
+  field: {
+    name: "field",
+    ancestry: "shadcn",
     whenToUse:
-      'Campo de código em casas (one-time password) montado sobre input-otp: InputOTP define `maxLength`, cada InputOTPSlot recebe seu `index`, InputOTPGroup agrupa as casas e InputOTPSeparator divide em blocos. Controle por `value`/`onChange`. Use pra confirmar acesso/2FA com código numérico; pra texto livre, use Input.',
+      "Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e as orientações horizontal ou responsiva quando controle e texto precisarem ficar lado a lado. Field cuida do layout; o formulário continua responsável por estado e validação.",
   },
-  'item': {
-    name: 'item',
-    ancestry: 'shadcn',
+  "input-otp": {
+    name: "input-otp",
+    ancestry: "shadcn",
     whenToUse:
-      'Linha de conteúdo composta — mídia + título/descrição + ações numa linha clicável ou estática. Item é o container (`variant` default/outline/muted, `size` default/sm, `asChild` pra virar link/botão); componha ItemMedia (`variant` icon/image), ItemContent (ItemTitle + ItemDescription), ItemActions e, na borda, ItemHeader/ItemFooter. Empilhe vários num ItemGroup: `variant="framed"` aplica a moldura e a superfície; ItemSeparator declara os divisores internos tanto no modo framed quanto no plain. É o padrão pra listas de workspaces, agentes, repositórios e sessões.',
+      "Receba um código numérico dividido em posições, como uma confirmação de acesso ou segundo fator. InputOTP define o comprimento, os slots representam as posições e o separador organiza blocos. Para texto livre, use Input.",
   },
-  'kbd': {
-    name: 'kbd',
-    ancestry: 'shadcn',
+  item: {
+    name: "item",
+    ancestry: "shadcn",
     whenToUse:
-      'Tecla ou combinação de teclas num atalho (renderiza `<kbd>`). `Kbd` é uma tecla; envolva várias num `KbdGroup` pra formar o combo (ex.: ⌘ + K), com o conector ("+") como texto entre elas. Estiliza, não captura — o handler do atalho é seu. Aceita ícone (lucide) como filho. Dentro de um TooltipContent ganha o tom invertido automaticamente.',
+      "Monte uma linha de conteúdo com mídia, título, descrição, corpo e ações. Ícones e imagens mantêm uma moldura quadrada alinhada ao topo; ItemGroup organiza várias linhas e seus divisores. ItemContent permanece apenas como alias legado.",
   },
-  'pagination': {
-    name: 'pagination',
-    ancestry: 'shadcn',
+  kbd: {
+    name: "kbd",
+    ancestry: "shadcn",
     whenToUse:
-      'Navegação entre páginas montada por composição: Pagination › PaginationContent › PaginationItem com PaginationLink, mais PaginationPrevious/PaginationNext e PaginationEllipsis. `page` dá o número e o nome acessível (“Página N”); `isActive` marca a atual. Com `href` o link é `<a>`; sem `href` vira `<button>` (modo controlado, com foco e `disabled`). Os números têm largura mínima quadrada e crescem com os dígitos; as setas seguem quadradas (`iconOnly`). `label` localiza as setas. É o único paginador: ActionList compõe esta primitiva na escala densa do rodapé. Pra rolagem infinita ou listas curtas, dispense a barra.',
+      "Apresente uma tecla ou combinação de teclas. KbdGroup reúne várias teclas e conectores, mas não registra o atalho; o consumidor continua responsável pelo evento de teclado.",
   },
-  'progress': {
-    name: 'progress',
-    ancestry: 'shadcn',
+  pagination: {
+    name: "pagination",
+    ancestry: "shadcn",
     whenToUse:
-      'Barra de progresso determinada (Radix): mostra o quanto de uma tarefa já foi feito num valor de 0 a 100 em `value`. Pra etapas de um processo conhecido — opus check, sincronização, cobertura. O preenchimento anima a cada mudança de `value`; sem `value` (ou null) fica vazia. Pra carga sem percentual (girando até chegar), use Spinner; pra placeholder com forma de conteúdo, Skeleton.',
+      "Navegação entre páginas montada por composição: Pagination › PaginationContent › PaginationItem com PaginationLink, mais PaginationPrevious/PaginationNext e PaginationEllipsis. `page` dá o número e o nome acessível (“Página N”); `isActive` marca a atual. Com `href` o link é `<a>`; sem `href` vira `<button>` (modo controlado, com foco e `disabled`). Os números têm largura mínima quadrada e crescem com os dígitos; as setas seguem quadradas (`iconOnly`). `label` localiza as setas. É o único paginador: ActionList compõe esta primitiva na escala densa do rodapé. Para rolagem infinita ou listas curtas, dispense a barra.",
   },
-  'radio-group': {
-    name: 'radio-group',
-    ancestry: 'shadcn',
+  progress: {
+    name: "progress",
+    ancestry: "shadcn",
     whenToUse:
-      'Escolha única entre opções mutuamente exclusivas, todas visíveis ao mesmo tempo (Radix). Cada RadioGroupItem tem um `value`; o item escolhido vira o `value` do RadioGroup, controlado por `value`/`onValueChange` (ou `defaultValue` no modo não controlado). Pareie cada item com um Label. Pra poucas opções que cabem na tela; com muitas, prefira Select; pra ligar/desligar um único item, Checkbox ou Switch.',
+      "Mostre o avanço conhecido de uma tarefa com um valor entre zero e cem. Para uma espera sem percentual, use Spinner; para reservar a forma do conteúdo, use Skeleton.",
   },
-  'split': {
-    name: 'split',
-    ancestry: 'opus',
+  "radio-group": {
+    name: "radio-group",
+    ancestry: "shadcn",
     whenToUse:
-      'Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. É o mecanismo espacial para sidebar, conteúdo e rail.',
+      "Escolha única entre opções mutuamente exclusivas, todas visíveis ao mesmo tempo (Radix). Cada RadioGroupItem tem um `value`; o item escolhido vira o `value` do RadioGroup, controlado por `value`/`onValueChange` (ou `defaultValue` no modo não controlado). Pareie cada item com um Label. Para poucas opções que cabem na tela; com muitas, prefira Select; para ligar/desligar um único item, Checkbox ou Switch.",
   },
-  'sidebar': {
-    name: 'sidebar',
-    ancestry: 'opus',
+  split: {
+    name: "split",
+    ancestry: "opus",
     whenToUse:
-      'Chrome e navegação de uma coluna lateral, encaixada onde um Split decidir. `Sidebar` possui o colapso; `PaneHeader`, `PaneContent` e `PaneFooter` estruturam qualquer pane, e `SidebarNav`/`SidebarItem` apresentam navegação com grupos e subgrupos. Serve tanto a barra global quanto uma nav contextual; em Split redimensionável passe `divider={false}` para não duplicar a divisória.',
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. É o mecanismo espacial para sidebar, conteúdo e rail.",
   },
-  'scroll-area': {
-    name: 'scroll-area',
-    ancestry: 'shadcn',
+  sidebar: {
+    name: "sidebar",
+    ancestry: "opus",
     whenToUse:
-      'Região rolável com barra estilizada da casa (Radix), no lugar da scrollbar do sistema. Dê altura (ou largura) ao ScrollArea via className e ponha o conteúdo dentro; a barra vertical já vem por padrão. Pra rolagem horizontal, acrescente `<ScrollBar orientation="horizontal" />` como filho. Pra a página inteira rolar, deixe o navegador cuidar — isto é pra um painel com altura fixa (lista de sessões, log, trilho de skills).',
+      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos, componha árvores com SidebarItem e SidebarTreeGroup e use ShellNav quando a navegação precisar de cabeçalho e rodapé próprios.",
   },
-  'slider': {
-    name: 'slider',
-    ancestry: 'shadcn',
+  "scroll-area": {
+    name: "scroll-area",
+    ancestry: "shadcn",
     whenToUse:
-      'Controle de valor numa faixa contínua, arrastado pelo thumb (Radix). `min`/`max`/`step` delimitam a faixa; `value`/`onValueChange` controlam (array de números — `[n]` pra um thumb, `[a, b]` pra um intervalo) ou `defaultValue` no modo não controlado. `orientation` horizontal/vertical, `disabled` esmaece. Pra um número exato digitado, use Input type=number; pra ligar/desligar, Switch.',
+      'Região rolável com barra estilizada da casa (Radix), no lugar da scrollbar do sistema. Dê altura (ou largura) ao ScrollArea via className e ponha o conteúdo dentro; a barra vertical já vem por padrão. Para rolagem horizontal, acrescente `<ScrollBar orientation="horizontal" />` como filho. Para a página inteira rolar, deixe o navegador cuidar — isto é para um painel com altura fixa (lista de sessões, log, trilho de skills).',
   },
-  'switch': {
-    name: 'switch',
-    ancestry: 'shadcn',
+  slider: {
+    name: "slider",
+    ancestry: "shadcn",
     whenToUse:
-      'Liga/desliga imediato de uma preferência booleana (Radix). Controlado por `checked`/`onCheckedChange` (boolean) e em par com Label. Use pra estado que vale na hora (ativar agente, sincronizar); pra confirmar dentro de um formulário, prefira Checkbox.',
+      "Controle de valor em uma faixa contínua, arrastado pelo thumb (Radix). `min`/`max`/`step` delimitam a faixa; `value`/`onValueChange` controlam (array de números — `[n]` para um thumb, `[a, b]` para um intervalo) ou `defaultValue` no modo não controlado. `orientation` horizontal/vertical, `disabled` esmaece. Para um número exato digitado, use Input type=number; para ligar/desligar, Switch.",
   },
-  'toggle': {
-    name: 'toggle',
-    ancestry: 'shadcn',
+  switch: {
+    name: "switch",
+    ancestry: "shadcn",
     whenToUse:
-      'Botão de duas posições — liga/desliga um estado in-loco, sem sair da tela (Radix). `variant` default (fundo só quando ativo) ou outline (com borda); `size` sm/default/lg. Controlado por `pressed`/`onPressedChange` (ou `defaultPressed` no modo não controlado); ótimo pra alternar uma opção numa toolbar (negrito, quebra de linha, modo somente-leitura). Pra um conjunto de toggles mutuamente exclusivos ou um grupo de formatação, use ToggleGroup; pra um booleano com rótulo num formulário, prefira Switch ou Checkbox.',
+      "Liga/desliga imediato de uma preferência booleana (Radix). Controlado por `checked`/`onCheckedChange` (boolean) e em par com Label. Use para estado que vale na hora (ativar agente, sincronizar); para confirmar dentro de um formulário, prefira Checkbox.",
   },
-  'toggle-group': {
-    name: 'toggle-group',
-    ancestry: 'shadcn',
+  toggle: {
+    name: "toggle",
+    ancestry: "shadcn",
     whenToUse:
-      'Grupo de botões de alternância (Radix). `type` single (um ativo, value: string) ou multiple (vários, value: string[]). Controlado por `value`/`onValueChange`. `variant` default|outline, `size` default|sm|lg e `spacing` descem pros itens via contexto. Serve para alternar a visão de uma seção, montar uma barra de formatação ou apresentar escolhas ricas em cards pelo `ActionForm` com `widget: toggle-group`. Para uma escolha textual comum em formulário, especialmente com rótulos longos sem conteúdo de apoio, prefira RadioGroup.',
+      "Alterne um estado diretamente no contexto atual. ToggleGroup reúne escolhas únicas ou múltiplas e compartilha aparência e escala entre os itens. Para um valor booleano com rótulo em formulário, prefira Switch ou Checkbox.",
   },
 
-  'confirm': {
-    name: 'dialog',
-    ancestry: 'opus',
+  confirm: {
+    name: "dialog",
+    ancestry: "opus",
     whenToUse:
-      'O trio imperativo `dialog.alert` (Promise<void>, reconhecimento obrigatório) · `dialog.confirm` (Promise<boolean>, com slot `body` pra corpo próprio) · `dialog.prompt` (Promise<string|null>, um input). Superfície imperativa como o `toast`, mas que RESPONDE — exige `<DialogHost />` no shell (sem ele LANÇA, em vez de pendurar a promise). Namespace de propósito: `window.alert/confirm/prompt` são globais do browser e um import esquecido cai no nativo; `window.dialog` não existe. Por baixo é o AlertDialog (role=alertdialog, não fecha fora); fila de uma por vez. `confirm()`/`<ConfirmHost/>` seguem como aliases. Pra excluir por contrato, ActionTrigger; pra form de verdade, ActionFormDialog; mais de duas ações, componha o AlertDialog.',
+      "Solicite reconhecimento, confirmação ou uma resposta curta por uma API imperativa. Monte DialogHost uma vez no shell e use `dialog.alert`, `dialog.confirm` ou `dialog.prompt`; as solicitações são exibidas uma por vez. Para ações declaradas em contrato, prefira ActionTrigger; para formulários, use ActionFormDialog.",
   },
-  'action-form': {
-    name: 'action-form',
-    ancestry: 'opus',
+  "action-form": {
+    name: "action-form",
+    ancestry: "opus",
     whenToUse:
-      'Form de uma FormAction do Opus — submit + validação + toast encapsulados. AUTO (sem children): campos auto-detectados do Zod na ordem do contrato. COMPOSIÇÃO (children): diagrame com <ActionFormField name/> — label/widget/erro/asterisco vêm do contrato, o layout é seu. Pra ação sem form, ActionTrigger.',
+      "Renderize e envie uma FormAction com validação, estado de envio e notificação consistentes. Sem filhos, os campos seguem o schema do contrato; com ActionFormField, o consumidor controla o layout sem duplicar rótulos ou erros. Para uma ação sem campos, use ActionTrigger.",
   },
-  'action-form-dialog': {
-    name: 'action-form-dialog',
-    ancestry: 'opus',
+  "action-form-dialog": {
+    name: "action-form-dialog",
+    ancestry: "opus",
     whenToUse:
-      'ActionForm dentro de um Dialog (form em modal) — controla open/onOpenChange + title; fecha no sucesso. Aceita children (modo composição) como o ActionForm. Pra form inline numa página, use ActionForm direto.',
+      "ActionForm dentro de um Dialog (form em modal) — controla open/onOpenChange + title; fecha no sucesso. Aceita children (modo composição) como o ActionForm. Para form inline em uma página, use ActionForm direto.",
   },
-  'action-form-card': {
-    name: 'action-form-card',
-    ancestry: 'opus',
+  "action-form-card": {
+    name: "action-form-card",
+    ancestry: "opus",
     whenToUse:
-      'O ActionForm dentro de um Card do Opus (header/conteúdo/rodapé) — pra estruturar uma seção da página como painel. Segue o padrão do Card (sem divisor nem faixa de modal, com o respiro do Card). Pra form em overlay, ActionFormDialog; pra form cru sem chrome, ActionForm direto.',
+      "Apresente uma FormAction como seção delimitada da página. ActionFormCard combina a estrutura do Card com o comportamento de ActionForm. Para um modal, use ActionFormDialog; sem superfície adicional, use ActionForm.",
   },
-  'action-list': {
-    name: 'action-list',
-    ancestry: 'opus',
+  "action-list": {
+    name: "action-list",
+    ancestry: "opus",
     whenToUse:
-      'A listagem padronizada de uma ListAction — DECLARATIVA pelo contrato: `columns` (tipos, sortable, hidden) vira a tabela (com column picker); `filters` vira a toolbar (inline + `advanced` em modal + chips); `periods` vira o controle de período (presets + Personalizado com calendário → from/to); `text` liga a busca (q, à direita); sort escreve `sort: chave:dir`. `views` = renderers alternativos (board/galeria/lista) com segment — mesma fonte e filtros. Paginação server-driven (limit/page → total no rodapé + pager) e `batch` = multi-seleção com `can` (elegibilidade por item governa checkbox, selecionar-todos e o run). Células via `cells`; URL sync com listParamsToState/listStateToParams. Pra detalhe de 1 recurso, ActionView.',
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. Para um único recurso, use ActionView.",
   },
-  'action-trigger': {
-    name: 'action-trigger',
-    ancestry: 'opus',
+  "action-trigger": {
+    name: "action-trigger",
+    ancestry: "opus",
     whenToUse:
-      'Botão que dispara uma SimpleAction do Opus (sem form): assign, close, archive, excluir. Loading + toast + confirmação (do `action.confirm` do contrato, ou pela prop). `icon` faz o botão virar icon-only com tooltip — a ação que mora NO item (linha, card), sem vazar o clique pro item; `itemLabel` nomeia o alvo na pergunta. Erro de NEGÓCIO (conflict/validation/not_found) mostra a frase do servidor; o resto cai no rótulo do contrato, pra não vazar texto técnico. ATENÇÃO: contrato sem `confirm` dispara DIRETO — a confirmação de ação destrutiva se declara no contrato. Absorveu o DeleteButton (7.0.0). Pra mutação com campos, ActionForm.',
+      "Dispare uma SimpleAction sem campos com carregamento, notificação e confirmação consistentes. Declare confirmações destrutivas no contrato; sem essa declaração, a ação é executada diretamente. Para mutações com campos, use ActionForm.",
   },
-  'action-view': {
-    name: 'action-view',
-    ancestry: 'opus',
+  "action-view": {
+    name: "action-view",
+    ancestry: "opus",
     whenToUse:
-      'Carrega e exibe 1 recurso de uma ViewAction do Opus — loading/error/empty encapsulados; o layout vem por children `(data, refetch) => nó` (render segue como alias). Pra listagem, ActionList.',
+      "Carregue e apresente um recurso de uma ViewAction com estados de carregamento, erro e ausência consistentes. Os filhos definem o layout a partir dos dados e de `refetch`; para uma coleção, use ActionList.",
   },
-  'page': {
-    name: 'page',
-    ancestry: 'opus',
+  page: {
+    name: "page",
+    ancestry: "opus",
     whenToUse:
-      'O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 72rem (`max-w-6xl`) + header com título, descrição e ação à direita (em geral o criar). `className` substitui o teto quando a composição pede outra largura. Presentacional (a página agrega N fontes); o action-driven mora dentro. Pra listagem em modal, ActionListDialog.',
+      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand com title, description, count e actions cria a mesma anatomia de PageHeader(PageTitle/PageDescription/PageMeta/PageActions) + PageBody disponível na forma explícita. `className` substitui o teto quando a composição pede outra largura. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState. Para listagem em modal, ActionListDialog.",
   },
-  'router': {
-    name: 'router',
-    ancestry: 'opus',
+  router: {
+    name: "router",
+    ancestry: "opus",
     whenToUse:
-      'Roteamento history-based sem dependência: `usePathname`/`useSegments`/`useSearchParams` (leitura reativa da URL) + `navigate(path, { replace? })`. O pathname É o estado, então deep-link, reload e o botão voltar funcionam sem um segundo lugar guardando "onde estou". Escopo PEQUENO de propósito: não há tabela de rotas, params tipados nem data loader — quem decide o que renderizar é o app, com if/switch sobre os segmentos. Precisa casar padrão (`/users/:id/posts/:postId`) ou carregar dado por rota? O caso pede uma biblioteca de rotas, não isto. `navigate` é no-op em destino igual (senão o "voltar" não sai do lugar) e usa useSyncExternalStore (useState sofre tearing em concurrent).',
+      "Sincronize navegação simples com a URL sem adicionar uma biblioteca de rotas. Os hooks leem caminho, segmentos e busca de forma reativa, enquanto `navigate` preserva links diretos, recarga e histórico. Para padrões de rota, parâmetros tipados ou carregamento por rota, use um roteador dedicado.",
   },
-  'data-state': {
-    name: 'data-state',
-    ancestry: 'opus',
+  "data-state": {
+    name: "data-state",
+    ancestry: "opus",
     whenToUse:
-      'O estado "carregando" (ANTES do conteúdo): orquestra erro/carregando/vazio/conteúdo de uma carga assíncrona num só lugar — Spinner centralizado no loading, texto em moldura sólida no vazio em bloco e aviso calmo no erro. Em tabela emoldurada, `colSpan` mantém a borda somente no pai. Pra uma região disponível para criação ou vínculo, use Empty, cuja moldura é tracejada. Pra "processando" (ação em andamento DEPOIS do clique), use o `busy` do Button. Pra placeholder com forma, Skeleton.',
+      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
   },
-  'action-list-dialog': {
-    name: 'action-list-dialog',
-    ancestry: 'opus',
+  "action-list-dialog": {
+    name: "action-list-dialog",
+    ancestry: "opus",
     whenToUse:
-      'Uma ListAction em modal: lista query-backed (busca no mount, refaz via invalidates) + chrome padronizado (título/descrição, toolbar com nota "N no total" derivada + ação de criar). Children (items, refetch) diagrama os itens. `loading` agrega a query irmã; `empty` sobrepõe o vazio derivado (ex.: form inline aberto). Pra tabela numa página, ActionList; pra form em modal, ActionFormDialog.',
+      "Apresente uma ListAction dentro de um modal com título, descrição, total e ação relacionada. Os filhos recebem itens e `refetch` para definir a composição da lista. Para uma coleção na página, use ActionList; para um formulário modal, use ActionFormDialog.",
   },
-} as const satisfies Record<string, ComponentMeta>
+} as const satisfies Record<string, ComponentMeta>;
 
-export type ComponentMetaKey = keyof typeof componentMeta
+export type ComponentMetaKey = keyof typeof componentMeta;