@softize/opus 18.0.1 → 18.1.1

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

@@ -29,6 +29,8 @@ Use a forma curta quando o aviso tiver ícone, título e uma frase. Declare `tit
 
 Título é opcional — o aviso de uma linha dispensa. O contexto continua visível por superfície,
 borda e texto; o conteúdo comunica o significado sem depender somente da cor.
+O Alert usa o corpo produtivo e `0.75rem` de padding; não reduza cada uso localmente para obter a
+densidade comum.
 
 ```tsx preview col
 <Alert description="Nenhuma sessão aberta neste repositório." />
@@ -39,7 +41,7 @@ borda e texto; o conteúdo comunica o significado sem depender somente da cor.
 
 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
@@ -86,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>

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

@@ -2,7 +2,8 @@
 
 `context` declara a hierarquia ou o risco da ação; `variant` escolhe o tratamento visual. Use
 `primary` para a ação principal, `neutral` para ações de apoio e `danger` quando a ação tiver uma
-consequência perigosa.
+consequência perigosa. A variante `outline` mantém o fundo transparente em repouso e usa uma
+superfície apenas no hover, preservando o fundo da região onde o botão está inserido.
 
 ```tsx preview
 <Button>Criar workspace</Button>
@@ -18,8 +19,9 @@ consequência perigosa.
 `size` usa a escala única dos controles: o mesmo nome tem a mesma medida em `Button`, `Select`,
 `Tabs`, `Toggle`, `Switch`, `Avatar`, `Spinner` e nos botões embutidos. Os tamanhos de texto dão a
 altura da linha; os `icon-*` são quadrados para botões só de ícone, que exigem `aria-label` porque não
-há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em `xs` e `sm`, 1rem em
-`default`, 1.25rem em `lg`), a menos que o ícone traga um `size-*` próprio.
+há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em `xs`, `sm`,
+`icon-xs`, `icon-sm` e `icon`; 1rem em `default`; 1.25rem em `lg` e `icon-lg`), a menos que o
+ícone traga um `size-*` próprio. O quadrado `icon` mantém a área de 2.25rem com o glifo discreto.
 
 | Nome      | Medida  | Uso                                                                                                                              |
 | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- |
@@ -35,8 +37,12 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 Escolha o tamanho pela região, não pela importância visual: `variant` e `context` resolvem a
 hierarquia da ação. Headers de Page e footers de Dialog/Drawer usam `default`; ações operacionais
 de seção, toolbar e coleção usam `sm`; ações dentro de linha ou célula usam `xs` ou `icon-xs`.
-Controles de chrome, como voltar e fechar, usam `icon`. Assim a mesma decisão mantém a mesma
-altura mesmo quando uma superfície troca uma ação secundária por uma primária.
+Assim a mesma decisão mantém a mesma altura mesmo quando uma superfície troca uma ação secundária
+por uma primária.
+
+O retorno de `PageBack` usa `icon`. O fechamento de Dialog e Drawer é um `CloseButton` circular
+(`shape="pill"`), `neutral` e `subtle`, no quadrado `icon-sm` por padrão, ou `icon-xs` com
+`closeSize="xs"`.
 
 ```tsx preview
 <Button size="xs">Mínimo</Button>
@@ -79,9 +85,10 @@ buttonVariants serve para o caso sem filho único.
 
 | Propriedade | Tipo                                                                                 | Padrão      | Descrição                                                                                                                                         |
 | ----------- | ------------------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `context`   | `'neutral' \| 'primary' \| 'danger'`                                                 | `'primary'` | A hierarquia ou o risco comunicado pela ação.                                                                                                     |
+| `context`   | `'neutral' \| 'primary' \| 'danger'`                                                 | `'primary'` em `solid` e `subtle`; `'neutral'` nas demais variantes | A hierarquia ou o risco comunicado pela ação. |
 | `variant`   | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'`                              | `'solid'`   | O tratamento visual aplicado ao contexto.                                                                                                         |
 | `size`      | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'default'` | A medida na escala única dos controles (tabela acima). Os `icon-*` são quadrados para botões só de ícone, com `aria-label`.                       |
+| `shape`     | `'default' \| 'pill'`                                                                 | `'default'` | Geometria do botão; `pill` arredonda as extremidades por completo. |
 | `asChild`   | `boolean`                                                                            | `false`     | Renderiza como o filho (Radix Slot) em vez de `<button>` — para âncoras e afins.                                                                  |
 | `busy`      | `boolean`                                                                            | `false`     | Ação em andamento (depois do clique): mostra Spinner + desabilita. Não é "carregando" de conteúdo (que é Spinner/Skeleton em um nível de página). |
 | `icon`      | `React.ReactNode`                                                                    |             | Ícone à esquerda, como nó (ex.: `icon={<Plus />}`); o glifo segue o `size`. No busy é trocado pelo Spinner — não soma.                            |
@@ -114,12 +121,30 @@ conectar bordas. Esse modo atende ações icon-only em barras e linhas de listag
   <Button variant="ghost" size="icon" aria-label="Exibição">
     <SlidersHorizontal />
   </Button>
-  <Button context="primary" size="icon" aria-label="Novo item">
-    <Plus />
+  <Button variant="ghost" size="icon" aria-label="Exportar">
+    <Download />
   </Button>
 </ButtonGroup>
 ```
 
+### No rodapé de Dialog e Drawer
+
+`DialogFooter` e `DrawerFooter` cuidam somente da faixa; envolva as decisões em um
+`ButtonGroup mode="spaced"`, que responde pelo agrupamento e pela distribuição. Por padrão, as
+ações preservam a largura do conteúdo e `Cancelar` usa `ghost`. Use `distribution="equal"` somente
+quando as duas decisões tiverem peso equivalente; nesse caso, `Cancelar` usa `outline`.
+
+```tsx
+<DialogFooter>
+  <ButtonGroup mode="spaced">
+    <DialogClose asChild>
+      <Button variant="ghost">Cancelar</Button>
+    </DialogClose>
+    <Button>Salvar</Button>
+  </ButtonGroup>
+</DialogFooter>
+```
+
 ### Ação dividida
 
 Combine a ação principal, um separador e um botão de ícone quando o mesmo comando oferecer

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

@@ -67,7 +67,7 @@ captionLayout=dropdown troca o título do mês por seletores de mês e ano — b
 | `locale` | `Locale` | `ptBR` | Idioma dos nomes de mês e de dia (um locale do date-fns). |
 | `labels` | `Partial<Labels>` | rótulos em pt-BR | Rótulos acessíveis da navegação e dos seletores; mescla sobre o padrão. |
 
-## CalendarDayButton
+## Personalizar o dia com CalendarDayButton
 
 Cada dia é um `CalendarDayButton` — um `Button` ghost quadrado que recebe os modificadores do
 dia (`selected`, `range-start`, `today`…). Use `components={{ DayButton: … }}` para

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

@@ -72,4 +72,4 @@ Para painel com estrutura: cada slot é dono do próprio padding (como o Dialog)
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `asChild` | `boolean` | `false` | Renderiza o filho com a superfície do Card (ex.: um `<button>` clicável inteiro). |
-| `className` | `string` | | Compõe sobre a superfície; os slots (`CardHeader`, `CardBody`, `CardContent`, `CardFooter`, `CardAction`) são donos do próprio padding. |
+| `className` | `string` | | Compõe sobre a superfície; os slots (`CardHeader`, `CardBody`, `CardFooter`, `CardAction`) são donos do próprio padding. `CardContent` é alias depreciado de `CardBody`. |

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

@@ -79,12 +79,23 @@ orientation=vertical empilha os slides; as setas migram para cima e para baixo (
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Eixo do deslocamento. No modo vertical, os slides são empilhados e as setas apontam para cima e para baixo. |
-| `opts` | `CarouselOptions` | | Opções repassadas ao Embla, como `{ loop: true }` ou `{ align: 'start' }`. |
-| `setApi` | `(api: CarouselApi) => void` | | Recebe a instância para controle externo, como navegar com `scrollTo` ou ler o slide ativo. |
-| `plugins` | `CarouselPlugin[]` | | Plugins do Embla associados ao carrossel, como autoplay. |
+| `opts` | `EmblaOptionsType` | | Opções repassadas ao Embla, como `{ loop: true }` ou `{ align: 'start' }`. O Opus não reexporta esse tipo; para nomeá-lo sem depender de `embla-carousel`, use `React.ComponentProps<typeof Carousel>['opts']`. |
+| `setApi` | `(api: EmblaCarouselType \| undefined) => void` | | Recebe a instância do Embla para controle externo, como navegar com `scrollTo` ou ler o slide ativo. |
+| `plugins` | `EmblaPluginType[]` | | Plugins do Embla associados ao carrossel, como autoplay. |
 
 ## Propriedades de CarouselItem
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `className` | `string` | | Classes de dimensão; a base define quantos slides cabem na área visível. |
+
+## Propriedades de CarouselPrevious e CarouselNext
+
+Além das props abaixo, as setas aceitam as props de `Button`. O nome acessível já vem pronto:
+“Slide anterior” e “Próximo slide”. O clique e o estado desabilitado acompanham a posição do trilho.
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `ButtonProps['variant']` | `'outline'` | Tratamento visual da seta. |
+| `size` | `ButtonProps['size']` | `'icon'` | Escala do botão. A seta aplica `size-8 rounded-full` por cima da escala, então o círculo mede 2rem; use `className` para outra medida. |
+| `className` | `string` | | Classes adicionais, como ajustar a posição fora do trilho. |

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

@@ -58,7 +58,7 @@ async function chatRoute(req) {
 <Chat send={async (messages) => (await api.post('/chat', { messages })).reply} />
 ```
 
-O modelo só faz o que o usuário pode (`ctx.can`); o que é destrutivo pede `confirm`. Para expor as actions ao agente, marque-as com `ai: { enabled: true }` no contrato — ver o recurso **IA generativa**.
+O agente só executa actions marcadas com `ai.enabled` e, nelas, aplica o `authorize` com o contexto do usuário; uma action sem `authorize` fica aberta a qualquer usuário autenticado. Actions com `ai.destructive` ou `ai.requiresConfirmation` são recusadas nesse exemplo, porque ele não passa `confirm`; para aprovar essas chamadas, use `run(messages, { confirm })`. Para expor as actions ao agente, marque-as com `ai: { enabled: true }` no contrato — ver o recurso **IA generativa**.
 
 ## Streaming — eventos de conversa
 

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

@@ -20,9 +20,11 @@ opus db check         # drift entidade ↔ banco (read-only)
 opus seed check       # bindings, dependências, ciclos e scripts paralelos de seed
 ```
 
-`opus check` lê o source sem executar nada e aplica nove regras: cinco sobre as actions
-(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`) e quatro sobre a UI
-(`ui-structure`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`). Um projeto
+`opus check` lê o source sem executar nada e aplica regras em três grupos: actions
+(`action-name`, `kind`, `field-order`, `export`, `requires-sem-authorize`), UI
+(`ui-structure`, `ui-semantic-api`, `removed-ui-token`, `unpaired-ui-surface`) e Produtos de Dados
+(`data-product-export`, `-id`, `-duplicate`, `-version`, `-interfaces`, `-interface`, `-entities`
+e `-entity`, todas com o prefixo `data-product`). Um projeto
 marcado com `opus.json` e ainda sem actions passa vacuamente; sem o marcador, zero actions
 falha, porque um gate vazio não é aprovação. `opus check --help` descreve cada regra.
 
@@ -43,15 +45,19 @@ opus pre-push materialization  # só a freshness dos artefatos materializados
 ## Seeds de desenvolvimento e teste
 
 > Seeds registrados no `opus.config.ts` têm perfis, métricas e escopos explícitos. Listagem e gate
-> não abrem o banco; planejamento, aplicação e verificação são bloqueados em produção.
+> não abrem o banco; planejamento, aplicação e verificação só conectam com
+> `NODE_ENV=development` ou `NODE_ENV=test`.
 
 ```bash
 opus seed list
-opus seed plan customers.scenarios --profile smoke --scope local
-opus seed apply customers.scenarios --profile smoke --scope local
-opus seed verify customers.scenarios --profile smoke --scope local
+NODE_ENV=development opus seed plan customers.scenarios --profile smoke --scope local
+NODE_ENV=development opus seed apply customers.scenarios --profile smoke --scope local
+NODE_ENV=development opus seed verify customers.scenarios --profile smoke --scope local
 ```
 
+Com qualquer outro valor de `NODE_ENV`, inclusive ausente, esses três comandos falham antes de
+abrir a conexão. O escopo informado também precisa constar em `safety.scopes` do seed.
+
 `--profile` escolhe o perfil (default: o `defaultProfile` do seed) e `--scope` declara o escopo
 dos dados (a variável `OPUS_SEED_SCOPE` é a alternativa). `--json` devolve o resultado
 estruturado, inclusive em caso de erro. `apply` converge quando repetido; não há reset ou

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

@@ -49,14 +49,36 @@ render(
 )
 ```
 
+## Propriedades de Command
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `shouldFilter` | `boolean` | `true` | Com `false`, desliga a filtragem e a ordenação automáticas; o aplicativo passa a renderizar somente os itens que correspondem à busca. |
+| `filter` | `(value: string, search: string, keywords?: string[]) => number` | | Pontua cada item para a busca atual, de `0` (oculto) a `1` (melhor resultado). |
+| `value` | `string` | | Item destacado no modo controlado. |
+| `onValueChange` | `(value: string) => void` | | Chamado quando o item destacado muda. |
+| `loop` | `boolean` | `false` | Faz as setas voltarem ao início ou ao fim da lista. |
+| `label` | `string` | | Nome acessível do menu, sem exibição visual. |
+| `className` | `string` | | Classes adicionais aplicadas à raiz. |
+
+## Propriedades de CommandInput
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `placeholder` | `string` | | Texto exibido enquanto a busca está vazia. |
+| `value` | `string` | | Texto da busca no modo controlado. |
+| `onValueChange` | `(search: string) => void` | | Chamado quando o texto da busca muda. |
+| `disabled` | `boolean` | `false` | Desabilita o campo de busca. |
+| `className` | `string` | | Classes adicionais aplicadas ao campo; o ícone de busca fica no wrapper. |
+
 ## Propriedades de CommandDialog
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `open` | `boolean` | | Estado do modal no modo controlado. |
 | `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado do modal; pode ser conectado ao atalho do aplicativo. |
-| `title` | `string` | `'Comandos'` | Nome acessível do diálogo, disponível para leitura assistiva. |
-| `description` | `string` | `'Busque um comando para executar.'` | Descrição acessível do diálogo. |
+| `title` | `string` | `'Paleta de comandos'` | Título exibido no header compacto; também nomeia o diálogo para tecnologias assistivas. |
+| `description` | `string` | `'Busque um comando para executar…'` | Descrição disponível somente para tecnologias assistivas. |
 | `showCloseButton` | `boolean` | `true` | Exibe o botão de fechamento. |
 
 ## Propriedades de CommandItem
@@ -64,3 +86,13 @@ render(
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `onSelect` | `(value: string) => void` | | Chamado ao selecionar o item por clique ou teclado. |
+| `value` | `string` | | Valor estável usado na busca e no destaque. Sem ele, o valor é inferido do texto do item. |
+| `keywords` | `string[]` | | Termos adicionais considerados na busca. |
+| `disabled` | `boolean` | `false` | Impede a seleção do item. |
+
+## Propriedades de CommandGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `heading` | `React.ReactNode` | | Título exibido acima dos itens do grupo. |
+| `value` | `string` | | Identificador do grupo; obrigatório e único quando não há `heading`. |

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

@@ -1,6 +1,6 @@
 ## Envio de texto
 
-A caixa de escrever da casa: textarea em uma pílula elevada (`rounded-xl` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/components/chat) extraído — use sozinho quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse dono consuma **↑/↓**; sem eles, as setas mantêm o comportamento nativo da textarea.
+A caixa de escrever da casa: textarea em uma pílula elevada (`rounded-xl` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/ui/chat) extraído — use sozinho quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse dono consuma **↑/↓**; sem eles, as setas mantêm o comportamento nativo da textarea.
 
 ```tsx preview col
 const [text, setText] = React.useState('')

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

@@ -14,7 +14,7 @@ render(
     actions={<Button variant="outline">Encerrar outras sessões</Button>}
   >
     <div className="rounded-lg border border-border p-4">
-      MacBook Para o · ativo agora
+      MacBook Pro · ativo agora
     </div>
   </Content>,
 );
@@ -40,7 +40,7 @@ render(
     </ContentHeader>
     <ContentBody>
       <div className="rounded-lg border border-border p-4">
-        MacBook Para o · ativo agora
+        MacBook Pro · ativo agora
       </div>
     </ContentBody>
   </Content>,
@@ -57,7 +57,8 @@ Quando a região principal da página é uma coleção, `Content` nomeia e gover
 `ContentActions`. Busca, filtros, atualização e operações dependentes do recorte atual permanecem na
 toolbar da lista. Essa divisão aproxima cada comando do objeto que ele afeta sem criar uma família
 paralela de componentes `List*`. Na variante `page`, as ações ficam no extremo oposto ao título. A
-criação usa um botão textual `default`, sem ícone, nomeado `Criar recurso`; o diálogo aberto pelo
+criação usa um `Button` textual na variante padrão (`solid`) e no tamanho `default`, sem ícone,
+nomeado `Criar recurso`; o diálogo aberto pelo
 gatilho repete esse título e a edição usa `Editar recurso`.
 
 ## Propriedades de Content
@@ -68,7 +69,7 @@ gatilho repete esse título e a edição usa `Editar recurso`.
 | `count`       | `number`                     |             | Forma curta: total de itens ao lado do título da região.                                                 |
 | `description` | `ReactNode`                  |             | Forma curta: frase de apoio sob o título.                                                                |
 | `actions`     | `ReactNode`                  |             | Forma curta: ações sobre a região inteira; em `page`, ficam no extremo oposto ao título.                 |
-| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | herdado     | Nível semântico do heading, independente do destaque visual.                                             |
+| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2`         | Nível semântico do heading, independente do destaque visual.                                             |
 | `variant`     | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície. |
 
 Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e

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

@@ -33,6 +33,16 @@ Quando o produto precisa de outra densidade, declare essa escolha no CSS do app.
 `html { font-size: 93.75%; }` conserva a proporção que uma raiz de 15 teria sobre a base usual
 de 16, sem transformar esse valor em uma regra da biblioteca.
 
+## Layout desktop
+
+O Opus oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
+Classes de tamanho, como `size="sm"`, escolhem a densidade do componente; não representam
+breakpoints. Overflow e limites contra a janela continuam protegendo o conteúdo.
+
+Não adicione uma adaptação isolada por viewport ou container em `className`. Uma futura
+responsividade precisa começar pelo shell e formar um contrato comum para navegação, splits,
+tabelas e componentes.
+
 ## 2 · className em tudo
 
 > Todo componente termina em `cn(base, className)` com tailwind-merge: o utilitário do consumidor
@@ -41,7 +51,7 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 ```tsx
 <Button className="w-full">Continuar</Button>
 <Card className="max-w-sm" />
-<DialogContent className="sm:max-w-2xl" />
+<DialogContent className="max-w-2xl" />
 ```
 
 ## 3 · Recomposição estrutural
@@ -106,7 +116,7 @@ const [open, setOpen] = useState(false)
 
 ## O limite — de propósito
 
-> O look curado não é customizável no app: rodapé-faixa do dialog, elevação no dark, `active:scale`
+> O look curado não é customizável no app: rodapé-faixa do dialog, elevação no dark, `active:brightness-90`
 > do botão, a seta do tooltip — é identidade da casa, igual em todo projeto.
 
 ```tsx preview