@softize/opus 20.0.0 → 21.0.0

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

@@ -117,7 +117,7 @@ function DrawerContent({
         data-slot="drawer-content"
         data-layout={layout}
         className={cn(
-          "fixed z-50 flex flex-col bg-background shadow-lg transition ease-in-out data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
+          "fixed z-50 flex flex-col bg-background shadow-lg transition ease-in-out [--surface-background:var(--background)] data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:animate-in data-[state=open]:duration-500",
           side === "right" &&
             "inset-y-0 right-0 h-full w-3/4 max-w-sm border-l data-[state=closed]:slide-out-to-right data-[state=open]:slide-in-from-right",
           side === "left" &&

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

@@ -96,10 +96,11 @@ apresentação para o consumidor, como cards de status acima da lista. No modal,
 `section` formam um grupo, e `advancedFilters.columns` distribui os grupos em até três colunas.
 Use `advancedFilters.sectionIcons` quando os grupos representarem dimensões recorrentes; a chave é
 o mesmo rótulo de `section`, e cada grupo usa `Content as="fieldset"` para manter uma legenda
-nativa. Quando os grupos precisarem de limites mais explícitos,
-`advancedFilters.sectionVariant: 'framed'` envolve cada seção e pede ao `Content` o acabamento
-`frameVariant="legend"`, integrando visualmente a legenda à borda sem atribuir esse design à
-semântica de `fieldset`.
+nativa. O ícone ocupa a mídia do grupo, antes do título, e recebe a moldura padrão: passe só o
+glifo. Um `IconTile` é adotado pela mídia com o que declara, e um ícone `null` não desenha nada.
+Quando os grupos precisarem de limites mais explícitos, `advancedFilters.sectionVariant: 'framed'`
+envolve cada seção e pede ao `Content` o acabamento `frameVariant="legend"`, integrando visualmente
+a legenda à borda sem atribuir esse design à semântica de `fieldset`.
 Um filtro `select` pode declarar `searchable: true` quando a lista fechada for longa; a opção geral
 continua disponível e participa da busca. Campos de data avançados usam calendário. A antiga `advanced: true` continua aceita durante a
 migração e equivale a `placement: 'advanced'`.
@@ -138,8 +139,8 @@ filters: {
     columns: 2,
     sectionVariant: 'framed',
     sectionIcons: {
-      Relacionamento: <IconTile size="xs"><UserRound /></IconTile>,
-      Datas: <IconTile size="xs"><CalendarDays /></IconTile>,
+      Relacionamento: <UserRound />,
+      Datas: <CalendarDays />,
     },
   }}
 />

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

@@ -147,7 +147,8 @@ validações: `z.object({ tag: t.slug().zod(), contato: t.email().zod() })`. O `
 schema zod de cada tipo lógico (slug, email, phone, money…), importado de `@softize/opus/schema/zod`.
 
 A autorização é fechada por padrão: sem `public: true`, a action exige usuário autenticado; com
-`authorize`, exige também a permissão declarada.
+`authorize`, exige também a permissão declarada. `automatable: true` permite que um
+[schedule](/docs/scheduler) execute a action como o sistema, sem abri-la a chamadores anônimos.
 
 ## Prototipar com dados simulados
 

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

@@ -99,6 +99,16 @@ O que cada action captura se ajusta no contrato: `audit: false` desliga a audito
 `audit: { redact: ['senha'], output: false }` refina o registro. Por padrão, o registro inclui
 input, output e provenance.
 
+O `actor` diz quem executou. Uma pessoa aparece com `type: 'user'` e o próprio `id`; uma execução
+iniciada pelo sistema, como o disparo de um [schedule](/docs/scheduler), aparece com
+`{ id: null, type: 'system' }` e o nome do schedule na provenance.
+
+Reactions também geram registros, um por evento que chega ao handler. Eles têm `provenance.kind`
+igual a `reaction`, o nome da reaction em `action`, `meta: { kind: 'reaction', attempts }` e nenhum
+`actionKind`. O `input` traz só a identidade do evento (`id`, `type` e `source`), sem o payload, que
+já está no registro da action que emitiu. Um sink que filtra leituras por `actionKind` deve tratar
+esses registros à parte. Veja [Eventos](/docs/events).
+
 ## Limites atuais
 
 Os sinks só acrescentam registros: consulta e retenção ficam com o seu banco. Os drivers disponíveis

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

@@ -73,7 +73,11 @@ export const notaEmitir = bindAction(notaEmitirContract, {
 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`.
+2. Sem `public: true`, exige `ctx.user`; sem usuário, responde `auth.unauthenticated`. A exceção é
+   o disparo de um schedule, que executa como o sistema uma action com `automatable: true` e recebe
+   `auth.system_forbidden` nas demais (veja [Agendador](/docs/scheduler)). Para aceitar o sistema no
+   `authorize`, use uma função com `isSystemActor(ctx)`: a expressão em string não o reconhece, e
+   `ctx.provenance` não prova que a chamada veio de um schedule.
 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á.

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

@@ -31,21 +31,15 @@ render(
 
 Use `framed` quando título e corpo precisarem formar uma única região delimitada. A moldura pertence
 ao `Content`; componentes internos, como `DetailGroup`, continuam responsáveis somente pelo layout
-e pela semântica dos próprios dados.
+e pela semântica dos próprios dados. Por padrão, a borda permanece contínua e o header fica dentro
+do recuo da região.
 
 ```tsx preview col
 render(
   <Content
     framed
-    title={
-      <span className="flex items-center gap-2">
-        <UserRound
-          className="size-4 text-muted-foreground"
-          aria-hidden="true"
-        />
-        Cliente
-      </span>
-    }
+    title="Cliente"
+    media={<UserRound aria-hidden="true" />}
   >
     <DetailGroup columns={2}>
       <DetailField label="Nome" value="Carla Souza" />
@@ -55,16 +49,66 @@ render(
 );
 ```
 
+## Header integrado à moldura
+
+Quando uma região compacta precisar integrar visualmente o header à borda, use
+`frameVariant="legend"`. O acabamento não muda a semântica: uma região de leitura continua sendo
+uma `section`, o título continua sendo um heading e descrição, contador e ações permanecem
+disponíveis.
+
+```tsx preview col
+render(
+  <Content
+    framed
+    frameVariant="legend"
+    title="Veículo"
+    media={<CarFront aria-hidden="true" />}
+  >
+    <DetailGroup columns={2}>
+      <DetailField label="Placa" value="ABC1D23" />
+      <DetailField label="Modelo" value="Corolla XEi" />
+    </DetailGroup>
+  </Content>,
+);
+```
+
+Para interromper a borda, o header pinta o título e as ações com o fundo da superfície que hospeda o
+`Content`, lido da variável CSS `--surface-background`. `Card`, `Dialog` e `Drawer` já a declaram
+com o fundo que pintam; fora deles, vale `--background`. Uma superfície com fundo próprio, como um
+`Card` com `bg-*`, um `Popover` ou um contêiner da aplicação, precisa declarar a variável com o
+mesmo fundo. Sem isso, a faixa atrás do título aparece com a cor da página.
+
+```tsx preview col
+render(
+  <Card className="bg-muted [--surface-background:var(--muted)]">
+    <CardBody>
+      <Content framed frameVariant="legend" title="Veículo">
+        <DetailGroup columns={2}>
+          <DetailField label="Placa" value="ABC1D23" />
+          <DetailField label="Modelo" value="Corolla XEi" />
+        </DetailGroup>
+      </Content>
+    </CardBody>
+  </Card>,
+);
+```
+
 ## Grupo de campos
 
 Quando a região nomear um conjunto de campos relacionados, use `as="fieldset"`. O `Content`
 renderiza o título como `legend`, preserva as props nativas do `fieldset` e mantém o mesmo contrato
 de título e corpo. Essa escolha altera somente a semântica e o comportamento nativo; com `framed`,
-a moldura permanece contínua. Nesse modo, contador, descrição e ações não entram na legenda.
+a moldura permanece contínua. A mídia usa a mesma apresentação da `section`; contador, descrição e
+ações não entram na legenda.
 
 ```tsx preview col
 render(
-  <Content as="fieldset" framed title="Proprietário">
+  <Content
+    as="fieldset"
+    framed
+    title="Proprietário"
+    media={<UserRound aria-hidden="true" />}
+  >
     <FieldGroup>
       <Field>
         <FieldLabel htmlFor="owner-name">Nome</FieldLabel>
@@ -79,8 +123,9 @@ render(
 );
 ```
 
-Quando a legenda precisar integrar visualmente a borda, declare essa escolha separadamente. Use
-`frameVariant="legend"` em agrupamentos compactos, como as seções de filtros avançados.
+O mesmo acabamento pode integrar a legenda nativa à borda. Declare `frameVariant="legend"` em
+agrupamentos compactos, como as seções de filtros avançados; `as="fieldset"` continua sendo a
+decisão semântica, e não uma forma de obter esse desenho.
 
 ```tsx preview col
 render(
@@ -104,13 +149,16 @@ render(
 
 Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
 `ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
-uma descrição, um contador (`ContentMeta`) e uma região de ações. O contador é próprio de
-`Content`; `PageHeader` reconhece somente navegação, título e ações.
+uma mídia (`ContentMedia`), uma descrição, um contador (`ContentMeta`) e uma região de ações. O
+contador é próprio de `Content`; `PageHeader` reconhece somente navegação, título e ações.
 
 ```tsx preview col
 render(
   <Content level={2}>
     <ContentHeader>
+      <ContentMedia>
+        <Monitor aria-hidden="true" />
+      </ContentMedia>
       <ContentTitle>Dispositivos conectados</ContentTitle>
       <ContentMeta>3</ContentMeta>
       <ContentDescription>Sessões com acesso à sua conta.</ContentDescription>
@@ -166,6 +214,7 @@ classes adicionais; um `Content` irmão, sem lista, mantém a altura do próprio
 | Propriedade    | Tipo                         | Padrão      | Descrição                                                                                                               |
 | -------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
 | `title`        | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                                      |
+| `media`        | `ReactNode`                  |             | Forma curta: ícone ou imagem que identifica a região antes do título.                                                   |
 | `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, no extremo oposto ao título.                                                 |
@@ -173,11 +222,30 @@ classes adicionais; um `Content` irmão, sem lista, mantém a altura do próprio
 | `variant`      | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície.                |
 | `as`           | `'section' \| 'fieldset'`    | `'section'` | Usa uma região com heading ou um grupo de campos cujo título é a legenda nativa.                                        |
 | `framed`       | `boolean`                    | `false`     | Envolve o header e o body com a moldura estrutural da região.                                                           |
-| `frameVariant` | `'default' \| 'legend'`      | `'default'` | Em `fieldset` com moldura, mantém a borda contínua ou integra visualmente a legenda à borda. Não altera a semântica.    |
+| `frameVariant` | `'default' \| 'legend'`      | `'default'` | Mantém a borda contínua ou integra visualmente o header à moldura. Não altera o elemento nem sua semântica.             |
 | `children`     | `ReactNode`                  |             | Corpo da região na forma curta, ou `ContentHeader` e `ContentBody` na composição explícita.                             |
 
 As demais propriedades são as nativas de `section` ou, com `as="fieldset"`, de `fieldset`.
 
-Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e
-`ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`
-próprios — a hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.
+Na composição explícita de uma `section`, `ContentHeader` recebe `ContentMedia`, `ContentTitle`,
+`ContentMeta`, `ContentDescription` e `ContentActions`. Em `fieldset`, recebe `ContentMedia` e
+`ContentTitle`, preservando a apresentação enquanto a legenda continua nomeando somente o grupo de
+campos. `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level` próprios — a
+hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.
+
+## Propriedades de ContentMedia
+
+| Propriedade | Tipo                                                                     | Padrão      | Descrição                                                                                                                   |
+| ----------- | ------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `size`      | `'xs' \| 'sm' \| 'default' \| 'lg'`                                      | `'xs'`      | Tamanho da moldura e do glifo na escala compartilhada dos controles.                                                        |
+| `context`   | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Declara o significado da cor.                                                                                               |
+| `variant`   | `'subtle' \| 'outline'`                                                   | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                                                                                |
+| `className` | `string`                                                                 |             | Ajusta a moldura sem substituir a escala.                                                                                   |
+| `asChild`   | `boolean`                                                                | `false`     | Cede o elemento para uma marca com visual próprio — um orbe, um logotipo — que ocupa o slot sem ganhar a moldura por cima. |
+
+`ContentMedia` já é a moldura. Passe só o glifo e escolha `size`, `context` e `variant` no slot. Um
+`IconTile` passado em `media` ou dentro de `ContentMedia` não vira moldura dentro de moldura: o slot
+assume o lugar dele e herda o que ele declara. `media` com `null` ou `false` não desenha nada.
+
+Em `fieldset`, a mídia é sempre decorativa: o `Content` a esconde da árvore de acessibilidade para
+que o grupo seja anunciado apenas pelo título.

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

@@ -23,7 +23,8 @@ interface DomainEvent<T = unknown> {
   actor: { id: string | null; type?: 'user' | 'system' | 'integration' }
   tenant?: string | null
   data: T
-  source: { action: string; actionId: string; correlation?: string }
+  source: { action: string; actionId: string; correlation?: string } // action que iniciou a cadeia
+  cause?: { reaction: string; eventId: string; eventType: string; depth: number } // só se publicado por reaction
   trace?: TraceContext                           // trace da execução que emitiu
   meta?: Record<string, unknown>                 // o terceiro argumento de ctx.emit
 }
@@ -105,17 +106,114 @@ com `runtime.eventbus_required` quando ele não existe. `defineReaction` declara
 quando não há separação entre cliente e servidor.
 
 A reaction roda com provenance `reaction`; `ctx.user` traz somente o `id` do autor do evento, e
-`ctx.tenantId`, o tenant do evento. O contexto não tem `can`: a decisão fica no `authorize(ctx, event)` opcional, e uma resposta `false` descarta o evento
-sem erro. Uma falha no handler é registrada no log e não chega à action que emitiu.
+`ctx.tenantId`, o tenant do evento. O contexto não tem `can`: a decisão fica no
+`authorize(ctx, event)` opcional, e uma resposta `false` descarta o evento sem erro. Uma falha na
+reaction fica no log e no audit e não chega à action que emitiu.
 
-## Limites atuais
+## Proteger a entrega
+
+Uma reaction costuma falar com algo que falha ou demora: uma API externa, uma fila, outro banco. A
+política de entrega, declarada no binding, diz como o runtime lida com isso:
+
+```ts
+export const leadSincronizarImpl = bindReaction(leadSincronizar, {
+  retry: { attempts: 3, backoff: { kind: 'exponential', initialMs: 1_000, maxMs: 30_000 } },
+  timeout: 10_000,
+  dedup: (event) => event.data.leadId,
+  concurrency: 2,
+  handler: async (ctx, event) => {
+    await crm.upsertLead(event.data.leadId, { signal: ctx.signal })
+  },
+})
+```
+
+O runtime aplica cada campo a cada evento entregue, nesta ordem:
+
+- **`dedup`** calcula uma chave para o evento. Outro evento com a mesma chave é descartado enquanto
+  o primeiro está na fila ou em andamento e durante `config.dedupCacheTtl` depois de ele concluir
+  (padrão de 60 segundos). Se a entrega falhar em definitivo, a chave é liberada, e o evento pode ser
+  entregue de novo. Cada reaction guarda no máximo `config.dedupCacheMaxEntries` chaves concluídas
+  (padrão 10.000); acima disso, a mais antiga sai antes do TTL, e um evento com ela volta a ser
+  aceito.
+- **`concurrency`** limita quantos eventos da reaction rodam ao mesmo tempo. O padrão é 1: sem
+  declarar, a reaction processa um evento por vez, na ordem de chegada. Acima disso,
+  `config.maxConcurrentReactions` (padrão 10) limita a soma de todas as reactions do processo. Com o
+  padrão, um handler sem `timeout` que trava — uma chamada de rede sem resposta, por exemplo —
+  segura a única vaga, e a reaction inteira para de processar eventos até o processo reiniciar.
+  Declare `timeout` em toda reaction que depende de algo externo.
+- **`authorize`**, quando declarado, roda uma vez, antes da primeira tentativa.
+- **`timeout`** é o prazo de cada tentativa, em milissegundos. Ao vencer, o runtime aborta
+  `ctx.signal` e encerra a tentativa com `runtime.reaction_timeout`. Passe o sinal adiante, como no
+  exemplo: um handler que o ignora continua executando em segundo plano, fora do limite de
+  concorrência.
+- **`retry`** repete o handler que falhou. `attempts` é o total de execuções, contando a primeira.
+  `fixed` espera `delayMs` entre elas; `exponential` começa em `initialMs`, multiplica por
+  `multiplier` (padrão 2) e para em `maxMs`. A espera entre tentativas não ocupa vaga de
+  concorrência.
+
+Uma exceção comum, como `throw new Error(...)`, e o `runtime.reaction_timeout` são sempre repetidos.
+Um `ActionError`, criado com `error()`, segue o próprio `retriable`, que por padrão vem da categoria:
+só `rate_limit` e `dependency` repetem; `validation`, `authentication`, `authorization`,
+`not_found`, `conflict` e `internal` encerram as tentativas. Para repetir um erro de outra categoria,
+declare-o ao criá-lo:
+
+```ts
+throw error({ code: 'crm.lead.locked', category: 'conflict', retriable: true })
+```
+
+Sem política declarada, o handler roda uma vez e um evento por vez. `config.defaultRetry` vale só
+para jobs em background, não para reactions. Com `retry`, o handler precisa tolerar a repetição: o
+`dedup` evita processar o mesmo evento duas vezes, mas não desfaz o que uma tentativa anterior
+já gravou. Declare também `timeout`: com a concorrência padrão, é ele que impede um handler travado
+de parar a reaction inteira.
+
+Cada tentativa que falha e será repetida gera o aviso `runtime.reaction_retry` no log, e a falha
+definitiva, a linha `reaction failed` com o número de tentativas. Um evento descartado pelo `dedup`
+gera uma linha `debug` com `runtime.reaction_duplicate_skipped`. Valores fora do domínio, como
+`concurrency: 0`, interrompem o registro com `runtime.invalid_reaction_policy`.
 
-O driver `mitt` funciona no mesmo processo, sem durabilidade nem entrega entre processos.
+Cada entrega que chega ao handler gera um registro de [auditoria](/docs/audit): `action` traz o
+nome da reaction, `meta` traz `{ kind: 'reaction', attempts }` e `input` traz só a identidade do
+evento (`id`, `type` e `source`). O payload fica no registro da action que emitiu, com a redação
+dela. Um evento recusado pelo `authorize` ou descartado pelo `dedup` não gera registro.
+
+## Encadear reactions
+
+Quando o efeito de uma reaction é um fato que outra parte do sistema precisa saber, ela o publica
+com `ctx.emit`, como uma action. A reaction declara no binding os eventos que publica:
+
+```ts
+export const leadSincronizarImpl = bindReaction(leadSincronizar, {
+  emits: ['lead.sincronizado'],
+  handler: async (ctx, event) => {
+    const externo = await crm.upsertLead(event.data.leadId)
+    await ctx.emit('lead.sincronizado', { leadId: event.data.leadId, externoId: externo.id })
+  },
+})
+```
+
+Diferente de uma action, uma reaction só publica o que está em `emits`. Um evento fora da lista,
+inclusive de uma reaction sem `emits`, é descartado, e o runtime registra o aviso
+`runtime.reaction_emit_ignored` com a reaction, o evento e a lista declarada. O aviso vem de
+`config.warnUndeclaredEmits`, ativo por padrão fora de produção.
+
+O evento publicado mantém `actor`, `tenant` e `source` do evento que a reaction processava: `source`
+continua apontando para a action que iniciou a cadeia. O campo `cause` registra a reaction que
+publicou, o evento de origem e a profundidade na cadeia, que começa em 1. Evento emitido por action
+não tem `cause`.
+
+Uma cadeia pode dar até `config.maxReactionDepth` saltos de reaction (padrão 5). O limite impede que
+um laço, como uma reaction que publica um evento que volta a acioná-la, consuma o processo. O
+`ctx.emit` que passaria do limite não publica e registra o erro `runtime.reaction_chain_too_deep`
+com a cadeia observada. Com `emitMode: 'strict'`, o mesmo código também interrompe a reaction.
+
+O manifest projeta o `emits` de cada reaction, e o [`opus introspect`](/docs/cli) liga esse `emits`
+às reactions que escutam o evento.
+
+## Limites atuais
 
-Uma reaction não encadeia outra por evento: dentro dela, `ctx.emit` descarta o evento sem publicá-lo.
-Com `config.dev` ativo, cada descarte registra o aviso `runtime.reaction_emit_ignored` no log, com o
-nome da reaction e do evento; em produção, o descarte continua silencioso. Quando outro consumidor
-precisa desse fato, emita o evento no handler da action que o produz e declare-o em `emits`.
+O driver `mitt` funciona no mesmo processo, sem durabilidade nem entrega entre processos. As
+políticas de entrega também valem por processo, em memória: com vários processos consumindo o mesmo
+barramento, cada um mantém o próprio `dedup` e os próprios limites de concorrência, e um evento que
+espera vaga se perde se o processo cair.
 
-`retry`, `timeout`, `dedup` e `concurrency` são aceitos na declaração, mas o runtime ainda não os
-aplica: uma reaction que falha não é repetida.

package/src/ui/docs/content/icon-tile.md

@@ -13,24 +13,24 @@ com tamanho de ícone e um nome acessível.
 O tamanho controla a caixa e o glifo pela escala compartilhada dos controles. Um ícone que declara
 uma classe `size-*` preserva a própria medida.
 
-## Em uma legenda
+## Em slots de ícone e de mídia
 
-Slots de ícone não criam a moldura automaticamente. Componha `IconTile` somente quando ela fizer
-sentido para a superfície, como na legenda de um [`Content`](/ui/content) emoldurado.
+Slots genéricos de ícone, como `FieldLegend.icon`, não criam a moldura: passe o glifo quando quiser
+só o ícone e componha `IconTile` quando a moldura reforçar a hierarquia.
+
+Os slots de mídia das superfícies já são um `IconTile`: `CardMedia`, `ContentMedia`, `DialogMedia`,
+`DrawerMedia` e `PaneMedia` desenham a moldura sozinhos. Passe só o glifo e escolha `size`,
+`context` e `variant` no próprio slot. Em [`Content`](/ui/content), um `IconTile` passado em
+`media` é adotado pelo slot, que herda o que ele declara, em vez de desenhar uma moldura dentro da
+outra.
 
 ```tsx preview col md
 <Content
   as="fieldset"
   framed
   frameVariant="legend"
-  title={
-    <span className="flex items-center gap-2">
-      <IconTile size="xs">
-        <CarFront />
-      </IconTile>
-      Veículo
-    </span>
-  }
+  title="Veículo"
+  media={<CarFront aria-hidden="true" />}
 >
   <FieldGroup>
     <Field>

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

@@ -41,8 +41,10 @@ subdomínios; um nome repetido de action, reaction, schedule ou Produto de Dados
 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).
+schedules sem `scheduler` (`runtime.scheduler_required`), e quando um schedule ativo aponta para uma
+action não registrada (`runtime.schedule_action_not_found`) ou que não aceita execução pelo sistema
+(`runtime.schedule_action_not_automatable`); veja [Agendador](/docs/scheduler). A declaração de um
+domínio está em [Actions & contratos](/docs/actions).
 
 ## As capacidades
 
@@ -122,6 +124,13 @@ Duas formas de código rodam sem uma requisição: um evento de domínio dispara
 [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.
 
+O runtime aplica a cada reaction a política de entrega declarada — `retry`, `timeout`, `dedup` e
+`concurrency` — e limita as execuções simultâneas de todas elas com `config.maxConcurrentReactions`
+(padrão 10). Uma reaction publica os eventos que declara em `emits`, e a cadeia para em
+`config.maxReactionDepth` saltos (padrão 5). O schedule executa a action como o sistema, sem
+usuário, quando o contrato dela declara `automatable: true`; `isSystemActor(ctx)` identifica essa
+execução no `authorize` e no handler.
+
 `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

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

@@ -5,8 +5,8 @@ title: Agendador
 # Agendador
 
 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.
+`SchedulerAdapter` registra o agendamento, e o runtime executa a action como o sistema, com
+provenance `schedule`, que aparece no audit e no contexto do handler.
 
 ## O contrato
 
@@ -47,7 +47,7 @@ Declare o schedule com `defineSchedule` e registre-o no domínio, ao lado da act
 
 ```ts
 import { createRuntime, defineDomain, defineSchedule } from '@softize/opus/core'
-import { caixaFechar } from './caixa-fechar.ts' // a action 'caixa.fechar', definida com bindAction
+import { caixaFechar } from './caixa-fechar.ts' // a action 'caixa.fechar', preparada abaixo
 
 const fecharDia = defineSchedule({
   name: 'caixa.fechar-dia',
@@ -71,22 +71,63 @@ await runtime.start()
 ```
 
 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
+e que aceita execução pelo sistema, e depois o registra no adapter. As duas conferências acontecem
+antes de inicializar os adapters, e cada mensagem lista os schedules e as actions afetadas. Um nome
+sem action registrada interrompe o `start()` com `runtime.schedule_action_not_found`; uma action
+sem `automatable` nem `public`, com `runtime.schedule_action_not_automatable` (veja a próxima
+seção). 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.
+O schedule executa a action como o sistema, sem uma pessoa por trás. Uma action que exige usuário
+recusa o sistema até que o contrato dela aceite essa execução com `automatable: true`:
+
+```ts
+import { defineContract, isSystemActor } from '@softize/opus/core'
+
+export const caixaFecharContract = defineContract({
+  name: 'caixa.fechar',
+  kind: 'simple',
+  input: z.object({}),
+  output: z.object({ fechados: z.number() }),
+  automatable: true,
+})
+
+export const caixaFechar = bindAction(caixaFecharContract, {
+  // O sistema não tem permissões: aceite-o de forma explícita ao lado da regra das pessoas.
+  authorize: (ctx) => isSystemActor(ctx) || ctx.can('caixa:fechar'),
+  handler: async (ctx) => ({ fechados: await caixa.fecharDia() }),
+})
+```
+
+`automatable` só vale para o disparo de um schedule. A action continua exigindo usuário em
+qualquer outra chamada: uma requisição HTTP sem usuário recebe `auth.unauthenticated`, como antes,
+mesmo que informe uma provenance `schedule`.
+
+Na execução pelo sistema, `ctx.user` é `null`, `ctx.can` nega toda permissão e `ctx.provenance` é
+`{ kind: 'schedule', scheduleName }`. `isSystemActor(ctx)` responde `true` só quando o próprio
+runtime criou essa execução, a partir de um schedule ou do job em background que ele enfileirou; o
+job leva a identidade em uma marca que o runtime grava no envelope, e não pela provenance. Uma tool
+que a action agendada chama por `ctx.ai` não herda a identidade.
+
+Aceite o sistema no `authorize` escrito como função, com `isSystemActor(ctx)`, como no exemplo. Um
+`authorize` em string, como `'user.role == "admin"'`, não tem como reconhecer o sistema: para uma
+action agendada com autorização própria, use a função. Não teste `ctx.provenance.kind` para esse
+fim: qualquer código do servidor que chama `runtime.execute` pode preencher a provenance com
+`schedule`. Sem `authorize`, `automatable` basta. O audit registra o ator como
+`{ id: null, type: 'system' }`, com o nome do schedule na provenance.
+
+Um schedule ativo que aponta para uma action sem `automatable` e sem `public` impede o `start()` com
+`runtime.schedule_action_not_automatable`. Para resolver, declare `automatable: true` no contrato da
+action ou, se o agendamento não deve rodar neste ambiente, `enabled: false` no schedule. Uma action
+`public: true` continua podendo ser agendada, mas fica aberta a qualquer chamador; prefira
+`automatable`.
 
 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,
+novo. Uma falha dentro do pipeline da action, como um erro do `authorize` ou 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`.
 

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

@@ -12,8 +12,8 @@ autorização. `@softize/opus/testing` executa esse fluxo em unidade, sem montar
 `runAction` segue a ordem do runtime: valida a entrada, exige usuário quando a action não é
 `public`, avalia `authorize`, executa o handler e valida a saída. Em `list`, a validação da saída é
 pulada, porque o schema descreve o item e o handler devolve a página. Falhas usam o mesmo
-`ActionError` tipado do runtime, como `validation.invalid_input`, `auth.unauthenticated` e
-`auth.forbidden`.
+`ActionError` tipado do runtime, como `validation.invalid_input`, `auth.unauthenticated`,
+`auth.system_forbidden` e `auth.forbidden`.
 
 Passe a action ligada ao handler, produzida por `bindAction`. O contrato puro não tem handler e só
 executa em modo design, descrito abaixo.
@@ -59,10 +59,22 @@ opcionais.
 | `ai` | Adapter de IA entregue em `ctx.ai`. Sem runtime, `run` e `runStream` não recebem tools. |
 | `meta`, `trace` | Valores de `ctx.meta` e `ctx.trace`. |
 | `loaded` | Substitui os loaders e chega ao `authorize` e ao handler. |
+| `schedule` | Executa como o sistema, no disparo do schedule com esse nome: ignora `user` e `can`. |
 
 `requires` é declarativo também no harness: nada o executa. Um handler que chama `ctx.can` recebe a
 resposta da opção `can`.
 
+Para uma action agendada, a opção `schedule` reproduz a execução pelo sistema com a mesma regra do
+runtime: `ctx.user` é `null`, `ctx.can` nega tudo e `isSystemActor(ctx)` responde `true`. Sem
+`automatable: true` no contrato, a action falha com `auth.system_forbidden`:
+
+```ts
+it('o fechamento diário roda pelo sistema', async () => {
+  const { output } = await runAction(caixaFechar, {}, { schedule: 'caixa.fechar-dia' })
+  expect(output.fechados).toBeGreaterThan(0)
+})
+```
+
 ## Observar efeitos
 
 `runAction` devolve, além de `output`, os efeitos capturados: `emitted` guarda cada `ctx.emit` e

package/src/ui/meta.ts

@@ -123,7 +123,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      'Estruture uma região com título e corpo. No caso comum, declare título, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `as="fieldset"` para agrupar campos sob uma legenda nativa e `frameVariant="legend"` somente quando essa legenda precisar integrar visualmente a borda. Componha ContentHeader apenas quando precisar controlar a anatomia.',
+      'Estruture uma região com título e corpo. No caso comum, declare título, mídia, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `frameVariant="legend"` para integrar visualmente o header à borda e `as="fieldset"` somente para agrupar campos sob uma legenda nativa. Componha ContentHeader apenas quando precisar controlar a anatomia.',
   },
   copyable: {
     name: "copyable",

package/src/ui/react.tsx

@@ -487,6 +487,7 @@ export type {
 export {
   Content,
   ContentHeader,
+  ContentMedia,
   ContentTitle,
   ContentDescription,
   ContentMeta,