@softize/opus 18.5.0 → 20.0.0

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

@@ -1,10 +1,15 @@
 ## Forma curta
 
+Use `Alert` para manter uma informação visível no contexto da página até que ela deixe de valer.
+Para confirmar o resultado de uma ação que a pessoa acabou de fazer, sem ocupar espaço na página,
+use [`toast`](/ui/toast). Para o erro ou o vazio de uma consulta, use
+[`DataState`](/ui/data-state), que já monta o `Alert` de erro com a ação de recuperação.
+
 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"`.
+`icon`; o componente monta os slots e escolhe o papel acessível pelo `context`.
 
 ```tsx preview col
-<Alert icon={<Info />} title="Opus 2.8.0" description="Este workspace usa a versão pinada em opus.json." />
+<Alert icon={<Info />} title="Versão fixada" description="Este workspace usa a versão do Opus declarada em opus.json." />
 <Alert
   context="danger"
   icon={<CircleAlert />}
@@ -25,12 +30,18 @@ Use a forma curta quando o aviso tiver ícone, título e uma frase. Declare `tit
 />
 ```
 
+O `context` também decide como leitores de tela anunciam o aviso. Em `danger` e `warning`, o
+`Alert` usa `role="alert"`: o anúncio interrompe o que a pessoa estiver ouvindo, porque o aviso pede
+atenção imediata. Em `neutral`, `info` e `success`, usa `role="status"`: o anúncio espera a leitura
+em curso terminar. Para outro comportamento, passe `role` ao componente; o valor informado substitui
+o padrão do contexto.
+
 ## Só a frase
 
 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.
+O `Alert` usa o texto de corpo das telas de operação (`text-sm`) e `0.75rem` de recuo interno; essa
+já é a densidade comum, então não a reduza em cada uso.
 
 ```tsx preview col
 <Alert description="Nenhuma sessão aberta neste repositório." />
@@ -41,8 +52,8 @@ 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 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.
+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
 <Alert title="Sem provider próprio" description="As conversas usam o padrão do sistema." />
@@ -51,15 +62,18 @@ vale (`<Alert>Sincronizado.</Alert>`) e se torna uma descrição.
 
 ## Composição (conteúdo rico)
 
-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. 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.
+Quando a mensagem precisa de conteúdo rico, componha os slots da família:
+
+- `AlertMedia` recebe o ícone, pintado com a cor do contexto.
+- `AlertHeader` agrupa `AlertTitle` e `AlertDescription`.
+- `AlertActions` reúne as ações no fim lógico da superfície, centralizadas verticalmente na linha do
+  conteúdo — a mesma posição usada pelas ações do [Toast](/ui/toast).
 
 Use `ghost` como tratamento padrão para ações dentro do alert: a mensagem já fornece a superfície e
 o botão não precisa desenhar outra moldura. Mantenha texto quando a ação expressa um resultado
-específico. Para tentar novamente, recarregar ou repetir a operação descrita pelo aviso, prefira um
-botão só com ícone, nome acessível e tooltip.
+específico. Para tentar de novo, recarregar ou repetir a operação descrita pelo aviso, prefira um
+botão só com ícone, nome acessível e [tooltip](/ui/tooltip). O `TooltipProvider` montado uma vez na
+raiz do aplicativo atende a esse tooltip.
 
 ```tsx preview col
 <Alert context="danger">
@@ -67,30 +81,27 @@ botão só com ícone, nome acessível e tooltip.
     <CircleAlert />
   </AlertMedia>
   <AlertHeader>
-    <AlertTitle>Não deu para publicar</AlertTitle>
+    <AlertTitle>Não foi possível 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>
+      <p>O registry recusou a versão 3.0.0 porque ela já existe.</p>
+      <p>Aumente o número da versão e tente de novo.</p>
     </AlertDescription>
   </AlertHeader>
   <AlertActions>
-    <TooltipProvider>
-      <Tooltip>
-        <TooltipTrigger asChild>
-          <Button variant="ghost" size="icon" aria-label="Tentar novamente">
-            <RefreshCw />
-          </Button>
-        </TooltipTrigger>
-        <TooltipContent>Tentar novamente</TooltipContent>
-      </Tooltip>
-    </TooltipProvider>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="ghost" size="icon" aria-label="Tentar de novo">
+          <RefreshCw />
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent>Tentar de novo</TooltipContent>
+    </Tooltip>
   </AlertActions>
 </Alert>
 ```
 
 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.
+entra depois da mensagem, na posição de `AlertActions`.
 
 ```tsx preview col
 <Alert
@@ -104,14 +115,57 @@ entra depois da mensagem, na posição de `AlertActions`. Não combine a forma c
 </Alert>
 ```
 
+## Composições que lançam erro
+
+A família confere a própria estrutura ao renderizar e lança erro, com a regra violada na
+mensagem, quando:
+
+- a forma curta (`title` ou `description`) é combinada com `AlertMedia`, `AlertHeader`
+  ou `AlertActions`;
+- a composição explícita recebe `icon` em vez de `AlertMedia`;
+- a composição explícita não tem exatamente um `AlertHeader`, repete `AlertMedia` ou
+  `AlertActions`, ou recebe outro filho direto além desses três;
+- `AlertMedia`, `AlertHeader` ou `AlertActions` aparecem fora de um `Alert`;
+- `AlertTitle` ou `AlertDescription` aparecem fora de um `AlertHeader`;
+- `AlertHeader` fica vazio, repete `AlertTitle` ou `AlertDescription`, ou recebe um elemento HTML
+  direto, como `<div>` ou `<p>`. Componentes próprios que envolvem o título ou a descrição são
+  aceitos.
+
 ## Propriedades de Alert
 
 | 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. |
+| `title`       | `React.ReactNode`                                           |             | Título do alert (a forma curta). Não é o atributo `title` do HTML: o componente não aceita a dica nativa do navegador; use [`Tooltip`](/ui/tooltip). |
 | `description` | `React.ReactNode`                                           |             | A frase. Sozinha, dispensa título.                                                                                                      |
 | `icon`        | `React.ReactNode`                                           |             | Ícone à esquerda; materializa `AlertMedia` com realce tonal. Decorativo — quem nomeia é o título.                                       |
-| `context`     | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado da mensagem e do realce do ícone.                                                                                         |
+| `context`     | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado da mensagem e do realce do ícone. Também define o papel acessível: `role="alert"` em `danger` e `warning`, `role="status"` nos demais. |
+| `role`        | `React.AriaRole`                                            |             | Papel acessível da raiz. Quando informado, substitui o papel derivado do `context`.                                                      |
 | `variant`     | `'subtle' \| 'outline'`                                     | `'subtle'`  | O tratamento visual aplicado ao contexto.                                                                                               |
 | `children`    | `React.ReactNode`                                           |             | Composição explícita, texto cru ou, junto da forma curta, ações exibidas após a mensagem.                                               |
 | `style`       | `React.CSSProperties`                                       |             | Ajuste excepcional da raiz; medidas escaláveis usam `rem`.                                                                              |
+
+## Propriedades de AlertMedia
+
+`AlertMedia` recebe o ícone e o apresenta em uma moldura quadrada tingida pelo `context` do
+`Alert`. A mídia é decorativa (`aria-hidden`): o título e a descrição comunicam o conteúdo. Não tem
+props próprias; aceita as de um elemento `div`.
+
+## Propriedades de AlertHeader
+
+`AlertHeader` agrupa no máximo um `AlertTitle` e um `AlertDescription`, empilhados na coluna de
+texto. Não tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de AlertTitle
+
+`AlertTitle` exibe o título em uma linha, com reticências quando não cabe. Não tem props próprias;
+aceita as de um elemento `div`.
+
+## Propriedades de AlertDescription
+
+`AlertDescription` apresenta o texto de apoio em cor atenuada e aceita mais de um parágrafo. Não
+tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de AlertActions
+
+`AlertActions` posiciona as ações depois do texto, centralizadas na linha do conteúdo. Não tem
+props próprias; aceita as de um elemento `div`.

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

@@ -1,42 +1,67 @@
-Elicitação estruturada controlada baseada diretamente em `AskQuestion` e `AskAnswer`. O componente só apresenta e valida respostas; transporte, persistência e continuação do agente pertencem ao consumidor.
+## Perguntas durante uma conversa
+
+Use `Ask` quando um agente precisar de uma decisão da pessoa antes de continuar, como escolher o
+ambiente ou as verificações de uma tarefa. Cada pergunta oferece opções clicáveis e um campo de
+resposta livre. No Opus, o modelo pede essas respostas pela tool `ask_user`, e o backend as recebe
+em `onAsk`, como descreve a página de [IA generativa](/docs/ai). `Ask` cuida apenas da
+apresentação e da validação: levar as respostas até o backend e retomar a conversa continuam com o
+aplicativo.
 
 ```tsx preview
-const [answers, setAnswers] = React.useState([])
+const [answers, setAnswers] = useState<AskAnswer[]>([])
 
 render(
   <Ask
-      questions={[
-        {
-          question: 'Qual ambiente devemos usar?',
-          header: 'Ambiente',
-          options: [
-            { label: 'Produção', description: 'Usa dados e serviços reais.' },
-            { label: 'Homologação', description: 'Usa o ambiente de validação.' },
-          ],
-        },
-        {
-          question: 'Quais verificações devo executar?',
-          header: 'Verificações',
-          multiSelect: true,
-          options: [{ label: 'Testes' }, { label: 'Typecheck' }, { label: 'Build' }],
-        },
-      ]}
-      answers={answers}
-      onChange={setAnswers}
-      onSubmit={(next) => console.log(next)}
+    questions={[
+      {
+        question: 'Qual ambiente devemos usar?',
+        header: 'Ambiente',
+        options: [
+          { label: 'Produção', description: 'Usa dados e serviços reais.' },
+          { label: 'Homologação', description: 'Usa o ambiente de validação.' },
+        ],
+      },
+      {
+        question: 'Quais verificações devo executar?',
+        header: 'Verificações',
+        multiSelect: true,
+        options: [{ label: 'Testes' }, { label: 'Typecheck' }, { label: 'Build' }],
+      },
+    ]}
+    answers={answers}
+    onChange={setAnswers}
+    onSubmit={(next) => console.log(next)}
   />,
 )
 ```
 
-Cada pergunta exige pelo menos uma opção válida selecionada **ou** texto livre não vazio. `busy` mostra o progresso no botão e trava os controles; `disabled` apenas trava a interação. A ordem de `answers` acompanha a ordem de `questions`, e o `header` de cada resposta é derivado de `question.header` (ou do próprio enunciado quando o header estiver vazio).
+Cada opção é um botão; a `description`, quando existe, aparece em um tooltip. Perguntas com
+`multiSelect` aceitam várias opções, e as demais funcionam como grupo de escolha única, navegável
+pelas setas. Abaixo das opções, o campo “Outro (opcional)…” recebe uma resposta livre.
+
+## Envio e validação
+
+O botão “Responder” envia as respostas. Cada pergunta exige pelo menos uma opção selecionada ou um
+texto livre preenchido; ao tentar enviar sem isso, a pergunta mostra “Escolha uma opção ou escreva
+uma resposta.” e `onSubmit` não é chamado. `Ask` aceita de uma a quatro perguntas; fora dessa faixa,
+o envio fica bloqueado e o componente exibe o aviso correspondente.
+
+`busy` indica que o envio está em andamento: o botão mostra o progresso e os controles ficam
+bloqueados. `disabled` apenas bloqueia a interação. A ordem de `answers` acompanha a de
+`questions`, e o `header` de cada resposta vem de `question.header`, ou do próprio enunciado quando
+o `header` estiver vazio. O `header` não aparece na tela: ele identifica a resposta para o modelo.
 
 ## Propriedades de Ask
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `questions` | `AskQuestion[]` | | Uma a quatro perguntas do contrato de elicitação; fora dessa faixa o envio é bloqueado. |
+| `questions` | `AskQuestion[]` | | De uma a quatro perguntas. Cada uma declara `question`, `options` (`{ label, description? }`) e, opcionalmente, `header` e `multiSelect`. |
 | `answers` | `AskAnswer[]` | | Respostas controladas, na mesma ordem de `questions`; entradas ausentes contam como vazias. |
 | `onChange` | `(answers: AskAnswer[]) => void` | | Recebe a lista completa a cada alteração. |
-| `onSubmit` | `(answers: AskAnswer[]) => void` | | Dispara somente quando toda pergunta tem uma opção ou texto livre. |
-| `disabled` | `boolean` | `false` | Trava as opções e o envio. |
-| `busy` | `boolean` | `false` | Envio em andamento: o botão mostra o spinner e desabilita. |
+| `onSubmit` | `(answers: AskAnswer[]) => void` | | Chamado somente quando toda pergunta tem uma opção ou um texto livre. |
+| `disabled` | `boolean` | `false` | Bloqueia as opções, o texto livre e o envio. |
+| `busy` | `boolean` | `false` | Envio em andamento: o botão mostra o progresso e os controles ficam bloqueados. |
+| `className` | `string` | | Classes aplicadas à superfície do formulário. |
+
+`AskQuestion` e `AskAnswer` são exportados por `@softize/opus`. Cada `AskAnswer` traz `header`,
+`selected` (os rótulos escolhidos) e `text`, quando a pessoa escreveu uma resposta livre.

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

@@ -1,13 +1,14 @@
-## Vídeo e preview (16/9)
+## Vídeo e imagem (16/9)
 
-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.
+Use `AspectRatio` para reservar a moldura de uma imagem ou vídeo antes que o conteúdo carregue.
+`ratio` é a razão entre largura e altura; `16 / 9` é o formato comum de vídeo. Defina a largura no
+contêiner pai, e o componente deriva a altura.
 
 ```tsx preview col
 <div className="w-full max-w-md">
   <AspectRatio ratio={16 / 9} className="overflow-hidden rounded-lg border bg-muted">
     <div className="flex h-full w-full items-center justify-center text-sm text-muted-foreground">
-      Preview do worktree — Empresa X
+      Vídeo de apresentação do veículo
     </div>
   </AspectRatio>
 </div>
@@ -15,42 +16,39 @@ contêiner (o pai): a altura o componente deriva sozinho.
 
 ## Quadrado (1/1)
 
-ratio={1} trava em um quadrado — o formato dos avatares de agente e dos ícones de skill, onde a
-moldura precisa ser previsível.
+Use `ratio={1}` quando a moldura precisar ser previsível em qualquer largura, como a foto de um
+veículo em uma listagem ou o logotipo de uma marca.
 
 ```tsx preview col-start
 <div className="w-40">
   <AspectRatio ratio={1} className="overflow-hidden rounded-lg border bg-muted">
-    <div className="flex h-full w-full items-center justify-center text-sm font-medium text-muted-foreground">
-      developer
+    <div className="flex h-full w-full items-center justify-center text-muted-foreground">
+      <CarFront className="size-8" />
     </div>
   </AspectRatio>
 </div>
 ```
 
-## Galeria de previews
+## Galeria
 
-Mesmo ratio em vários cards: as molduras alinham antes mesmo do conteúdo chegar — sem o pulo de
-layout quando o preview carrega.
+Com o mesmo `ratio` em todos os itens, as molduras ficam alinhadas antes mesmo de o conteúdo chegar,
+e a página não pula quando as imagens carregam.
 
 ```tsx preview col
 <div className="grid w-full grid-cols-3 gap-3">
   {[
-    { ref: 'empresa-x-api', branch: 'feat/preview-pipeline' },
-    { ref: 'empresa-x-web', branch: 'fix/handoff-modal' },
-    { ref: 'empresa-x-infra', branch: 'chore/caddy-bump' },
-  ].map((session) => (
+    { plate: 'ABC-1D23', model: 'Corolla XEi 2022' },
+    { plate: 'BRA-2E19', model: 'Onix LT 2021' },
+    { plate: 'RIO-4F56', model: 'Compass Longitude 2023' },
+  ].map((vehicle) => (
     <AspectRatio
-      key={session.ref}
+      key={vehicle.plate}
       ratio={16 / 9}
       className="overflow-hidden rounded-lg border bg-muted"
     >
       <div className="flex h-full w-full flex-col justify-end gap-1 p-2">
-        <span className="text-sm font-medium">{session.ref}</span>
-        <span className="flex items-center gap-1 text-xs text-muted-foreground">
-          <GitBranch className="size-3" />
-          {session.branch}
-        </span>
+        <span className="text-sm font-medium">{vehicle.plate}</span>
+        <span className="text-xs text-muted-foreground">{vehicle.model}</span>
       </div>
     </AspectRatio>
   ))}
@@ -61,6 +59,6 @@ layout quando o preview carrega.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `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. |
+| `ratio` | `number` | `1` | Razão entre largura e altura: `16 / 9` para vídeo, `1` para quadrado, `4 / 3` para o formato clássico. |
+| `children` | `ReactNode` | | Conteúdo enquadrado, como `img`, `iframe` ou `div`. Preencha a moldura com `h-full w-full` e, em imagens, `object-cover`. |
+| `className` | `string` | | Ajusta a moldura. Borda, raio e `overflow-hidden` ficam aqui, não no filho. |

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

@@ -4,9 +4,9 @@ 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 para o(s) sink(s) configurado(s) — de
-graça, sem o handler pedir. O contrato é o `AuditSink`.
+Use a auditoria para saber quem executou cada action, quando, com qual entrada e com qual
+resultado. O runtime emite um `AuditRecord` por execução para cada sink configurado, sem código no
+handler. Uma action com `audit: false` fica fora da trilha. O contrato de um sink é o `AuditSink`.
 
 ## O contrato
 
@@ -43,15 +43,17 @@ interface AuditRecord {
 import { consoleAudit } from '@softize/opus/audit/console'
 import { pgAudit } from '@softize/opus/audit/pg'
 
-// Dev: uma linha por action (pretty em um TTY, json senão).
+// Desenvolvimento: no terminal, cada action gera duas linhas formatadas (a action e seus
+// metadados); fora dele, uma linha JSON por action.
 const dev = consoleAudit()
 
 // Produção: grava na tabela audit_log (Postgres).
 const prod = pgAudit({ pool, table: 'audit_log' })
 ```
 
-O default continua compatível com a tabela legada. Para persistir o contexto novo, primeiro
-adicione colunas próprias e depois habilite o opt-in — não reutilize as colunas legadas:
+Por padrão, o `pgAudit` grava as mesmas colunas da tabela legada. Para persistir também o
+`traceContext`, adicione colunas próprias e só depois habilite a opção; não reutilize as colunas
+legadas:
 
 ```sql
 ALTER TABLE audit_log ADD COLUMN trace_id text;
@@ -62,14 +64,15 @@ ALTER TABLE audit_log ADD COLUMN span_id text;
 const prod = pgAudit({ pool, traceContextColumns: true })
 ```
 
-Rollouts com nomes existentes podem usar
+Se as colunas já existem com outros nomes, informe-os:
 `traceContextColumns: { traceId: 'otel_trace_id', spanId: 'otel_span_id' }`.
 
-## Dado sensível: o redator global
+## Proteger dados sensíveis
 
-Sem redator, os sinks persistem input e output **crus** — `user.create`/`setPassword`
-gravaria senha em claro. Os dois drivers aceitam `redact` (função `unknown → unknown`
-aplicada a input/output antes de persistir/imprimir), e a base traz o redator recursivo:
+Sem redator, os sinks persistem input e output sem alteração: uma action como `user.create` ou
+`setPassword` gravaria a senha em texto claro. Os dois drivers aceitam `redact`, uma função
+`unknown → unknown` aplicada a input e output antes de gravar ou imprimir, e o Opus oferece um
+redator recursivo:
 
 ```ts
 import { redactDeep } from '@softize/opus/audit'
@@ -79,9 +82,9 @@ import { redactDeep } from '@softize/opus/audit'
 const prod = pgAudit({ pool, redact: redactDeep })
 ```
 
-Sink próprio reusa as peças: `redactRecord(record, redator)` e `SENSITIVE_KEY_PATTERN`
-saem do mesmo módulo. O `audit: { redact: [...] }` por action (dot-paths) continua
-valendo — o redator do sink é o cinto de segurança global, não o substituto.
+Um sink próprio pode reutilizar `redactRecord(record, redator)` e `SENSITIVE_KEY_PATTERN`, do mesmo
+módulo. O `audit: { redact: [...] }` de cada action, com caminhos separados por ponto, continua
+valendo: o redator do sink é uma proteção global adicional, não um substituto.
 
 ## No runtime
 
@@ -92,10 +95,11 @@ const runtime = createRuntime({
 })
 ```
 
-O que cada action captura se ajusta no contrato (`audit: false` desliga; `audit: { redact:
-['senha'], output: false }` refina). O default captura tudo — input, output e provenance.
+O que cada action captura se ajusta no contrato: `audit: false` desliga a auditoria, e
+`audit: { redact: ['senha'], output: false }` refina o registro. Por padrão, o registro inclui
+input, output e provenance.
 
-## Limites (por enquanto)
+## Limites atuais
 
-Sink append-only (sem query/retenção embutida — isso é do seu banco). Drivers hoje:
-`console` e `pg`; outros (arquivo, OpenTelemetry…) entram por reincidência.
+Os sinks só acrescentam registros: consulta e retenção ficam com o seu banco. Os drivers disponíveis
+são `console` e `pg`; outros destinos, como arquivo e OpenTelemetry, ainda não têm driver.

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

@@ -4,10 +4,10 @@ title: Autenticação
 
 # 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 para o `can` que o driver pluga.
+Use um adapter de autenticação para que cada action saiba quem chama, em qual tenant e com quais
+permissões. A cada requisição, o runtime chama `resolveContext` do `AuthAdapter` e entrega o
+resultado ao handler em `ctx.user`, `ctx.tenantId` e `ctx.can`. O Opus não implementa RBAC nem
+ABAC: a decisão fica com a função `can` fornecida pelo driver.
 
 ## O contrato
 
@@ -21,7 +21,7 @@ interface AuthAdapter {
 }
 ```
 
-`req` é o request cru do `ServerAdapter`. O `user` vem dos claims ou da sessão, e o driver
+`req` é a requisição original recebida pelo `ServerAdapter`. O `user` vem dos claims ou da sessão, e o driver
 fornece a função `can` que decide cada autorização. O Opus chama essa função sem definir a
 política usada por ela.
 
@@ -47,14 +47,17 @@ const idp = betterAuthSession({
 
 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).
+padrão nega tudo. O `secret` pode ser string, `Buffer` ou uma função assíncrona, chamada sem o
+`kid` do token.
+
+O `betterAuthSession` busca a sessão no IdP (`timeoutMs`, padrão de 5 segundos) e a converte em
+`User`, tenant e `can`; o `can` padrão também nega tudo.
 
 ## No runtime
 
 ```ts
+import { bindAction, createRuntime } from '@softize/opus/core'
+
 const runtime = createRuntime({
   // …server/data…
   auth: idp,
@@ -67,20 +70,36 @@ export const notaEmitir = bindAction(notaEmitirContract, {
 })
 ```
 
-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`.
+Antes do handler, o runtime verifica a chamada nesta ordem:
+
+1. Valida a entrada pelo schema do contrato.
+2. Sem `public: true`, exige `ctx.user`; sem usuário, responde `auth.unauthenticated`.
+3. Executa os `loads`, que carregam os dados usados na autorização.
+4. Avalia `authorize`, se houver: `false` vira `auth.forbidden`, e um `ActionError` devolvido é
+   lançado como está.
+
+A autenticação vem antes dos loaders para que um chamador anônimo não dispare consultas nem
+descubra, pelo erro de um loader, se um registro existe. `authorize` aceita uma closure, como
+acima, ou uma expressão avaliada contra `user`, `input` e os dados carregados por `loads`, como
+`'task.ownerId == user.id'`.
 
 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
+`ctx.can` e lance o mesmo erro que o runtime usaria:
+
+```ts
+import { error } from '@softize/opus/core'
+
+if (!(await ctx.can('nota.cancelar', nota))) {
+  throw error({ code: 'auth.forbidden', category: 'authorization', message: 'Acesso negado' })
+}
+```
+
+Sem adapter `auth` configurado, os servidores HTTP resolvem `ctx.user` como `null` e só actions
 `public` executam.
 
-## Limites (por enquanto)
+## Limites atuais
 
-O Opus não modela papéis/permissões — isso é do seu `can`. Drivers hoje: `jwt` e
-`better-auth`; outros (Clerk, Auth.js…) entram por reincidência.
+O Opus não modela papéis nem permissões; isso fica na sua função `can`. Os drivers disponíveis são
+`jwt` e `better-auth`. Outros provedores, como Clerk e Auth.js, ainda não têm driver.