@softize/opus 13.0.0 → 14.0.0

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

@@ -28,10 +28,14 @@ para agente.
 
 ## Tamanhos
 
-size sm/default/lg — o fallback acompanha o tamanho. sm para listas densas, lg para cabeçalho de
-workspace.
+`size` usa a escala única dos controles: o avatar de uma linha mede o mesmo que o controle ao lado
+(`sm` 2rem, `default` 2.25rem, `lg` 2.5rem); `xs` (1.5rem) é a lista densa. O fallback e o selo
+acompanham o tamanho.
 
 ```tsx preview
+<Avatar size="xs">
+  <AvatarFallback>AL</AvatarFallback>
+</Avatar>
 <Avatar size="sm">
   <AvatarFallback>AL</AvatarFallback>
 </Avatar>
@@ -86,7 +90,7 @@ excedente — os membros do workspace Empresa X.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato; o fallback e o selo acompanham a escala. |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Diâmetro do retrato na escala única dos controles (1.5 · 2 · 2.25 · 2.5rem); o fallback e o selo acompanham. |
 
 ## Propriedades de AvatarImage
 

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

@@ -2,8 +2,7 @@
 
 `context` declara a hierarquia ou o risco da ação; `variant` escolhe o tratamento visual. Use
 `primary` para a ação principal, `neutral` para ações de apoio e `danger` quando a ação tiver uma
-consequência perigosa. `default`, `secondary` e `destructive` permanecem apenas como aliases de
-compatibilidade.
+consequência perigosa.
 
 ```tsx preview
 <Button>Criar workspace</Button>
@@ -16,28 +15,45 @@ compatibilidade.
 
 ## Tamanhos
 
-O tamanho icon exige `aria-label`, porque não há texto visível. Os botões só-ícone vêm em três tamanhos: `icon` (2.25rem), `icon-sm` (2rem, para uma fileira densa como o cabeçalho) e `icon-xs` (1.5rem, para uma ação dentro de um campo, como o `trailing` de Input ou Select).
+`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.
+
+| Nome | Medida | Uso |
+|---|---|---|
+| `xs` | 1.5rem | Ação dentro de um campo (`InputGroupButton`). |
+| `sm` | 2rem | Toolbar e cabeçalho densos, ao lado de `Select` e `Tabs` `sm`. |
+| `default` | 2.25rem | A linha padrão, a mesma de `Input`. |
+| `lg` | 2.5rem | Chamada principal com mais área de toque. |
+| `icon-xs` | 1.5rem | Ação só de ícone dentro de um campo, como o `trailing` de Input ou Select. |
+| `icon-sm` | 1.75rem | Ação só de ícone dentro de uma linha ou card; é o quadrado de `ActionTrigger` com `icon` e das setas do pager de `ActionList`. |
+| `icon` | 2.25rem | Ação só de ícone na linha padrão. |
+| `icon-lg` | 2.5rem | Ação só de ícone ao lado de um `lg`. |
 
 ```tsx preview
+<Button size="xs">Mínimo</Button>
 <Button size="sm">Pequeno</Button>
 <Button>Padrão</Button>
 <Button size="lg">Grande</Button>
-<Button size="icon" aria-label="Novo"><Plus /></Button>
-<Button size="icon-sm" variant="ghost" aria-label="Novo"><Plus /></Button>
 <Button size="icon-xs" variant="ghost" aria-label="Novo"><Plus /></Button>
+<Button size="icon-sm" variant="ghost" aria-label="Novo"><Plus /></Button>
+<Button size="icon" aria-label="Novo"><Plus /></Button>
+<Button size="icon-lg" aria-label="Novo"><Plus /></Button>
 ```
 
 ## Estados
 
-busy = ação em andamento (DEPOIS do clique): o Spinner e o disabled vêm do botão. Com icon, o
-Spinner TROCA o ícone (não soma). Não confunda com carregar conteúdo (ANTES) — isso é Spinner
-centralizado/Skeleton em um nível de página.
+busy = ação em andamento (DEPOIS do clique): o Spinner e o disabled vêm do botão. `icon` recebe o
+elemento do ícone e o dimensiona pelo `size`; com icon, o Spinner TROCA o ícone (não soma). Não
+confunda com carregar conteúdo (ANTES) — isso é `DataState` ou `Skeleton` em um nível de página.
 
 ```tsx preview
 <Button disabled>Desabilitado</Button>
 <Button busy>Salvando…</Button>
-<Button icon={Plus}>Novo</Button>
-<Button icon={Plus} busy>Novo</Button>
+<Button icon={<Plus />}>Novo</Button>
+<Button icon={<Plus />} busy>Novo</Button>
 ```
 
 ## Como outro elemento (asChild)
@@ -57,10 +73,10 @@ buttonVariants serve para o caso sem filho único.
 |---|---|---|---|
 | `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | A hierarquia ou o risco comunicado pela ação. |
 | `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'solid'` | O tratamento visual aplicado ao contexto. |
-| `size` | `'default' \| 'sm' \| 'lg' \| 'icon' \| 'icon-sm' \| 'icon-xs'` | `'default'` | O tamanho. Os icon* são quadrados (2.25/2/1.5rem) para botões só de ícone, com `aria-label`. |
+| `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`. |
 | `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.ElementType` | | Ícone à esquerda (ex.: icon={Plus}). No busy é trocado pelo Spinner — não soma. |
+| `icon` | `React.ReactNode` | | Ícone à esquerda, como nó (ex.: `icon={<Plus />}`); o glifo segue o `size`. No busy é trocado pelo Spinner — não soma. |
 
 ## ButtonGroup
 
@@ -83,7 +99,7 @@ variações.
 
 ```tsx preview
 <ButtonGroup>
-  <Button icon={Play}>Rodar agente developer</Button>
+  <Button icon={<Play />}>Rodar agente developer</Button>
   <ButtonGroupSeparator />
   <Button size="icon" aria-label="Mais opções">
     <ChevronDown />
@@ -102,7 +118,7 @@ semântica de outro elemento, como `label`.
     <GitBranch />
     empresa-x-api
   </ButtonGroupText>
-  <Button variant="outline" icon={RotateCw}>Sincronizar</Button>
+  <Button variant="outline" icon={<RotateCw />}>Sincronizar</Button>
 </ButtonGroup>
 ```
 

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

@@ -1,3 +1,7 @@
+O calendário fala pt-BR por padrão: nomes de mês e de dia vêm do `locale` (`ptBR` de
+`date-fns/locale`) e os controles de navegação têm rótulos acessíveis em português. Passe outro
+`locale` para trocar o idioma; `labels` sobrescreve rótulos individualmente.
+
 ## Dia único
 
 mode=single guarda uma Date — controle por selected/onSelect. defaultMonth abre o calendário no mês certo sem mexer na seleção.
@@ -60,3 +64,12 @@ captionLayout=dropdown troca o título do mês por seletores de mês e ano — b
 | `disabled` | `Matcher` | | Datas não selecionáveis — uma Date, um array, um { from, to } ou um predicado (date) => boolean. |
 | `buttonVariant` | `Button['variant']` | `'ghost'` | A variante dos botões de navegação (anterior/próximo). |
 | `showOutsideDays` | `boolean` | `true` | Mostra os dias do mês vizinho que completam a primeira e a última semana. |
+| `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
+
+Cada dia é um `CalendarDayButton` — um `Button` ghost quadrado que recebe os modificadores do
+dia (`selected`, `range-start`, `today`…). Use `components={{ DayButton: … }}` para
+decorar o dia (um marcador de evento, por exemplo) partindo dele em vez de reimplementar o
+foco e a seleção.

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

@@ -47,3 +47,29 @@ Para painel com estrutura: cada slot é dono do próprio padding (como o Dialog)
   </CardFooter>
 </Card>
 ```
+
+## Ação no cabeçalho
+
+`CardAction` é o slot de ação do header (um botão ou menu). Quem compõe posiciona — em geral um
+`CardHeader` em `flex-row` com o título de um lado e a ação do outro.
+
+```tsx preview col
+<Card>
+  <CardHeader className="flex-row items-start justify-between">
+    <div>
+      <CardTitle>Empresa X</CardTitle>
+      <CardDescription>3 agentes vinculados.</CardDescription>
+    </div>
+    <CardAction>
+      <Button size="sm" variant="outline">Editar</Button>
+    </CardAction>
+  </CardHeader>
+</Card>
+```
+
+## Propriedades de Card
+
+| 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. |

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

@@ -91,3 +91,23 @@ continua valendo — é o caso degenerado do protocolo.
 Reidratação: passe `initialMessages` com o histórico persistido e troque a `key` do
 componente ao trocar de conversa. O rótulo do indicador é customizável por
 `humanizeTool={(name) => '…'}`.
+
+## Propriedades de Chat
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `send` | `(messages: ChatMessage[]) => Promise<string> \| AsyncIterable<ChatEvent>` | | Modo autogerenciado: envia o histórico e devolve a resposta inteira ou um stream de eventos. Ignorado no modo controlado. |
+| `messages` | `ChatTranscriptItem[]` | | Modo controlado: o transcript vem do app; com ele, `onSend`, `busy` e `activity` assumem. |
+| `onSend` | `(text: string) => void \| boolean \| Promise<void \| boolean>` | | Modo controlado: recebe o texto enviado; retornar `false` devolve o texto ao composer. |
+| `busy` | `boolean` | | Modo controlado: trava o composer enquanto o turno corre. |
+| `activity` | `string \| null` | `undefined` | Indicador vivo: `null` mostra “Pensando…”, string mostra o rótulo; `undefined` esconde. |
+| `notice` | `ReactNode` | | Aviso do app acima do composer (credencial, agente desatualizado…). |
+| `composerActions` | `ReactNode` | | Seletores discretos na barra do composer (agente, app, escopo). |
+| `composerClassName` | `string` | | Ajusta o contêiner externo do composer sem alcançar o DOM interno. |
+| `greeting` | `string` | | Texto do estado vazio; some quando a conversa começa. |
+| `empty` | `ReactNode` | | Estado vazio composto pelo app; vence `greeting` quando os dois existem. |
+| `initialMessages` | `ChatMessage[]` | | Histórico inicial do modo autogerenciado; troque a `key` ao trocar de conversa. |
+| `kickoff` | `() => Promise<string> \| AsyncIterable<ChatEvent>` | | Conversa que começa pelo assistente, uma vez, quando o transcript nasce vazio. |
+| `renderArtifact` | `(artifact: ChatArtifact) => ReactNode` | link com o título | Render do evento `artifact`. |
+| `humanizeTool` | `(name: string, detail?: string) => string` | pt-BR embutido | Rótulo humano do tool em uso no indicador vivo. |
+| `placeholder` | `string` | `'Escreva uma mensagem…'` | Placeholder do composer. |

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

@@ -5,18 +5,39 @@ title: CLI opus
 # CLI opus
 
 O Opus traz um CLI que cobre o ciclo: faz o bootstrap, gera artefatos a partir das declarações,
-valida as convenções e expõe o estado vivo para os agentes via MCP.
+valida as convenções e expõe o estado vivo para os agentes via MCP. `opus --help` lista os
+comandos e `opus <comando> --help` detalha cada um.
 
 ## Gates
 
-> Use o check no CI e antes de entregar uma mudança. Ele informa quais contratos precisam de
-> ajuste e encerra com sucesso quando não encontra violações.
+> Use os gates no CI e antes de entregar uma mudança. Cada um informa o que precisa de ajuste e
+> encerra com sucesso (exit 0) quando não encontra violação.
 
 ```bash
-opus check src    # valida as convenções das actions (exit ≠ 0 se violar)
-opus db check     # drift entidade ↔ banco (read-only)
-opus db migrate   # aplica o schema idempotente + drift-check na sequência
-opus seed check   # valida bindings, dependências, ciclos e comandos paralelos
+opus check src        # convenções das actions e da UI (exit ≠ 0 se violar)
+opus copy --check     # inventário de copy ausente ou desatualizado
+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
+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.
+
+### Hook de pré-push
+
+O hook Git que `opus setup` instala roda, antes de cada push: `opus copy --check`; depois
+`opus pre-push materialization` na raiz, para confirmar que os artefatos Opus materializados
+(skills, hooks, instruções) correspondem à versão adotada; e `opus check` em cada app com
+`opus.json`. Qualquer um com exit ≠ 0 bloqueia o push. Os mesmos comandos podem ser executados à
+mão para antecipar o resultado:
+
+```bash
+opus pre-push                  # o mesmo opus check no diretório atual
+opus pre-push apps/portal      # o check de um app específico
+opus pre-push materialization  # só a freshness dos artefatos materializados
 ```
 
 ## Seeds de desenvolvimento e teste
@@ -31,9 +52,11 @@ opus seed apply customers.scenarios --profile smoke --scope local
 opus seed verify customers.scenarios --profile smoke --scope local
 ```
 
-`apply` converge quando repetido; não há reset ou truncate no contrato. A skill
-`$create-opus-seed` estrutura um novo dataset, e `$apply-opus-seed` opera um seed registrado pela
-mesma CLI.
+`--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
+truncate no contrato. A skill `$create-opus-seed` estrutura um novo dataset, e
+`$apply-opus-seed` opera um seed registrado pela mesma CLI.
 
 ## Geração e introspecção
 
@@ -41,23 +64,52 @@ mesma CLI.
 > é um lockfile versionado. A diferença do manifest torna a revisão objetiva.
 
 ```bash
-opus gen              # manifest / openapi / docs / stubs a partir do opus.config.ts
-opus introspect       # modelo da estrutura (actions/reactions/schedules + wiring)
+opus gen                                    # manifest / openapi / docs / stubs a partir do opus.config.ts
+opus gen --config ./apps/api/opus.config.ts # config fora do diretório atual
+opus gen --output ./custom/gen              # pasta de saída (default: a do config, ou ./.gen)
+opus copy                                   # inventário semântico de copy dos contratos
+opus introspect                             # modelo da estrutura (actions/reactions/schedules + wiring)
 opus introspect --json
 ```
 
-## Bootstrap e templates
+`opus copy` projeta os textos de `defineAction`/`defineContract` no inventário que a política de
+copy da `@softize/base` valida. O caminho vem de `base.json` (`copy.inventory`; default
+`.base/copy-inventory.json` na raiz Git), a escrita é atômica e o arquivo gerado deve ser
+versionado. `--check` compara sem escrever e falha quando o inventário está ausente,
+desatualizado ou contém copy dinâmica não declarada.
+
+`--config` vale para `gen`, `db` e `seed` e sempre aponta para um caminho dentro do projeto. O
+`gen` aceita `--force` por compatibilidade, mas a flag não altera nada: a saída mora em um
+diretório dedicado e é sempre sobrescrita.
+
+## Banco
+
+> Os comandos `db` carregam o `opus.config.ts` e abrem conexão; por isso rodam num runner isolado
+> via `tsx`. O padrão é um schema idempotente: um script SQL evolutivo re-rodável, não migrations
+> versionadas.
+
+```bash
+opus db check      # compara o schema do banco com as entidades (read-only)
+opus db migrate    # aplica o schema idempotente e roda o drift-check na sequência
+opus db scaffold   # rascunho kysely a partir do diff, como referência para escrever o SQL
+```
+
+`db scaffold` gera um rascunho para revisão à mão; a verdade continua sendo o script. `db migrate
+down` está aposentado e encerra com erro: sem histórico de migrations não há o que reverter —
+rollback é editar o schema e rodar `opus db migrate` de novo. O `opus.config.ts` precisa expor a
+factory lazy `database`, as entidades (ou domínios) e, opcionalmente, `schema` e `migrations`;
+`opus db --help` detalha.
+
+## Bootstrap
 
 > `create` scaffolda um app novo com os pré-requisitos plugados; `setup` é per-app
-> (idempotente, nunca sobrescreve o seu); `add` copia um template do catálogo empacotado.
+> (idempotente, nunca sobrescreve o seu).
 
 ```bash
-opus create meu-app              # app canônico do zero: protocolo + UI + preview + automação
+opus create meu-app                 # app canônico do zero: protocolo + UI + preview + automação
 opus create meu-cliente --monorepo  # a RAIZ de um workspace (apps/* + packages/*)
-opus create apps/portal          # dentro de um workspace: só o app (modo detectado)
-opus setup                       # grava opus.json e materializa a camada específica do SDK
-opus list                        # lista os templates disponíveis
-opus add action-form             # copia um template do catálogo para o projeto
+opus create apps/portal             # dentro de um workspace: só o app (modo detectado)
+opus setup                          # grava opus.json e materializa a camada específica do SDK
 ```
 
 O esqueleto do `create` versiona com o Opus (sai do mesmo pacote que o SDK que ele

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

@@ -50,6 +50,42 @@ frase. Não copie as regras da Base para cá.
 | placeholder de campo ou busca | `placeholder` |
 | `Select.emptyText` e grupos de opção | `empty-state` e `heading` |
 | confirmação local do `ActionTrigger` | `title`, `dialog-body` e `button` |
+| `dialog.alert/confirm/prompt/choose` — `title`, `description`/`body`, `action`/`cancel`, `actions[].label` | `title`, `dialog-body`, `button` (e `placeholder` no `prompt`) |
+| filhos de `TooltipContent` | `label` |
+| `LabelHelp.help` | `helper-text` |
+| `emptyMessage`, `errorMessage`, `retryLabel` de `DataState`, `PageState`, `ActionList`, `ActionListDialog` e `ActionView` | `empty-state`, `error`, `button` |
+
+O tooltip entra como `label` porque nomeia um controle icon-only: é um fragmento curto, sem
+ponto final, e a Base não define um papel próprio para tooltip. Texto de ajuda que precisa de
+frase completa pertence ao `help` de um campo (contrato ou `LabelHelp`), não ao tooltip.
+
+## Alcance do inventário além das props
+
+Quem vê o gate reprovar ou precisa de uma dispensa deve saber o que o extrator alcança sem
+declaração adicional:
+
+- **Diálogos imperativos.** `dialog.confirm({ title, description, action })` e as demais
+  respostas (`alert`, `prompt`, `choose`) entram no inventário como se fossem props de um
+  `ActionFormDialog`; o campo do diagnóstico é `dialog.confirm().title`,
+  `dialog.choose().actions[0].label` etc. Constantes locais resolvem normalmente. Uma função
+  que devolve template (`description: describe(nome)`) gera o diagnóstico `content` habitual e
+  se declara em `copy.dynamic` como `message-template`. Opções construídas em tempo de execução
+  ou mutadas depois de declaradas reprovam como estrutura, porque nenhum texto pode ser
+  atribuído a elas.
+- **`LabelHelp` como filho.** `<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>` inventaria
+  `Nome` como label e a ajuda como helper-text; o ícone não torna o label opaco. Um wrapper
+  local com o mesmo nome continua opaco, porque o extrator não infere o que ele renderiza.
+- **Rótulos em array literal local.** Quando um componente mapeado lê `item.label` (ou a chave
+  destruturada) dentro de `map`, `forEach`, `filter` ou `for…of` sobre um array literal do
+  mesmo arquivo, cada literal do array vira um texto na linha em que foi escrito, em vez de um
+  diagnóstico sobre a prop. `filter`, `slice`, `toSorted` e `toReversed` podem ficar entre o
+  array e a iteração. O limite é deliberado: o array precisa ser literal e declarado no mesmo
+  arquivo; o elemento só pode ser lido (`item.chave`), nunca passado adiante, espalhado ou
+  atribuído; o callback não pode receber o próprio array como terceiro parâmetro; e nenhum
+  elemento pode ter a chave dinâmica. Arrays importados, derivados por spread ou por
+  concatenação continuam gerando o diagnóstico da prop.
+- **Elementos JSX genéricos.** `<ActionList<Input, Row> emptyMessage="…">` extrai igual a
+  `<ActionList emptyMessage="…">`.
 
 Copy visual e nome acessível são superfícies cumulativas. Um `aria-label` estático nomeia
 um controle icon-only, mas não torna aceitável nem invisível ao gate um texto visual opaco.

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

@@ -48,3 +48,18 @@ render(
   />,
 )
 ```
+
+## Propriedades de Composer
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Texto controlado; o dono do estado é quem compõe. |
+| `onChange` | `(value: string) => void` | | Recebe cada alteração do texto. |
+| `onSubmit` | `() => void` | | Enter (sem Shift) ou o botão enviar; só dispara quando dá para enviar. |
+| `onHistoryPrevious` / `onHistoryNext` | `() => boolean` | | Navegação por ↑/↓ no histórico do dono; retorne `true` quando a tecla foi consumida. |
+| `busy` | `boolean` | `false` | Trava o composer enquanto o turno corre; o enviar vira spinner. |
+| `submitDisabled` | `boolean` | `false` | Gate extra de envio além de vazio e `busy` (ex.: falta escolher o app). |
+| `placeholder` | `string` | `'Escreva uma mensagem…'` | Texto de orientação do campo. |
+| `rows` | `number` | `1` | Linhas iniciais do textarea; ele cresce com o conteúdo. |
+| `autoFocus` | `boolean` | | Foca o campo ao montar. |
+| `actions` | `ReactNode` | | Controles discretos à esquerda do enviar; presente, o composer vira duas linhas. |

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

@@ -22,7 +22,8 @@ render(
 
 Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
 `ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
-uma descrição, um metadado e uma região de ações.
+uma descrição, um contador (`ContentMeta`) e uma região de ações — a mesma anatomia de `PageHeader`,
+com os mesmos slots e o mesmo layout; só o nível do heading e a hierarquia visual mudam.
 
 ```tsx preview col
 render(
@@ -42,3 +43,18 @@ render(
 
 As duas formas geram os mesmos elementos, estilos e `data-slot`. `opus check` reprova slots fora
 do pai correto, filhos estruturais indiretos e a mistura de shorthand com composição explícita.
+
+## Propriedades de Content
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `title` | `ReactNode` | | Forma curta: título da região (vira o heading ligado à `section`). |
+| `count` | `number` | | Forma curta: total de itens ao lado do título — o mesmo `count` de `Page`. |
+| `description` | `ReactNode` | | Forma curta: frase de apoio sob o título. |
+| `actions` | `ReactNode` | | Forma curta: ações alinhadas à direita do header. |
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | herdado | 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
+`ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`
+próprios — a hierarquia é declarada em `Content`. `ContentHeader` não existe fora de `Content`.

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

@@ -29,3 +29,11 @@ Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar n
   copiar (3s)
 </Copyable>
 ```
+
+## Propriedades de Copyable
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | O texto que vai para a área de transferência no clique. |
+| `feedbackMs` | `number` | `1500` | Duração do estado “copiado”, em milissegundos. |
+| `children` | `ReactNode` | | Rótulo ao lado do ícone; sem ele, o controle é só o ícone com nome acessível. |

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

@@ -1,19 +1,21 @@
 ## Estados
 
-Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta. O
-carregamento usa `Spinner`; o vazio preserva uma moldura sólida; e o erro apresenta uma mensagem
-segura, sem expor detalhes técnicos. Para uma ação em andamento depois do clique, use `busy` em
-`Button`.
+Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta. As
+superfícies são as mesmas de `PageState`, na escala de uma seção: o carregamento é um contêiner
+`role="status"` com o `Spinner`; o vazio compõe `Empty` com moldura sólida e `emptyMessage` como
+título; o erro é um `Alert` de contexto `danger` com uma mensagem segura, sem expor detalhes
+técnicos, e o botão de recuperação quando há `onRetry`. Para uma ação em andamento depois do
+clique, use `busy` em `Button`.
 
 ```tsx preview col
 <div className="w-full space-y-3">
   <DataState loading>
     <div />
   </DataState>
-  <DataState empty emptyText="Nenhum papel.">
+  <DataState empty emptyMessage="Nenhum papel.">
     <div />
   </DataState>
-  <DataState error={{ message: 'detalhe técnico fica no console' }}>
+  <DataState error={{ message: 'detalhe técnico fica no console' }} onRetry={() => undefined}>
     <div />
   </DataState>
 </div>
@@ -22,13 +24,13 @@ segura, sem expor detalhes técnicos. Para uma ação em andamento depois do cli
 ## Dentro de uma tabela
 
 Em uma tabela já emoldurada, passe `colSpan` para ocupar uma linha inteira dentro de `<tbody>`. A
-tabela continua responsável pela borda, evitando uma segunda moldura no estado vazio. Para uma
-região disponível para criação ou vínculo, use `Empty`.
+tabela continua responsável pela borda: o `Empty` dentro dela vem sem moldura. Para uma região
+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>
-    <DataState empty emptyText="Nenhum usuário." colSpan={3}>
+    <DataState empty emptyMessage="Nenhum usuário." colSpan={3}>
       <tr>
         <td />
       </tr>
@@ -42,8 +44,10 @@ região disponível para criação ou vínculo, use `Empty`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `loading` | `boolean` | | Carregando (antes do conteúdo) — mostra o Spinner centralizado. |
-| `empty` | `boolean` | | Sem itens — mostra o emptyText. |
-| `emptyText` | `string` | | Texto do vazio (pt-BR, ex.: "Nenhum papel."). |
-| `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica não vai para tela (use errorText). |
-| `errorText` | `string` | `'Não foi possível carregar.'` | Aviso de erro, orientado ao usuário. |
+| `empty` | `boolean` | | Sem itens — compõe `Empty` com o `emptyMessage`. |
+| `emptyMessage` | `string` | `'Nada por aqui.'` | Frase do vazio (ex.: "Nenhum papel."). |
+| `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica não vai para tela (use `errorMessage`). |
+| `errorMessage` | `string` | `'Não foi possível carregar.'` | Título do aviso de erro, orientado à pessoa. |
+| `onRetry` | `() => void \| Promise<void>` | | Recuperação: mostra o botão de tentar de novo no estado de erro. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botão de recuperação. |
 | `colSpan` | `number` | | Em tabela: renderiza o estado como `<tr><td colSpan>` (cabe direto no tbody). |

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

@@ -9,7 +9,7 @@ validação, use `Field`.
     label="Estágio"
     value={
       <DictionaryValue
-        dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
+        dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospecto' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
         value="prospect"
       />
     }
@@ -56,3 +56,21 @@ mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
   />
 </DetailGroup>
 ```
+
+## Propriedades de DetailGroup
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica a superfície e a moldura canônicas ao conjunto. |
+| `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. |
+| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chave sobre o valor ou ao lado dele em cada campo. |
+
+## Propriedades de DetailField
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `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. |

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

@@ -305,7 +305,7 @@ avançada; ele recebe `children` e `container` conforme o portal do Radix.
 ## Propriedades de DialogHost
 
 `DialogHost` não recebe propriedades. Monte uma instância no shell para atender toda a API
-imperativa. `ConfirmHost` permanece como alias de migração.
+imperativa.
 
 ## Opções de dialog.alert
 
@@ -363,6 +363,3 @@ imperativa. `ConfirmHost` permanece como alias de migração.
 | `context` | `ButtonContext` | Última ação: `primary`; demais: `neutral` | Define o significado semântico. |
 | `variant` | `ButtonVariant` | Última ação: `solid`; demais: `ghost` | Define o tratamento visual. |
 | `disabled` | `boolean` | `false` | Impede a escolha desta ação. |
-
-`confirm()` e `ConfirmHost` continuam disponíveis apenas como aliases de migração para
-`dialog.confirm()` e `DialogHost`.

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

@@ -8,7 +8,7 @@ sem perder o rótulo visível.
   value="pj"
 />
 <DictionaryValue
-  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
+  dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospecto' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
   value="customer"
 />
 <DictionaryValue
@@ -37,7 +37,7 @@ export const customerKindDict = t.dict(
 
 export const customerStageDict = t.dict(
   {
-    prospect: { label: 'Prospect', description: 'Relacionamento ainda em prospecção.' },
+    prospect: { label: 'Prospecto', description: 'Relacionamento ainda em prospecção.' },
     customer: { label: 'Cliente', context: 'success' },
   },
   { doc: 'Estágio comercial atual da parte.', presentation: 'stage' },
@@ -106,6 +106,13 @@ dicionário registrado no provider: `{ key: 'source', label: 'Fonte', dictionary
 Dimensões independentes (tipo e estágio, por exemplo) ficam em colunas distintas; não empilhar
 uma sob a outra como texto secundário.
 
+## useDicts
+
+`useDicts()` devolve os dicionários registrados em `OpusProvider` (`dicts`), chaveados pela `ref`.
+É o que `ActionList`, `ActionForm` e `DictionaryValue` consultam para resolver
+`options: { kind: 'dictionary', ref }` e colunas nomeadas por `dictionary`; fora do provider, o
+resultado é vazio e a resolução cai na meta do `t.dict` que viaja no schema.
+
 ## Propriedades de DictionaryValue
 
 | Propriedade | Tipo | Padrão | Descrição |

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

@@ -67,3 +67,11 @@ já monta.
 | --- | --- | --- | --- |
 | `position` | `'bottom' \| 'bottom-left' \| 'bottom-right'` | `'bottom'` | Aresta do contêiner onde a barra se ancora. |
 | `label` | `string` | | Nome acessível da barra. |
+
+## Propriedades de SurfaceStatus
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `position` | `'top-right' \| 'top-left'` | `'top-right'` | Canto da superfície onde o estado se ancora. |
+| `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O que o estado comunica; tinge borda e texto pela família semântica. |
+| `actions` | `ReactNode` | | Ações do recurso aberto, fora da região viva. |

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

@@ -15,3 +15,11 @@ acessível. Sem `label`, o ponto é decorativo.
 ```
 
 Use `Badge` quando o estado precisar permanecer legível sem depender do contexto ao redor.
+
+## Propriedades de Dot
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | O significado da cor. |
+| `variant` | `'solid' \| 'outline'` | `'solid'` | Ponto preenchido ou só contornado. |
+| `label` | `string` | | Nome acessível quando a cor comunica estado; sem ele o ponto é decorativo (`aria-hidden`). |

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

@@ -53,8 +53,8 @@ título e descrição agrupados no centro.
 
 ## Mídia sem moldura
 
-`EmptyMedia variant="default"` não desenha fundo. Use essa variação para ilustrações ou mídias que
-tenham presença visual própria.
+`EmptyMedia` sem `variant` (o padrão, `default`) não desenha fundo. Use essa forma para ilustrações
+ou mídias que tenham presença visual própria.
 
 ```tsx preview col
 <Empty>

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

@@ -1,8 +1,8 @@
 ---
-title: Getting started
+title: Primeiros passos
 ---
 
-# Getting started
+# Primeiros passos
 
 O Opus ajuda cliente e servidor a preservar as mesmas regras à medida que uma aplicação
 evolui. Entidades e contratos de action ficam em uma camada compartilhada; o runtime, a UI e