@softize/opus 19.0.0 → 20.1.0

package/src/ui/docs/content/data-products.md

@@ -0,0 +1,115 @@
+---
+title: Produtos de Dados
+---
+
+# Produtos de Dados
+
+Use um Produto de Dados quando um conjunto de dados precisar de identidade estável para catálogos,
+agentes e revisão, independentemente da action que o entrega. A declaração diz o que o conjunto
+representa, de onde vem, quem responde por ele e quais actions o disponibilizam. Ela não é uma
+consulta, uma tabela nem uma view, e não executa nada: cada action continua sendo a fronteira de
+execução, recorte e autorização.
+
+## Declarar e registrar
+
+`defineDataProduct` declara o produto e valida seus campos no momento em que roda. O domínio o
+registra em `dataProducts`, ao lado das actions e entidades citadas:
+
+```ts
+import { defineDataProduct, defineDomain } from '@softize/opus/core'
+import { LeadEntity } from './entity.ts'          // defineEntity({ name: 'lead', … })
+import { leadList } from './actions/list.ts'      // action 'lead.list'
+import { leadFunnel } from './actions/funnel.ts'  // action 'lead.funnel'
+
+export const salesLeads = defineDataProduct({
+  id: 'sales.leads',
+  version: 1,
+  label: 'Leads comerciais',
+  description: 'Leads e seus resultados comerciais.',
+  owner: 'Vendas',
+  grain: 'Um lead.',
+  classification: 'internal',
+  nature: 'real',
+  sources: [{ id: 'crm', label: 'CRM comercial' }],
+  entities: ['lead'],
+  access: {
+    permissionContexts: ['sales'],
+    organizationalScopes: ['unit', 'team'],
+  },
+  interfaces: ['lead.list', 'lead.funnel'],
+})
+
+export const leadDomain = defineDomain({
+  name: 'lead',
+  entities: { LeadEntity },
+  actions: { leadList, leadFunnel },
+  dataProducts: { salesLeads },
+})
+```
+
+`interfaces` e `entities` usam os nomes declarados em `bindAction`/`defineContract` e em
+`defineEntity`, não nomes de arquivo ou de tabela. `sources` identifica os sistemas ou conjuntos de
+origem; uma fonte não precisa ser uma entidade do Opus.
+
+## Verificações
+
+A declaração é conferida em três momentos:
+
+- `defineDataProduct` lança `TypeError` quando o `id` não tem namespace (como `sales.leads`), a
+  `version` não é um inteiro positivo, falta texto obrigatório, `sources` ou `interfaces` estão
+  vazias ou há itens repetidos.
+- `defineDomain` recusa um produto duplicado no domínio e referências a actions ou entidades que o
+  domínio não declara (`domain.data_product_interface_not_found` e
+  `domain.data_product_entity_not_found`).
+- `opus check` lê o código sem executá-lo e confere exportação, `id`, `version`, duplicidade e as
+  referências a actions e entidades do projeto, com as regras de prefixo `data-product`. Para isso,
+  o produto precisa ser `export const` e usar valores literais.
+
+## Acesso e segurança
+
+`access` documenta o alcance esperado de forma verificável. Ele ajuda o catálogo e a revisão a
+perceber, por exemplo, que uma interface deveria respeitar unidade e equipe. `access` não é RLS nem
+autorização automática: cada action listada em `interfaces` precisa aplicar o próprio `authorize` e
+os recortes no handler ou no repositório, inclusive quando chamada por IA ou por
+[MCP](/docs/mcp).
+
+`permissionContexts` nomeia chaves do vocabulário de permissão do projeto. Ele não descreve área,
+departamento nem contexto de tela; um projeto que não usa essa dimensão declara uma lista vazia.
+O nome antigo `contexts` ainda é aceito e projetado para compatibilidade, mas declarações novas usam
+`permissionContexts`.
+
+## Onde o produto aparece
+
+- `opus gen` publica os produtos no `.opus/manifest.json`, e `opus introspect` os inclui no modelo
+  do projeto. Veja [CLI opus](/docs/cli).
+- Em `runtime.aiTools()`, cada action exposta à IA traz em `metadata.dataProducts` os IDs dos
+  produtos relacionados e, em `metadata.dataProductLabels`, o `label` de cada ID. Veja
+  [IA generativa](/docs/ai).
+- No servidor MCP, as mesmas informações aparecem em `_meta['com.softize.opus/data-products']` e
+  `_meta['com.softize.opus/data-product-labels']`.
+
+Esses metadados servem a quem hospeda o agente: mostre o `label` às pessoas e use o ID na execução e
+na auditoria. Eles não entram no prompt e não concedem acesso. Nenhuma dessas projeções é a fonte
+da verdade: para mudar um produto, corrija a declaração e gere de novo.
+
+## Evoluir um produto
+
+Incremente `version` quando a forma observável do produto mudar. Para substituí-lo, mantenha a
+declaração anterior com `status: 'deprecated'` e `replacedBy` apontando para o novo ID durante a
+migração. Um produto ativo não declara `replacedBy`.
+
+## Referência de DataProductConfig
+
+| Campo | Contrato |
+| --- | --- |
+| `id` | Identidade estável com namespace, como `sales.leads`. |
+| `version` | Inteiro positivo; muda com a forma observável do produto. |
+| `label`, `description` | Nome e descrição para pessoas. |
+| `owner` | Responsável técnico ou de negócio. |
+| `grain` | O que uma linha ou observação representa. |
+| `classification`, `nature` | Classificação (como `internal` ou `personal`) e natureza (como `real`, `demo` ou `synthetic`) definidas pelo projeto. |
+| `sources` | Pelo menos uma fonte `{ id, label, description? }`, sem `id` repetido. |
+| `entities` | Nomes das entidades Opus que estruturam o produto; pode ser vazia. |
+| `access` | `permissionContexts` e `organizationalScopes`, ambos listas de texto. |
+| `interfaces` | Nomes das actions que disponibilizam o produto; pelo menos uma. |
+| `status`, `replacedBy` | `active` (padrão) ou `deprecated`; um produto `deprecated` exige `replacedBy`. |

package/src/ui/docs/content/data-state.md

@@ -1,11 +1,25 @@
 ## Estados
 
-Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta. As
-superfícies são as mesmas de `PageState`, na escala de uma seção: o carregamento é um contêiner
-`role="status"` com o `Spinner`; o vazio compõe `Empty` com moldura sólida e `emptyMessage` como
-título; o erro é um `Alert` de contexto `danger` com uma mensagem segura, sem expor detalhes
-técnicos, e uma ação `ghost` só com ícone quando há `onRetry`. `retryLabel` fornece o nome acessível
-e o tooltip dessa ação. Para uma ação em andamento depois do clique, use `busy` em `Button`.
+Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta, na escala
+de uma seção. Para o estado da página inteira, use `PageState`, descrito em [`Page`](/ui/page); para
+uma coleção carregada por uma action `kind: 'list'`, [`ActionList`](/ui/action-list) já trata esses
+estados.
+
+Cada estado tem uma apresentação fixa:
+
+- **Carregando:** um contêiner `role="status"` com o [`Spinner`](/ui/spinner) centralizado. Quando o
+  formato do conteúdo já é conhecido, em vez de passar `loading`, renderize o
+  [`Skeleton`](/ui/skeleton) durante a espera: ele reproduz esse formato e evita o salto de layout.
+- **Vazio:** um [`Empty`](/ui/empty) com moldura sólida e `emptyMessage` como frase discreta.
+- **Erro:** um [`Alert`](/ui/alert) de contexto `danger` com a mensagem segura de `errorMessage`,
+  sem expor o texto técnico de `error`. Com `onRetry`, o aviso ganha uma ação `ghost` só com ícone,
+  e `retryLabel` fornece o nome acessível e o tooltip dessa ação.
+
+Quando mais de uma condição vale ao mesmo tempo, vence a primeira desta ordem: erro, carregando,
+vazio. O conteúdo aparece somente quando nenhuma delas vale. Assim, uma nova tentativa com
+`loading` e `error` ativos continua mostrando o erro até que `error` volte a `null`.
+
+Para uma ação em andamento depois do clique, use `busy` em [`Button`](/ui/button).
 
 ```tsx preview col
 <div className="w-full space-y-3">

package/src/ui/docs/content/data.md

@@ -32,9 +32,9 @@ export const SkillEntity = defineEntity({
 
 ## Código em camelCase, banco em snake_case
 
-O schema tipado do Kysely e todas as consultas usam camelCase
-(`workspaceId`, `ghRepo`). O banco é snake (a DDL no schema idempotente — `db/schema.sql`).
-`CamelCasePlugin` converte nomes nas consultas e nos resultados. Um sink que não usa o Kysely com o
+O schema tipado do Kysely e todas as consultas usam camelCase (`workspaceId`, `ghRepo`). O banco
+usa snake_case, definido na DDL do schema idempotente, como `db/schema.sql`. `CamelCasePlugin`
+converte os nomes nas consultas e nos resultados. Um sink que não usa o Kysely com o
 plugin, como `audit_log`, mantém os nomes do banco.
 
 ```ts
@@ -52,19 +52,20 @@ await db.selectFrom('agents').select(['isDefault', 'roleId']).where('workspaceId
 
 Cada etapa possui um papel diferente:
 
-- `opus db migrate` — aplica o **schema idempotente** (`config.schema`, um script SQL
-  evolutivo: `IF NOT EXISTS` + guards cobrem nascer do zero e upgrade no mesmo artefato)
-  e roda o drift-check entidade ↔ banco na sequência (exit ≠ 0 se divergir).
-- `opus seed` — aplica datasets de desenvolvimento e teste declarados com `defineSeed` e registrados
-  no `opus.config.ts`; só conecta com `NODE_ENV=development` ou `test`. Ver [CLI opus](cli).
+- `opus db migrate` aplica o schema idempotente (`config.schema`), um único script SQL em que
+  `IF NOT EXISTS` e condições de guarda cobrem tanto o banco novo quanto a atualização. Em seguida,
+  compara entidades e banco e encerra com exit ≠ 0 quando há divergência.
+- `opus seed` aplica datasets de desenvolvimento e teste declarados com `defineSeed` e registrados no
+  `opus.config.ts`. Ele só conecta com `NODE_ENV=development` ou `test`. Veja
+  [CLI opus](/docs/cli).
 
 ## Campos JSON
 
-`kyselyRepo` serializa campos `t.json()` na escrita (`insert` e `update`), guiado pela
-declaração. Sem isso, o pg até stringifica objeto plano — mas **array vira literal de
-array do PG** (errado para jsonb) sem quebrar typecheck. String passa direto (quem já
-mandava pré-serializado segue valendo); na leitura o pg devolve objeto. Query à mão
-(fora do repo) continua responsável pelo próprio stringify.
+`kyselyRepo` serializa os campos `t.json()` na escrita (`insert` e `update`), guiado pela
+declaração da entidade. Sem essa etapa, o driver `pg` converte um objeto simples, mas transforma um
+array em literal de array do Postgres, o que é inválido para `jsonb` e não aparece no typecheck.
+Uma string passa sem alteração, o que preserva valores já serializados; na leitura, o `pg` devolve
+o objeto. Uma consulta escrita fora do repositório continua responsável pela própria serialização.
 
 ## SQL gerado por modelo
 
@@ -79,13 +80,13 @@ const bi = readOnlyContextPool({ pool: new Pool({ connectionString, max: 4 }) })
 const { rows } = await bi.query(sqlDoLlm, { role: roleFor(ctx) })
 ```
 
-1. **Pool com limite** (`max` e/ou `maxConcurrent`) — impede que as consultas consumam todas as
+1. **Pool com limite** (`max`, `maxConcurrent` ou ambos): impede que as consultas consumam todas as
    conexões do aplicativo.
-2. **`BEGIN TRANSACTION READ ONLY`** — o servidor rejeita tentativas de escrita;
-3. **`SET LOCAL ROLE` por transação** — o alcance é definido pelo contexto (crie os roles com grants
-   default-fechado nas suas migrações: sem isso, `sales_read` leria `hr_employees`);
-4. **Protocolo estendido** — o SQL sempre recebe os valores separadamente; múltiplas instruções
-   (`SELECT 1; DROP …`) é recusada pelo próprio protocolo.
+2. **`BEGIN TRANSACTION READ ONLY`:** o servidor rejeita tentativas de escrita.
+3. **`SET LOCAL ROLE` por transação:** o contexto define o alcance da consulta. Crie os roles nas
+   suas migrações com grants fechados por padrão; sem isso, `sales_read` leria `hr_employees`.
+4. **Protocolo estendido:** o SQL sempre recebe os valores separadamente, e múltiplas instruções
+   (`SELECT 1; DROP …`) são recusadas pelo próprio protocolo.
 
 Ao terminar, `DISCARD ALL` limpa a conexão. Se a limpeza falhar, a conexão é descartada em vez de
 voltar ao pool. `statement_timeout`, aplicado por transação, limita consultas demoradas; o padrão é

package/src/ui/docs/content/detail.md

@@ -1,6 +1,6 @@
 Use `DetailGroup` para organizar dados somente leitura como pares de rótulo e valor.
 `DetailField` representa cada par e aceita conteúdo React em `label` e `value`. Para entrada e
-validação, use `Field`.
+validação, use [`Field`](/ui/field).
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -27,7 +27,8 @@ validação, use `Field`.
 
 `null`, `undefined`, string vazia ou só com espaços mostram um travessão; a leitura assistiva
 recebe “Não informado”. Uma string em `empty` troca esse significado no domínio, enquanto um nó
-React substitui a apresentação. `0` e `false` seguem como valores. Ver `EmptyValue`.
+React substitui a apresentação. `0` e `false` seguem como valores. A regra é a mesma de
+[`EmptyValue`](/ui/empty-value).
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -64,15 +65,21 @@ começam depois da mesma coluna de rótulo, com largura padrão de `7rem` em gru
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica a moldura canônica ao conjunto, com fundo transparente; na orientação horizontal, a coluna de rótulos recebe fundo sutil. |
-| `dividers` | `boolean` | `false` | Hairlines somente entre os campos, sem exigir moldura externa. |
+| `dividers` | `boolean` | `false` | Linhas finas somente entre os campos, sem exigir moldura externa. |
 | `columns` | `1 \| 2 \| 3 \| 4 \| 'auto'` | `1` | Número fixo de colunas ou distribuição automática por largura mínima. |
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chave sobre o valor ou ao lado dele em cada campo. |
 
+O grupo renderiza uma lista de definições (`<dl>`); os demais atributos, como `className`, vão para
+ela.
+
 ## Propriedades de DetailField
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `label` | `ReactNode` | | A chave do par. |
-| `value` | `ReactNode` | | O valor; `null`, `undefined` e string vazia renderizam a ausência, `0` e `false` seguem como valores. |
+| `label` | `ReactNode` | obrigatório | A chave do par. |
+| `value` | `ReactNode` | obrigatório | O valor; `null`, `undefined` e string vazia renderizam a ausência, `0` e `false` seguem como valores. |
 | `icon` | `ReactNode` | | Ícone decorativo antes do par chave/valor. |
 | `empty` | `ReactNode` | `“Não informado”` | Uma string dá significado acessível ao travessão; um nó próprio substitui a apresentação. |
+
+Os demais atributos, como `className`, vão para o contêiner do par. `DetailField` não aceita
+`children`: o conteúdo entra por `value`.

package/src/ui/docs/content/dialog.md

@@ -10,7 +10,8 @@ contexto da página. A forma escolhida depende do tipo de interrupção:
 | Pedir reconhecimento, confirmação binária ou uma string sem montar a superfície. | Use `dialog.alert`, `dialog.confirm` ou `dialog.prompt`. |
 | Escolher entre vários resultados simples.                                        | Use `dialog.choose`.                                     |
 
-Para conteúdo ancorado e não modal, use `Popover`. Para uma lista de ações, use `Menu`.
+Para conteúdo ancorado e não modal, use [`Popover`](/ui/popover). Para uma lista de ações, use
+[`Menu`](/ui/menu).
 
 ## Compor uma tarefa modal
 
@@ -118,13 +119,13 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
   <DialogContent>
     <DialogHeader>
       <DialogNavigation>
-        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DialogNavigation>
       <DialogTitle>Evento 4821</DialogTitle>
       <DialogActions>
-        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+        <Button variant="ghost" size="icon" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DialogActions>
@@ -136,9 +137,82 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
 </Dialog>
 ```
 
+Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
+[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
+quadrado `icon-sm` (1.75rem) por padrão.
+
 O cabeçalho não recebe descrição: um modal já é a superfície de uma tarefa, e o contexto que ajuda a
 decidir aparece no começo do corpo, como texto ou `Alert`.
 
+## Identificar a tarefa com um ícone
+
+Use `DialogMedia` quando um ícone ajuda a reconhecer a tarefa antes da leitura do título. No modo
+padrão, ele abre a linha do cabeçalho com a mesma moldura de [`IconTile`](/ui/icon-tile) das demais
+superfícies. No `mode="alert"`, a moldura cresce e fica centralizada acima do título, porque ali o
+ícone é o principal sinal de reconhecimento da resposta.
+
+```tsx preview
+render(
+  <div className="flex flex-wrap gap-3">
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline">Compartilhar contrato</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogMedia>
+            <Share2 />
+          </DialogMedia>
+          <DialogTitle>Compartilhar contrato</DialogTitle>
+        </DialogHeader>
+        <DialogBody className="space-y-2">
+          <Label htmlFor="share-email">E-mail</Label>
+          <Input id="share-email" placeholder="nome@empresa.com.br" />
+        </DialogBody>
+        <DialogFooter>
+          <ButtonGroup mode="spaced">
+            <DialogClose asChild>
+              <Button variant="ghost">Cancelar</Button>
+            </DialogClose>
+            <Button>Compartilhar</Button>
+          </ButtonGroup>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+    <Dialog mode="alert">
+      <DialogTrigger asChild>
+        <Button variant="outline">Revogar acesso</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogMedia context="danger">
+            <ShieldOff />
+          </DialogMedia>
+          <DialogTitle>Revogar acesso de Marina?</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          <p className="text-sm text-muted-foreground">
+            Ela deixa de ver o contrato imediatamente.
+          </p>
+        </DialogBody>
+        <DialogFooter>
+          <ButtonGroup mode="spaced" distribution="equal">
+            <DialogClose initialFocus asChild>
+              <Button variant="outline">Cancelar</Button>
+            </DialogClose>
+            <DialogClose asChild>
+              <Button context="danger">Revogar acesso</Button>
+            </DialogClose>
+          </ButtonGroup>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  </div>,
+);
+```
+
+Na API imperativa, a opção `media` recebe o ícone e o apresenta na mesma moldura do alerta.
+
 ## Pedir uma resposta pela API imperativa
 
 Use `dialog.alert`, `dialog.confirm`, `dialog.prompt` e `dialog.choose` quando a resposta couber em
@@ -169,12 +243,13 @@ function Demo() {
         size="sm"
         onClick={async () => {
           const accepted = await dialog.confirm({
-            title: "Excluir sessão?",
-            body: "O worktree e o preview desta sessão serão removidos.",
+            title: "Excluir rascunho?",
+            body: "O rascunho e os comentários dele serão removidos.",
+            media: <Trash2 />,
             action: "Excluir",
             context: "danger",
           });
-          setResult(accepted ? "Sessão excluída." : "Sessão mantida.");
+          setResult(accepted ? "Rascunho excluído." : "Rascunho mantido.");
         }}
       >
         Confirmar exclusão
@@ -184,14 +259,14 @@ function Demo() {
         size="sm"
         onClick={async () => {
           const name = await dialog.prompt({
-            title: "Renomear snapshot",
+            title: "Renomear versão",
             action: "Renomear",
             placeholder: "Ex.: versão final",
           });
           setResult(name === null ? "Nome mantido." : `Novo nome: ${name}`);
         }}
       >
-        Renomear snapshot
+        Renomear versão
       </Button>
       <Button
         variant="outline"
@@ -229,7 +304,8 @@ render(<Demo />);
 `dialog.prompt` devolve `Promise<string | null>` e `dialog.choose` infere a união dos resultados
 declarados, acrescida de `null`. Fechar ou cancelar resolve a resposta negativa de cada operação,
 em vez de deixar a promise pendente. No aviso com uma ação, o botão ocupa toda a largura do rodapé;
-confirmações e prompts distribuem confirmar e cancelar em duas colunas.
+confirmações e prompts distribuem confirmar e cancelar em duas colunas. O `dialog.choose` usa uma
+superfície mais larga, de `32rem`, para que as ações caibam lado a lado.
 
 Em `dialog.choose`, declare pelo menos uma ação e marque exatamente uma ação habilitada com
 `initialFocus`. Essa ação representa a saída segura. Os valores de `result` precisam ser únicos.
@@ -238,7 +314,7 @@ neutro e variante outline. Defina `context` ou `variant` na própria ação para
 
 ### Montar o host
 
-Monte um `DialogHost` no shell do aplicativo, ao lado do `Toaster`:
+Monte um `DialogHost` no shell do aplicativo, ao lado do [`Toaster`](/ui/toast):
 
 ```tsx
 <>
@@ -248,8 +324,8 @@ Monte um `DialogHost` no shell do aplicativo, ao lado do `Toaster`:
 </>
 ```
 
-Sem o host, a chamada lança um erro imediatamente. Solicitações concorrentes entram em uma fila e
-aparecem uma por vez, preservando a resposta de cada `await`.
+Sem o host, a promise é rejeitada imediatamente com um erro. Solicitações concorrentes entram em
+uma fila e aparecem uma por vez, preservando a resposta de cada `await`.
 
 ### Adicionar contexto relevante
 
@@ -259,21 +335,21 @@ texto, um `Alert` ou uma composição própria:
 
 ```tsx
 const accepted = await dialog.confirm({
-  title: "Encerrar três sessões?",
+  title: "Revogar três acessos?",
   body: (
     <Alert
       context="warning"
-      description="Os agentes vinculados serão interrompidos."
+      description="As pessoas convidadas deixam de ver o contrato imediatamente."
     />
   ),
-  action: "Encerrar sessões",
+  action: "Revogar acessos",
 });
 ```
 
-Use `ActionTrigger` quando a confirmação já pertencer ao contrato de uma action. Use
-`ActionFormDialog` para formulários com validação ou vários campos. `dialog.prompt` atende somente
-uma string livre. Componha `Dialog` quando uma ação precisar manter a superfície
-aberta para exibir carregamento, validação ou falha antes do fechamento.
+Use [`ActionTrigger`](/ui/action-trigger) quando a confirmação já pertencer ao contrato de uma
+action. Use [`ActionFormDialog`](/ui/action-form-dialog) para formulários com validação ou vários
+campos. `dialog.prompt` atende somente uma string livre. Componha `Dialog` quando uma ação precisar
+manter a superfície aberta para exibir carregamento, validação ou falha antes do fechamento.
 
 ## Compor uma resposta personalizada
 
@@ -282,6 +358,10 @@ com o clique externo. Prefira a API imperativa quando a resposta couber em `aler
 `prompt` ou `choose`. Componha o componente quando a resposta depender de estado próprio ou de um
 layout específico.
 
+O alerta tem `20rem` de largura máxima, suficiente para duas ações lado a lado. Com três ações,
+amplie a superfície com `className="max-w-lg"` em `DialogContent`, a mesma largura que o
+`dialog.choose` usa; sem isso, os rótulos não cabem no rodapé.
+
 ```tsx preview
 function ResponseDialogDemo() {
   const [result, setResult] = useState("Nenhuma resposta.");
@@ -292,7 +372,7 @@ function ResponseDialogDemo() {
         <DialogTrigger asChild>
           <Button variant="outline">Fechar editor</Button>
         </DialogTrigger>
-        <DialogContent>
+        <DialogContent className="max-w-lg">
           <DialogHeader>
             <DialogTitle>Fechar editor?</DialogTitle>
           </DialogHeader>
@@ -328,13 +408,16 @@ render(<ResponseDialogDemo />);
 contexto, variante e tamanho pertencem ao botão. `result` identifica a resposta entregue a
 `Dialog onResult`. Marque com `initialFocus` a saída segura — normalmente `Cancelar`; em um aviso
 com uma única ação, marque essa ação. Para uma confirmação destrutiva, use `context="danger"` no
-botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Encerrar sessões`.
+botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Arquivar contratos`.
 
 ## Acessibilidade
 
 - `DialogTitle` nomeia a superfície para tecnologias assistivas. Quando um texto conciso do corpo
   também precisar descrevê-la, relacione seu `id` por `aria-describedby` em `DialogContent`.
 - O modo padrão permite fechamento externo; `mode="alert"` exige uma resposta explícita.
+- Enquanto uma operação não puder ser interrompida, `closeDisabled` em `DialogContent` impede que o
+  botão de fechar, Esc e o clique externo fechem a superfície. As ações que você compõe com
+  `DialogClose` continuam ativas; desabilite-as pelo mesmo estado da operação.
 - O comportamento selecionado por `mode` determina o papel de acessibilidade; `role` não configura
   o comportamento.
 - O foco permanece dentro do diálogo aberto e retorna ao gatilho após o fechamento.
@@ -363,10 +446,10 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 | Propriedade       | Tipo        | Padrão | Descrição                                                                                                 |
 | ----------------- | ----------- | ------ | --------------------------------------------------------------------------------------------------------- |
 | `showCloseButton` | `boolean`   | `true` | No modo padrão, inclui a ação de fechamento no header; o modo de alerta exige uma resposta identificável. |
-| `closeDisabled`   | `boolean`   | `false` | Mantém a ação visível e impede o fechamento enquanto a tarefa está bloqueada.                            |
+| `closeDisabled`   | `boolean`   | `false` | Mantém o botão de fechar visível e desabilitado e impede que Esc e o clique externo fechem a superfície. Handlers como `onEscapeKeyDown` e `onPointerDownOutside` continuam sendo chamados antes do bloqueio. |
 | `closeSize`       | `"xs" \| "sm"` | `"sm"` | Define o tamanho da ação circular de fechar.                                                  |
 | `layout`          | `'continuous' \| 'sectioned'` | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem. Ignorado em `mode="alert"`. |
-| `className`       | `string`    |        | Ajusta a superfície.                                                                                      |
+| `className`       | `string`    |        | Ajusta a superfície. A largura máxima é `32rem` no modo padrão e `20rem` no alerta; amplie o alerta com `max-w-lg` quando o rodapé tiver três ações. |
 | `children`        | `ReactNode` |        | Cabeçalho, corpo, rodapé ou conteúdo próprio.                                                             |
 
 ## Propriedades de DialogHeader
@@ -409,7 +492,7 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 | Propriedade | Tipo        | Padrão | Descrição                            |
 | ----------- | ----------- | ------ | ------------------------------------ |
 | `level`     | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `h2` da primitiva | Hierarquia do documento. O tamanho vem do `layout`, nunca do nível. |
-| `className` | `string`    |        | Ajusta o título, que trunca quando não cabe na linha. |
+| `className` | `string`    |        | Ajusta o título. No modo padrão, ele trunca quando não cabe na linha; no alerta, fica centralizado e pode ocupar mais de uma linha. |
 | `children`  | `ReactNode` |        | Nome da tarefa ou do conteúdo modal. |
 
 ## Propriedades de DialogMedia

package/src/ui/docs/content/dictionary-value.md

@@ -1,6 +1,6 @@
 Use `DictionaryValue` para apresentar um valor de `t.dict` de acordo com o papel declarado pelo
-próprio dicionário. A tela fornece o dicionário e o código; o componente escolhe texto, badge e ícone
-sem perder o rótulo visível.
+próprio dicionário. A tela fornece o dicionário e o código; o componente escolhe texto,
+[`Badge`](/ui/badge) e ícone sem perder o rótulo visível.
 
 ```tsx preview
 <DictionaryValue
@@ -56,7 +56,7 @@ export const customerStageDict = t.dict(
 - `context` (`neutral` · `info` · `success` · `warning` · `danger`) só existe em status e estágio;
   `t.dict` rejeita o contexto em classificação e em `plain`.
 - `icon` é um nome do catálogo do Opus (`iconPickerIcons`). Nome fora do catálogo não renderiza
-  ícone; o renderer não inventa. Vocabulário próprio entra por `icons`.
+  ícone; o componente não escolhe um substituto. Vocabulário próprio entra por `icons`.
 - `description` é o texto curto para a pessoa e aparece em tooltip focável. Descrição igual ao
   rótulo não vira tooltip. `doc` é o entendimento de negócio para manifest e Lens; não aparece.
 
@@ -100,7 +100,7 @@ Valor fora do dicionário aparece como texto com o próprio código, marcado com
 
 ## Em ActionList
 
-Coluna cujo campo do schema de saída é um `t.dict().zod()` já renderiza `DictionaryValue` com o
+Em [`ActionList`](/ui/action-list), a coluna cujo campo do schema de saída é um `t.dict().zod()` já renderiza `DictionaryValue` com o
 papel declarado, sem `cells`. Quando o campo de saída é uma string comum, a coluna nomeia o
 dicionário registrado no provider: `{ key: 'source', label: 'Fonte', dictionary: 'customerSource' }`.
 Dimensões independentes (tipo e estágio, por exemplo) ficam em colunas distintas; não empilhar