@softize/opus 12.11.0 → 13.0.0

package/src/ui/meta.ts

@@ -1,7 +1,7 @@
 /**
  * @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
@@ -15,37 +15,37 @@ export const componentMeta = {
     name: "content",
     ancestry: "opus",
     whenToUse:
-      "Região semântica nomeada dentro de uma página ou outra superfície. O shorthand cria ContentHeader e ContentBody; a forma explícita compõe Content > ContentHeader(ContentTitle/ContentDescription/ContentMeta/ContentActions) + ContentBody. ContentHeader nunca fica solto. Para o cabeçalho principal, use Page.",
+      "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.",
   },
   ask: {
     name: "ask",
     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.",
+      "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.",
   },
   alert: {
     name: "alert",
     ancestry: "opus",
     whenToUse:
-      "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 acompanha a altura útil do header. O texto comunica o significado sem depender só da cor. Para interromper cobrando decisão, use `dialog.confirm()`; para recado passageiro, `toast`.",
+      "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`.",
   },
   badge: {
     name: "badge",
     ancestry: "shadcn",
     whenToUse:
-      "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` num <a>. Valor de dicionário com papel declarado usa DictionaryValue em vez de escolher contexto ou variante na tela.",
+      "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.",
   },
   "empty-value": {
     name: "empty-value",
     ancestry: "opus",
     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.",
+      "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.",
   },
   "dictionary-value": {
     name: "dictionary-value",
     ancestry: "opus",
     whenToUse:
-      "Valor de um `t.dict` com apresentação declarada: `classification` vira Badge neutral/outline, `status` e `stage` viram Badge context/subtle, `plain` vira texto (ADRs 0003 e 0006). Ícone e tooltip vêm da metadata e o texto permanece presente. Overrides explícitos por `presentation`, `context`, `variant`, `icon`, `tooltip` e `fallback`; não inferir contexto, badge, cor ou ícone pelo nome do dicionário.",
+      "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.",
   },
   dot: {
     name: "dot",
@@ -63,19 +63,19 @@ export const componentMeta = {
     name: "dock",
     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.",
+      "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.",
   },
   button: {
     name: "button",
     ancestry: "shadcn",
     whenToUse:
-      'Ação clicável. `context` declara neutral/primary/danger e `variant` escolhe solid/subtle/outline/ghost/link (ADR 0006). `size` define altura (default/sm/lg · icon/icon-sm/icon-xs) e `shape="pill"` troca somente a geometria. `busy` mostra spinner e desabilita. Ação destrutiva usa `context="danger"`; `destructive` continua sendo metadata comportamental do contrato.',
+      "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.",
   },
   card: {
     name: "card",
     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) + CardBody + CardFooter — o padding mora nos slots (como o Dialog). `CardContent` é um alias temporário de compatibilidade. Divergência declarada vs shadcn: sem shadow e sem flex/gap forçados (o upstream brigava com card-box simples).',
+      "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.",
   },
   "metric-card": {
     name: "metric-card",
@@ -87,85 +87,85 @@ export const componentMeta = {
     name: "chat",
     ancestry: "opus",
     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`).",
+      "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.",
   },
   checkbox: {
     name: "checkbox",
     ancestry: "shadcn",
     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.",
+      "Caixa de marcação booleana (Radix). Controlado por `checked`/`onCheckedChange`. Parear com Label. Para escolha única de várias opções, use Select/RadioGroup.",
   },
   "icon-picker": {
     name: "icon-picker",
     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).",
+      "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.",
   },
   command: {
     name: "command",
     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.",
+      "Lista filtrável com teclado (cmdk) — base de command-palettes. Use CommandDialog para palette modal (⌘K). Para escolha simples, use o Select direto.",
   },
   composer: {
     name: "composer",
     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.",
+      "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.",
   },
   "content-header": {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "Header estrutural de Content: agrupa ContentTitle, ContentDescription, ContentMeta e ContentActions. Não use solto. Para o caso comum, declare title, description, meta e actions diretamente em Content; o level controla a hierarquia semântica do heading.",
+      "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.",
   },
   copyable: {
     name: "copyable",
     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).",
+      "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.",
   },
   dialog: {
     name: "dialog",
-    ancestry: "shadcn",
+    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.',
+      "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.",
   },
   input: {
     name: "input",
     ancestry: "shadcn",
     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.",
+      "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.",
   },
   label: {
     name: "label",
     ancestry: "shadcn",
     whenToUse:
-      "Rótulo acessível de um campo. `htmlFor` aponta pro id do controle. Parear com Input/Textarea/Select.",
+      "Rótulo acessível de um campo. `htmlFor` aponta para o id do controle. Parear com Input/Textarea/Select.",
   },
   markdown: {
     name: "markdown",
     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.",
+      "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.",
   },
   menu: {
     name: "menu",
     ancestry: "opus",
     whenToUse:
-      'O menu de ações da casa: lista flutuante ancorada num 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.',
+      '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.',
   },
   popover: {
     name: "popover",
     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.",
+      "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.",
   },
   select: {
     name: "select",
     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`.',
+      "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.",
   },
   separator: {
     name: "separator",
@@ -177,25 +177,25 @@ export const componentMeta = {
     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.",
+      "Reserve a forma aproximada do conteúdo enquanto ele carrega. Defina dimensões com `className`; para uma espera sem forma conhecida, use Spinner.",
   },
   spinner: {
     name: "spinner",
     ancestry: "shadcn",
     whenToUse:
-      "Loading girando (ação em andamento: botão, fetch). Pra placeholder com forma de conteúdo, use Skeleton.",
+      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. Para reservar a forma do conteúdo, use Skeleton.",
   },
   table: {
     name: "table",
     ancestry: "shadcn",
     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.',
+      '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.',
   },
   tabs: {
     name: "tabs",
     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).",
+      "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.",
   },
   textarea: {
     name: "textarea",
@@ -207,133 +207,115 @@ export const componentMeta = {
     name: "toast",
     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.",
+      "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.",
   },
   tooltip: {
     name: "tooltip",
     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.",
+      "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.",
   },
   truncate: {
     name: "truncate",
     ancestry: "opus",
     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.",
+      "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.",
   },
   accordion: {
     name: "accordion",
     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.",
-  },
-  "alert-dialog": {
-    name: "alert-dialog",
-    ancestry: "opus",
-    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.',
+      "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.",
   },
   "aspect-ratio": {
     name: "aspect-ratio",
     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.",
+      "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.",
   },
   avatar: {
     name: "avatar",
     ancestry: "shadcn",
     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").',
+      "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.",
   },
   breadcrumb: {
     name: "breadcrumb",
     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.",
-  },
-  "button-group": {
-    name: "button-group",
-    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.',
+      "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.",
   },
   calendar: {
     name: "calendar",
     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.',
+      '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.',
   },
   carousel: {
     name: "carousel",
     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.",
+      "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.",
   },
   collapsible: {
     name: "collapsible",
     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.",
+      "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.",
   },
   drawer: {
     name: "drawer",
     ancestry: "opus",
     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) + DrawerBody + 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.',
+      "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.",
   },
   empty: {
     name: "empty",
     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.",
+      "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.",
   },
   field: {
     name: "field",
     ancestry: "shadcn",
     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).",
-  },
-  "input-group": {
-    name: "input-group",
-    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.',
+      "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.",
   },
   "input-otp": {
     name: "input-otp",
     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.",
+      "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.",
   },
   item: {
     name: "item",
     ancestry: "shadcn",
     whenToUse:
-      'Linha de conteúdo composta — ItemMedia + ItemHeader (ItemTitle e ItemDescription) + ItemBody ou ItemActions, com ItemFooter opcional. A mídia acompanha a altura útil do header. Item é o container (`variant` default/outline/muted, `size` default/sm, `asChild` pra virar link/botão); `ItemContent` permanece só como alias legado. Empilhe vários num ItemGroup: `variant="framed"` aplica a moldura e a superfície; ItemSeparator declara os divisores internos. É o padrão pra listas de workspaces, agentes, repositórios e sessões.',
+      "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.",
   },
   kbd: {
     name: "kbd",
     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.',
+      "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.",
   },
   pagination: {
     name: "pagination",
     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.",
+      "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.",
   },
   progress: {
     name: "progress",
     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.",
+      "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.",
   },
   "radio-group": {
     name: "radio-group",
     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.",
+      "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.",
   },
   split: {
     name: "split",
@@ -345,110 +327,98 @@ export const componentMeta = {
     name: "sidebar",
     ancestry: "opus",
     whenToUse:
-      "Chrome e navegação de uma coluna lateral, encaixada onde um Split decidir. `Sidebar` possui o colapso; `PaneHeader`, `PaneBody` e `PaneFooter` estruturam qualquer pane, e `SidebarNav`/`SidebarItem` apresentam navegação com grupos e subgrupos. `PaneContent` é um alias temporário de compatibilidade. Serve tanto a barra global quanto uma nav contextual; em Split redimensionável passe `divider={false}` para não duplicar a divisória.",
+      "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.",
   },
   "scroll-area": {
     name: "scroll-area",
     ancestry: "shadcn",
     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).',
+      '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).',
   },
   slider: {
     name: "slider",
     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.",
+      "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.",
   },
   switch: {
     name: "switch",
     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.",
+      "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: {
     name: "toggle",
     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.",
-  },
-  "toggle-group": {
-    name: "toggle-group",
-    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",
     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",
     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",
     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",
     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",
     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",
     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",
     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",
     whenToUse:
-      "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. Pra listagem em modal, ActionListDialog.",
-  },
-  "page-state": {
-    name: "page-state",
-    ancestry: "opus",
-    whenToUse:
-      "Estado integral da área de conteúdo de Page: loading centralizado, error em Alert com recuperação aplicável, empty em Empty com contexto/ação e ready sem moldura adicional. Use como filho direto de Page somente quando o estado substitui TODO o conteúdo principal; pra seção ou coleção parcial, use DataState, ActionView ou ActionList.",
+      "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",
     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",
     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",
     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>;