@softize/opus 18.1.0 → 18.1.1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -116,7 +116,7 @@ const [open, setOpen] = useState(false)
 
 ## O limite — de propósito
 
-> O look curado não é customizável no app: rodapé-faixa do dialog, elevação no dark, `active:scale`
+> O look curado não é customizável no app: rodapé-faixa do dialog, elevação no dark, `active:brightness-90`
 > do botão, a seta do tooltip — é identidade da casa, igual em todo projeto.
 
 ```tsx preview

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

@@ -4,12 +4,14 @@ O Opus cresce por **reincidência, nunca por especulação**. Quando o mesmo com
 
 ## Onde você aponta
 
-No seu projeto, uma linha por apontamento em `.opus/issues.jsonl` na raiz do repo. Dois tipos:
+Cada apontamento vira uma Issue no repositório do Opus. Antes de abrir, procure uma Issue existente para o mesmo comportamento e comente nela. Dois tipos:
 
 - **`enhancement`** — código genérico que o Opus deveria ganhar (serviria a qualquer projeto). Antes de apontar, confira o que o Opus já tem (o inventário de componentes, os exports, esta doc): se já existe, use.
 - **`bug`** — um defeito ou limitação no próprio Opus, achado usando-o.
 
-```json
+Descreva cada apontamento com estes campos — um exemplo de cada tipo:
+
+```text
 {"type": "enhancement", "behavior": "o comportamento em uma frase.", "file": "src/onde-vive.ts", "kind": "ui|sdk|driver|infra"}
 {"type": "bug", "behavior": "o que quebra ou falta.", "file": "onde se manifesta.", "note": "repro + o workaround aplicado."}
 ```
@@ -20,15 +22,15 @@ O ponto do ciclo é **não bloquear a entrega**. Bateu em um gap ou em um bug do
 
 1. **Contorne local** — componha um wrapper no seu projeto. O Opus entrega _source_, então dá para embrulhar qualquer superfície dele. Nunca edite `node_modules` (some no próximo install).
 2. **Entregue** a feature com o workaround.
-3. **Aponte** no `.opus/issues.jsonl` e siga em frente.
+3. **Aponte** na Issue e siga em frente.
 
 O "depois" — o conserto no Opus — corre em paralelo. Ele não segura o seu trabalho; o único custo de demorar é o workaround viver um pouco mais.
 
 ## Como fecha
 
-O apontamento é colhido e abre uma **Issue no repositório do Opus**, onde a triagem acontece (deduplicada — re-apontar o mesmo é idempotente):
+A triagem acontece em uma **Issue em [github.com/softize-dev/opus](https://github.com/softize-dev/opus/issues)**; procure uma existente antes de abrir. O pacote não coleta apontamentos do seu projeto por conta própria. O desfecho depende do tipo:
 
-- **Enhancement** aceito (com reincidência) → implementado no Opus → sai em um _bump_ → seu projeto atualiza o pin (`opus.json`) e troca o workaround pelo import.
+- **Enhancement** aceito (com reincidência) → implementado no Opus → sai em um _bump_ → seu projeto [atualiza o Opus](upgrading) e troca o workaround pelo import.
 - **Bug** → vira _fix_ + entrada no `CHANGELOG` → no _bump_, o workaround sai.
 
 A régua e a decisão ficam com quem mantém o Opus — hoje, a **Softize**. O registro curado das promoções vive no `PROMOTED.md` do pacote.

package/src/ui/docs/content/data-state.md

@@ -15,7 +15,7 @@ e o tooltip dessa ação. Para uma ação em andamento depois do clique, use `bu
   <DataState empty emptyMessage="Nenhum papel.">
     <div />
   </DataState>
-  <DataState error={{ message: 'detalhe técnico fica no console' }} onRetry={() => undefined}>
+  <DataState error={{ message: 'detalhe técnico que não aparece na tela' }} onRetry={() => undefined}>
     <div />
   </DataState>
 </div>
@@ -28,15 +28,15 @@ tabela continua responsável pela borda: o `Empty` dentro dela vem sem moldura.
 disponível para criação ou vínculo, use `Empty` diretamente, com a moldura tracejada.
 
 ```tsx preview col
-<table className="w-full overflow-hidden rounded-lg border border-border text-sm">
-  <tbody>
+<Table variant="framed">
+  <TableBody>
     <DataState empty emptyMessage="Nenhum usuário." colSpan={3}>
       <tr>
         <td />
       </tr>
     </DataState>
-  </tbody>
-</table>
+  </TableBody>
+</Table>
 ```
 
 ## Propriedades de DataState
@@ -51,3 +51,4 @@ disponível para criação ou vínculo, use `Empty` diretamente, com a moldura t
 | `onRetry` | `() => void \| Promise<void>` | | Recuperação: mostra a ação de tentar de novo somente com ícone no estado de erro. |
 | `retryLabel` | `string` | `'Tentar de novo'` | Nome acessível e tooltip da ação de recuperação. |
 | `colSpan` | `number` | | Em tabela: renderiza o estado como `<tr><td colSpan>` (cabe direto no tbody). |
+| `children` | `ReactNode` | | Obrigatório. Conteúdo renderizado quando não há erro, carregamento nem vazio. |

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

@@ -48,15 +48,15 @@ const db = new Kysely<AdminDB>({
 await db.selectFrom('agents').select(['isDefault', 'roleId']).where('workspaceId', '=', id).execute()
 ```
 
-## Migrações, preparação e seeds
+## Migrações e seeds
 
 Cada etapa possui um papel diferente:
 
 - `opus db migrate` — aplica o **schema idempotente** (`config.schema`, um script SQL
   evolutivo: `IF NOT EXISTS` + guards cobrem nascer do zero e upgrade no mesmo artefato)
   e roda o drift-check entidade ↔ banco na sequência (exit ≠ 0 se divergir).
-- `prepare` — backfill estrutural, prod-safe e idempotente; roda no deploy (depois do migrate).
-- `seed` — cria dados de desenvolvimento e teste. Não é executado em produção.
+- `opus seed` — aplica datasets de desenvolvimento e teste declarados com `defineSeed` e registrados
+  no `opus.config.ts`; só conecta com `NODE_ENV=development` ou `test`. Ver [CLI opus](cli).
 
 ## Campos JSON
 

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

@@ -38,7 +38,8 @@ React substitui a apresentação. `0` e `false` seguem como valores. Ver `EmptyV
 
 ## Moldura e divisórias internas
 
-`variant="framed"` adiciona a superfície e a borda externa. `dividers` desenha apenas as
+`variant="framed"` adiciona a borda externa sem preencher o fundo; na orientação horizontal, só a
+coluna de rótulos recebe um fundo sutil. `dividers` desenha apenas as
 divisórias internas; as duas opções são independentes e podem ser combinadas. `orientation`
 define se a chave fica sobre o valor ou ao lado dele. Na orientação horizontal, todos os valores
 começam depois da mesma coluna de rótulo, com largura padrão de `7rem` em grupos simples e
@@ -62,7 +63,7 @@ começam depois da mesma coluna de rótulo, com largura padrão de `7rem` em gru
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica a superfície e a moldura canônicas ao conjunto. |
+| `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica a moldura canônica ao conjunto, com fundo transparente; na orientação horizontal, a coluna de rótulos recebe fundo sutil. |
 | `dividers` | `boolean` | `false` | Hairlines somente entre os campos, sem exigir moldura externa. |
 | `columns` | `1 \| 2 \| 3 \| 4 \| 'auto'` | `1` | Número fixo de colunas ou distribuição automática por largura mínima. |
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chave sobre o valor ou ao lado dele em cada campo. |

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

@@ -37,7 +37,7 @@ distinta da página.
         <DialogClose asChild>
           <Button variant="ghost">Cancelar</Button>
         </DialogClose>
-        <Button>Criar workspace</Button>
+        <Button>Salvar</Button>
       </ButtonGroup>
     </DialogFooter>
   </DialogContent>
@@ -149,7 +149,7 @@ confirmações e prompts distribuem confirmar e cancelar em duas colunas.
 Em `dialog.choose`, declare pelo menos uma ação e marque exatamente uma ação habilitada com
 `initialFocus`. Essa ação representa a saída segura. Os valores de `result` precisam ser únicos.
 Por padrão, a última ação recebe contexto primário e variante sólida; as anteriores usam contexto
-neutro e variante ghost. Defina `context` ou `variant` na própria ação para substituir o padrão.
+neutro e variante outline. Defina `context` ou `variant` na própria ação para substituir o padrão.
 
 ### Montar o host
 

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

@@ -120,7 +120,7 @@ resultado é vazio e a resolução cai na meta do `t.dict` que viaja no schema.
 | `dict` | `DictType \| LogicalTypeMeta \| DictionaryDescriptor` | — | O dicionário (`t.dict`), a meta lida do schema ou um descritor normalizado. |
 | `value` | `string \| null \| undefined` | — | O código. Vazio renderiza `fallback`. |
 | `presentation` | `'classification' \| 'status' \| 'stage' \| 'plain'` | do dicionário | Sobrepõe o papel só nesta ocorrência. |
-| `context` | contexto de `Badge` | pelo dicionário | Sobrepõe o significado semântico e promove texto a badge. |
+| `context` | contexto de `Badge` | pelo dicionário | Sobrepõe o significado semântico quando a ocorrência já é badge; sozinho, não promove texto a badge. |
 | `variant` | variante de `Badge` | pelo papel | Sobrepõe a variante e promove texto a badge. |
 | `icon` | `boolean \| ReactNode` | `true` | `false` esconde o ícone declarado; um nó substitui. |
 | `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Catálogo nome → componente. |

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

@@ -1,5 +1,3 @@
-# Dock
-
 Ferramentas ancoradas à superfície de trabalho. Um canvas ou um editor raramente comporta mais
 uma faixa de chrome no topo: a trilha da aplicação já ocupa esse papel, e um segundo cabeçalho
 empilha duas faixas com a mesma função. A Dock coloca as ações sobre a própria superfície,
@@ -63,10 +61,33 @@ A barra é uma `toolbar`: as setas andam entre as ações e Home/End vão às po
 por tooltip, então `<TooltipProvider>` precisa existir na raiz do app — o esqueleto do `opus create`
 já monta.
 
+## Propriedades de Dock
+
 | Propriedade | Tipo | Padrão | Descrição |
 | --- | --- | --- | --- |
 | `position` | `'bottom' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Aresta do contêiner onde a barra se ancora. |
 | `label` | `string` | | Nome acessível da barra. |
+| `children` | `ReactNode` | | Os grupos de ações, em `DockGroup`. |
+| `className` | `string` | | Classes adicionais da barra. |
+
+## Propriedades de DockGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | As ações do grupo, em `DockAction`. A divisória antes do grupo é aplicada automaticamente, exceto no primeiro. |
+| `className` | `string` | | Classes adicionais do grupo. |
+
+## Propriedades de DockAction
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `icon` | `ReactNode` | | Ícone exibido no botão. |
+| `label` | `string` | | Nome da ação; vira o nome acessível e o tooltip quando não há `hint`. |
+| `pressed` | `boolean` | | Presente quando a ação liga um modo: aplica o preenchimento e expõe `aria-pressed`. Ausente quando a ação apenas executa. |
+| `disabled` | `boolean` | `false` | Desabilita a ação e a tira da navegação por setas. |
+| `hint` | `ReactNode` | `label` | Conteúdo do tooltip quando ele precisa dizer mais que o rótulo. |
+| `onClick` | `() => void` | | Executa a ação ou alterna o modo. |
+| `className` | `string` | | Classes adicionais do botão. |
 
 ## Propriedades de SurfaceStatus
 

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

@@ -1,5 +1,3 @@
-# Dot
-
 Indicador visual compacto para estados que já têm contexto. O tamanho permanece fixo; `context`
 seleciona o significado e `variant` escolhe ponto sólido ou contornado. Quando a cor reforça significado, `label` fornece o nome
 acessível. Sem `label`, o ponto é decorativo.

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

@@ -11,7 +11,7 @@ entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fe
   </DrawerTrigger>
   <DrawerContent side="right">
     <DrawerHeader>
-      <DrawerTitle>criarTicket</DrawerTitle>
+      <DrawerTitle>Criar ticket</DrawerTitle>
     </DrawerHeader>
     <DrawerBody className="text-sm text-muted-foreground">
       <p>Ação · domínio Suporte</p>

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

@@ -43,10 +43,7 @@ título e descrição agrupados no centro.
     </EmptyDescription>
   </EmptyHeader>
   <EmptyActions>
-    <Button>
-      <Plus />
-      Anexar skill
-    </Button>
+    <Button icon={<Plus />}>Anexar skill</Button>
   </EmptyActions>
 </Empty>
 ```

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

@@ -46,7 +46,7 @@ const runtime = createRuntime({
 // No handler: emite pelo tipo declarado; o core preenche id/timestamp/actor/source.
 handler: async (ctx, input) => {
   const nota = await repo.create(input)
-  ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
+  await ctx.emit('nota.emitida', { id: nota.id, valor: nota.valor })
   return nota
 }
 ```

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

@@ -1,29 +1,33 @@
 ## Campo empilhado
 
 Use `Field` para manter rótulo, controle, ajuda e erro com espaçamento consistente. Na orientação
-vertical, `FieldLabel`, o controle e `FieldDescription` ficam empilhados. Quando o controle usa
-`aria-invalid`, o rótulo acompanha o contexto de erro.
+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.
 
 ```tsx preview col md
 <Field>
-  <FieldLabel htmlFor="workspace-slug">Slug do workspace</FieldLabel>
+  <FieldLabel htmlFor="workspace-slug" className="items-center gap-1.5">
+    <span>Slug do workspace</span>
+    <LabelHelp help="Vira o subdomínio do preview: empresa-x.preview.softize.com.br." />
+  </FieldLabel>
   <Input id="workspace-slug" defaultValue="empresa-x" />
-  <FieldDescription>Vira o subdomínio do preview: empresa-x.preview.softize.com.br.</FieldDescription>
 </Field>
 ```
 
 ## Horizontal com toggle
 
 `orientation="horizontal"` posiciona o controle ao lado do texto. `FieldContent` agrupa título e
-descrição; `FieldTitle` nomeia o campo quando o texto não puder ser um `<label>`.
+descrição; `FieldTitle` exibe o título quando o texto não puder ser um `<label>`. Como ele não se
+vincula ao controle, ligue-o ao controle por `aria-labelledby` para manter o nome acessível.
 
 ```tsx preview col md
 <Field orientation="horizontal">
   <FieldContent>
-    <FieldTitle>Acionar o revisor no handoff</FieldTitle>
+    <FieldTitle id="auto-review-title">Acionar o revisor no handoff</FieldTitle>
     <FieldDescription>Ao abrir o handoff, o agente reviewer entra na sessão automaticamente.</FieldDescription>
   </FieldContent>
-  <Switch id="auto-review" defaultChecked />
+  <Switch id="auto-review" aria-labelledby="auto-review-title" defaultChecked />
 </Field>
 ```
 
@@ -31,21 +35,25 @@ descrição; `FieldTitle` nomeia o campo quando o texto não puder ser um `<labe
 
 `FieldSet` agrupa campos sob uma `FieldLegend`; `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 `ActionForm` define os dois atributos sozinho.
 
 ```tsx preview col md
 <FieldSet>
   <FieldLegend>Novo agente</FieldLegend>
   <FieldGroup>
-    <Field>
+    <Field data-invalid="true">
       <FieldLabel htmlFor="agent-name">Nome</FieldLabel>
       <Input id="agent-name" defaultValue="" aria-invalid placeholder="Ex.: developer" />
       <FieldError>Informe um nome para o agente.</FieldError>
     </Field>
     <FieldSeparator />
     <Field>
-      <FieldLabel htmlFor="agent-prompt">Prompt</FieldLabel>
+      <FieldLabel htmlFor="agent-prompt" className="items-center gap-1.5">
+        <span>Prompt</span>
+        <LabelHelp help="A síntese vira a primeira mensagem da sessão." />
+      </FieldLabel>
       <Textarea id="agent-prompt" rows={3} defaultValue="Veste o papel de developer no workspace Empresa X." />
-      <FieldDescription>A síntese vira a primeira mensagem da sessão.</FieldDescription>
     </Field>
   </FieldGroup>
 </FieldSet>
@@ -56,6 +64,7 @@ descrição; `FieldTitle` nomeia o campo quando o texto não puder ser um `<labe
 | Propriedade | Tipo | Padrão | Descriçã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. |
 
 ## Propriedades de FieldLegend
 
@@ -67,7 +76,7 @@ descrição; `FieldTitle` nomeia o campo quando o texto não puder ser um `<labe
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `errors` | `Array<{ message?: string }>` | | Deduplica e apresenta uma lista de erros; sem conteúdo, o componente não renderiza. |
+| `errors` | `Array<{ message?: string } \| undefined>` | | Deduplica e apresenta uma lista de erros; sem conteúdo, o componente não renderiza. |
 | `children` | `ReactNode` | | Mensagem literal, com prioridade sobre `errors`. |
 
 ## Propriedades de FieldSeparator

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

@@ -75,8 +75,10 @@ pnpm add @softize/opus
 pnpm add -D @softize/base
 pnpm exec opus setup
 pnpm exec base setup
+```
 
-# index.css do app — o tema canônico + os componentes do Opus no scan do Tailwind.
+```css
+/* index.css do app — o tema canônico + os componentes do Opus no scan do Tailwind. */
 @import '@softize/opus/ui/theme.css';
 @source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
 ```
@@ -111,4 +113,4 @@ await runtime.start()
 
 - `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) + `opus db check` (drift entidade ↔ banco). Rode antes de entregar.
+- 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.