@softize/opus 18.1.0 → 18.1.1

package/src/ui/components/primitives/select.tsx

@@ -92,7 +92,7 @@ interface SelectCustomBase extends SelectBaseProps {
   clearable?: boolean
   /** `outline`: compacto com borda; `ghost`: compacto sem borda nem fundo. */
   variant?: 'default' | 'outline' | 'ghost'
-  /** Placeholder enquanto se digita a busca (cai pro `placeholder`). */
+  /** Placeholder da linha de busca dentro da lista. Default: `'Buscar…'`. */
   searchPlaceholder?: string
   emptyText?: string
   /** Ação custom no FIM do campo, dentro do controle (antes do chevron) — ex.: um botão que

package/src/ui/docs/content/action-form-dialog.md

@@ -3,8 +3,11 @@
 Use `ActionFormDialog` quando o formulário precisar interromper o fluxo atual sem levar a pessoa
 para outra página. O consumidor controla `open`; depois de uma execução bem-sucedida, o componente
 fecha o modal. O cabeçalho e o rodapé permanecem visíveis enquanto os campos podem rolar.
-Quando há cancelamento, o rodapé usa um `ButtonGroup` dividido: `Cancelar` aparece em `outline` e
-a ação principal permanece `solid`, ambas no tamanho normal de uma decisão modal.
+O rodapé agrupa as decisões em um `ButtonGroup` cuja largura acompanha o conteúdo: `Cancelar`
+aparece em `ghost` e a ação principal permanece `solid`, ambas no tamanho normal de uma decisão
+modal. `Cancelar` está sempre presente; sem `onCancel` próprio, ele fecha o modal.
+Com `footerDistribution="equal"`, as duas decisões dividem a faixa e `Cancelar` passa a `outline`,
+salvo escolha explícita em `cancelVariant`.
 
 ```tsx preview
 const [open, setOpen] = useState(false);
@@ -26,8 +29,12 @@ render(
 
 | Propriedade           | Tipo                                              | Padrão     | Descrição                                                                                                                                                                   |
 | --------------------- | ------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e ao cancelar.                                                                                       |
+| `open / onOpenChange` | `boolean / (open: boolean) => void`               |            | Estado controlado do modal. `onOpenChange(false)` é chamado no sucesso e, quando não há `onCancel` próprio, ao cancelar.                                                                                       |
 | `title`               | `string`                                          |            | Nome da tarefa exibido no cabeçalho.                                                                                                                                        |
 | `intro`               | `ReactNode`                                       |            | Contexto relevante no início do corpo, como texto ou `Alert`.                                                                                                               |
 | `submitLabel`         | `string`                                          | `'Salvar'` | Resultado da ação principal. Preserve o padrão em criação e edição comuns; sobrescreva apenas quando a operação tiver outro efeito, como `Renomear` ou `Criar nova versão`. |
-| `…ActionFormProps`    | `action, defaultValues, onSuccess, fieldOptions…` |            | Demais propriedades repassadas ao `ActionForm` interno.                                                                                                                     |
+| `footerDistribution`  | `'content' \| 'equal'`                            | `'content'` | Mantém a largura das ações pelo conteúdo ou divide a faixa igualmente. |
+| `cancelVariant`       | `'ghost' \| 'outline'`                            | `'ghost'`; `'outline'` com `equal` | Tratamento do `Cancelar`. O valor explícito vence o default derivado de `footerDistribution`. |
+| `onCancel`            | `() => void`                                      | fecha o modal | Substitui o fechamento padrão do `Cancelar`; nesse caso, o consumidor decide quando chamar `onOpenChange(false)`. |
+| `onSuccess`           | `(data: TData) => void`                           |            | Executado depois do sucesso, antes de o componente fechar o modal. |
+| `…ActionFormProps`    | `action, defaultValues, fieldOptions…`            |            | Demais propriedades repassadas ao `ActionForm` interno. `className`, `body` e `footer` não são repassadas: o wrapper as substitui para montar o corpo rolável e o footer do modal. |

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

@@ -34,7 +34,8 @@ invalidação continuam sob responsabilidade de `ActionForm`.
 
 ## Valores iniciais e rótulos
 
-`defaultValues` preenche o formulário para edição. `submitLabel` e `cancelLabel` nomeiam as ações;
+`defaultValues` preenche o formulário para edição. Criação e edição comuns mantêm o rótulo padrão
+`Salvar`; use `submitLabel` somente quando a operação pedir outro verbo, como `Renomear`.
 `onCancel` devolve ao consumidor a decisão de fechar um painel ou navegar para outra página.
 
 ```tsx preview col md
@@ -42,7 +43,6 @@ invalidação continuam sob responsabilidade de `ActionForm`.
   <ActionForm
     action={docWorkspaceCreate}
     defaultValues={{ name: "Empresa X", status: "active" }}
-    submitLabel="Atualizar"
     onCancel={() => undefined}
   />
 </DocBrowserActionProvider>
@@ -50,10 +50,11 @@ invalidação continuam sob responsabilidade de `ActionForm`.
 
 ## Formulário modal
 
-`ActionFormDialog` acrescenta a moldura, o corpo rolável e o footer ao formulário. Por padrão, as
+[`ActionFormDialog`](/ui/action-form-dialog) acrescenta a moldura, o corpo rolável e o footer ao formulário. Por padrão, as
 ações ficam alinhadas no fim da faixa e preservam a largura do conteúdo; `Cancelar` usa `ghost`.
 Use `footerDistribution="equal"` somente quando as duas decisões precisarem do mesmo peso visual.
 Nesse caso, o cancelamento muda para `outline`, salvo escolha explícita em `cancelVariant`.
+As propriedades do wrapper estão documentadas na página dele.
 
 ## Pré-requisitos
 
@@ -82,7 +83,9 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | `action`                                               | `FormContract<TInput, TData>`                         |                                   | O contrato da FormAction — dele saem campos (input Zod + fields), mensagens e invalidação de cache.                                                                                     |
 | `defaultValues`                                        | `Partial<TInput>`                                     |                                   | Valores iniciais — o modo edição de um update/patch.                                                                                                                                    |
 | `onSuccess`                                            | `(data: TData) => void`                               |                                   | Pós-sucesso (o toast e a invalidação de cache já aconteceram).                                                                                                                          |
-| `submitLabel / cancelLabel / cancelVariant / onCancel` | `string / string / 'ghost' \| 'outline' / () => void` | `'Salvar' / 'Cancelar' / 'ghost'` | Rodapé do form — o Cancelar só aparece com onCancel. Use `outline` quando ele dividir o footer com a ação principal.                                                                    |
+| `submitLabel / cancelLabel / cancelVariant / onCancel` | `string / string / 'ghost' \| 'outline' / () => void` | `'Salvar' / 'Cancelar' / 'ghost'` | Rodapé do form — o Cancelar só aparece com onCancel. Fora de um modal, mantenha `ghost`; o `ActionFormDialog` usa `outline` somente com `footerDistribution="equal"`.                                                                    |
+| `disabled`                                             | `boolean`                                             | `false`                           | Bloqueia campos e ações sem desmontar o formulário. |
+| `onLoadingChange`                                      | `(loading: boolean) => void`                          |                                   | Informa início e fim da execução a quem coordena ações como um grupo. |
 | `fieldOptions`                                         | `Record<string, SelectOption[]>`                      |                                   | Opções de runtime por campo (ex.: ids de skills) — sobrepõe as inferidas do z.enum.                                                                                                     |
 | `className / body / footer`                            | `string / (node) => node / (node) => node`            |                                   | className = classes do `<form>`. body/footer = slots: recebem os campos / os botões e escolhem o invólucro — é como o ActionFormDialog injeta DialogBody/DialogFooter (scroll + faixa). |
 | `children`                                             | `ReactNode`                                           |                                   | Modo composição: diagrame com `<ActionFormField name />`. Sem children, o automático monta todos os campos na ordem do contrato.                                                        |
@@ -95,18 +98,6 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | `options`   | `SelectOption[]` | Opções por id de runtime — sobrepõe o fieldOptions do form e o z.enum.         |
 | `className` | `string`         | Classes do invólucro (ex.: `col-span-2` em uma grid).                          |
 
-## Propriedades de ActionFormDialog
-
-Além das propriedades de `ActionForm`, o wrapper modal aceita:
-
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `open` | `boolean` | | Estado visível do diálogo. |
-| `onOpenChange` | `(open: boolean) => void` | | Recebe abertura e fechamento. |
-| `title` | `string` | | Nomeia a tarefa modal. |
-| `intro` | `ReactNode` | | Contexto relevante apresentado antes dos campos. |
-| `footerDistribution` | `'content' \| 'equal'` | `'content'` | Mantém a largura das ações pelo conteúdo ou divide a faixa igualmente. |
-
 ## Ajuda na label
 
 `FieldSpec.help` aparece como um ícone junto à label, com o texto num tooltip. Escreva ali o

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

@@ -18,9 +18,7 @@ render(
       onOpenChange={setOpen}
       title="Workspaces"
       actions={
-        <Button size="sm" variant="outline">
-          <Plus /> Workspace
-        </Button>
+        <Button>Criar workspace</Button>
       }
       emptyMessage="Nenhum workspace."
     >
@@ -65,14 +63,14 @@ corpo do modal.
 
 | Propriedade                                | Tipo                                | Padrão               | Descrição                                                                                         |
 | ------------------------------------------ | ----------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
-| `action / input`                           | `ListAction / TInput`               |                      | O contrato e os filtros — mudou o input, re-busca; `invalidates` de forms/triggers refaz sozinho. |
+| `action / input`                           | `ListAction / TInput`               | `input`: `{}`        | O contrato e o escopo base opcional da consulta — mudou o input, re-busca; `invalidates` de forms/triggers refaz sozinho. |
 | `open / onOpenChange`                      | `boolean / (open) => void`          |                      | Controle do modal — de quem orquestra.                                                            |
 | `title`                                    | `string`                            |                      | Nome da lista exibido no cabeçalho fixo.                                                          |
 | `intro`                                    | `ReactNode`                         |                      | Contexto relevante no início do corpo, como texto ou `Alert`.                                     |
 | `children`                                 | `(items, refetch) => ReactNode`     |                      | O layout dos itens (cards/linhas) — os estados já saíram daqui.                                   |
-| `note`                                     | `ReactNode \| (items) => ReactNode` | `"N no total"`       | Nota à esquerda da toolbar — o default é derivado dos itens.                                      |
+| `note`                                     | `ReactNode`                         |                      | Contexto curto à esquerda da toolbar. O total de itens já aparece no rodapé do `ActionList`.      |
 | `actions`                                  | `ReactNode`                         |                      | Ação à direita da toolbar — em geral o botão de criar.                                            |
 | `empty`                                    | `(items) => boolean`                | `items.length === 0` | Sobrepõe o vazio derivado.                                                                        |
 | `loading`                                  | `boolean`                           |                      | Carga extra agregada à do fetch (query irmã).                                                     |
-| `emptyMessage / errorMessage / retryLabel` | `string`                            |                      | Textos dos estados; `retryLabel` nomeia a ação somente com ícone e seu tooltip.                   |
+| `emptyMessage / errorMessage / retryLabel` | `string`                            | `'Nenhum resultado.'` / `'Não foi possível carregar.'` / `'Tentar de novo'` | Textos dos estados, herdados do `ActionList`; `retryLabel` nomeia a ação somente com ícone e seu tooltip. |
 | `className`                                | `string`                            | `max-w-3xl`          | Largura do DialogContent.                                                                         |

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

@@ -64,6 +64,44 @@ Seletores inline mantêm largura previsível (`w-40`; lookup e múltiplo usam `w
 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.
 
+## Onde cada filtro aparece
+
+Cada filtro declara `placement`. `inline`, o padrão, mantém o controle na barra; `advanced` o leva
+ao modal “Filtros”; `external` mantém o filtro no estado navegável e no input, mas deixa a
+apresentação para o consumidor, como cards de status acima da lista. No modal, filtros com a mesma
+`section` formam um grupo, e `advancedFilters.columns` distribui os grupos em até três colunas.
+Campos de data avançados usam calendário. A antiga `advanced: true` continua aceita durante a
+migração e equivale a `placement: 'advanced'`.
+
+```tsx
+// No contrato:
+filters: {
+  status: {
+    label: 'Status',
+    type: 'select',
+    placement: 'inline',
+    options: { kind: 'dictionary', ref: 'workspace.status' },
+  },
+  client: {
+    label: 'Cliente',
+    type: 'lookup',
+    placement: 'advanced',
+    section: 'Relacionamento',
+    options: { kind: 'lookup', source: 'client.lookup' },
+  },
+  createdAt: { label: 'Criado em', type: 'date', placement: 'advanced', section: 'Datas' },
+  stage: {
+    label: 'Estágio',
+    type: 'select',
+    placement: 'external',
+    options: { kind: 'dictionary', ref: 'workspace.stage' },
+  },
+}
+
+// Na tela:
+<ActionList action={workspaceList} input={{}} advancedFilters={{ columns: 2 }} />
+```
+
 ## Colunas de dicionário
 
 Quando o campo de saída usa `t.dict().zod()`, a coluna apresenta o valor com `DictionaryValue` e
@@ -305,11 +343,11 @@ render(
 
 | 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.             |
+| `columns` | `{ key, label, type?, sortable?, fit?, hidden?, dateFormat?, dictionary?, empty? }` — a tabela. `hidden` nasce oculta e pode ser exibida pelo seletor de colunas; `dictionary` nomeia o dicionário do provider; `empty` dá o significado da ausência.             |
 | `filters` | `{ [nome]: { label, type, options?, multiple?, placement?, section?, depends?, … } }` — a toolbar. `placement` classifica o controle como `inline`, `advanced` ou `external`; filtros avançados com `section` são agrupados no diálogo; `external` mantém estado e input, mas delega a apresentação ao consumidor. `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.                                                                                                                        |
+| `periods` | `{ value, label, default? }[]` — o controle de período (presets + Personalizado com calendário); `default: true` marca o preset inicial, senão vale o primeiro; materializa em `from`/`to` no input.                                                                                                                        |
 
 ## useListAction
 
@@ -323,17 +361,21 @@ chamar a action.
 
 | Propriedade             | Tipo                                  | Padrão                         | Descrição                                                                                                                                                                    |
 | ----------------------- | ------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `action`                | `ListAction<TInput, TItem>`           |                                | A ListAction do Opus (kind list, output = item, paginate cursor).                                                                                                            |
+| `action`                | `ListAction<TInput, TItem>`           |                                | A ListAction do Opus (kind list, output = item). A paginação envia `limit`/`page` e usa o `total` devolvido.                                                                                                            |
 | `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 para os filtros select/lookup (chave = nome do filtro).                                                                                                    |
 | `advancedFilters`       | `{ columns?: 1 \| 2 \| 3 }`         | `{ columns: 1 }`               | Define as colunas dos grupos de filtros avançados; o Opus deriva a largura correspondente do diálogo.                                                                       |
+| `views`                 | `Record<string, ActionListView<TItem>>` |                         | Visualizações alternativas `{ label, icon?, render }`; o seletor alterna entre a tabela e estas. |
+| `beforeContent`         | `ReactNode`                           |                                | Conteúdo entre a toolbar e o corpo, como um resumo que reage ao recorte atual. |
 | `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.                                                                                               |
-| `batch`                 | `ActionListBatchAction[]`             |                                | Ações em lote: `{ label, can?, run, confirm?, destructive? }` — liga a multi-seleção.                                                                                        |
+| `batch`                 | `ActionListBatchAction[]`             |                                | Ações em lote: `{ label, can?, run, confirm?: { title, message? }, destructive? }` — liga a multi-seleção.                                                                                        |
 | `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.                                                                                                       |
+| `empty`                 | `(items) => boolean`                  | `items.length === 0`           | Sobrepõe o vazio derivado, por exemplo quando um formulário inline aberto conta como conteúdo. |
+| `loading`               | `boolean`                             |                                | Carga extra agregada à da consulta, como uma query irmã de que os `children` dependem. |
 | `emptyMessage`          | `string`                              | `'Nenhum resultado.'`          | Frase do estado vazio (o `Empty` do `DataState`).                                                                                                                            |
 | `errorMessage`          | `string`                              | `'Não foi possível carregar.'` | Título do aviso de erro; a ação de tentar de novo refaz a consulta.                                                                                                          |
 | `retryLabel`            | `string`                              | `'Tentar de novo'`             | Nome acessível e tooltip da ação de recuperação.                                                                                                                             |

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

@@ -2,7 +2,8 @@
 
 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`.
+um toast. O rótulo padrão vem de `action.label` quando ele é texto; se o label for uma referência
+de tradução ou estiver ausente, o botão usa `action.name`.
 
 ```tsx preview
 <DocBrowserActionProvider>
@@ -58,7 +59,8 @@ não aciona o item clicável ao redor. `itemLabel` identifica o registro na mens
 ## Erro que a pessoa entende
 
 Quando a action falha, uma mensagem do servidor substitui o texto genérico somente nos erros de
-negócio `conflict`, `validation` e `not_found`:
+negócio `conflict`, `validation` e `not_found`, e nos erros de acesso `authorization` e
+`authentication`, cuja frase o runtime já entrega em pt-BR:
 
 > Este agente tem 3 conversas — desabilite em vez de excluir.
 
@@ -78,10 +80,12 @@ um atalho, um arrastar, um item de menu.
 |---|---|---|---|
 | `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 }. |
-| `label` | `string` | `action.label` | Sobrepõe o texto do botão. |
-| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `icon-xs` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando a action é `destructive`, senão a prop `context` do gatilho (ou `primary`). |
-| `confirm` | `{ title, description?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
+| `label` | `string` | `action.label` quando é texto; senão `action.name` | Sobrepõe o texto do botão. |
+| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `default`, ou `icon-xs` com `icon` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando a action é `destructive`, senão a prop `context` do gatilho (ou `primary`). |
+| `confirm` | `{ title, body?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
+| `disabled` | `boolean` | `false` | Desabilita o botão independentemente da execução em andamento. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
+| `onLoadingChange` | `(loading: boolean) => void` | | Informa início e fim da execução a quem coordena bloqueio entre várias actions. |
 | `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. O tamanho vem de `size` (escala única); com `icon`, o default é `icon-xs`. |

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

@@ -1,6 +1,6 @@
 ## Carregar um recurso
 
-Use `ActionView` para carregar um recurso por uma `ViewAction` e manter carregamento, erro e vazio no
+Use `ActionView` para carregar um recurso por uma `ViewAction` e manter carregamento e erro 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.
 
@@ -12,7 +12,7 @@ render(
     <div className="w-full space-y-3">
       <div className="flex flex-wrap gap-2">
         <Button variant="outline" size="sm" onClick={() => setId('empresa-x')}>Empresa X</Button>
-        <Button variant="outline" size="sm" onClick={() => setId('softize-multica')}>Softize · Multica</Button>
+        <Button variant="outline" size="sm" onClick={() => setId('empresa-y')}>Empresa Y</Button>
         <Button variant="outline" size="sm" onClick={() => setId('sessao-fantasma')}>Inexistente (erro)</Button>
       </div>
       <div className="rounded-lg border border-border p-4">
@@ -21,7 +21,7 @@ render(
             <div className="space-y-1.5">
               <div className="flex items-center gap-2">
                 <h3 className="text-sm font-semibold">{ws.name}</h3>
-                <Badge context={ws.status === 'active' ? 'success' : 'warning'}>{ws.status}</Badge>
+                <DictionaryValue dict={docWorkspaceStatus} value={ws.status} />
               </div>
               <p className="text-sm text-muted-foreground">
                 Cliente {ws.client} · {ws.agents} agentes vinculados.
@@ -35,6 +35,10 @@ render(
 )
 ```
 
+O handler da view deve devolver um valor. Uma consulta que resolve `undefined` é tratada como erro
+pelo react-query, então `ActionView` apresenta o estado de erro, não um vazio. Represente um recurso
+ausente com o erro `not_found`, cuja frase aparece para a pessoa.
+
 ## useViewAction
 
 `ActionView` é uma composição sobre `useViewAction(action, input)`, que devolve `data`, `error`,
@@ -45,11 +49,11 @@ mais de uma região da tela ou quando o carregamento precisa ser orquestrado por
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `action` | `ViewAction<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
+| `action` | `ViewContract<TInput, TData>` | | A ViewAction do Opus (kind view, 1 recurso). |
 | `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
-| `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. |
+| `children` | `(data: TData, refetch) => ReactNode` | | Obrigatório, salvo quando `render` é informado. 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. Sem nenhum dos dois, o componente lança erro. |
 | `loading` | `ReactNode \| boolean` | `3 skeletons` | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega. |
-| `empty` | `ReactNode` | `emptyMessage` ou nada | Sobrescreve o estado vazio (200 sem dado). |
-| `emptyMessage` | `string` | | Atalho do vazio: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida). |
+| `empty` | `ReactNode` | `emptyMessage` ou nada | Estado reservado a `data` indefinido. Como o react-query converte esse resultado em erro, ele não aparece na prática; devolva um valor ou o erro `not_found`. |
+| `emptyMessage` | `string` | | Atalho do vazio, sujeito à mesma limitação de `empty`: a frase na mesma superfície de `DataState` (`Empty` com moldura sólida). |
 | `error` | `(err, retry) => ReactNode` | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |

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

@@ -37,8 +37,9 @@ export const workspaceListContract = defineContract({
 
 ```ts
 // api/ — server-only. bindAction amarra o handler no contrato compartilhado.
+import { randomUUID } from 'node:crypto'
 import { bindAction } from '@softize/opus/core'
-import { workspaceCreateContract } from '@app/shared' // o mesmo contrato do bloco acima
+import { workspaceCreateContract } from '@app/shared' // contrato `form`, declarado no shared/ como o acima
 
 export const workspaceCreate = bindAction(workspaceCreateContract, {
   handler: async (ctx, input) => {
@@ -81,16 +82,20 @@ 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)):
 
 ```ts
+import { entityRowSchema } from '@softize/opus/schema'
 import { fake, fakeMany } from '@softize/opus/testing'
 
+// `defineEntity` devolve o próprio config; o schema da linha vem de `entityRowSchema`.
+const eventRowSchema = entityRowSchema(EventEntity)
+
 export const eventGet = defineContract({
   name: 'event.get',
   kind: 'view',
   input: z.object({ id: z.string().uuid() }),
-  output: EventEntity.zod(),
-  mockHandler: () => fake(EventEntity.zod()), // 1 evento fake
+  output: eventRowSchema,
+  mockHandler: () => fake(eventRowSchema), // 1 evento fake
 })
-// listas: `mockHandler: () => fakeMany(EventEntity.zod(), 20)`
+// listas: `mockHandler: () => fakeMany(eventRowSchema, 20)`
 
 // o handoff, depois, só pluga o real — mesmo contrato:
 export const eventGetImpl = bindAction(eventGet, { handler: async (ctx, input) => { /* db */ } })
@@ -103,12 +108,27 @@ qualquer `server.proxy` para backend externo desligado (prefixo ex-proxy sem cob
 503 em envelope — nada vaza para prod). A SPA chama `/api` normal e recebe o dado fake, isolado:
 
 ```ts
-// vite.config.ts
-import { opusDesign } from '@softize/opus/vite'
-export default defineConfig({ plugins: [react(), opusDesign()] })
-// sobe com: vite --mode design
+// vite.config.ts — o plugin só carrega no modo design, por import dinâmico.
+const DESIGN_RUN =
+  process.argv.includes('--mode=design') ||
+  process.argv.some((arg, i) => (arg === '--mode' || arg === '-m') && process.argv[i + 1] === 'design')
+
+async function designPlugin(): Promise<PluginOption> {
+  const { opusDesign } = await import('@softize/opus/vite')
+  return opusDesign()
+}
+
+const designPlugins: PluginOption[] = DESIGN_RUN ? [await designPlugin()] : []
+
+export default defineConfig({ plugins: [react(), ...designPlugins] })
+// sobe com: vite --mode design --configLoader runner (script dev:design do template)
 ```
 
+O import fica dinâmico e condicionado porque o Opus publica TypeScript: o carregador padrão de
+config do Vite externaliza um import estático, e o Node 22+ recusa type stripping dentro de
+`node_modules` (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). Com `--configLoader runner`, o Vite
+transforma o TypeScript antes de avaliar o plugin. O app criado por `opus create` já traz esse arranjo.
+
 O `entry` (default `./opus.config.ts`) também aceita **glob** — `opusDesign({ entry:
 'src/domains/*/contract.ts' })` — re-expandido a cada rebuild: **domínio novo entra no ar ao
 salvar o arquivo**, sem editar entry nem reiniciar o dev server (criar o arquivo já invalida o
@@ -128,12 +148,15 @@ descartável — vira o contrato que o backend honra.
 > action inteira a partir do contrato — o spec é a fonte, o pattern é o renderizador.
 
 ```tsx
-import { useLookupAction } from '@softize/opus/client'
-import { ActionForm } from '@softize/opus/ui/react'
+import { ActionForm, useListAction } from '@softize/opus/ui/react'
 
-// O contrato mantém a lista paginada tipada sem exigir uma definição paralela.
-const { rows, fetchNextPage } = useLookupAction(workspaceListContract)
+// Lista declarativa: busca ao montar e refaz quando uma action invalida `workspace.list`.
+const { items, total, isLoading } = useListAction<WorkspaceRow>(workspaceListContract, { q })
 
 // Form contract-driven: os campos (fields) moram NO contrato.
-<ActionForm contract={workspaceCreateContract} onSuccess={…} />
+<ActionForm action={workspaceCreateContract} onSuccess={…} />
 ```
+
+`useListAction` exige `OpusProvider` e um `QueryClientProvider` acima da árvore. Para buscar sob demanda, como num
+autocomplete, use `useLookupAction`: ele não busca ao montar, expõe `run(input)` e `reset()` e
+devolve `items`, `cursor`, `total` e os estados da última execução.

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

@@ -5,7 +5,7 @@ title: IA generativa
 # IA generativa
 
 > **Experimental.** Superfície mínima — cresce por reincidência de caso real, não por
-> especulação (streaming e memória longa de conversa entram quando um caso real cobrar).
+> especulação (memória longa de conversa entra quando um caso real cobrar).
 
 Três coisas: **completar** texto, **extrair** dado estruturado, e **rodar um agente** sobre
 as actions do app. O contrato é um adapter do core (`AiAdapter`). O diferencial do `extract`
@@ -20,7 +20,9 @@ interface AiAdapter {
   complete(prompt: string, opts?: AiCompleteOptions): Promise<string>
   extract<T>(prompt: string, schema: Schema<T>, opts?: AiCompleteOptions): Promise<T>
   // Loop agêntico: o modelo chama tools (as actions ai:enabled) até responder em texto.
-  run(input: string | AiMessage[], opts): Promise<AiRunResult>
+  run?(input: string | AiMessage[], opts: AiRunOptions): Promise<AiRunResult>
+  // O mesmo loop emitindo ChatEvent conforme acontece (ver Streaming, abaixo).
+  runStream?(input: string | AiMessage[], opts: AiRunOptions): AsyncIterable<ChatEvent>
 }
 // opts: { system?, model?, maxTokens?, temperature? } — tudo tem default do driver.
 ```
@@ -71,21 +73,38 @@ o modelo escolhe a tool → o runtime executa a action **como o usuário logado*
 export const buscarNotas = defineContract({
   name: 'nota.buscar',
   kind: 'list',
+  label: 'Buscar notas',
   input: z.object({ cliente: z.string(), mes: z.string() }),
-  output: z.object({ total: z.number() }),
+  output: z.object({ numero: z.string(), valor: z.number() }), // em `list`, o schema de cada item
   ai: { enabled: true, description: 'Busca notas por cliente e mês.' },
 })
 
 // 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?')
+const { text } = await ctx.ai!.run('Quais notas a Empresa X emitiu em junho?')
 // o modelo chamou nota.buscar sozinho, como o usuário logado, e respondeu em texto.
 ```
 
-O que é `destructive` ou pede `requiresConfirmation` **não roda sem aprovação**: passe
-`run(prompt, { confirm })` — o chat mostra o "confirmar?"; sem isso, a action é recusada e o
-modelo avisa. Fora do handler, `runtime.aiFor(base)` devolve o `ai` já ligado a um contexto —
+`runtime.aiTools()` projeta cada action exposta como um `AiTool`: `name` é o identificador técnico
+usado na execução e na auditoria; `title` traz a `label` legível da action, quando existe;
+`description` vem de `ai.description` (ou da `description` da action) e `inputSchema`, do input.
+`metadata.dataProducts` lista os Produtos de Dados relacionados e `metadata.dataProductLabels`
+associa cada identificador ao seu nome legível. Esses metadados servem ao host: não entram no
+prompt e não concedem acesso.
+
+O agente só executa nomes que `aiTools()` anunciou; uma chamada a outra action volta como erro
+para o modelo. Actions marcadas com `ai: { destructive: true }` ou `ai: { requiresConfirmation: true }`
+**não rodam sem aprovação**: passe `run(prompt, { confirm })` — o chat mostra o "confirmar?"; sem
+isso, a action é recusada e o modelo avisa. O gate lê somente esses dois campos de `ai`: o
+`confirm: { destructive: true }` da action configura a confirmação da UI e não protege a chamada
+feita pelo agente. Fora do handler, `runtime.aiFor(base)` devolve o `ai` já ligado a um contexto —
 o backend do chat resolve o usuário e chama `.run(historico)`.
 
+Para o modelo perguntar algo à pessoa no meio do turno, passe `onAsk` em `run` ou `runStream`. O
+driver Anthropic então oferece a tool reservada `ask_user`, entrega as perguntas (`AskQuestion[]`)
+ao seu `onAsk` e devolve as respostas (`AskAnswer[]`) ao modelo. Sem `onAsk`, uma chamada a
+`ask_user` é recusada com a orientação de perguntar em texto. Na interface, o componente
+[Ask](/ui/ask) apresenta essas perguntas e coleta as respostas.
+
 ## Streaming — o protocolo de eventos de conversa
 
 `runStream` é o mesmo loop agêntico do `run`, emitindo **`ChatEvent`** conforme acontece

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

@@ -41,7 +41,7 @@ densidade comum.
 
 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 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
+estável, mesmo quando a descrição ocupa mais linhas; o título fica limitado a uma linha. Texto solto como filho também
 vale (`<Alert>Sincronizado.</Alert>`) e se torna uma descrição.
 
 ```tsx preview col
@@ -88,8 +88,9 @@ botão só com ícone, nome acessível e tooltip.
 </Alert>
 ```
 
-Os dois modos convivem: com `title` ou `description`, `children` entra depois da mensagem e recebe a
-ação.
+A forma curta também aceita uma ação como `children`: com `title` ou `description`, esse conteúdo
+entra depois da mensagem, na posição de `AlertActions`. Não combine a forma curta com os slots
+`AlertMedia`, `AlertHeader` ou `AlertActions`; essa mistura lança erro.
 
 ```tsx preview col
 <Alert

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

@@ -1,6 +1,6 @@
-## Padrão (16/9)
+## Vídeo e preview (16/9)
 
-O `ratio` é a proporção entre largura e altura — 16/9 é o padrão de vídeo. Defina a largura no
+O `ratio` é a proporção entre largura e altura — 16/9 é o formato comum de vídeo. Defina a largura no
 contêiner (o pai): a altura o componente deriva sozinho.
 
 ```tsx preview col

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

@@ -32,7 +32,10 @@ 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 para o User.
-const jwt = jwtAuth({ secret: process.env.JWT_SECRET! })
+const jwt = jwtAuth({
+  secret: process.env.JWT_SECRET!,
+  mapUser: (payload) => ({ id: String(payload.sub), email: payload.email }),
+})
 
 // better-auth: valida a sessão contra um IdP better-auth remoto.
 const idp = betterAuthSession({
@@ -42,8 +45,10 @@ 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
+O `jwt` procura o token no `Authorization: Bearer` e depois no cookie `auth_token` (troque o nome
+com `cookieName` ou a extração inteira com `tokenExtractor`). `mapUser` é obrigatório; o `can`
+default nega tudo. O `secret` pode ser string, `Buffer` ou um resolver async, hoje chamado sem o
+`kid` do token. O `betterAuthSession` faz fetch da
 sessão no IdP (`timeoutMs`, default 5s) e mapeia para o `User`/tenant/can (o `can` default nega
 tudo — plugue o seu).
 
@@ -55,15 +60,25 @@ const runtime = createRuntime({
   auth: idp,
 })
 
-// No handler: o contexto já vem resolvido.
-handler: async (ctx, input) => {
-  if (!(await ctx.can('nota.emitir'))) throw error({ code: 'forbidden' })
-  return repo.create({ ...input, tenantId: ctx.tenantId })
-}
+// Na action: `authorize` decide antes do handler, com o contexto já resolvido.
+export const notaEmitir = bindAction(notaEmitirContract, {
+  authorize: (ctx) => ctx.can('nota.emitir'),
+  handler: async (ctx, input) => repo.create({ ...input, tenantId: ctx.tenantId }),
+})
 ```
 
-A action declara o gate no contrato (`auth: 'nota.emitir'`) e o runtime cobra antes do
-handler. Sem `auth` configurado, `ctx.user` é null.
+O runtime aplica duas barreiras antes do handler. Sem `public: true`, a action exige
+`ctx.user`; sem usuário, responde `auth.unauthenticated`. Depois, se houver `authorize`, o
+runtime o avalia: `false` vira `auth.forbidden` e um `ActionError` devolvido é lançado como está.
+`authorize` aceita uma closure, como acima, ou uma expressão da DSL avaliada contra `user`,
+`input` e os dados carregados por `loads`.
+
+Uma action sem `authorize` fica aberta a qualquer usuário autenticado. `requires` só documenta a
+permissão esperada: o runtime não o executa, e `opus check` acusa `requires` sem `authorize`.
+Quando a decisão depende de dado que só o handler conhece, verifique no próprio handler com
+`ctx.can` e lance `error({ code: 'forbidden', category: 'authorization' })`.
+Sem adapter `auth` configurado, os servidores HTTP resolvem `ctx.user` como null e só actions
+`public` executam.
 
 ## Limites (por enquanto)
 

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

@@ -57,7 +57,7 @@ para o ocioso. Tinja com className.
   <AvatarFallback>
     <Bot className="size-4" />
   </AvatarFallback>
-  <AvatarBadge className="bg-emerald-500" />
+  <AvatarBadge className="bg-context-success" />
 </Avatar>
 <Avatar>
   <AvatarFallback>RV</AvatarFallback>

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

@@ -32,8 +32,8 @@ Um svg filho ganha size-3 automaticamente — bom para reforçar o estado sem cr
 
 ## Como link (asChild)
 
-asChild renderiza o filho (Radix Slot) — um `<a>` com cara de badge, com hover próprio das
-variantes.
+asChild renderiza o filho (Radix Slot) — um `<a>` com cara de badge. O Badge não aplica estado de
+hover; acrescente-o por `className` quando o link precisar de retorno visual.
 
 ```tsx preview
 <Badge asChild context="neutral" variant="solid">

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

@@ -53,8 +53,9 @@ chevron padrão por outro glifo (aqui, uma barra).
 
 ## Colapsado
 
-Trilha funda demais para o espaço: BreadcrumbEllipsis substitui os níveis do meio (que viram um
-menu/popover) e mantém só a raiz e o destino.
+Trilha funda demais para o espaço: BreadcrumbEllipsis marca os níveis do meio omitidos e mantém só a
+raiz e o destino. A elipse é decorativa (`aria-hidden`), não um menu: os níveis ocultos deixam de ser
+alcançáveis pela trilha. Ofereça esse caminho por outro meio, como a navegação da seção.
 
 ```tsx preview col-start
 <Breadcrumb>