@softize/opus 19.0.0 → 20.1.0

package/src/ui/docs/content/radio-group.md

@@ -1,8 +1,10 @@
 ## Escolha única
 
-Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Cada
-`RadioGroupItem` declara um `value` e deve estar associado a um `Label`. `defaultValue` define a
-opção inicial no modo não controlado.
+Use `RadioGroup` quando todas as opções mutuamente exclusivas precisarem permanecer visíveis. Com
+muitas opções, prefira [`Select`](/ui/select); para ligar ou desligar um único item, use
+[`Checkbox`](/ui/checkbox) ou [`Switch`](/ui/switch). Cada `RadioGroupItem` declara um `value` e
+deve estar associado a um `Label`, escrito logo depois do item. `defaultValue` define a opção
+inicial no modo não controlado.
 
 ```tsx preview col-start
 <RadioGroup defaultValue="balanced">
@@ -68,6 +70,25 @@ bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 </RadioGroup>
 ```
 
+## Estado inválido
+
+Quando a escolha for obrigatória e nenhuma opção estiver marcada, declare `aria-invalid` em cada
+`RadioGroupItem` e explique o que falta em um texto associado ao grupo por `aria-describedby`.
+
+```tsx preview col-start
+<RadioGroup aria-describedby="review-mode-error">
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="review-auto" value="auto" aria-invalid />
+    <Label htmlFor="review-auto">Revisar automaticamente</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem id="review-manual" value="manual" aria-invalid />
+    <Label htmlFor="review-manual">Revisar manualmente</Label>
+  </div>
+</RadioGroup>
+<FieldError id="review-mode-error">Escolha como a sessão será revisada.</FieldError>
+```
+
 ## Propriedades de RadioGroup
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -82,4 +103,5 @@ bloquear todas as opções, aplique `disabled` ao `RadioGroup`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `string` | | Valor que o item atribui ao grupo quando selecionado. |
-| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` associado acompanha o estado. |
+| `disabled` | `boolean` | `false` | Desabilita somente este item; o `Label` escrito logo depois dele acompanha o estado. |
+| `aria-invalid` | `boolean` | | Aplica a borda e o anel de erro ao item. |

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

@@ -19,11 +19,13 @@ function App() {
 O router oferece leitura reativa da URL e `navigate`; o aplicativo decide o que renderizar. Ele não
 inclui tabela de rotas, parâmetros tipados nem carregamento de dados.
 
-A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:postId`), params tipados ou data loaders, o caso pede uma biblioteca de rotas, não isto. Um app de back-office com uma dúzia de destinos quase nunca precisa.
+Se a tela precisa casar padrões como `/users/:id/posts/:postId`, receber parâmetros tipados ou
+carregar dados por rota, use uma biblioteca de rotas. Um app de back-office com uma dúzia de
+destinos costuma dispensar esses recursos.
 
 ## As quatro peças
 
-| | |
+| API | Comportamento |
 |---|---|
 | `usePathname()` | O pathname como estado reativo. |
 | `useSegments()` | Os segmentos, já sem os vazios: `/settings/users` → `['settings','users']`. |
@@ -32,15 +34,23 @@ A régua: se a sua tela precisa de casamento de padrão (`/users/:id/posts/:post
 
 ## Comportamentos preservados
 
-**Destino igual é no-op.** `navigate` resolve o destino com `new URL` e compara o `href` inteiro — não faz nada se você já está exatamente lá. Sem isso, clicar duas vezes no mesmo item do menu empilha entradas idênticas e o botão "voltar" não sai do lugar.
+**Navegar para o destino atual não cria entrada.** `navigate` resolve o destino com `new URL` e
+compara o `href` inteiro; se a pessoa já está exatamente lá, nada acontece. Assim, clicar duas vezes
+no mesmo item do menu não empilha entradas idênticas, e o botão Voltar continua saindo da página.
 
-Comparar strings cruas parece bastar e não basta, em duas frentes. O **hash**: estando em `/a#secao`, `navigate('/a')` pareceria destino repetido e a âncora nunca sairia da URL. E o **encoding**: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então a comparação crua nunca casa e cada clique empilha — bem no caso pt-BR, e no ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
+A comparação usa a URL resolvida, e não o texto cru, por dois motivos. O hash: estando em
+`/a#secao`, `navigate('/a')` precisa remover a âncora, e não ser tratado como destino repetido. E a
+codificação: `window.location` devolve `/relatórios` como `/relat%C3%B3rios`, então uma comparação
+crua nunca casaria e cada clique empilharia uma entrada, o que afeta caminhos acentuados e
+chamadas como ``navigate(`/reports?report=${arquivo}`)`` com nome de arquivo acentuado.
 
 **A notificação usa um evento do navegador.** Como `pushState` não dispara `popstate`, `navigate`
 emite o evento explicitamente. Isso mantém listeners existentes e cópias diferentes do pacote
 sincronizados pela mesma janela.
 
-**`useSyncExternalStore`, não `useState`.** Ler `window.location` dentro de `useState`/`useEffect` sofre *tearing* no modo concurrent: dois componentes podem renderizar o mesmo commit com URLs diferentes. As cópias que este módulo substituiu faziam isso.
+**Todos os componentes leem a mesma URL.** Os hooks usam `useSyncExternalStore`. Ler
+`window.location` dentro de `useState` ou `useEffect` permite que, na renderização concorrente, dois
+componentes mostrem URLs diferentes no mesmo commit.
 
 ## `replace`: quando o passo não é história
 
@@ -48,14 +58,23 @@ sincronizados pela mesma janela.
 navigate(`/reports?report=${file}`, { replace: true })
 ```
 
-Use quando a mudança não merece uma volta do botão "voltar" — um rascunho que ganha id no meio do fluxo, um filtro que a pessoa ajusta várias vezes seguidas. O default (`pushState`) é o certo para navegação de verdade.
+Use `replace` quando a mudança não deve virar um passo do botão Voltar: um rascunho que ganha id no
+meio do fluxo, um filtro que a pessoa ajusta várias vezes seguidas. Para uma navegação entre
+destinos, mantenha o padrão, `pushState`.
 
 ## SSR
 
-Os hooks têm snapshot de servidor constante (`/` e busca vazia): renderizam sem `window` e reconciliam com a URL real no primeiro render do cliente. Se a sua página precisa do path correto **no HTML servido**, isto não resolve — aí o path tem que vir do framework, por prop.
+No servidor, os hooks usam um valor fixo (`/` e busca vazia): renderizam sem `window` e passam a
+refletir a URL real no primeiro render do cliente. Se a página precisa do caminho correto no HTML
+servido, receba o caminho do framework por prop.
 
-O `navigate` **não** tem essa cortesia: ele toca `window` direto e estoura no servidor. É de propósito — ler a URL sem browser tem resposta razoável, navegar não tem, e engolir a chamada em silêncio esconderia o erro de uso.
+`navigate` acessa `window` diretamente e lança um erro quando chamado no servidor. Ler a URL fora
+do navegador tem uma resposta razoável; navegar não tem, e ignorar a chamada em silêncio esconderia
+o erro de uso.
 
-## Destino externo não é problema daqui
+## Validar destinos vindos de fora
 
-`navigate` espera um caminho da própria origem. Validar destino que veio de terceiro — o `?redirect=` de um pós-login, por exemplo — é responsabilidade de quem recebe esse input, e a checagem certa é resolver com `new URL(valor, origin)` e comparar `origin`, não olhar prefixo.
+`navigate` espera um caminho da própria origem e não valida destinos. Quando o destino vem de fora,
+como o `?redirect=` de um pós-login, valide-o antes de navegar: resolva com
+`new URL(valor, origin)` e compare o `origin` do resultado, em vez de conferir apenas o prefixo do
+texto.

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

@@ -4,94 +4,130 @@ title: Runtime & adapters
 
 # Runtime & adapters
 
-O Opus não é framework — é **protocolo + SDK**: você compõe o runtime a partir de
-adapters plugáveis, e cada capacidade é opcional. O litmus é a inversão de controle:
-o runtime não toma o seu app; o seu app monta o runtime com as peças que quer.
+O runtime executa as actions registradas e entrega a elas as capacidades que o app configurou:
+servidor HTTP, banco, autenticação, auditoria e as demais. Cada capacidade é um adapter opcional.
+O app monta o runtime com as peças de que precisa, e o Opus não assume o controle do restante da
+aplicação.
 
 ## O modelo
 
-> Todo adapter implementa `name`/`kind`; `init`/`dispose`/`healthCheck` são opcionais e
-> entram no ciclo de vida do runtime (start inicializa, dispose desliga em ordem reversa,
-> healthCheck agrega).
+Todo adapter declara `name` e `kind`. `init`, `dispose` e `healthCheck` são opcionais e acompanham o
+ciclo de vida do runtime: `start()` inicializa os adapters, `dispose()` os desliga em ordem inversa
+e `healthCheck()` reúne o estado de todos.
 
 ```ts
 import { createRuntime } from '@softize/opus/core'
 
 const runtime = createRuntime({
-  server: fastifyServer({ app }),      // monta as actions como endpoints
+  server: fastifyServer({ app }),      // expõe as actions como endpoints
   data: kyselyData({ db }),            // fornece ctx.db
-  auth: makeAuthAdapter(),             // resolve user/tenant/can
-  audit: [pgAudit({ pool })],          // trilha de auditoria (N sinks)
-  observability: makeObservability(),  // span ativo + TraceContext vendor-neutral
+  auth: jwtAuth({ secret, mapUser }),  // resolve user, tenant e can
+  audit: [pgAudit({ pool })],          // trilha de auditoria; aceita vários sinks
+  observability: openTelemetryObservability(), // span ativo e trace sem fornecedor fixo
   storage: fsStorage({ root }),        // fornece ctx.storage (experimental)
   config: { env, i18n: { defaultLocale: 'pt-BR' } },
 })
 
-runtime.register([dealsDomain, billingDomain]) // não registrado = não existe
+runtime.register([workspaceDomain])
 await runtime.start()
 ```
 
+## Registrar domínios
+
+Só o que foi registrado existe para o runtime: uma action fora do registro não é montada no servidor
+nem pode ser executada. `runtime.register` aceita domínios criados com `defineDomain` e também
+actions, reactions e schedules soltos, em uma mesma lista. Um domínio é achatado com seus
+subdomínios; um nome repetido de action, reaction, schedule ou Produto de Dados lança erro, inclusive
+entre domínios registrados separadamente.
+
+O `start()` falha quando há reactions registradas sem `eventBus` (`runtime.eventbus_required`) ou
+schedules sem `scheduler` (`runtime.scheduler_required`). A declaração de um domínio está em
+[Actions & contratos](/docs/actions).
+
 ## As capacidades
 
-> Um subpath por driver; quem não usa, não instala (peers opcionais onde há dependência
-> pesada). A tabela é o mapa — cada linha é um recurso do protocolo.
+Cada driver fica num subpath próprio do pacote. Drivers que dependem de bibliotecas maiores as
+declaram como dependências opcionais: só quem usa o driver as instala.
 
 | Capacidade | Fornece | Driver pronto |
 |---|---|---|
-| `server` | monta as actions (HTTP) | `fastifyServer` — `@softize/opus/server/fastify` · `nodeServer` — `…/server/node` |
-| `data` | `ctx.db` + drift-check + CRUD | `kyselyData`, `kyselyRepo`, `crudActions` — `@softize/opus/data/kysely` |
-| `auth` | `user`/`tenantId`/`can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
+| `server` | expõe as actions por HTTP | `fastifyServer` — `@softize/opus/server/fastify` · `nodeServer` — `…/server/node` |
+| `data` | `ctx.db`, verificação de drift e CRUD | `kyselyData`, `kyselyRepo`, `crudActions` — `@softize/opus/data/kysely` |
+| `auth` | `user`, `tenantId` e `can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
 | `audit` | trilha por execução de action | `pgAudit` — `…/audit/pg` · `consoleAudit` — `…/audit/console` |
 | `logger` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
-| `observability` | span ativo + propagação de trace | `openTelemetryObservability` — `@softize/opus/observability/opentelemetry` |
-| `eventBus` | `ctx.emit` + **reactions** | `mittEvents` — `@softize/opus/events/mitt` |
+| `observability` | span ativo e propagação de trace | `openTelemetryObservability` — `@softize/opus/observability/opentelemetry` |
+| `eventBus` | `ctx.emit` e reactions | `mittEvents` — `@softize/opus/events/mitt` |
 | `queue` | jobs em background | `bullmqQueue` — `@softize/opus/queue/bullmq` |
-| `scheduler` | **schedules** (cron/intervalo) | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
-| `storage` | `ctx.storage` (arquivos) | `fsStorage` — `…/storage/fs` · `s3Storage` — `…/storage/s3` |
-| `cache` | `ctx.cache` (leitura, experimental) | `memoryCache` — `@softize/opus/cache/memory` |
-| `ai` | `ctx.ai` (complete/extract) | `anthropicAi` — `@softize/opus/ai/anthropic` |
-| `client` | chamar actions de fora (stubs) | `fetchClient` — `@softize/opus/client/fetch` |
+| `scheduler` | schedules por cron ou intervalo | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
+| `storage` | `ctx.storage` para arquivos | `fsStorage` — `…/storage/fs` · `s3Storage` — `…/storage/s3` |
+| `cache` | `ctx.cache` de leitura (experimental) | `memoryCache` — `@softize/opus/cache/memory` |
+| `ai` | `ctx.ai`: `complete`, `extract`, `run` e `runStream` | `anthropicAi` — `@softize/opus/ai/anthropic` |
+| `client` | chamar actions de fora do servidor | `fetchClient` — `@softize/opus/client/fetch` |
 
-Fora do runtime, mas parte do protocolo: o harness de teste (`runAction`/`testContext`
-— `@softize/opus/testing`) roda uma action em unidade com o mesmo pipeline do
-`execute`. Ver **Testes de action**.
+`fastifyServer` devolve o adapter diretamente. `nodeServer` devolve `{ adapter, handler, hasRoute }`:
+passe `adapter` ao runtime e ligue `handler` a um servidor `node:http`, ao Vite ou a um middleware no
+estilo connect.
+
+```ts
+import { createServer } from 'node:http'
+import { nodeServer } from '@softize/opus/server/node'
+
+const node = nodeServer()
+const runtime = createRuntime({ server: node.adapter })
+createServer(node.handler).listen(3000)
+```
+
+Fora do runtime, o harness de teste (`runAction` e `testContext`, de `@softize/opus/testing`) executa
+uma action em unidade com as etapas centrais do `execute`: valida a entrada, exige autenticação
+quando a action não é pública, avalia o `authorize`, roda o handler e valida a saída. Ele não roda os
+`loads` (os dados carregados entram pela opção `loaded`) nem grava audit. Veja
+[Testes de action](/docs/testing).
 
 ## O contexto do handler
 
-> O `ctx` é a soma do que os adapters fornecem — sem adapter, o campo é `null`/`unknown`
-> e o handler decide como degradar.
+O `ctx` recebido pelo handler reúne o que os adapters fornecem. Sem o adapter correspondente, o
+campo chega como `null`, ou como `undefined` no caso de `db`, e o handler decide como seguir.
+
+- `user`, `tenantId` e `can`, do adapter `auth`.
+- `db`, do adapter `data`.
+- `log`, do `logger`; sem ele, o runtime usa um logger de console.
+- `emit`, que publica no `eventBus`.
+- `storage`, `cache` e `ai`, dos adapters homônimos.
+- `provenance`, que identifica a origem da execução: HTTP, schedule, reaction, job, agente de IA ou
+  integração.
+- `trace`, quando há contexto de trace.
+- `meta`, com dados livres da chamada.
 
-`user`/`tenantId`/`can` (auth) · `db` (data) · `log` (logger) · `emit` (eventBus) ·
-`storage` (storage) · `cache` (cache) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
-reaction…) · `trace` (quando configurado) · `meta`.
+## Trace e observabilidade
 
-O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions
-com `runInSpan`; o `TraceContext` efetivo também segue para resultado, audit e eventos. Os
-envelopes de job recebem o trace da execução que enfileirou; `executeJob()` cria a execução
-filha no worker sem reenfileirar a action.
-Falha de instrumentação é lenient e nunca repete o handler.
+O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions com
+`runInSpan`, e o `TraceContext` efetivo segue para o resultado, o audit e os eventos. Um job recebe
+o trace da execução que o enfileirou, e `executeJob()` cria a execução filha no worker sem
+enfileirar a action de novo. Uma falha de instrumentação é tratada de forma tolerante e nunca
+executa o handler outra vez.
 
-O core não extrai headers HTTP. Os drivers Fastify e Node podem fornecer
-`ContextBase.trace` com `traceContext: 'w3c'`; o opt-in é desativado por default. Outros
-transportes continuam responsáveis por sua fronteira. Em audit, o contexto novo usa
-`traceContext`; o campo `trace` legado continua disponível sem mudança.
+O core não lê headers HTTP. Os drivers Fastify e Node preenchem `ContextBase.trace` com a opção
+`traceContext: 'w3c'`, desativada por padrão; outros transportes continuam responsáveis pela própria
+fronteira. O registro de audit traz dois campos: `traceContext`, com o contexto de trace (`traceId`, `spanId` e flags), e `trace`, com o
+`requestId` e a action de origem (`parentActionId`). Os detalhes estão em [Observabilidade](/docs/observability).
 
-Para actions, o callback observável resolve com `ActionResult`: `resultKind: 'action-result'`
-indica que o driver deve inspecionar `result.ok`. Uma Promise resolvida com `ok:false` ainda
-representa span de erro. Reactions usam `resultKind: 'void'` e rejeitam em falha.
+Para actions, a execução observada resolve com `ActionResult` e declara `resultKind:
+'action-result'`: o driver inspeciona `result.ok`, e uma Promise resolvida com `ok: false` ainda
+representa um span de erro. Reactions usam `resultKind: 'void'` e rejeitam em caso de falha.
 
-## Reactions e schedules
+## Execução sem requisição
 
-> Os dois jeitos de código rodar SEM request: evento de domínio dispara reaction;
-> tempo dispara schedule (que executa uma action, com provenance própria).
+Duas formas de código rodam sem uma requisição: um evento de domínio dispara uma
+[reaction](/docs/events), e o tempo dispara um [schedule](/docs/scheduler), que executa uma action
+com provenance própria. Ambos são registrados junto com as actions, e o manifest projeta os três.
 
-Declarados como as actions e registrados no mesmo `runtime.register` — o manifest
-projeta os três. `opus introspect` lista reactions, schedules e o wiring entre eles, mas por
-enquanto só reconhece actions declaradas com `defineAction`: as do split `defineContract` +
-`bindAction` ficam de fora do modelo que ele monta.
+`opus introspect` lista reactions, schedules e as ligações entre eles, mas só reconhece
+declarações feitas com `defineAction`, `defineReaction` e `defineSchedule`. Actions do par
+`defineContract` e `bindAction` e reactions do par `defineReactionContract` e `bindReaction` ficam de
+fora do modelo que ele monta.
 
-## Referência profunda
+## Referência completa
 
-O contrato completo (tipos, garantias, ordem de execução, erros) vive no
-`docs/protocol.md` **dentro do pacote** — como o changelog, viaja com a versão
-que você instalou.
+O contrato completo, com tipos, garantias, ordem de execução e erros, está em `docs/protocol.md`,
+dentro do pacote instalado. Como o changelog, ele acompanha a versão que o projeto usa.

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

@@ -4,62 +4,94 @@ title: Agendador
 
 # Agendador
 
-Use um schedule para executar uma action por cron ou intervalo. O `SchedulerAdapter` registra o
-agendamento e o runtime executa a action com provenance `schedule`, preservando sua rastreabilidade.
+Use um schedule para executar uma action por cron ou em intervalos, sem uma requisição. O
+`SchedulerAdapter` registra o agendamento, e o runtime executa a action com provenance `schedule`,
+que aparece no audit e no contexto do handler.
 
 ## O contrato
 
 ```ts
-interface SchedulerAdapter {
+interface SchedulerAdapter extends Adapter {
+  name: string                // herdado de Adapter; identifica o driver
+  kind: 'scheduler'
   register(spec: ScheduleDef, fire: () => Promise<void> | void): Unsubscribe
 }
 
 interface ScheduleDef {
   name: string
-  action: string              // action do registry, executada quando dispara
-  cron?: string               // '0 9 * * *' (9h todo dia)
-  every?: string              // '1h', '30m', '15s' — atalho de intervalo
-  timezone?: string           // IANA, ex.: 'America/Sao_Paulo' (sem ele: hora local do processo)
-  input?: unknown | (() => unknown | Promise<unknown>)   // estático ou dinâmico
-  enabled?: boolean
+  action: string              // action registrada, executada a cada disparo
+  cron?: string               // '0 9 * * *' (todo dia às 9h)
+  every?: string              // '15s', '5m', '1h', '1d': atalho de intervalo
+  timezone?: string           // IANA, como 'America/Sao_Paulo'; sem ela, vale a hora local do processo
+  input?: unknown | (() => unknown | Promise<unknown>)   // fixo ou calculado a cada disparo
+  enabled?: boolean           // padrão true
+  description?: string
+  tags?: string[]
 }
 ```
 
-O timing é exclusivo: `cron` **ou** `every`. A action referenciada tem que existir no
-registry.
+Declare `cron` ou `every`, não os dois. `every` aceita segundos e minutos até 59, horas até 23 e
+somente `1d` para dias; intervalos maiores usam `cron`. Sem `input`, a action recebe `{}`.
 
 ## Driver
 
 ```ts
 import { nodeCronScheduler } from '@softize/opus/scheduler/node-cron'
 
-const scheduler = nodeCronScheduler()   // in-process
+const scheduler = nodeCronScheduler() // no mesmo processo do runtime
 ```
 
-## No runtime
+## Declarar no domínio
+
+Declare o schedule com `defineSchedule` e registre-o no domínio, ao lado da action que ele executa:
 
 ```ts
-import { defineSchedule } from '@softize/opus/core'
+import { createRuntime, defineDomain, defineSchedule } from '@softize/opus/core'
+import { caixaFechar } from './caixa-fechar.ts' // a action 'caixa.fechar', definida com bindAction
 
-// Declarado no domínio, junto das actions:
 const fecharDia = defineSchedule({
-  name: 'fechar-dia',
+  name: 'caixa.fechar-dia',
   action: 'caixa.fechar',
   cron: '0 23 * * *',
   timezone: 'America/Sao_Paulo',
 })
 
+export const caixaDomain = defineDomain({
+  name: 'caixa',
+  actions: { caixaFechar },
+  schedules: [fecharDia],
+})
+
 const runtime = createRuntime({
   // …server/data…
   scheduler,
 })
+runtime.register([caixaDomain])
+await runtime.start()
 ```
 
-O runtime registra os schedules do domínio no `start()` e chama a action quando o tempo bate
-— nada de disparar no handler.
+No `start()`, o runtime confere se cada schedule aponta para uma action registrada no mesmo runtime
+e depois o registra no adapter. Um nome sem action registrada interrompe o `start()` com
+`runtime.schedule_action_not_found`, antes de inicializar os adapters; a mensagem lista cada
+schedule e a action que ele procurou. Com schedules registrados e sem `scheduler`, o `start()`
+falha com `runtime.scheduler_required`. Um schedule com `enabled: false` não é registrado nem
+conferido, então pode apontar para uma action que ainda não existe no ambiente.
+
+## Preparar a action agendada
+
+O schedule executa a action sem usuário: `ctx.user` é `null` e `ctx.can` nega tudo. Por isso, a
+action alvo precisa declarar `public: true`; sem isso, cada disparo termina em
+`auth.unauthenticated`. Para que ela não fique acessível por HTTP, declare também `internal: true`:
+os servidores do Opus não expõem actions internas, e o schedule continua executando-a pelo runtime.
+
+Quando um disparo não conclui a action, o runtime registra um erro no log com o schedule, a action,
+o código e a mensagem do erro; o agendamento continua ativo e o próximo disparo executa a action de
+novo. Uma falha dentro do pipeline da action, como `auth.unauthenticated` ou um erro do handler,
+também fica registrada no audit. O callback `onError` do driver recebe somente erros lançados antes
+da execução, como uma falha na função `input`.
 
 ## Limites atuais
 
-Driver hoje: `node-cron` (in-process — some se o processo cair; em um cluster, cada nó
-dispararia). Backends duráveis/distribuídos (BullMQ repeatable, Temporal…) entram por
-reincidência.
+O único driver é o `node-cron`, que roda no mesmo processo: o agendamento some se o processo cair e,
+em um cluster, cada nó dispara o mesmo schedule. O modo design do Vite não registra schedules.
+Backends duráveis ou distribuídos, como jobs repetidos do BullMQ ou Temporal, ainda não têm driver.

package/src/ui/docs/content/scroll-area.md

@@ -1,26 +1,28 @@
 ## Lista de altura fixa
 
-Dê a altura ao ScrollArea (h-48) e ponha o conteúdo dentro — a barra vertical já vem por padrão, sem precisar de ScrollBar.
+Use `ScrollArea` quando um bloco precisa manter a própria altura e rolar o conteúdo que passar dela.
+Dê a altura ao `ScrollArea`, como `h-48`, e coloque o conteúdo dentro. A barra vertical já vem
+incluída; não é preciso acrescentar `ScrollBar`.
 
 ```tsx preview col
-const sessions = [
-  { id: 'empresa-x-1842', title: 'Migrar billing para o novo schema', agent: 'developer' },
-  { id: 'empresa-x-1839', title: 'Revisar handoff do checkout', agent: 'reviewer' },
-  { id: 'empresa-x-1835', title: 'Redesenhar o painel de rotas', agent: 'designer' },
-  { id: 'empresa-x-1830', title: 'Corrigir flaky no teste de webhook', agent: 'developer' },
-  { id: 'empresa-x-1827', title: 'Vincular skill clean-code ao agente', agent: 'reviewer' },
-  { id: 'empresa-x-1821', title: 'Subir preview do worktree', agent: 'developer' },
-  { id: 'empresa-x-1818', title: 'Ajustar copy do empty state', agent: 'designer' },
-  { id: 'empresa-x-1814', title: 'Rodar opus check no monorepo', agent: 'reviewer' },
+const orders = [
+  { id: 'OS-1842', title: 'Revisão dos 20.000 km', vehicle: 'ABC-1D23' },
+  { id: 'OS-1839', title: 'Troca das pastilhas de freio', vehicle: 'BRA-2E19' },
+  { id: 'OS-1835', title: 'Alinhamento e balanceamento', vehicle: 'RIO-4F56' },
+  { id: 'OS-1830', title: 'Diagnóstico de ruído na suspensão', vehicle: 'SPO-7G88' },
+  { id: 'OS-1827', title: 'Troca de óleo e filtro', vehicle: 'ABC-1D23' },
+  { id: 'OS-1821', title: 'Substituição da bateria', vehicle: 'CWB-3H45' },
+  { id: 'OS-1818', title: 'Higienização do ar-condicionado', vehicle: 'BRA-2E19' },
+  { id: 'OS-1814', title: 'Revisão dos 40.000 km', vehicle: 'POA-9J12' },
 ]
 
 render(
   <ScrollArea className="h-48 w-full rounded-md border border-border">
     <div className="p-3">
-      {sessions.map((s) => (
-        <div key={s.id} className="rounded-md px-2 py-1.5 text-sm hover:bg-muted">
-          <p className="font-medium">{s.title}</p>
-          <p className="text-xs text-muted-foreground">{s.id} · {s.agent}</p>
+      {orders.map((order) => (
+        <div key={order.id} className="rounded-md px-2 py-1.5 text-sm hover:bg-muted">
+          <p className="font-medium">{order.title}</p>
+          <p className="text-xs text-muted-foreground">{order.id} · {order.vehicle}</p>
         </div>
       ))}
     </div>
@@ -30,17 +32,18 @@ render(
 
 ## Trilho horizontal
 
-Para rolar na horizontal, acrescente <ScrollBar orientation="horizontal" /> como filho e deixe o conteúdo em uma linha que não quebra (flex + w-max).
+Para rolar na horizontal, acrescente `<ScrollBar orientation="horizontal" />` como filho e mantenha
+o conteúdo em uma linha que não quebra, com `flex` e `w-max`.
 
 ```tsx preview col
-const skills = ['implement-opus-change', 'create-opus-action', 'test-opus-action', 'build-opus-ui', 'upgrade-opus']
+const services = ['Troca de óleo', 'Filtro de ar', 'Alinhamento', 'Balanceamento', 'Pastilhas de freio', 'Velas de ignição']
 
 render(
   <ScrollArea className="w-full rounded-md border border-border whitespace-nowrap">
     <div className="flex w-max gap-2 p-3">
-      {skills.map((skill) => (
-        <span key={skill} className="rounded-md border border-border bg-muted px-3 py-1.5 text-sm">
-          {skill}
+      {services.map((service) => (
+        <span key={service} className="rounded-md border border-border bg-muted px-3 py-1.5 text-sm">
+          {service}
         </span>
       ))}
     </div>
@@ -49,28 +52,30 @@ render(
 )
 ```
 
-## Painel com divisórias
+## Histórico com divisórias
 
-O conteúdo é livre: aqui o log do agente, com Separator entre as linhas. A barra só aparece quando o conteúdo passa da altura.
+O conteúdo interno é livre. Neste exemplo, o histórico de uma ordem de serviço usa `Separator`
+entre as linhas. A barra só aparece quando o conteúdo passa da altura e o ponteiro está sobre a
+área; para mantê-la sempre visível, passe `type="always"`.
 
 ```tsx preview col
-const log = [
-  '12:04 developer clonou o worktree de empresa-x-api',
-  '12:05 developer rodou pnpm install',
-  '12:07 developer abriu a sessão empresa-x-1842',
-  '12:11 developer aplicou o diff no schema de billing',
-  '12:14 reviewer foi acionado no handoff',
-  '12:16 reviewer apontou 2 ajustes de microcopy',
-  '12:19 developer corrigiu a microcopy',
-  '12:22 opus check passou em todos os pacotes',
-  '12:24 reviewer aprovou o handoff',
+const history = [
+  '08:02 Veículo recebido na oficina',
+  '08:15 Checklist de entrada concluído',
+  '08:40 Diagnóstico iniciado',
+  '09:10 Orçamento enviado ao cliente',
+  '09:32 Orçamento aprovado',
+  '10:05 Peças separadas no estoque',
+  '11:20 Serviço concluído',
+  '11:45 Teste de rodagem aprovado',
+  '12:00 Veículo liberado para retirada',
 ]
 
 render(
   <ScrollArea className="h-40 w-full rounded-md border border-border">
     <div className="p-3 text-sm">
-      {log.map((line, i) => (
-        <div key={i}>
+      {history.map((line, i) => (
+        <div key={line}>
           {i > 0 && <Separator className="my-1.5" />}
           <p className="text-muted-foreground">{line}</p>
         </div>
@@ -84,11 +89,13 @@ render(
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `className` | `string` | | Classes que definem as dimensões da janela rolável. Sem uma dimensão limitada, não há conteúdo a recortar. |
-| `children` | `React.ReactNode` | | Conteúdo da janela, incluindo uma `ScrollBar` horizontal quando necessária. |
+| `className` | `string` | | Define as dimensões da janela rolável. Sem uma dimensão limitada, não há conteúdo a recortar. |
+| `type` | `'hover' \| 'scroll' \| 'auto' \| 'always'` | `'hover'` | Quando a barra aparece: sob o ponteiro, durante a rolagem, sempre que houver excedente ou sempre. |
+| `children` | `ReactNode` | | Conteúdo da janela, incluindo uma `ScrollBar` horizontal quando necessária. |
 
 ## Propriedades de ScrollBar
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Direção da barra. A barra vertical já faz parte de `ScrollArea`. |
+| `className` | `string` | | Ajusta o trilho da barra. |