@softize/opus 19.0.0 → 20.0.0

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

@@ -8,15 +8,15 @@ de fechamento.
 ```tsx preview
 <Drawer>
   <DrawerTrigger asChild>
-    <Button variant="outline">Ver detalhe</Button>
+    <Button variant="outline">Ver veículo</Button>
   </DrawerTrigger>
   <DrawerContent side="right">
     <DrawerHeader>
-      <DrawerTitle>Criar ticket</DrawerTitle>
+      <DrawerTitle>ABC-1D23</DrawerTitle>
     </DrawerHeader>
-    <DrawerBody className="text-sm text-muted-foreground">
-      <p>Ação · domínio Suporte</p>
-      <p>Campos, entrada/saída, arquivo…</p>
+    <DrawerBody className="space-y-1 text-sm text-muted-foreground">
+      <p>Corolla XEi 2022 · 38.400 km</p>
+      <p>Última revisão em 12 de maio.</p>
     </DrawerBody>
   </DrawerContent>
 </Drawer>
@@ -36,11 +36,11 @@ neutra e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
   </DrawerTrigger>
   <DrawerContent side="left">
     <DrawerHeader>
-      <DrawerTitle>Editar workspace</DrawerTitle>
+      <DrawerTitle>Editar veículo</DrawerTitle>
     </DrawerHeader>
     <DrawerBody className="space-y-2">
-      <Label htmlFor="ws-nome">Nome</Label>
-      <Input id="ws-nome" defaultValue="Empresa X" />
+      <Label htmlFor="vehicle-owner">Responsável</Label>
+      <Input id="vehicle-owner" defaultValue="Marina Alves" />
     </DrawerBody>
     <DrawerFooter>
       <ButtonGroup mode="spaced">
@@ -75,11 +75,11 @@ ruído.
   </DrawerTrigger>
   <DrawerContent layout="continuous">
     <DrawerHeader>
-      <DrawerTitle>Resumo da execução</DrawerTitle>
+      <DrawerTitle>Resumo da revisão</DrawerTitle>
     </DrawerHeader>
     <DrawerBody>
       <p className="text-sm text-muted-foreground">
-        Concluída em 2 minutos, sem falhas registradas.
+        Concluída em 2 horas, sem pendências registradas.
       </p>
     </DrawerBody>
   </DrawerContent>
@@ -98,7 +98,7 @@ título ocupa a folga, as ações vão para o extremo oposto e o botão de fecha
 nó que não seja um desses slots interrompe a renderização com um erro; contexto e conteúdo
 pertencem ao `DrawerBody`.
 
-`DrawerMedia` é a moldura de ícone da casa — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
+`DrawerMedia` é a moldura de ícone do Opus — o mesmo [`IconTile`](/ui/icon-tile) —, útil para
 identificar o tipo do recurso aberto. `DrawerNavigation` carrega o retorno de um fluxo encadeado,
 em que o painel permanece aberto e troca de etapa.
 
@@ -110,7 +110,7 @@ em que o painel permanece aberto e troca de etapa.
   <DrawerContent side="right">
     <DrawerHeader>
       <DrawerNavigation>
-        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DrawerNavigation>
@@ -119,7 +119,7 @@ em que o painel permanece aberto e troca de etapa.
       </DrawerMedia>
       <DrawerTitle>ABC-1D23</DrawerTitle>
       <DrawerActions>
-        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+        <Button variant="ghost" size="icon" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DrawerActions>
@@ -131,15 +131,57 @@ em que o painel permanece aberto e troca de etapa.
 </Drawer>
 ```
 
+Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
+[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
+quadrado `icon-sm` (1.75rem) por padrão.
+
 O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
 aparece no começo do corpo, como texto ou `Alert`.
 
+## Impedir o fechamento durante uma operação
+
+Esc, o clique no overlay e o botão de fechar encerram o painel. Enquanto uma operação não puder ser
+interrompida, passe `closeDisabled` a `DrawerContent`: o botão de fechar continua visível, mas
+desabilitado, e Esc e o clique no overlay deixam de fechar o painel. Se você também passar
+`onEscapeKeyDown`, `onPointerDownOutside` ou `onInteractOutside`, esses handlers continuam sendo
+chamados antes do bloqueio.
+
+`closeDisabled` não alcança as ações que você compõe no painel, como um `Cancelar` com
+`DrawerClose`; desabilite-as pelo mesmo estado da operação. Quando a pessoa precisar responder antes
+de continuar, use [`Dialog mode="alert"`](/ui/dialog), que não fecha pelo clique externo.
+
+## Acessibilidade
+
+- `DrawerTitle` nomeia o painel para tecnologias assistivas. Quando um texto conciso do corpo também
+  precisar descrevê-lo, relacione seu `id` por `aria-describedby` em `DrawerContent`.
+- Com `modal` ativo, o padrão, o foco permanece dentro do painel e o restante da página fica
+  inacessível até o fechamento.
+- Ao fechar, o foco retorna ao gatilho.
+- O botão de fechar tem o nome acessível `Fechar`. Botões só com ícone no cabeçalho precisam de
+  `aria-label`.
+
 ## Propriedades de Drawer
 
-| Propriedade    | Tipo                      | Padrão | Descrição                                                          |
-| -------------- | ------------------------- | ------ | ------------------------------------------------------------------ |
-| `open`         | `boolean`                 |        | Estado no modo controlado.                                         |
-| `onOpenChange` | `(open: boolean) => void` |        | Atualiza o estado para permitir abertura ou fechamento por código. |
+| Propriedade    | Tipo                      | Padrão  | Descrição                                                                    |
+| -------------- | ------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `open`         | `boolean`                 |         | Estado no modo controlado.                                                   |
+| `defaultOpen`  | `boolean`                 | `false` | Abertura inicial no modo não controlado.                                     |
+| `onOpenChange` | `(open: boolean) => void` |         | Recebe as mudanças de abertura, inclusive Esc, overlay e botão de fechar.    |
+| `modal`        | `boolean`                 | `true`  | Mantém foco e interação restritos ao painel aberto e exibe o overlay.        |
+
+## Propriedades de DrawerTrigger
+
+| Propriedade | Tipo        | Padrão  | Descrição                                          |
+| ----------- | ----------- | ------- | -------------------------------------------------- |
+| `asChild`   | `boolean`   | `false` | Usa o filho como gatilho sem criar outro elemento. |
+| `children`  | `ReactNode` |         | Controle que abre o painel.                        |
+
+## Propriedades de DrawerClose
+
+| Propriedade | Tipo        | Padrão  | Descrição                                                   |
+| ----------- | ----------- | ------- | ----------------------------------------------------------- |
+| `asChild`   | `boolean`   | `false` | Aplica o fechamento ao filho; use com `Button`.             |
+| `children`  | `ReactNode` |         | Controle que fecha o painel, como o `Cancelar` do rodapé.   |
 
 ## Propriedades de DrawerContent
 
@@ -147,9 +189,11 @@ aparece no começo do corpo, como texto ou `Alert`.
 | ----------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
 | `side`            | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece.                                                            |
 | `layout`          | `'continuous' \| 'sectioned'`            | `'sectioned'` | Anatomia da superfície inteira; os slots leem esse valor e não o recebem.              |
-| `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no cabeçalho. Desative quando o painel exigir uma ação explícita. |
-| `closeDisabled`   | `boolean`                                | `false`   | Mantém a ação visível e impede fechar enquanto o painel está bloqueado.                    |
+| `showCloseButton` | `boolean`                                | `true`    | Inclui o botão de fechar no cabeçalho. Sem ele, Esc e o overlay continuam fechando o painel. |
+| `closeDisabled`   | `boolean`                                | `false`   | Mantém o botão de fechar visível e desabilitado e impede que Esc e o clique no overlay fechem o painel. |
 | `closeSize`       | `"xs" \| "sm"`                           | `"sm"`    | Define o tamanho da ação circular de fechar.                                               |
+| `className`       | `string`                                 |           | Ajusta o painel, como a largura.                                                           |
+| `children`        | `ReactNode`                              |           | Cabeçalho, corpo e rodapé.                                                                 |
 
 ## Propriedades de DrawerHeader
 

package/src/ui/docs/content/empty-value.md

@@ -1,7 +1,7 @@
-Valor ausente tem uma representação padrão. Nas células de tabela e nos pares de `DetailField`
-aparece o travessão, enquanto a leitura assistiva recebe “Não informado”. As colunas de
-`ActionList` e o `DetailField` já fazem isso sozinhos; um renderer customizado reutiliza a
-primitiva em vez de repetir a condicional.
+Valor ausente tem uma representação padrão. Nas células de tabela e nos pares de
+[`DetailField`](/ui/detail) aparece o travessão, enquanto a leitura assistiva recebe “Não
+informado”. As colunas de [`ActionList`](/ui/action-list) e o `DetailField` já fazem isso sozinhos;
+uma célula ou um componente próprio usa `EmptyValue` em vez de repetir a condicional.
 
 ```tsx preview
 <div className="flex items-center gap-6 text-sm">
@@ -15,8 +15,19 @@ primitiva em vez de repetir a condicional.
 ## O que conta como ausência
 
 `null`, `undefined`, string vazia e string só com espaços. `0`, `false` e coleções vazias são
-valores legítimos: quem apresenta booleanos e listas decide a própria forma. `isAbsentValue`
-exporta a mesma regra para renderers customizados.
+valores legítimos: quem apresenta booleanos e listas decide a própria forma. `isAbsentValue` aplica
+a mesma regra em células e componentes próprios.
+
+```ts
+function isAbsentValue(value: unknown): boolean
+```
+
+```tsx
+import { EmptyValue, isAbsentValue } from '@softize/opus/ui/react'
+
+// Em uma célula própria:
+isAbsentValue(row.phone) ? <EmptyValue compact /> : formatPhone(row.phone)
+```
 
 ## O domínio dá o significado
 
@@ -46,3 +57,6 @@ columns: [
 |---|---|---|---|
 | `label` | `string` | `'Não informado'` | O que a ausência significa neste domínio. |
 | `compact` | `boolean` | `false` | Célula compacta: travessão visível, rótulo só para leitura assistiva. |
+
+Os demais atributos, como `className`, vão para o elemento `span`. `EmptyValue` não aceita
+`children`: o texto entra por `label`.

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

@@ -4,9 +4,9 @@ Use `Empty` quando a própria região está disponível para receber ou criar co
 tracejada diferencia esse espaço de uma estrutura de dados já estabelecida e pode combinar título,
 descrição, mídia e ação.
 
-Para uma lista ou tabela carregada, mas sem registros, use `DataState` ou `ActionList`: a moldura
-sólida preserva a estrutura. Se a região já estiver emoldurada pelo pai, mantenha a borda somente
-no pai para evitar uma moldura dupla.
+Para uma lista ou tabela carregada, mas sem registros, use [`DataState`](/ui/data-state) ou
+[`ActionList`](/ui/action-list): a moldura sólida preserva a estrutura. Se a região já estiver
+emoldurada pelo pai, mantenha a borda somente no pai para evitar uma moldura dupla.
 
 ## Com ícone
 
@@ -78,3 +78,24 @@ ou mídias que tenham presença visual própria.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'default' \| 'icon'` | `'default'` | `icon` aplica uma moldura quadrada e muted; `default` exibe a mídia sem fundo. |
+
+## Propriedades de EmptyHeader
+
+`EmptyHeader` agrupa mídia, título e descrição no centro, com largura limitada para a leitura. Não
+tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyTitle
+
+`EmptyTitle` exibe a situação em destaque. Ele renderiza um `div`, sem nível de heading; quando a
+região precisar de um título na estrutura da página, passe `role="heading"` e `aria-level`. Não tem
+props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyDescription
+
+`EmptyDescription` apresenta a explicação em cor atenuada e sublinha os links filhos diretos. Não
+tem props próprias; aceita as de um elemento `div`.
+
+## Propriedades de EmptyActions
+
+`EmptyActions` empilha e centraliza as ações abaixo do cabeçalho. Não tem props próprias; aceita as
+de um elemento `div`.

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

@@ -4,9 +4,9 @@ title: Eventos
 
 # Eventos
 
-Use eventos quando uma action precisar anunciar um fato sem conhecer seus consumidores.
-`ctx.emit` publica o evento; reactions e integrações podem assiná-lo pelo `EventBusAdapter`. O
-formato declarado permanece o mesmo durante todo o fluxo.
+Use eventos quando uma action precisar anunciar um fato sem conhecer quem vai reagir a ele.
+`ctx.emit` publica o evento; reactions e integrações o recebem pelo `EventBusAdapter`. O formato do
+evento é o mesmo do handler que emite até quem consome.
 
 ## O contrato
 
@@ -24,6 +24,8 @@ interface DomainEvent<T = unknown> {
   tenant?: string | null
   data: T
   source: { action: string; actionId: string; correlation?: string }
+  trace?: TraceContext                           // trace da execução que emitiu
+  meta?: Record<string, unknown>                 // o terceiro argumento de ctx.emit
 }
 ```
 
@@ -32,10 +34,15 @@ interface DomainEvent<T = unknown> {
 ```ts
 import { mittEvents } from '@softize/opus/events/mitt'
 
-const bus = mittEvents()   // in-process (mesmo processo do runtime)
+const bus = mittEvents() // no mesmo processo do runtime
 ```
 
-## No runtime
+O `mitt` entrega pelo nome exato do evento ou por `*`, que recebe todos. Padrões parciais, como
+`nota.*`, não são reconhecidos: assine `*` e filtre no handler.
+
+## Emitir de uma action
+
+Configure o barramento no runtime e declare no binding os eventos que a action emite:
 
 ```ts
 const runtime = createRuntime({
@@ -43,19 +50,72 @@ const runtime = createRuntime({
   eventBus: bus,
 })
 
-// No handler: emite pelo tipo declarado; o core preenche id/timestamp/actor/source.
-handler: async (ctx, input) => {
-  const nota = await repo.create(input)
-  await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
-  return nota
-}
+export const notaEmitir = bindAction(notaEmitirContract, {
+  emits: ['nota.emitida'],
+  handler: async (ctx, input) => {
+    const nota = await repo.create(input)
+    // O runtime preenche id, timestamp, actor, tenant, source e trace.
+    await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
+    return nota
+  },
+})
 ```
 
-Actions declaram no contrato o que emitem (`emits: ['nota.emitida']`); o runtime avisa se
-o handler emitir algo não-declarado (`emitMode`). Uma reaction assina `nota.emitida` e roda
-como sua própria action rastreável (provenance `reaction`).
+`emits` pertence ao binding, como `handler`, e o runtime só o considera em actions `simple` e
+`form`. Quando uma delas declara `emits` e o handler emite um evento fora da lista, o runtime
+registra um aviso no log. Esse aviso vem de `config.warnUndeclaredEmits`, ativo por padrão fora de produção. Sem `emits`
+declarado, nenhum aviso é gerado.
+
+Em uma action `list` ou `view`, o tipo do binding aceita `emits`, mas a lista não entra no manifest
+nem na conferência dos eventos emitidos. Para que a declaração não pareça ter efeito, o runtime
+registra o aviso `runtime.action_field_ignored` quando a action é registrada com `config.dev` ativo,
+o padrão sempre que `config.env` não é `'production'`. O [`opus check`](/docs/cli) aponta o mesmo
+caso com a regra `ignored-by-kind`. Se a operação anuncia um fato, declare-a como `simple` ou `form`.
+
+`config.emitMode` decide o que acontece quando a publicação não é possível. No padrão, `lenient`, a
+falta de `EventBusAdapter` e uma falha de `publish` viram aviso no log e o handler segue. Em
+`strict`, as duas situações interrompem a action com `emit.no_bus` ou `emit.failed`.
+
+## Reagir a um evento
+
+Uma reaction executa código quando um evento é publicado. Como nas actions, a declaração pode ficar
+no código compartilhado e o efeito, no servidor:
+
+```ts
+import { bindReaction, defineReactionContract } from '@softize/opus/core'
+
+// shared/ — qual evento e o que a reação significa.
+export const notaAvisarFinanceiro = defineReactionContract<{ id: string; valor: number }>({
+  name: 'nota.avisar-financeiro',
+  on: 'nota.emitida',
+  description: 'Avisa o financeiro quando uma nota é emitida.',
+})
+
+// api/ — o efeito.
+export const notaAvisarFinanceiroImpl = bindReaction(notaAvisarFinanceiro, {
+  handler: async (ctx, event) => {
+    ctx.log.info('nota emitida', { id: event.data.id, valor: event.data.valor })
+  },
+})
+```
+
+Registre a reaction com as actions, em `defineDomain({ reactions: [notaAvisarFinanceiroImpl] })`
+ou em `runtime.register`. Com reactions registradas, o `start()` exige um `EventBusAdapter` e falha
+com `runtime.eventbus_required` quando ele não existe. `defineReaction` declara tudo num objeto só,
+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.
 
 ## Limites atuais
 
-O driver `mitt` é in-process — sem durabilidade nem entre-processos. Barramentos duráveis/
-distribuídos (Redis, NATS…) entram por reincidência de caso real.
+O driver `mitt` funciona no mesmo processo, sem durabilidade nem entrega entre processos.
+
+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`.
+
+`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/executions.md

@@ -9,7 +9,7 @@ O módulo é experimental e opt-in: instalar o Opus não passa a descobrir crons
 O executor continua dono do estado; este recurso mantém uma fotografia para consulta.
 
 Para colocar trabalho em segundo plano, use [Filas](/docs/queue). Para acompanhar trabalho já
-existente, adapte seu executor à projeção abaixo. Não usar a projeção para decidir reenvio ou retry.
+existente, adapte seu executor à projeção abaixo. Não use a projeção para decidir reenvio ou retry.
 
 ## Publicar uma fotografia
 
@@ -43,8 +43,8 @@ Cron que enfileira trabalho continua com
 `trigger: 'schedule'`; entrar na fila não cria outra execução. Retomada mantém o ID e avança
 revisão/tentativa conforme o executor. A projeção não valida transições de negócio.
 
-Uma falha de projeção lança erro para o adaptador tratar. Registrar essa falha e reconciliar
-depois a partir do executor; não deixar o erro provocar retry de um efeito já realizado.
+Uma falha de projeção lança erro para o adaptador tratar. Registre essa falha e reconcilie
+depois a partir do executor; não deixe o erro provocar retry de um efeito já realizado.
 `observe` não contém proteção automática para o fluxo de negócio do consumidor.
 
 ## Persistência e processos separados
@@ -60,7 +60,7 @@ durável; o aviso não é histórico nem fila de entrega.
 
 `pgExecutionChanges({ connect, onError, channel?, reconnectMs? })` compartilha uma conexão
 LISTEN entre seus assinantes. `connect` deve entregar uma conexão nova, já conectada, dedicada
-e com timeout de conexão configurado. Não fornecer uma conexão emprestada por um pooler
+e com timeout de conexão configurado. Não forneça uma conexão emprestada por um pooler
 transacional. O driver fecha a conexão quando sai o último assinante, registra falhas por
 `onError` e tenta reconectar após `reconnectMs` (padrão: 1.000 ms; mínimo: 100 ms).
 
@@ -87,15 +87,15 @@ async function openProgress(
 }
 ```
 
-Para `authorize(null)`, verificar sessão e direito de acompanhar. Para um aviso, verificar
+Para `authorize(null)`, verifique a sessão e o direito de acompanhar. Para um aviso, verifique
 também tenant, operação e recurso exato. Essa verificação ocorre novamente durante o stream,
 inclusive nos heartbeats e antes de emitir uma invalidação. Heartbeats revalidam a sessão
 independentemente da fila de avisos: a função pode receber um aviso e `null` concorrentemente.
 As actions de leitura devem aplicar a mesma política: filtrar a
 consulta por tenant não substitui autorização.
 
-O cliente recebe somente `event: invalidate` com `{}`. Ao recebê-lo, invalidar as queries das
-actions autorizadas. Manter uma conexão compartilhada no provider da aplicação, não uma por
+O cliente recebe somente `event: invalidate` com `{}`. Ao recebê-lo, invalide as queries das
+actions autorizadas. Mantenha uma conexão compartilhada no provider da aplicação, não uma por
 card. A primeira invalidação e a reconexão exigem nova fotografia; não há `Last-Event-ID` nem
 replay. O navegador pode usar `EventSource` com cookies same-origin e sua reconexão nativa.
 
@@ -105,9 +105,9 @@ de 128 avisos pendentes e 16 frames na saída; excedê-los encerra a conexão pa
 sem acumular um log em memória. Sessão é reavaliada no máximo a cada heartbeat enquanto a
 autorização responde; configure timeout no serviço de autorização para não mantê-la pendente.
 
-IDs, tenant e operação nos avisos são metadados operacionais internos. Não usar CPF, telefone,
+IDs, tenant e operação nos avisos são metadados operacionais internos. Não use CPF, telefone,
 e-mail ou segredo nesses identificadores. PostgreSQL NOTIFY não é uma fronteira de autorização:
-restringir as credenciais e o acesso ao banco. Nada do aviso é copiado para o SSE.
+restrinja as credenciais e o acesso ao banco. Nada do aviso é copiado para o SSE.
 
 ## Detectar ausência de sinal
 

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

@@ -1,9 +1,11 @@
 ## Campo empilhado
 
-Use `Field` para manter rótulo, controle, ajuda e erro com espaçamento consistente. Na orientação
-vertical, `FieldLabel` e o controle ficam empilhados. A ajuda fica junto ao rótulo, com `LabelHelp`,
-o mesmo ícone que o `ActionForm` usa para `FieldSpec.help`. Use `FieldDescription` somente quando a
-frase precisar ficar visível o tempo todo abaixo do controle.
+Use `Field` para manter rótulo, controle, ajuda e erro com espaçamento consistente em um formulário
+montado à mão. Quando o formulário executa uma action, prefira [`ActionForm`](/ui/action-form), que
+monta os mesmos campos a partir do contrato. Na orientação vertical, `FieldLabel` e o controle ficam
+empilhados. A ajuda fica junto ao rótulo, com [`LabelHelp`](/ui/action-form), o mesmo ícone que o
+`ActionForm` usa para `FieldSpec.help`. Use `FieldDescription` somente quando a frase precisar
+ficar visível o tempo todo abaixo do controle.
 
 ```tsx preview col md
 <Field>
@@ -15,7 +17,7 @@ frase precisar ficar visível o tempo todo abaixo do controle.
 </Field>
 ```
 
-## Horizontal com toggle
+## Horizontal com Switch
 
 `orientation="horizontal"` posiciona o controle ao lado do texto. `FieldContent` agrupa título e
 descrição; `FieldTitle` exibe o título quando o texto não puder ser um `<label>`. Como ele não se
@@ -35,7 +37,7 @@ vincula ao controle, ligue-o ao controle por `aria-labelledby` para manter o nom
 
 ## Conjunto com legenda e erro
 
-Use `Content as="fieldset"` para nomear um conjunto de campos relacionados. O título vira a legenda
+Use [`Content`](/ui/content) com `as="fieldset"` para nomear um conjunto de campos relacionados. O título vira a legenda
 nativa, enquanto `FieldGroup` define o espaçamento e `FieldSeparator` marca uma divisão.
 `FieldError` aparece somente quando existe mensagem de erro. Declare `data-invalid="true"` no
 `Field` para que o rótulo acompanhe o contexto de erro; `aria-invalid` marca apenas o controle. O
@@ -70,6 +72,18 @@ nativa, enquanto `FieldGroup` define o espaçamento e `FieldSeparator` marca uma
 </Content>
 ```
 
+## Campo desabilitado
+
+Declare `disabled` no controle para bloquear a edição. Para que o rótulo acompanhe o estado,
+declare também `data-disabled="true"` no `Field`: `FieldLabel` e `FieldTitle` esmaecem junto.
+
+```tsx preview col md
+<Field data-disabled="true">
+  <FieldLabel htmlFor="workspace-client">Cliente</FieldLabel>
+  <Input id="workspace-client" defaultValue="Empresa X" disabled />
+</Field>
+```
+
 ## Conjunto com moldura
 
 Use a moldura para distinguir grupos vizinhos que continuem pertencendo ao mesmo formulário. O
@@ -117,6 +131,7 @@ demais regiões nomeadas. A migração pode ser gradual porque os controles e o
 | -------------- | -------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------- |
 | `orientation`  | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | Direção fixa do campo. `responsive` permanece como alias compatível de `horizontal`.                  |
 | `data-invalid` | `boolean \| 'true' \| 'false'`               |              | Com `true`, aplica o contexto de erro ao campo e ao rótulo. O `ActionForm` define o atributo sozinho. |
+| `data-disabled` | `'true' \| 'false'`                         |              | Com `true`, esmaece `FieldLabel` e `FieldTitle`. Declare `disabled` também no controle. |
 
 ## Propriedades de FieldLegend
 

package/src/ui/docs/content/getting-started.md

@@ -10,20 +10,18 @@ as ferramentas usam essas definições sem exigir schemas e tipos paralelos.
 
 ## O modelo
 
-> Comece pelo problema que o modelo compartilhado resolve antes de conhecer seus arquivos.
-
 As regras de uma aplicação costumam aparecer em vários lugares: validação, transporte, API,
-formulários e documentação. No Opus, entidades, dicts e contratos de action descrevem essas
+formulários e documentação. No Opus, entidades, dicionários e contratos de action descrevem essas
 regras uma vez. A API e a web consomem a mesma definição, enquanto runtime, adapters, UI, CLI
 e verificações ajudam a mantê-la consistente. Cada projeto acrescenta seu domínio sobre essa
 base versionada.
 
 ## Começar do zero
 
-> Projeto novo não se monta à mão: o esqueleto canônico sai do `opus create`, com os
-> pré-requisitos do protocolo, da UI e do preview já plugados — e os gates verdes.
+Para um projeto novo, use `opus create`: ele gera o app com os pré-requisitos do protocolo, da UI e
+do preview já configurados, e os gates passam desde o início.
 
-O Opus e a Base ficam no npm público: leitura não exige token nem configuração de escopo.
+O Opus e a Base ficam no npm público: a instalação não exige token nem configuração de escopo.
 Crie o projeto e materialize as duas camadas antes dos gates:
 
 ```bash
@@ -43,15 +41,21 @@ com `pnpm dlx @softize/opus@<versão> create meu-app` ou desative a quarentena a
 com `pnpm --config.minimum-release-age=0 dlx …`. Dentro do projeto, o workspace exclui Opus e Base
 da quarentena para preservar o par validado.
 
-Nasce com: `opus.config.ts` + domínio-exemplo canônico (0 violações, spec documentada),
-vite + react + tema do Opus (Tailwind v4 CSS-first), dev server na porta que o Maestro
-injeta no preview, `opus.json` (pin), instruções, skills e hooks gerenciados. A Base é
-dona do método geral, memória e revisão; o Opus acrescenta somente o conhecimento do SDK.
+O app criado inclui:
+
+- `opus.config.ts` e um domínio de exemplo documentado, sem violações no `opus check`;
+- Vite, React e o tema do Opus sobre Tailwind v4, configurado por CSS;
+- um dev server que respeita a variável `PORT`, para que um orquestrador de preview escolha a
+  porta;
+- `opus.json`, com a versão adotada, e as instruções, skills e hooks gerenciados.
+
+A Base cuida do método geral de trabalho, da memória e da revisão; o Opus acrescenta o conhecimento
+específico do SDK.
 
-**Monorepo:** a raiz nasce do `--monorepo` e cada app nasce dentro dela — o create
-detecta o `pnpm-workspace.yaml` e gera só o que é do app (sem workspace yaml aninhado),
-**avisando** o que a raiz precisa ter (glob de packages, allowBuilds e exclusões de
-quarentena para Opus/Base) sem tocar nos seus arquivos:
+Em um monorepo, crie primeiro a raiz com `--monorepo` e depois cada app dentro dela. O `create`
+detecta o `pnpm-workspace.yaml` e gera só os arquivos do app, sem um workspace aninhado. O que a raiz
+precisa ter, como o glob de packages, `allowBuilds` e as exclusões de quarentena para Opus e Base,
+aparece como aviso, sem alterar os arquivos da raiz:
 
 ```bash
 pnpm dlx @softize/opus create meu-cliente --monorepo   # a raiz do workspace
@@ -61,13 +65,10 @@ pnpm dlx @softize/opus create apps/portal              # o app (modo detectado)
 
 ## Carregar o Opus em um projeto existente
 
-> O `opus.json` registra a versão usada pelo projeto. Se o arquivo ainda não existe, o setup
-> cria a estrutura necessária antes das demais etapas.
-
-A versão do Opus fica pinada em `opus.json`. O `opus setup` é per-app: grava o marcador,
-o inventário de copy e as projeções específicas do SDK. O `base setup` materializa o
-método geral, memória, agentes e revisão na raiz do repositório. Os componentes vêm do
-barrel `@softize/opus/ui/react`; o tema, por CSS.
+O `opus.json` registra a versão do Opus adotada pelo app; se ele ainda não existe, o setup o cria.
+`opus setup` roda em cada app e grava o marcador, o inventário de copy e as projeções específicas do
+SDK. `base setup` materializa na raiz do repositório o método geral, a memória, os agentes e a
+revisão. Os componentes vêm de `@softize/opus/ui/react`, e o tema, de um arquivo CSS.
 
 ```bash
 # Bootstrap idempotente de um projeto existente.
@@ -78,39 +79,48 @@ pnpm exec base setup
 ```
 
 ```css
-/* index.css do app — o tema canônico + os componentes do Opus no scan do Tailwind. */
+/* index.css do app — o tema do Opus e os componentes do pacote no scan do Tailwind. */
 @import '@softize/opus/ui/theme.css';
 @source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
 ```
 
-## A stack do runtime
+## Montar o runtime
 
-> `createRuntime` compõe a stack a partir de adapters plugáveis. Cada capacidade (data, auth,
-> audit…) é um adapter — troca a implementação sem tocar o domínio.
+No servidor, `createRuntime` reúne as capacidades que o app usa. Cada capacidade, como banco,
+autenticação ou auditoria, é um adapter que pode ser trocado sem alterar o domínio. Os providers da
+interface estão em [Como consumir](/ui/como-consumir).
 
 ```ts
 import { createRuntime } from '@softize/opus/core'
+import { jwtAuth } from '@softize/opus/auth/jwt'
 import { kyselyData } from '@softize/opus/data/kysely'
 import { fastifyServer } from '@softize/opus/server/fastify'
 import { pgAudit } from '@softize/opus/audit/pg'
+import { workspaceDomain } from './domains/workspace/index.ts'
 
 const runtime = createRuntime({
   server: fastifyServer({ app }),
-  data: kyselyData({ db }),       // Kysely + Postgres
-  auth: makeAuthAdapter(),        // gate (IdP)
+  data: kyselyData({ db }),       // Kysely e Postgres
+  auth: jwtAuth({ secret: process.env.JWT_SECRET!, mapUser: (p) => ({ id: String(p.sub) }) }),
   audit: [pgAudit({ pool })],     // trilha de auditoria
   config: { env, i18n: { defaultLocale: 'pt-BR' } },
 })
 
-// Domínios = grupos de actions. Não registrado = não existe.
-runtime.register([workspacesDomain, agentsDomain, skillsDomain])
+// Só o que foi registrado existe para o runtime.
+runtime.register([workspaceDomain])
 await runtime.start()
 ```
 
-## Antes de mexer
+Cada capacidade e o registro de domínios estão detalhados em [Runtime & adapters](/docs/runtime).
+
+## Antes de alterar o projeto
 
-> O protocolo de leitura: a verdade local mora nos docs do repo, não nesta página.
+A documentação do próprio repositório descreve o que é específico dele; esta página cobre só o que
+vale para todo projeto Opus.
 
-- `CLAUDE.md` do repo e do app — o índice local: mapa, gates, gotchas.
-- As `description` das entidades/actions — a spec de negócio, projetada no manifest pelo `opus gen`.
-- Gate de build: `opus check` (convenções das actions e da UI) + `opus copy --check` e `base copy check` (inventário e política de copy) + `opus db check` (drift entidade ↔ banco). Rode antes de entregar.
+- O `CLAUDE.md` do repositório e de cada app reúne o mapa do código, os gates e os cuidados locais.
+- A `description` de entidades e actions registra a regra de negócio, que `opus gen` projeta no
+  manifest.
+- Antes de entregar, rode `opus check` (convenções das actions e da UI), `opus copy --check` e
+  `base copy check` (inventário e política de copy) e, com banco, `opus db check` (divergência entre
+  entidades e banco).