@softize/opus 12.11.0 → 13.1.0

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

@@ -4,15 +4,15 @@ title: Camada de dados
 
 # Camada de dados
 
-A entidade é a spec do armazenamento; o manifest a projeta. As queries falam Kysely tipado.
-Uma regra firme atravessa tudo: o código fala camelCase, o banco fala snake — e o
-`CamelCasePlugin` faz a ponte.
+As entidades descrevem o armazenamento que o manifest projeta, enquanto o Kysely mantém as
+consultas tipadas. No código, nomes usam camelCase; no banco, snake_case. `CamelCasePlugin` faz essa
+conversão nos dois sentidos.
 
 ## Entidade e manifest
 
-> `defineEntity` declara o storage (campos + tipos lógicos `t.*`). A `description` de cada
-> entidade/action é a spec de negócio, projetada no manifest pelo `opus gen`; `opus db check`
-> acusa drift entidade ↔ banco.
+`defineEntity` declara campos e tipos lógicos `t.*`. A `description` de cada entidade e action
+registra o significado de negócio projetado no manifest por `opus gen`. Use `opus db check` para
+detectar divergências entre a entidade e o banco.
 
 ```ts
 import { defineEntity } from '@softize/opus/schema'
@@ -30,16 +30,12 @@ export const SkillEntity = defineEntity({
 })
 ```
 
-## Código camelCase, banco snake
+## Código em camelCase, banco em snake_case
 
-> Regra dura do protocolo: uma camada em snake e outra em camel é defeito — não tem meio-termo.
-
-O schema tipado do Kysely e **toda** query (select/insert/update/where) usam camelCase
+O schema tipado do Kysely e todas as consultas usam camelCase
 (`workspaceId`, `ghRepo`). O banco é snake (a DDL no schema idempotente — `db/schema.sql`).
-O `CamelCasePlugin` no runtime faz a ponte camel↔snake nas queries E nos resultados — o
-mesmo que o prepare já faz.
-Única exceção: um sink escrito por fora do Kysely-com-plugin (ex.: o `audit_log` do Opus, pelo
-pool) fica snake.
+`CamelCasePlugin` converte 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
 import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely'
@@ -52,31 +48,28 @@ const db = new Kysely<AdminDB>({
 await db.selectFrom('agents').select(['isDefault', 'roleId']).where('workspaceId', '=', id).execute()
 ```
 
-## Migrações · prepare · seed
+## Migrações, preparação e seeds
 
-> Três coisas distintas — não confundir o que roda em prod.
+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).
 - `prepare` — backfill estrutural, prod-safe e idempotente; roda no deploy (depois do migrate).
-- `seed` — fixtures de desenvolvimento. **Não** roda em prod.
-
-## Campo `t.json()`: objeto entra, objeto sai
+- `seed` — cria dados de desenvolvimento e teste. Não é executado em produção.
 
-> A dupla `ColumnType<unknown, string, never>` + `JSON.stringify` na mão está aposentada
-> no caminho do `kyselyRepo`.
+## Campos JSON
 
-O `kyselyRepo` serializa campo `t.json()` na ESCRITA (insert/update), guiado pela
+`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 pra jsonb) sem quebrar typecheck. String passa direto (quem já
+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.
 
-## SQL escrito por LLM: `readOnlyContextPool`
+## SQL gerado por modelo
 
-> Action `ai: true` que executa SQL livre precisa das **quatro defesas** — todas no
-> BANCO, nenhuma em regex sobre o texto da query.
+Uma action `ai: true` que executa SQL livre precisa de quatro proteções no banco. Validar o texto
+com expressão regular não substitui nenhuma delas:
 
 ```ts
 import { Pool } from 'pg'
@@ -86,14 +79,14 @@ const bi = readOnlyContextPool({ pool: new Pool({ connectionString, max: 4 }) })
 const { rows } = await bi.query(sqlDoLlm, { role: roleFor(ctx) })
 ```
 
-1. **Pool com teto** (`max` do pool e/ou `maxConcurrent`) — query de LLM não esgota as
-   conexões do app;
+1. **Pool com limite** (`max` e/ou `maxConcurrent`) — 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 é do CONTEXTO (crie os roles com grants
+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 roda sempre com array de valores; multi-sentença
+4. **Protocolo estendido** — o SQL sempre recebe os valores separadamente; múltiplas instruções
    (`SELECT 1; DROP …`) é recusada pelo próprio protocolo.
 
-Saindo, `DISCARD ALL` devolve a conexão limpa; se a limpeza falhar, a conexão é
-destruída — nunca volta suja pro pool. `statement_timeout` local por transação
-(default 15s) segura a query fugitiva.
+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 é
+15 segundos.

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

@@ -1,6 +1,6 @@
-DetailGroup organiza dados somente leitura como uma lista semântica de pares chave/valor.
-DetailField representa cada par e aceita conteúdo React rico em `label` e `value`. Use Field
-para entrada e validação; use DetailField quando a pessoa apenas consulta um valor.
+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`.
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -9,7 +9,7 @@ para entrada e validação; use DetailField quando a pessoa apenas consulta um v
     label="Estágio"
     value={
       <DictionaryValue
-        dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
+        dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospecto' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
         value="prospect"
       />
     }
@@ -56,3 +56,21 @@ mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
   />
 </DetailGroup>
 ```
+
+## Propriedades de DetailGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica a superfície e a moldura canônicas ao conjunto. |
+| `dividers` | `boolean` | `false` | Hairlines somente entre os campos, sem exigir moldura externa. |
+| `columns` | `1 \| 2 \| 3 \| 4 \| 'auto'` | `1` | Colunas responsivas ou distribuição automática por largura mínima. |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chave sobre o valor ou ao lado dele em cada campo. |
+
+## 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. |
+| `icon` | `ReactNode` | | Ícone decorativo antes do par chave/valor. |
+| `empty` | `ReactNode` | `“Não informado”` | O que a ausência significa neste campo: um rótulo ou um nó próprio. |

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

@@ -1,6 +1,22 @@
-## Composição
+## Escolher a forma do diálogo
 
-Content é superfície pura; o espaço mora nos slots (body p-5; header/footer px-5 py-4): DialogHeader (fixo, com divisor), DialogBody (rola) e DialogFooter (faixa da casa — borda + fundo muted). DialogClose fecha sem estado manual.
+Use a família `Dialog` quando a pessoa precisar concluir uma tarefa ou responder sem perder o
+contexto da página. A forma escolhida depende do tipo de interrupção:
+
+| Necessidade | Escolha |
+|---|---|
+| Exibir uma tarefa ou conteúdo modal que pode ser fechado. | Componha `Dialog`. |
+| Exigir uma resposta e impedir o fechamento pelo clique externo. | Componha `Dialog mode="alert"`. |
+| 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`.
+
+## Compor uma tarefa modal
+
+`DialogContent` delimita a superfície. `DialogHeader`, `DialogBody` e `DialogFooter` organizam
+título, conteúdo rolável e ações com o espaçamento da família. A superfície usa o fundo base,
+borda semântica, raio `xl` e elevação para permanecer distinta da página.
 
 ```tsx preview
 <Dialog>
@@ -13,48 +29,340 @@ Content é superfície pura; o espaço mora nos slots (body p-5; header/footer p
       <DialogDescription>O workspace agrupa os repositórios e agentes do cliente.</DialogDescription>
     </DialogHeader>
     <DialogBody className="space-y-2">
-      <Label htmlFor="ws-nome">Nome</Label>
-      <Input id="ws-nome" placeholder="Ex.: Empresa X" />
+      <Label htmlFor="workspace-name">Nome</Label>
+      <Input id="workspace-name" placeholder="Ex.: Empresa X" />
     </DialogBody>
     <DialogFooter>
       <DialogClose asChild>
-        <Button variant="ghost" size="sm">Cancelar</Button>
+        <Button variant="ghost">Cancelar</Button>
       </DialogClose>
-      <Button size="sm">Criar</Button>
+      <Button>Criar workspace</Button>
     </DialogFooter>
   </DialogContent>
 </Dialog>
 ```
 
-## Sem o X (ação obrigatória)
+O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
+`DialogClose` encerra o modal sem exigir estado controlado. Use `open` e `onOpenChange` quando outra
+parte da interface também precisar controlar a abertura.
+
+## Pedir uma resposta pela API imperativa
 
-showCloseButton={false} esconde o X: o usuário decide pelos botões — pra confirmação que não pode ser dispensada no escuro.
+Use `dialog.alert`, `dialog.confirm`, `dialog.prompt` e `dialog.choose` quando a resposta couber em
+um contrato pronto. As chamadas são assíncronas e resolvem somente depois da resposta.
 
 ```tsx preview
-<Dialog>
-  <DialogTrigger asChild>
-    <Button context="danger">Excluir sessão</Button>
-  </DialogTrigger>
-  <DialogContent showCloseButton={false}>
-    <DialogHeader>
-      <DialogTitle>Excluir a sessão?</DialogTitle>
-      <DialogDescription>O worktree e o preview desta sessão serão removidos.</DialogDescription>
-    </DialogHeader>
-    <DialogFooter>
-      <DialogClose asChild>
-        <Button variant="ghost" size="sm">Cancelar</Button>
-      </DialogClose>
-      <DialogClose asChild>
-        <Button context="danger" size="sm">Excluir</Button>
-      </DialogClose>
-    </DialogFooter>
-  </DialogContent>
-</Dialog>
+function Demo() {
+  const [result, setResult] = useState('Nenhuma resposta.')
+
+  return (
+    <div className="flex flex-wrap items-center gap-3">
+      <DialogHost />
+      <Button variant="outline" size="sm" onClick={async () => {
+        await dialog.alert({
+          title: 'Sessão expirada',
+          description: 'Entre novamente para continuar.',
+        })
+        setResult('Aviso reconhecido.')
+      }}>
+        Abrir aviso
+      </Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const accepted = await dialog.confirm({
+          title: 'Excluir sessão?',
+          description: 'O worktree e o preview desta sessão serão removidos.',
+          action: 'Excluir',
+          context: 'danger',
+        })
+        setResult(accepted ? 'Sessão excluída.' : 'Sessão mantida.')
+      }}>
+        Confirmar exclusão
+      </Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const name = await dialog.prompt({
+          title: 'Renomear snapshot',
+          action: 'Renomear',
+          placeholder: 'Ex.: versão final',
+        })
+        setResult(name === null ? 'Nome mantido.' : `Novo nome: ${name}`)
+      }}>
+        Renomear snapshot
+      </Button>
+      <Button variant="outline" size="sm" onClick={async () => {
+        const choice = await dialog.choose({
+          title: 'Fechar editor?',
+          description: 'O contrato possui alterações que ainda não foram salvas.',
+          actions: [
+            { result: 'continue', label: 'Continuar editando', initialFocus: true },
+            { result: 'discard', label: 'Descartar', variant: 'outline' },
+            { result: 'save', label: 'Salvar e fechar' },
+          ],
+        })
+        setResult(choice === null ? 'Editor mantido.' : `Resultado: ${choice}`)
+      }}>
+        Fechar editor
+      </Button>
+      <span className="text-sm text-muted-foreground">{result}</span>
+    </div>
+  )
+}
+
+render(<Demo />)
+```
+
+`dialog.alert` devolve `Promise<void>`, `dialog.confirm` devolve `Promise<boolean>`,
+`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.
+
+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.
+Por padrão, a última ação recebe contexto primário e variante sólida; as anteriores usam contexto
+neutro e variante ghost. Defina `context` ou `variant` na própria ação para substituir o padrão.
+
+### Montar o host
+
+Monte um `DialogHost` no shell do aplicativo, ao lado do `Toaster`:
+
+```tsx
+<>
+  {routes}
+  <Toaster />
+  <DialogHost />
+</>
+```
+
+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`.
+
+### Adicionar conteúdo próprio
+
+Use `body` quando a descrição não for suficiente, como em uma lista de recursos afetados:
+
+```tsx
+const accepted = await dialog.confirm({
+  title: 'Encerrar três sessões?',
+  description: 'Os agentes vinculados serão interrompidos.',
+  body: <AffectedSessions />,
+  action: 'Encerrar sessões',
+})
 ```
 
-## Props
+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.
+
+## Compor uma resposta personalizada
+
+`Dialog mode="alert"` deriva `role="alertdialog"`, mantém o foco dentro da superfície e não fecha
+com o clique externo. Prefira a API imperativa quando a resposta couber em `alert`, `confirm`,
+`prompt` ou `choose`. Componha o componente quando a resposta depender de estado próprio ou de um
+layout específico.
+
+```tsx preview
+function ResponseDialogDemo() {
+  const [result, setResult] = useState('Nenhuma resposta.')
+
+  return (
+    <div className="space-y-3">
+      <Dialog mode="alert" onResult={setResult}>
+        <DialogTrigger asChild>
+          <Button variant="outline">Fechar editor</Button>
+        </DialogTrigger>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Fechar editor?</DialogTitle>
+            <DialogDescription>
+              O contrato possui alterações que ainda não foram salvas.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter className="grid-cols-3">
+            <DialogClose result="continue" initialFocus asChild>
+              <Button variant="ghost">Continuar editando</Button>
+            </DialogClose>
+            <DialogClose result="discard" asChild>
+              <Button variant="outline">Descartar</Button>
+            </DialogClose>
+            <DialogClose result="save" asChild>
+              <Button>Salvar e fechar</Button>
+            </DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      <p className="text-sm text-muted-foreground">{result}</p>
+    </div>
+  )
+}
+
+render(<ResponseDialogDemo />)
+```
+
+`DialogClose` fecha a superfície sem escolher a aparência. Use `asChild` e componha um `Button`;
+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`.
+
+## Acessibilidade
+
+- `DialogTitle` e `DialogDescription` nomeiam e descrevem a superfície para tecnologias assistivas.
+- O modo padrão permite fechamento externo; `mode="alert"` exige uma resposta explícita.
+- 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.
+- `DialogHost` apresenta uma solicitação por vez para que cada resposta tenha um alvo inequívoco.
+
+## Propriedades de Dialog
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Controla a abertura. |
+| `defaultOpen` | `boolean` | `false` | Define a abertura inicial no modo não controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Recebe mudanças de abertura. |
+| `mode` | `'default' \| 'alert'` | `'default'` | Exige resposta explícita em `alert`; o componente deriva o papel de acessibilidade. |
+| `onResult` | `(result: string) => void` | | Recebe o resultado do `DialogClose` acionado. |
+| `modal` | `boolean` | `true` | No modo padrão, mantém foco e interação restritos à superfície aberta. |
+
+## Propriedades de DialogTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Usa o filho como gatilho sem criar outro elemento. |
+| `children` | `ReactNode` | | Controle que abre o diálogo. |
+
+## Propriedades de DialogContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `showCloseButton` | `boolean` | `true` | No modo padrão, exibe o botão de fechamento no canto; o modo de alerta exige uma resposta identificável. |
+| `className` | `string` | | Ajusta a superfície. |
+| `children` | `ReactNode` | | Cabeçalho, corpo, rodapé ou conteúdo próprio. |
+
+## Propriedades de DialogHeader
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a faixa superior. |
+| `children` | `ReactNode` | | Título, descrição e mídia opcional. |
+
+## Propriedades de DialogBody
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta o corpo rolável do modo padrão ou o conteúdo próprio do alerta. |
+| `children` | `ReactNode` | | Conteúdo principal da tarefa. |
+
+## Propriedades de DialogFooter
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a faixa do modo padrão ou a grade de respostas do alerta. |
+| `children` | `ReactNode` | | Ações secundárias e principal. |
+
+## Propriedades de DialogTitle
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta o título. |
+| `children` | `ReactNode` | | Nome da tarefa ou do conteúdo modal. |
+
+## Propriedades de DialogDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a descrição. |
+| `children` | `ReactNode` | | Contexto, efeito ou consequência relevante. |
+
+## Propriedades de DialogMedia
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a moldura quadrada da mídia. |
+| `children` | `ReactNode` | | Ícone que reforça o contexto da resposta. |
+
+## Propriedades de DialogClose
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `Dialog.open / onOpenChange` | `boolean / (open: boolean) => void` | | Modo controlado (Radix) — pra abrir por código (ex.: depois de uma action). |
-| `DialogContent.showCloseButton` | `boolean` | `true` | Mostra o X de fechar no canto. Desligue pra modal que exige ação explícita. |
+| `initialFocus` | `boolean` | `false` | No modo de alerta, marca o controle como destino inicial seguro do foco. |
+| `result` | `string` | | Entrega esta resposta a `Dialog onResult` antes de fechar. |
+| `asChild` | `boolean` | `false` | Aplica o fechamento ao filho; use com `Button`. |
+| `children` | `ReactNode` | | Controle que fecha o diálogo. |
+
+## Propriedades de DialogOverlay
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Ajusta a camada que cobre a página. |
+
+## Propriedades de DialogPortal
+
+`DialogContent` já monta portal e overlay. Use `DialogPortal` diretamente somente em uma composição
+avançada; ele recebe `children` e `container` conforme o portal do Radix.
+
+## Propriedades de DialogHost
+
+`DialogHost` não recebe propriedades. Monte uma instância no shell para atender toda a API
+imperativa. `ConfirmHost` permanece como alias de migração.
+
+## Opções de dialog.alert
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia o aviso que exige reconhecimento. |
+| `description` | `ReactNode` | | Explica efeito, alcance ou próximo passo. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio abaixo da descrição. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `action` | `string` | `'OK'` | Define o rótulo de reconhecimento. |
+
+## Opções de dialog.confirm
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia a decisão. |
+| `description` | `ReactNode` | | Explica a consequência necessária para decidir. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio abaixo da descrição. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `action` | `string` | `'Confirmar'` | Define o rótulo do resultado afirmativo. |
+| `cancel` | `string` | `'Cancelar'` | Define o rótulo da resposta negativa. |
+| `context` | `'primary' \| 'danger'` | `'primary'` | Define o contexto da ação afirmativa. |
+
+## Opções de dialog.prompt
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia a informação solicitada. |
+| `description` | `ReactNode` | | Explica como a informação será usada. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio abaixo da descrição. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `action` | `string` | `'Confirmar'` | Define o rótulo do resultado afirmativo. |
+| `cancel` | `string` | `'Cancelar'` | Define o rótulo da resposta negativa. |
+| `context` | `'primary' \| 'danger'` | `'primary'` | Define o contexto da ação afirmativa. |
+| `placeholder` | `string` | | Orienta o formato esperado quando um exemplo ajuda. |
+| `defaultValue` | `string` | | Define e seleciona o valor inicial do campo. |
+
+## Opções de dialog.choose
+
+| Opção | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Nomeia a escolha. |
+| `description` | `ReactNode` | | Explica o contexto necessário para escolher. |
+| `body` | `ReactNode` | | Acrescenta conteúdo próprio antes das ações. |
+| `media` | `ReactNode` | | Exibe um ícone na moldura de `DialogMedia`. |
+| `actions` | `readonly DialogChoice[]` | | Declara os resultados disponíveis. |
+
+## Propriedades de DialogChoice
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `result` | `string` | | Valor único devolvido quando a ação for escolhida. |
+| `label` | `ReactNode` | | Rótulo que descreve o resultado da ação. |
+| `initialFocus` | `boolean` | `false` | Marca a única saída segura que recebe o foco inicial. |
+| `context` | `ButtonContext` | Última ação: `primary`; demais: `neutral` | Define o significado semântico. |
+| `variant` | `ButtonVariant` | Última ação: `solid`; demais: `ghost` | Define o tratamento visual. |
+| `disabled` | `boolean` | `false` | Impede a escolha desta ação. |
+
+`confirm()` e `ConfirmHost` continuam disponíveis apenas como aliases de migração para
+`dialog.confirm()` e `DialogHost`.

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

@@ -1,7 +1,6 @@
-Um valor de dicionário (`t.dict`) apresentado do jeito que o **dicionário** declarou. A tela não
-decide se o valor vira badge, cor ou ícone: ela passa o dicionário e o código, e o renderer
-aplica os defaults da apresentação declarada. O rótulo está sempre presente como texto — cor e
-ícone nunca comunicam sozinhos.
+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.
 
 ```tsx preview
 <DictionaryValue
@@ -9,7 +8,7 @@ aplica os defaults da apresentação declarada. O rótulo está sempre presente
   value="pj"
 />
 <DictionaryValue
-  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
+  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospecto' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
   value="customer"
 />
 <DictionaryValue
@@ -38,7 +37,7 @@ export const customerKindDict = t.dict(
 
 export const customerStageDict = t.dict(
   {
-    prospect: { label: 'Prospect', description: 'Relacionamento ainda em prospecção.' },
+    prospect: { label: 'Prospecto', description: 'Relacionamento ainda em prospecção.' },
     customer: { label: 'Cliente', context: 'success' },
   },
   { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
@@ -73,9 +72,10 @@ export const customerStageDict = t.dict(
 />
 ```
 
-## Override explícito
+## Substituição explícita
 
-Os defaults vêm do dicionário; a tela sobrepõe só quando tem um motivo, e sobrepõe às claras.
+Os padrões vêm do dicionário. Use as propriedades de apresentação somente quando esta ocorrência
+precisar de um tratamento diferente e a decisão estiver explícita na tela.
 
 ```tsx preview
 <DictionaryValue
@@ -106,9 +106,16 @@ dicionário registrado no provider: `{ key: 'source', label: 'Fonte', dictionary
 Dimensões independentes (tipo e estágio, por exemplo) ficam em colunas distintas; não empilhar
 uma sob a outra como texto secundário.
 
-## Props
+## useDicts
 
-| Prop | Tipo | Default | Descrição |
+`useDicts()` devolve os dicionários registrados em `OpusProvider` (`dicts`), chaveados pela `ref`.
+É o que `ActionList`, `ActionForm` e `DictionaryValue` consultam para resolver
+`options: { kind: 'dictionary', ref }` e colunas nomeadas por `dictionary`; fora do provider, o
+resultado é vazio e a resolução cai na meta do `t.dict` que viaja no schema.
+
+## Propriedades de DictionaryValue
+
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `dict` | `DictType \| LogicalTypeMeta \| DictionaryDescriptor` | — | O dicionário (`t.dict`), a meta lida do schema ou um descritor normalizado. |
 | `value` | `string \| null \| undefined` | — | O código. Vazio renderiza `fallback`. |

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

@@ -32,11 +32,11 @@ esquerda.
 
 A divisória entre grupos pertence ao componente: o consumidor declara `DockGroup` e a linha
 aparece entre grupos consecutivos, nunca antes do primeiro. Agrupe por intenção — modo, criação,
-IA, publicação — em vez de espalhar ícones numa fileira única.
+IA, publicação — em vez de espalhar ícones em uma fileira única.
 
 ## Estado da superfície
 
-Estado não é ferramenta, e por isso não mora na barra: `SurfaceStatus` flutua num canto da mesma
+Estado não é ferramenta, e por isso não mora na barra: `SurfaceStatus` flutua em um canto da mesma
 superfície — `top-right` por padrão — e recebe salvamento, versão publicada, execução percorrida.
 A região é `role="status"` com `aria-live="polite"`, então a mudança é anunciada sem roubar o foco.
 Separar os dois preserva a barra como toolbar navegável e dá ao estado um lugar estável, que não
@@ -63,7 +63,15 @@ A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às po
 por tooltip, então `<TooltipProvider>` precisa existir na raiz do app — o esqueleto do `opus create`
 já monta.
 
-| Prop | Tipo | Default | O que faz |
+| Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
 | `position` | `'bottom' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Aresta do contêiner onde a barra se ancora. |
 | `label` | `string` | | Nome acessível da barra. |
+
+## Propriedades de SurfaceStatus
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `position` | `'top-right' \| 'top-left'` | `'top-right'` | Canto da superfície onde o estado se ancora. |
+| `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O que o estado comunica; tinge borda e texto pela família semântica. |
+| `actions` | `ReactNode` | | Ações do recurso aberto, fora da região viva. |

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

@@ -15,3 +15,11 @@ acessível. Sem `label`, o ponto é decorativo.
 ```
 
 Use `Badge` quando o estado precisar permanecer legível sem depender do contexto ao redor.
+
+## Propriedades de Dot
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado da cor. |
+| `variant` | `'solid' \| 'outline'` | `'solid'` | Ponto preenchido ou só contornado. |
+| `label` | `string` | | Nome acessível quando a cor comunica estado; sem ele o ponto é decorativo (`aria-hidden`). |