@softize/opus 18.0.1 → 18.1.1

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

@@ -15,7 +15,7 @@ validação, use `Field`.
     }
   />
   <DetailField
-    className="sm:col-span-2"
+    className="col-span-2"
     label="E-mail"
     value="joao.silva@example.com"
     icon={<Mail />}
@@ -25,8 +25,9 @@ validação, use `Field`.
 
 ## Valor ausente
 
-`null`, `undefined`, string vazia ou só com espaços mostram “Não informado”; `empty` troca o
-significado no domínio. `0` e `false` seguem como valores. Ver `EmptyValue`.
+`null`, `undefined`, string vazia ou só com espaços mostram um travessão; a leitura assistiva
+recebe “Não informado”. Uma string em `empty` troca esse significado no domínio, enquanto um nó
+React substitui a apresentação. `0` e `false` seguem como valores. Ver `EmptyValue`.
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -37,11 +38,12 @@ significado no domínio. `0` e `false` seguem como valores. Ver `EmptyValue`.
 
 ## 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`. Quando a superfície exigir
-mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
+começam depois da mesma coluna de rótulo, com largura padrão de `7rem` em grupos simples e
+`8.5rem` na moldura horizontal. Quando a superfície exigir mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
 `className="[--detail-label-width:9rem]"`.
 
 ```tsx preview col
@@ -49,7 +51,7 @@ mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
   <DetailField label="Documento" value="Sem documento" />
   <DetailField label="Fontes" value="NBS e Followize" />
   <DetailField
-    className="sm:col-span-2"
+    className="col-span-2"
     label="E-mail"
     value="cliente@example.com"
     icon={<Mail />}
@@ -61,9 +63,9 @@ mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
 
 | 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` | Colunas responsivas ou distribuição automática por largura mínima. |
+| `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. |
 
 ## Propriedades de DetailField
@@ -73,4 +75,4 @@ mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
 | `label` | `ReactNode` | | A chave do par. |
 | `value` | `ReactNode` | | O valor; `null`, `undefined` e string vazia renderizam a ausência, `0` e `false` seguem como valores. |
 | `icon` | `ReactNode` | | Ícone decorativo antes do par chave/valor. |
-| `empty` | `ReactNode` | `“Não informado”` | O que a ausência significa neste campo: um rótulo ou um nó próprio. |
+| `empty` | `ReactNode` | `“Não informado”` | Uma string dá significado acessível ao travessão; um nó próprio substitui a apresentação. |

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

@@ -16,7 +16,8 @@ Para conteúdo ancorado e não modal, use `Popover`. Para uma lista de ações,
 
 `DialogContent` delimita a superfície. `DialogHeader`, `DialogBody` e `DialogFooter` organizam
 título, conteúdo rolável e ações com o espaçamento da família. A superfície usa o fundo base,
-borda semântica, raio `xl` e elevação para permanecer distinta da página.
+borda transparente no tema claro, borda sutil no escuro, raio `xl` e elevação para permanecer
+distinta da página.
 
 ```tsx preview
 <Dialog>
@@ -32,11 +33,11 @@ borda semântica, raio `xl` e elevação para permanecer distinta da página.
       <Input id="workspace-name" placeholder="Ex.: Empresa X" />
     </DialogBody>
     <DialogFooter>
-      <ButtonGroup mode="spaced" distribution="equal">
+      <ButtonGroup mode="spaced">
         <DialogClose asChild>
-          <Button variant="outline">Cancelar</Button>
+          <Button variant="ghost">Cancelar</Button>
         </DialogClose>
-        <Button>Criar workspace</Button>
+        <Button>Salvar</Button>
       </ButtonGroup>
     </DialogFooter>
   </DialogContent>
@@ -44,8 +45,12 @@ borda semântica, raio `xl` e elevação para permanecer distinta da página.
 ```
 
 O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
-O `ButtonGroup` divide o espaço entre decisões equivalentes no rodapé. O `DialogFooter` organiza
-a faixa, mas não decide a distribuição nem a aparência dos botões.
+O backdrop escurece a página sem aplicar desfoque.
+O fechamento do cabeçalho usa uma ação circular neutra e sutil. `closeSize` escolhe entre `xs` e
+`sm`; o padrão é `sm`.
+O `ButtonGroup` preserva a largura natural das ações por padrão. Use `distribution="equal"`
+somente para decisões deliberadamente equivalentes. O `DialogFooter` organiza a faixa, mas não
+decide a distribuição nem a aparência dos botões.
 `DialogClose` encerra o modal sem exigir estado controlado. Use `open` e `onOpenChange` quando outra
 parte da interface também precisar controlar a abertura.
 
@@ -144,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
 
@@ -273,6 +278,8 @@ botão. O texto informa o efeito real, como `Excluir`, `Revogar acesso` ou `Ence
 | Propriedade       | Tipo        | Padrão | Descrição                                                                                                 |
 | ----------------- | ----------- | ------ | --------------------------------------------------------------------------------------------------------- |
 | `showCloseButton` | `boolean`   | `true` | No modo padrão, inclui a ação de fechamento no header; o modo de alerta exige uma resposta identificável. |
+| `closeDisabled`   | `boolean`   | `false` | Mantém a ação visível e impede o fechamento enquanto a tarefa está bloqueada.                            |
+| `closeSize`       | `"xs" \| "sm"` | `"sm"` | Define o tamanho da ação circular de fechar.                                                  |
 | `className`       | `string`    |        | Ajusta a superfície.                                                                                      |
 | `children`        | `ReactNode` |        | Cabeçalho, corpo, rodapé ou conteúdo próprio.                                                             |
 

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>
@@ -26,7 +26,8 @@ entra pela direita e pode ser fechado por Esc, pelo overlay ou pelo botão de fe
 `side` aceita `top`, `right`, `bottom` e `left`. `DrawerFooter` mantém as ações no rodapé;
 `DrawerClose` fecha o painel sem exigir controle manual de estado. Como no `Dialog`, o cabeçalho
 recebe um divisor inferior e o rodapé usa um divisor superior. O corpo preserva o mesmo alinhamento
-horizontal entre título, conteúdo e ações.
+horizontal entre título, conteúdo e ações. O fechamento do cabeçalho usa uma ação circular neutra
+e sutil; `closeSize` escolhe entre `xs` e `sm`, com `sm` como padrão.
 
 ```tsx preview
 <Drawer>
@@ -42,9 +43,9 @@ horizontal entre título, conteúdo e ações.
       <Input id="ws-nome" defaultValue="Empresa X" />
     </DrawerBody>
     <DrawerFooter>
-      <ButtonGroup mode="spaced" distribution="equal">
+      <ButtonGroup mode="spaced">
         <DrawerClose asChild>
-          <Button variant="outline">Cancelar</Button>
+          <Button variant="ghost">Cancelar</Button>
         </DrawerClose>
         <Button>Salvar</Button>
       </ButtonGroup>
@@ -66,6 +67,8 @@ horizontal entre título, conteúdo e ações.
 | ----------------- | ---------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
 | `side`            | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` | Borda de onde o painel aparece.                                                            |
 | `showCloseButton` | `boolean`                                | `true`    | Inclui a ação de fechamento no header. 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.                    |
+| `closeSize`       | `"xs" \| "sm"`                         | `"sm"`   | Define o tamanho da ação circular de fechar.                                               |
 
 ## Propriedades de DrawerBody
 

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

@@ -1,7 +1,7 @@
-Valor ausente tem uma representação padrão. Em célula compacta de tabela aparece o travessão,
-e a leitura assistiva recebe “Não informado”; em texto corrido, como no `DetailField`, aparece o
-próprio rótulo. 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`
+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.
 
 ```tsx preview
 <div className="flex items-center gap-6 text-sm">

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>
@@ -55,7 +63,8 @@ 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 do campo; `responsive` se torna horizontal a partir do container médio. |
+| `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.

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

@@ -22,13 +22,13 @@ salvo em listas, cards e árvores.
 
 ```tsx preview col md
 const [icon, setIcon] = useState('store')
-const Icon = iconPickerIcons[icon] ?? FileText
+const SelectedIcon = iconPickerIcons[icon] ?? FileText
 
 render(
   <div className="flex items-center gap-3">
     <IconPicker value={icon} onChange={setIcon} className="w-56" />
     <span className="flex items-center gap-2 rounded-md border px-3 py-2 text-sm">
-      <Icon className="size-4 text-muted-foreground" />
+      <SelectedIcon className="size-4 text-muted-foreground" />
       Painel comercial
     </span>
   </div>,

package/src/ui/docs/content/input-otp.md

@@ -71,6 +71,8 @@ render(
 | `maxLength` | `number` | | Quantidade de posições do código. Defina um `InputOTPSlot` para cada posição. |
 | `value` | `string` | | Código no modo controlado. Use com `onChange`. |
 | `onChange` | `(value: string) => void` | | Chamado a cada entrada com o código acumulado. |
+| `onComplete` | `(value: string) => void` | | Chamado quando o código atinge `maxLength`. |
+| `pattern` | `string` | | Expressão regular que o código precisa satisfazer; entradas que não casam são descartadas. Sem `pattern`, qualquer caractere é aceito, inclusive letras. Para somente dígitos, use `'^\\d+$'`. |
 | `disabled` | `boolean` | `false` | Desabilita a digitação em todo o conjunto. |
 
 ## Propriedades de InputOTPSlot

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

@@ -21,7 +21,6 @@ como calendário em uma data; o `Label` continua responsável pelo nome acessív
 
 Quando o campo precisar combinar vários adornos, prefixos ou botões, use `InputGroup`.
 
-
 ## Ação no fim do campo (trailing)
 
 `trailing` posiciona no fim do campo uma ação relacionada ao valor, como limpar ou mostrar uma
@@ -37,7 +36,7 @@ function Demo() {
       onChange={(e) => setQ(e.target.value)}
       trailing={
         q ? (
-          <Button variant="ghost" size="icon-xs" onClick={() => setQ('')}>
+          <Button variant="ghost" size="icon-xs" aria-label="Limpar busca" onClick={() => setQ('')}>
             <X />
           </Button>
         ) : undefined
@@ -167,7 +166,7 @@ Com `InputGroupTextarea`, um addon em `block-end` forma uma região de ações a
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | O subconjunto da escala única que cabe num campo (1.5 · 2 · 1.5 · 1.75rem); os `icon-*` são quadrados. |
-| `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | Contexto semântico herdado de Button. |
+| `context` | `'neutral' \| 'primary' \| 'danger'` | `'neutral'` | Contexto semântico herdado de Button. Com `variant` `solid` ou `subtle` sem contexto declarado, o padrão passa a `'primary'`. |
 | `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'` | Tratamento visual; use `solid` quando a ação precisar de ênfase. |
 
 ### Propriedades de InputGroupInput

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

@@ -3,6 +3,9 @@
 A composição completa usa `ItemMedia` à esquerda, `ItemHeader` (`ItemTitle` +
 `ItemDescription`) no meio e `ItemActions` à direita. Ícone e imagem mantêm uma moldura quadrada
 alinhada ao topo, mesmo quando a descrição ocupa mais linhas. `variant="outline"` desenha a borda.
+O tamanho padrão usa corpo produtivo, `0.75rem` de padding e `0.75rem` entre regiões. `size="sm"`
+mantém o padding horizontal, reduz o padding vertical para `0.5rem` e o espaço entre regiões para
+`0.625rem` em listas densas.
 
 ```tsx preview col
 <Item variant="outline">
@@ -59,7 +62,7 @@ alinhada ao topo, mesmo quando a descrição ocupa mais linhas. `variant="outlin
 
 ## Clicável e compacto
 
-asChild funde o Item em um <a> — a linha inteira vira alvo (hover no fundo). size=sm aperta o respiro; ItemMedia variant=image ancora um avatar.
+`asChild` funde o Item em um `<a>` — a linha inteira vira alvo (hover no fundo). `size="sm"` aperta o respiro; `ItemMedia` na variante padrão recebe um `Avatar`, que já traz a própria moldura.
 
 ```tsx preview col
 <Item asChild size="sm" variant="outline">
@@ -97,7 +100,7 @@ Use `ItemBody` quando a linha também apresenta um valor ou controle que não pe
 </Item>
 ```
 
-`ItemContent` permanece exportado somente para compatibilidade durante a versão 12. Código novo
+`ItemContent` permanece exportado apenas por compatibilidade e está obsoleto. Código novo
 usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 
 ## Propriedades de Item
@@ -122,4 +125,4 @@ usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 
 `ItemHeader`, `ItemTitle`, `ItemDescription`, `ItemBody`, `ItemActions`, `ItemFooter` e
 `ItemSeparator` aceitam as props nativas dos respectivos elementos e não adicionam propriedades
-próprias. `ItemContent` preserva esse mesmo contrato somente durante a migração da versão 12.
+próprias. O `ItemContent` obsoleto preserva esse mesmo contrato por compatibilidade.

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

@@ -27,7 +27,7 @@ reconhecível que o nome da tecla.
 ```tsx preview col-start
 <KbdGroup>
   <Kbd>
-    <Command />
+    <CommandIcon />
   </Kbd>
   <Kbd>
     <CornerDownLeft />
@@ -49,6 +49,7 @@ ação antes de informar seu atalho.
     Buscar workspace
     <KbdGroup>
       <Kbd>⌘</Kbd>
+      <span>+</span>
       <Kbd>K</Kbd>
     </KbdGroup>
   </TooltipContent>

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

@@ -17,16 +17,22 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 const server = createOpusMcpServer(runtime, {
   name: 'meu-app',
   // Valida a identidade da requisição (IdP) → contexto do runtime. Sem isso, roda anônimo
-  // (o `can` nega → só actions públicas). Com isso, o agente age COMO O USUÁRIO.
+  // (sem usuário, só actions `public` rodam). Com isso, o agente age COMO O USUÁRIO.
   resolveContext: async (extra) => auth.resolveFromMcp(extra),
 })
 
 await server.connect(new StdioServerTransport()) // local; HTTP/SSE para remoto
 ```
 
-`ListTools` devolve as actions `ai:enabled` (nome + descrição + JSON Schema do input);
-`CallTool` executa a action pelo `runtime.execute` — validação, auth (`ctx.can`) e audit,
-tudo igual a uma chamada normal. Read-only? Marque só actions de leitura com `ai:enabled`.
+Só actions marcadas com `ai: { enabled: true }` ficam disponíveis, tanto para listar quanto para
+executar. `ListTools` devolve cada uma com `name` (identificador técnico), `title` (a `label`
+legível, quando existe), descrição, JSON Schema do input e, em `_meta`, os Produtos de Dados
+relacionados: `com.softize.opus/data-products` (identificadores) e
+`com.softize.opus/data-product-labels` (nome legível por identificador). `CallTool` recusa, com
+erro, qualquer nome fora dessa lista; os demais seguem pelo `runtime.execute` — validação,
+autorização e audit, tudo igual a uma chamada normal. Read-only? Marque só actions de leitura
+com `ai:enabled`: a marcação decide o que o cliente MCP pode executar, e a autorização do
+contexto continua valendo por cima.
 
 ## Escolher entre integração interna e MCP
 

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

@@ -104,6 +104,14 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 </Menu>
 ```
 
+## Propriedades de Menu
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Estado do painel no modo controlado, como no menu de contexto. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando o painel abre ou fecha. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
+
 ## Propriedades de MenuItem
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -137,3 +145,22 @@ próprias além das de DOM.
 |---|---|---|---|
 | `value` | `string` | | Valor selecionado no grupo. |
 | `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outro `MenuRadioItem`. |
+
+## Propriedades de MenuRadioItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Valor que o item entrega ao `MenuRadioGroup` quando é selecionado. |
+| `disabled` | `boolean` | `false` | Impede a seleção do item. |
+
+## Propriedades de MenuLabel
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `inset` | `boolean` | | Alinha o rótulo com itens que possuem ícone. |
+
+## Propriedades de MenuSubTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `inset` | `boolean` | | Alinha o gatilho do submenu sem ícone com os itens que possuem ícone. |