@softize/opus 12.11.0 → 13.0.0

package/src/ui/docs/content/action-list.md

@@ -1,6 +1,12 @@
-## Declarativo pelo contrato (a diagramação da casa)
+## Listagem derivada do contrato
 
-O contrato descreve, a UI deriva — zero configuração no call site. `columns` vira a tabela emoldurada (o datagrid da casa; tipos text/number/date/badge, `fit`, `hidden`, headers ordenáveis que escrevem `sort: 'chave:dir'` no input); `filters` vira a toolbar (os não-avançados inline, os `advanced: true` no modal "Filtros" com contador); `text` liga a busca (param `q`); filtros do modal aplicados viram chips removíveis. A linha é RESPONSIVA: a busca tem largura auto (encolhe primeiro) e filtro inline que não cabe migra pro modal — medição real, re-avaliada no resize; só no caso extremo (nada mais a ceder) a linha quebra. O handler implementa o que o input diz (orderBy, where) — mesmo modelo do resto do Opus.
+Use `ActionList` para apresentar uma coleção pesquisável descrita por uma `ListAction`. O contrato
+define colunas, busca, filtros, período, ordenação e paginação; a interface materializa esses
+recursos e envia o estado correspondente no input. Filtros avançados aparecem no modal “Filtros” e
+os filtros aplicados permanecem visíveis como chips removíveis.
+
+A barra se adapta ao espaço disponível. A busca cede largura primeiro e filtros que deixam de caber
+migram para o modal; a linha só quebra quando nenhum controle restante puder ceder espaço.
 
 ```tsx preview col
 render(
@@ -28,18 +34,16 @@ superfícies que não são listagens, como relatórios. O estado é controlado p
 />
 ```
 
-Selects inline têm largura fixa e previsível (`w-40`; lookup e múltiplo `w-52`): nem a label nem
-o valor selecionado alargam o controle — o rótulo trunca e a opção inteira continua na lista. No
-modal de filtros avançados, o select ocupa a largura toda. Busca e filtros são renderizados
-somente quando declarados. Períodos incluem os presets do
-contrato e o intervalo personalizado no mesmo calendário usado pela `ActionList`.
+Seletores inline mantêm largura previsível (`w-40`; lookup e múltiplo usam `w-52`). Rótulos longos
+são truncados no controle, mas permanecem completos na lista. No modal de filtros avançados, o
+seletor ocupa toda a largura. Busca, filtros e período aparecem somente quando declarados.
 
 ## Colunas de dicionário
 
-Coluna cujo campo no schema de saída é um `t.dict().zod()` renderiza `DictionaryValue` com a
-apresentação que o dicionário declarou (`presentation`: classificação em badge `outline`, status
-e estágio em badge tonal, `plain` ou ausente como texto). Nada a configurar na tela. Quando o
-campo de saída é uma string comum, a coluna nomeia o dicionário registrado no provider:
+Quando o campo de saída usa `t.dict().zod()`, a coluna apresenta o valor com `DictionaryValue` e
+respeita o papel declarado pelo dicionário. Classificações usam badge `outline`; status e estágio
+usam badge tonal; `plain` e papéis ausentes permanecem como texto. Para um campo `string`, a coluna
+pode indicar um dicionário registrado no provider:
 `{ key: 'source', label: 'Fonte', dictionary: 'customerSource' }`. Dimensões independentes, como
 tipo e estágio, ficam em colunas distintas — a leitura de comparação depende disso. `type:
 'badge'` continua sendo o chip `outline` legado; com dicionário, ele mostra o rótulo em vez do
@@ -56,7 +60,8 @@ Renderer customizado reutiliza `EmptyValue`.
 
 ## Células custom (cells)
 
-As colunas do contrato descrevem DADOS; apresentação especial entra por cima com `cells` (chave = key da coluna). É onde vivem links, composições e a coluna de ações; valor de dicionário já resolve sozinho pela coluna, sem `cells`.
+Use `cells` somente quando uma coluna precisar de apresentação própria, como link, composição ou
+ação. A chave corresponde à `key` da coluna. Valores de dicionário não precisam desse override.
 
 ```tsx preview col
 render(
@@ -78,9 +83,12 @@ render(
 )
 ```
 
-## Período (o campo dinâmico)
+## Período obrigatório
 
-Com `periods` no contrato, a toolbar ganha o controle de período: um popover com os presets e, no "Personalizado", o calendário de range ali mesmo. Período é recorte OBRIGATÓRIO do caso de uso: o default (o preset com `default: true`, ou o primeiro) já vem aplicado e não existe "sem período". O preset fica RELATIVO na URL (`?period=last7`; o default é omitido); no custom o range vai direto no param (`?period=2026-07-01..2026-07-07` — o "custom" é implícito). No fetch, o pattern materializa o range nos params `from`/`to` — o handler implementa o recorte.
+Quando o contrato declara `periods`, a listagem sempre possui um recorte temporal. O preset marcado
+com `default: true`, ou o primeiro da coleção, começa aplicado. Presets usam um valor relativo na
+URL, como `?period=last7`; o padrão é omitido. Um intervalo personalizado usa diretamente as datas,
+como `?period=2026-07-01..2026-07-07`, e chega ao handler pelos parâmetros `from` e `to`.
 
 ```tsx
 periods: [
@@ -91,13 +99,20 @@ periods: [
 // Presets computáveis: today · yesterday · last7 · last30 · thisMonth · lastMonth.
 ```
 
-## Paginação e loading
+## Paginação e carregamento
 
-O pattern manda `limit` (= `pageSize`, default 50) e `page` no input; o handler implementa o OFFSET e devolve `total` no Paginated. O rodapé (Página X de Y · páginas numeradas com reticências · "N itens no total") compõe a primitiva `Pagination` na escala densa — números com largura mínima que cresce com os dígitos, setas quadradas, nome acessível por página — e aparece sempre que há total; mudar filtro/busca/sort/período volta pra página 1 (a página vive na URL: `?page=2`). No primeiro carregamento, `DataState` centraliza o spinner; no refetch com a lista já na tela, o corpo esmaece (`aria-busy`) até os dados chegarem.
+`ActionList` envia `limit`, definido por `pageSize`, e `page` no input. O handler aplica o recorte e
+devolve `total` na resposta paginada. Quando existe total, o rodapé mostra a página atual, os links
+disponíveis e a quantidade de itens. Alterar busca, filtro, ordenação ou período retorna à primeira
+página. Durante a primeira consulta, `DataState` apresenta o carregamento; em atualizações
+posteriores, a lista permanece visível com `aria-busy`.
 
-## Multi-seleção com can (batch)
+## Ações em lote
 
-`batch` liga a coluna de checkbox na tabela. O `can(item)` é a fonte única de elegibilidade: linha inelegível não marca, o "selecionar todos" pega só os elegíveis, o botão mostra quantos dos selecionados valem e o `run` recebe apenas esses. Com `confirm`, um dialog pede confirmação; ao resolver, a seleção limpa e a lista refaz.
+`batch` acrescenta seleção à tabela. `can(item)` determina quais linhas podem participar: itens
+inelegíveis não são selecionáveis, “Selecionar todos” inclui somente os elegíveis e `run` recebe
+apenas essa seleção. Com `confirm`, o componente pede confirmação antes de executar. Ao concluir, a
+seleção é limpa e a consulta é refeita.
 
 ```tsx
 <ActionList action={runList} input={{}}
@@ -110,9 +125,12 @@ O pattern manda `limit` (= `pageSize`, default 50) e `page` no input; o handler
 />
 ```
 
-## Views (a mesma listagem, outro renderer)
+## Outras visualizações
 
-Nem toda listagem é tabela: board, galeria, lista, calendário… A view é APRESENTAÇÃO de quem chama (`render`); o pattern dá o segment na toolbar (ToggleGroup, ICON-ONLY: declare `icon` — o label vira title/aria; sem ícone cai pro texto), o estado (`view` na URL) e os dados — a mesma fonte, os mesmos filtros. A tabela ('Tabela') participa quando há columns.
+Uma coleção também pode aparecer como quadro, galeria, lista ou calendário. Cada entrada de `views`
+fornece um `render`; `ActionList` preserva a mesma fonte de dados, filtros e estado na URL. Declare
+`icon` para controles somente com ícone; sem ele, o rótulo permanece visível. A visualização
+“Tabela” aparece quando existem colunas.
 
 ```tsx preview col
 render(
@@ -146,13 +164,16 @@ render(
 )
 ```
 
-## Filtros dependentes, dictionary e lookup
+## Filtros dependentes e opções remotas
 
-Três recursos do FilterSpec que a toolbar honra:
+`FilterSpec` também cobre dependências, dicionários e consultas remotas:
 
-- **`depends: ['outroFiltro']`** — o filtro dependente fica DESABILITADO até o pai ter valor, e mudar o pai limpa o dependente em cascata (o recorte perde o sentido quando o pai muda). Vale inline e no modal.
-- **`options: { kind: 'dictionary', ref: 'sessionStatus' }`** — as opções vêm de um DICT registrado no `<TbdlibProvider dicts={{ sessionStatus: statusDict }}>` (o `DictType` do `t.dict` encaixa direto). Labels do vocabulário no filtro E nos chips; runtime (`filterOptions`) sobrepõe.
-- **`options: { kind: 'lookup', source: 'x.lookup' }`** — as opções vêm de uma ACTION (server-side): o campo vira Select typeahead que chama a `source` (debounced) com `{ q }` — e com os valores dos `depends` no input. Convenção: a action de lookup devolve itens `{ value, label }`. Com valor aplicado mas opções ainda não carregadas (URL, chip), o chip mostra o próprio value.
+- **`depends: ['outroFiltro']`:** desabilita o filtro até que suas dependências tenham valor e o
+  limpa quando uma delas muda.
+- **`options: { kind: 'dictionary', ref: 'sessionStatus' }`:** resolve opções e rótulos por um
+  dicionário registrado no `TbdlibProvider`. `filterOptions` substitui essa fonte quando informado.
+- **`options: { kind: 'lookup', source: 'x.lookup' }`:** consulta uma action com `{ q }` e os valores
+  das dependências. A resposta segue o formato `{ value, label }`.
 
 ```tsx
 filters: {
@@ -166,9 +187,12 @@ filters: {
 }
 ```
 
-## Exibição e URL sync
+## Exibição e estado na URL
 
-O botão de exibição (engrenagem) abre o popover de configuração da listagem — presente em QUALQUER view: colunas (liga/desliga, incluindo as `hidden` do contrato; só com a tabela ativa) e itens por página (o default do caller fica fora da URL) — e é a casa do que vier depois. E o estado inteiro da toolbar (q, sort, filtros, view, colunas, limit) serializa pra querystring com os helpers padrão:
+O botão de exibição abre as preferências da listagem em qualquer visualização. Na tabela, permite
+mostrar ou ocultar colunas, inclusive as declaradas com `hidden`; em todas as visualizações, permite
+alterar a quantidade de itens por página. Busca, ordenação, filtros, visualização, colunas e limite
+podem ser serializados na query string pelos helpers do componente:
 
 ```tsx
 <ActionList
@@ -181,9 +205,10 @@ O botão de exibição (engrenagem) abre o popover de configuração da listagem
 
 Convenção compacta (defaults omitidos): `?q=…&sort=chave:dir&status=…&view=board&cols=a,b,c&limit=25`.
 
-## Composição (layout livre)
+## Composição dos itens
 
-Com children, a tabela sai de cena e o layout dos itens é seu (cards, grid, o que for) — a toolbar declarativa e os estados (skeleton/erro/vazio) seguem daqui. Mesmo princípio do ActionForm com children.
+Passe `children` para substituir a tabela por uma composição própria. A barra de filtros e os
+estados de carregamento, erro e vazio continuam sendo tratados por `ActionList`.
 
 ```tsx preview col
 render(
@@ -209,30 +234,30 @@ render(
 )
 ```
 
-## No contrato (ListAction)
+## Declaração na ListAction
 
 | Chave | O que declara |
 |---|---|
 | `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat?, dictionary?, empty? }` — a tabela. `hidden` fica fora (base do futuro column picker); `dictionary` nomeia o dicionário do provider; `empty` dá o significado da ausência. |
-| `filters` | `{ [nome]: { label, type, options?, multiple?, advanced?, depends?, … } }` — a toolbar. `advanced` vai pro modal; `depends` desabilita/cascateia; options `kind: 'lookup'` busca numa action. Valor aplicado entra no input com o MESMO nome. |
+| `filters` | `{ [nome]: { label, type, options?, multiple?, advanced?, depends?, … } }` — a toolbar. `advanced` vai para o modal; `depends` desabilita/cascateia; options `kind: 'lookup'` busca em uma action. Valor aplicado entra no input com o mesmo nome. |
 | `text` | `{ fields }` — liga a busca; convenção: param `q` no input. Com período/filtros no contrato ela fica à direita; sendo a ÚNICA forma de recorte, abre a linha. |
 | `sort` | `{ fields, default }` — ordenação inicial; header ordenável escreve `sort: 'chave:dir'`. |
 | `periods` | `{ value, label }[]` — o controle de período (presets + Personalizado com calendário); materializa em `from`/`to` no input. |
 
-## Props
+## Propriedades de ActionList
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `ListAction<TInput, TItem>` | | A ListAction do Opus (kind list, output = item, paginate cursor). |
 | `input` | `TInput` | | O ESCOPO BASE (ex.: { workspaceId }) — a toolbar soma por cima, nunca sobrescreve. |
 | `cells` | `Record<string, (item) => ReactNode>` | | Células custom por cima das colunas do contrato (chave = column.key). |
-| `filterOptions` | `Record<string, SelectOption[]>` | | Opções de runtime pros filtros select/lookup (chave = nome do filtro). |
+| `filterOptions` | `Record<string, SelectOption[]>` | | Opções de runtime para os filtros select/lookup (chave = nome do filtro). |
 | `columns` | `ActionListColumn<TItem>[]` | | Tabela EXPLÍCITA — sobrepõe as colunas do contrato (escape hatch). |
-| `children` | `(items, refetch) => ReactNode` | | Modo COMPOSIÇÃO: layout livre; a toolbar segue. Tem precedência sobre columns. |
+| `children` | `(items, refetch) => ReactNode` | | Modo composição: layout livre; a toolbar segue. Tem precedência sobre columns. |
 | `batch` | `ActionListBatchAction[]` | | Ações em lote: `{ label, can?, run, confirm?, destructive? }` — liga a multi-seleção. |
-| `rowId` | `(item) => string` | `item.id` | Identidade da linha pra seleção. |
-| `pageSize` | `number` | `50` | Itens por página DEFAULT (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição. |
-| `state / onStateChange` | `ActionListState / (next) => void` | interno | Estado da toolbar controlado — pra quem embala sincronizar com a URL. |
+| `rowId` | `(item) => string` | `item.id` | Identidade da linha para seleção. |
+| `pageSize` | `number` | `50` | Itens por página padrão (vira `limit`/`page` no input; handler devolve `total`). O usuário troca no popover de exibição. |
+| `state / onStateChange` | `ActionListState / (next) => void` | interno | Estado da toolbar controlado — para quem embala sincronizar com a URL. |
 | `emptyMessage` | `string` | `'Nenhum resultado.'` | O texto do estado vazio. |
-| `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar pro detalhe) — só na tabela. |
+| `onRowClick` | `(item: TItem) => void` | | Clique na linha (ex.: navegar para o detalhe) — só na tabela. |
 | `rowActions` | `(item: TItem) => ReactNode` | | Ações por linha (coluna final, à direita) — apresentação de quem chama, como `cells`; cliques ali não disparam o `onRowClick`. |

package/src/ui/docs/content/action-trigger.md

@@ -1,7 +1,8 @@
-## Disparo direto
+## Executar uma action
 
-Sem confirm, dispara no clique: desabilita enquanto roda e toca o toast do contrato
-(messages.success/error). O label default vem do action.label.
+Use `ActionTrigger` para executar uma `SimpleAction` a partir de um botão. Sem confirmação, o clique
+inicia a operação, desabilita o controle durante a execução e apresenta as mensagens do contrato em
+um toast. O rótulo padrão vem de `action.label`.
 
 ```tsx preview
 <DocBrowserActionProvider>
@@ -11,8 +12,9 @@ Sem confirm, dispara no clique: desabilita enquanto roda e toca o toast do contr
 
 ## Confirmação declarada no contrato
 
-O ConfirmSpec mora na action (title/message/destructive) — o pattern monta o Dialog sozinho e o
-destructive já tonaliza o botão. Prop confirm sobrepõe quando a tela precisar de outro texto.
+Quando a action declara `confirm`, o componente monta o diálogo e aplica o contexto `danger` se a
+operação for destrutiva. Use a propriedade `confirm` somente quando esta ocorrência precisar de uma
+mensagem diferente da declarada no contrato.
 
 ```tsx preview
 <DocBrowserActionProvider>
@@ -33,9 +35,11 @@ confirm: {
 <ActionTrigger action={sessionDeleteContract} input={{ id: session.id }} />
 ```
 
-## A ação que mora no item (icon)
+## Ação somente com ícone
 
-Com `icon`, o botão vira icon-only: o `label` (ou o `action.label`) migra pro tooltip e pro `aria-label`, o visual fica discreto (ghost, e vermelho no hover quando o contrato marca `destructive`) e o clique **não vaza** pro item em volta — é o que permite viver dentro de uma linha ou card clicável. `itemLabel` nomeia o alvo na pergunta.
+Com `icon`, o botão exibe somente o ícone e usa `label`, ou `action.label`, no tooltip e no nome
+acessível. O clique não aciona o item clicável ao redor. `itemLabel` identifica o registro na
+mensagem de confirmação.
 
 ```tsx
 <ActionTrigger
@@ -47,19 +51,22 @@ Com `icon`, o botão vira icon-only: o `label` (ou o `action.label`) migra pro t
 />
 ```
 
-> Isto absorveu o antigo `DeleteButton` (7.0.0), que era exatamente este componente com uma lixeira dentro. Se você tinha `<DeleteButton action input itemLabel />`, troque por `<ActionTrigger … icon={<Trash2 />} />` — **e confira se o contrato declara `confirm`**: sem ele o disparo é direto, e o DeleteButton perguntava sempre.
+> `ActionTrigger` substitui o antigo `DeleteButton`. Ao migrar, declare `confirm` no contrato para
+> preservar a confirmação que o componente anterior sempre apresentava.
 
 ## Erro que a pessoa entende
 
-Quando a action falha, a frase do SERVIDOR só vence o rótulo do contrato se o erro for de negócio — `conflict`, `validation`, `not_found`:
+Quando a action falha, uma mensagem do servidor substitui o texto genérico somente nos erros de
+negócio `conflict`, `validation` e `not_found`:
 
 > Este agente tem 3 conversas — desabilite em vez de excluir.
 
-Isso é acionável. Erro inesperado carrega texto técnico cru: sem a allowlist, uma violação de FK viraria `violates foreign key constraint "user_unit_id_fkey"` no toast de quem só clicou num botão. Por isso allowlist e não denylist — categoria desconhecida cai no rótulo genérico, que é o lado seguro de errar.
+Erros inesperados mantêm a mensagem genérica do contrato, evitando expor detalhes de banco ou
+infraestrutura. O servidor registra o detalhe técnico para diagnóstico.
 
-## Props
+## Propriedades de ActionTrigger
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `SimpleContract<TInput, TData>` | | A SimpleAction do Opus — label, messages e confirm vêm do contrato. |
 | `input` | `TInput` | | O que a action recebe — geralmente { id }. |
@@ -67,6 +74,6 @@ Isso é acionável. Erro inesperado carrega texto técnico cru: sem a allowlist,
 | `variant / size` | `variants do Button` | `'default' (ou 'destructive' se o confirm declarar) / 'default'` | Visual do botão — o destructive do ConfirmSpec já escolhe sozinho. |
 | `confirm` | `{ title, description?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
-| `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza pro item. |
+| `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza para o item. |
 | `itemLabel` | `string` | | Nome do alvo na pergunta (sai entre aspas, em destaque, antes da mensagem do contrato). |
-| `className` | `string` | | Classes do botão (ex.: apertar o tamanho numa linha densa). |
+| `className` | `string` | | Classes do botão (ex.: apertar o tamanho em uma linha densa). |

package/src/ui/docs/content/action-view.md

@@ -1,8 +1,8 @@
-## Detalhe com estados padronizados
+## Carregar um recurso
 
-Troque o workspace pra ver o skeleton; o inexistente mostra o erro padrão com o Tentar de novo. O
-preview roda num client de mentira — no app, cada feature embrulha (TicketView…) delegando o
-fetching pra cá.
+Use `ActionView` para carregar um recurso por uma `ViewAction` e manter carregamento, erro e vazio no
+mesmo fluxo. No exemplo, alterne entre os workspaces para observar o carregamento e a recuperação de
+erro. O consumidor compõe somente o conteúdo disponível.
 
 ```tsx preview col
 const [id, setId] = useState('empresa-x')
@@ -35,13 +35,13 @@ render(
 )
 ```
 
-## Props
+## Propriedades de ActionView
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `action` | `ViewAction<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
 | `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
-| `children` | `(data: TData, refetch) => ReactNode` | | O estado feliz — layout 100% do consumidor; refetch pra recarregar por código. |
-| `render` | `(data: TData, refetch) => ReactNode` | | Alias de children (a API original). Children tem precedência. |
+| `children` | `(data: TData, refetch) => ReactNode` | | Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
+| `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. |
 | `loading / empty` | `ReactNode` | `3 skeletons / nada` | Sobrescreve os estados padrão quando o contexto pedir. |
 | `error` | `(err, retry) => ReactNode` | `mensagem + Tentar de novo` | Sobrescreve o estado de erro padrão. |

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

@@ -10,7 +10,7 @@ o handler e a web usa a mesma definição para executar ou renderizar a operaç
 
 ## Contrato primeiro
 
-> `defineContract` no `shared/` — entidades, schemas (zod + `t.*` pra tipos lógicos) e os
+> `defineContract` no `shared/` — entidades, schemas (zod + `t.*` para tipos lógicos) e os
 > metadados da action. `api` e `web` importam; nada se duplica.
 
 ```ts
@@ -64,18 +64,18 @@ name → kind → (label / summary / messages / tags…)
   → invalidates
 ```
 
-Fail-closed por padrão: `input`/`output` via `z.object` + `t.*` pros tipos lógicos; `authorize`
+Fail-closed por padrão: `input`/`output` via `z.object` + `t.*` para os tipos lógicos; `authorize`
 declarado ou gate explícito do adapter.
 
-Os átomos do catálogo servem TAMBÉM dentro dos schemas de input/output — não re-escreva
+Os átomos do catálogo servem também dentro dos schemas de input/output — não re-escreva
 regex do que o Opus já valida: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`.
 O `.zod()` devolve o schema zod subjacente do tipo lógico (slug, email, phone, money…).
 
 ## Modo design — o mock mora no contrato
 
 Um `mockHandler` no contrato deixa a UI rodar com dado realista **sem backend nem banco**: em
-`OPUS_MODE=design` o runtime roteia o `execute` pro `mockHandler` (cai no `handler` real se
-ausente). Como ele fica no CONTRATO (não no `bindAction`), é isomorfo — o design autora, o
+`OPUS_MODE=design` o runtime roteia o `execute` para o `mockHandler` (cai no `handler` real se
+ausente). Como ele fica no contrato, e não no `bindAction`, é isomorfo — o design autora, o
 handoff pluga o handler, e o mock nem toca `ctx.db`.
 
 Alimente com `fake`/`fakeMany` (fixtures determinísticas do próprio schema — ver [Testes](testing)):
@@ -92,15 +92,15 @@ export const eventGet = defineContract({
 })
 // listas: `mockHandler: () => fakeMany(EventEntity.zod(), 20)`
 
-// o handoff, depois, só pluga o real — MESMO contrato:
+// o handoff, depois, só pluga o real — mesmo contrato:
 export const eventGetImpl = bindAction(eventGet, { handler: async (ctx, input) => { /* db */ } })
 ```
 
 O `mockHandler` roda no **servidor em modo design** (`OPUS_MODE=design`), não no cliente — e
 quem sobe esse servidor é o próprio dev server: o plugin `opusDesign()` (`@softize/opus/vite`)
 monta o runtime Opus DENTRO do vite e serve `/api` in-process, com os mocks respondendo e
-qualquer `server.proxy` pra backend externo desligado (prefixo ex-proxy sem cobertura responde
-503 em envelope — nada vaza pra prod). A SPA chama `/api` normal e recebe o dado fake, isolado:
+qualquer `server.proxy` para backend externo desligado (prefixo ex-proxy sem cobertura responde
+503 em envelope — nada vaza para prod). A SPA chama `/api` normal e recebe o dado fake, isolado:
 
 ```ts
 // vite.config.ts
@@ -118,7 +118,7 @@ persistindo, o envelope traz a mensagem-guia apontando o entry.
 
 Como o contrato é isomorfo, o `mockHandler` também acompanha o **bundle web** — peso morto lá
 (a SPA nunca o chama; o dado é fake). Tirá-lo do bundle de prod é um transform de build
-(deferido); **não** dá pra gatear no call-site com `import.meta.env` sem quebrar o servidor
+(deferido); **não** dá para gatear no call-site com `import.meta.env` sem quebrar o servidor
 (não existe em Node). É a materialização Opus-nativa do "mock = contrato": o design não é
 descartável — vira o contrato que o backend honra.
 

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

@@ -64,10 +64,10 @@ handler: async (ctx, input) => {
 Marque uma action com `ai: { enabled: true }` no contrato e ela vira uma **tool** que o
 modelo pode chamar. Aí `ctx.ai.run(prompt)` roda o loop agêntico sobre as actions `ai:enabled`:
 o modelo escolhe a tool → o runtime executa a action **como o usuário logado** (limitado pelo
-`ctx.can`) → o resultado volta pro modelo → repete até a resposta em texto.
+`ctx.can`) → o resultado volta para o modelo → repete até a resposta em texto.
 
 ```ts
-// A action opta por entrar — o contrato já tem o schema, que vira a tool spec de graça:
+// A action opta por entrar; o schema do contrato também descreve a ferramenta:
 export const buscarNotas = defineContract({
   name: 'nota.buscar',
   kind: 'list',
@@ -76,7 +76,7 @@ export const buscarNotas = defineContract({
   ai: { enabled: true, description: 'Busca notas por cliente e mês.' },
 })
 
-// No handler — ou fora dele, via runtime.aiFor(base), pro backend de um chat:
+// No handler — ou fora dele, via runtime.aiFor(base), para o backend de um chat:
 const { text } = await ctx.ai!.run('Quantas notas a Empresa X emitiu em junho?')
 // o modelo chamou nota.buscar sozinho, como o usuário logado, e respondeu em texto.
 ```

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

@@ -1,6 +1,7 @@
 ## Forma curta
 
-Quase todo alert é ícone + título + uma frase — então isso é UMA linha: `title`, `description` e `icon` como props. O componente monta os slots e a a11y (`role="alert"`, que faz o leitor de tela anunciar sozinho).
+Use a forma curta quando o aviso tiver ícone, título e uma frase. Declare `title`, `description` e
+`icon`; o componente monta os slots e anuncia o conteúdo com `role="alert"`.
 
 ```tsx preview col
 <Alert icon={<Info />} title="Opus 2.8.0" description="Este workspace usa a versão pinada em opus.json." />
@@ -37,10 +38,9 @@ borda e texto; o conteúdo comunica o significado sem depender somente da cor.
 ## Mídia é opcional
 
 Sem `icon` o alert mantém somente a coluna de texto. Com ele, a forma curta materializa
-`AlertMedia` à esquerda e `AlertHeader` à direita. A mídia tem largura estável e acompanha a
-altura útil do header; com título e descrição de uma linha, a moldura termina junto do texto,
-sem sobra inferior. Texto solto como filho também vale (`<Alert>Sincronizado.</Alert>`) e se torna
-uma descrição.
+`AlertMedia` à esquerda e `AlertHeader` à direita. A mídia mantém uma moldura quadrada de tamanho
+estável, mesmo quando o título ou a descrição ocupam mais linhas. Texto solto como filho também
+vale (`<Alert>Sincronizado.</Alert>`) e se torna uma descrição.
 
 ```tsx preview col
 <Alert title="Sem provider próprio" description="As conversas usam o padrão do sistema." />
@@ -51,7 +51,8 @@ uma descrição.
 
 Quando a mensagem precisa de conteúdo rico, componha os slots da família. `AlertMedia`,
 `AlertHeader` e `AlertActions` são filhos diretos de `Alert`; `AlertTitle` e
-`AlertDescription` pertencem ao header.
+`AlertDescription` pertencem ao header. As ações ficam no fim lógico da superfície e centralizadas
+verticalmente na mesma linha do conteúdo — a mesma posição usada pelas ações do Toast.
 
 ```tsx preview col
 <Alert context="danger">
@@ -59,21 +60,22 @@ Quando a mensagem precisa de conteúdo rico, componha os slots da família. `Ale
     <CircleAlert />
   </AlertMedia>
   <AlertHeader>
-    <AlertTitle>Não deu pra publicar</AlertTitle>
+    <AlertTitle>Não deu para publicar</AlertTitle>
     <AlertDescription>
       <p>O registry recusou a versão 3.0.0 — ela já existe.</p>
       <p>Suba o patch e tente de novo.</p>
     </AlertDescription>
   </AlertHeader>
   <AlertActions>
-    <Button size="sm" variant="outline">
+    <Button size="sm">
       Tentar novamente
     </Button>
   </AlertActions>
 </Alert>
 ```
 
-Os dois modos convivem: com `title`/`description` preenchidos, `children` entra DEPOIS da frase — é onde vai a ação.
+Os dois modos convivem: com `title` ou `description`, `children` entra depois da mensagem e recebe a
+ação.
 
 ```tsx preview col
 <Alert
@@ -81,15 +83,15 @@ Os dois modos convivem: com `title`/`description` preenchidos, `children` entra
   title="Sessão presa"
   description="O ambiente não subiu no tempo esperado."
 >
-  <Button size="sm" variant="outline">
+  <Button size="sm">
     Reiniciar
   </Button>
 </Alert>
 ```
 
-## Props
+## Propriedades de Alert
 
-| Prop          | Tipo                                                        | Default     | Descrição                                                                                                                               |
+| Propriedade   | Tipo                                                        | Padrão      | Descrição                                                                                                                               |
 | ------------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `title`       | `React.ReactNode`                                           |             | Título do alert (a forma curta). Não é o atributo `title` do HTML — esse é tooltip nativo, banido na casa, e o componente não o aceita. |
 | `description` | `React.ReactNode`                                           |             | A frase. Sozinha, dispensa título.                                                                                                      |

package/src/ui/docs/content/aspect-ratio.md

@@ -15,7 +15,7 @@ contêiner (o pai): a altura o componente deriva sozinho.
 
 ## Quadrado (1/1)
 
-ratio={1} trava num quadrado — o formato dos avatares de agente e dos ícones de skill, onde a
+ratio={1} trava em um quadrado — o formato dos avatares de agente e dos ícones de skill, onde a
 moldura precisa ser previsível.
 
 ```tsx preview col-start
@@ -57,10 +57,10 @@ layout quando o preview carrega.
 </div>
 ```
 
-## Props
+## Propriedades de AspectRatio
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `ratio` | `number` | `1` | A razão largura/altura. 16/9 pra vídeo/preview, 1 pra quadrado, 4/3 pra clássico. |
+| `ratio` | `number` | `1` | A razão largura/altura. 16/9 para vídeo/preview, 1 para quadrado, 4/3 para clássico. |
 | `children` | `React.ReactNode` | | O conteúdo a enquadrar (img, iframe, div) — preencha com h-full w-full e object-cover. |
 | `className` | `string` | | Estilo do bloco — borda, rounded e overflow-hidden moram aqui, não no filho. |

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

@@ -5,7 +5,7 @@ title: Auditoria
 # Auditoria
 
 Toda action executada vira um registro imutável: quem, o quê, quando, com que entrada e
-resultado. O runtime emite um `AuditRecord` por execução pro(s) sink(s) configurado(s) — de
+resultado. O runtime emite um `AuditRecord` por execução para o(s) sink(s) configurado(s) — de
 graça, sem o handler pedir. O contrato é o `AuditSink`.
 
 ## O contrato
@@ -43,7 +43,7 @@ interface AuditRecord {
 import { consoleAudit } from '@softize/opus/audit/console'
 import { pgAudit } from '@softize/opus/audit/pg'
 
-// Dev: uma linha por action (pretty num TTY, json senão).
+// Dev: uma linha por action (pretty em um TTY, json senão).
 const dev = consoleAudit()
 
 // Produção: grava na tabela audit_log (Postgres).

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

@@ -7,7 +7,7 @@ title: Autenticação
 Quem é o usuário, de qual tenant, e o que ele pode. O contrato é um adapter do core
 (`AuthAdapter`): a cada request o runtime chama `resolveContext` e injeta o resultado no
 handler — `ctx.user`, `ctx.tenantId`, `ctx.can`. O Opus **não** implementa RBAC/ABAC; ele
-delega a decisão pro `can` que o driver pluga.
+delega a decisão para o `can` que o driver pluga.
 
 ## O contrato
 
@@ -31,7 +31,7 @@ política usada por ela.
 import { jwtAuth } from '@softize/opus/auth/jwt'
 import { betterAuthSession } from '@softize/opus/auth/better-auth'
 
-// JWT: valida o token (HS256 por padrão) e mapeia o payload pro User.
+// JWT: valida o token (HS256 por padrão) e mapeia o payload para o User.
 const jwt = jwtAuth({ secret: process.env.JWT_SECRET! })
 
 // better-auth: valida a sessão contra um IdP better-auth remoto.
@@ -44,7 +44,7 @@ const idp = betterAuthSession({
 
 O `jwt` procura o token no `Authorization: Bearer`, em cookie ou custom (via `getToken`); o
 `secret` pode ser string ou um resolver async por `kid`. O `betterAuthSession` faz fetch da
-sessão no IdP (`timeoutMs`, default 5s) e mapeia pro `User`/tenant/can (o `can` default nega
+sessão no IdP (`timeoutMs`, default 5s) e mapeia para o `User`/tenant/can (o `can` default nega
 tudo — plugue o seu).
 
 ## No runtime

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

@@ -1,4 +1,4 @@
-## Básico
+## Retrato com imagem
 
 AvatarImage com src/alt e AvatarFallback com as iniciais — o fallback aparece enquanto a imagem
 carrega ou se ela falha.
@@ -12,8 +12,8 @@ carrega ou se ela falha.
 
 ## Fallback de iniciais
 
-Sem AvatarImage (ou com src quebrado), só o AvatarFallback renderiza — iniciais pra pessoa, ícone
-pra agente.
+Sem AvatarImage (ou com src quebrado), só o AvatarFallback renderiza — iniciais para pessoa, ícone
+para agente.
 
 ```tsx preview
 <Avatar>
@@ -28,7 +28,7 @@ pra agente.
 
 ## Tamanhos
 
-size sm/default/lg — o fallback acompanha o tamanho. sm pra listas densas, lg pra cabeçalho de
+size sm/default/lg — o fallback acompanha o tamanho. sm para listas densas, lg para cabeçalho de
 workspace.
 
 ```tsx preview
@@ -45,8 +45,8 @@ workspace.
 
 ## Com selo de status
 
-AvatarBadge é o ponto no canto inferior — verde pro agente developer rodando uma sessão, cinza
-pro ocioso. Tinja com className.
+AvatarBadge é o ponto no canto inferior — verde para o agente developer rodando uma sessão, cinza
+para o ocioso. Tinja com className.
 
 ```tsx preview
 <Avatar>
@@ -82,13 +82,33 @@ excedente — os membros do workspace Empresa X.
 </AvatarGroup>
 ```
 
-## Props
+## Propriedades de Avatar
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` (Avatar) | `'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato — o fallback e o selo acompanham. |
-| `src` (AvatarImage) | `string` | | URL da imagem. Enquanto carrega (ou se falha), o AvatarFallback fica no lugar. |
-| `alt` (AvatarImage) | `string` | | Texto alternativo da imagem — o nome da pessoa ou do agente. |
-| `children` (AvatarFallback) | `React.ReactNode` | | O que aparece sem imagem: iniciais (pessoa) ou ícone (agente). |
-| `className` (AvatarBadge) | `string` | | Selo no canto inferior — tinja o fundo (ex.: bg-emerald-500) pra refletir o status. |
-| `children` (AvatarGroupCount) | `React.ReactNode` | | O excedente da pilha (ex.: "+3"), fechando o AvatarGroup. |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato; o fallback e o selo acompanham a escala. |
+
+## Propriedades de AvatarImage
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `src` | `string` | | URL da imagem. Enquanto ela carrega ou quando falha, `AvatarFallback` ocupa o lugar. |
+| `alt` | `string` | | Texto alternativo que identifica a pessoa ou o agente. |
+
+## Propriedades de AvatarFallback
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `React.ReactNode` | | Iniciais ou ícone exibido quando a imagem não está disponível. |
+
+## Propriedades de AvatarBadge
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Classes usadas para comunicar visualmente o status no selo. |
+
+## Propriedades de AvatarGroupCount
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `children` | `React.ReactNode` | | Quantidade excedente no fim do grupo, como `+3`. |