@softize/opus 13.0.0 → 13.1.0

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

@@ -64,6 +64,13 @@ negócio `conflict`, `validation` e `not_found`:
 Erros inesperados mantêm a mensagem genérica do contrato, evitando expor detalhes de banco ou
 infraestrutura. O servidor registra o detalhe técnico para diagnóstico.
 
+## useTriggerAction
+
+`ActionTrigger` é uma composição sobre `useTriggerAction(action, { onSuccess, onError })`, que
+devolve `trigger(input)`, `isLoading`, `error` e `reset`, e invalida o cache declarado em
+`action.invalidates`. Use o hook direto quando a execução parte de um gesto que não é um botão —
+um atalho, um arrastar, um item de menu.
+
 ## Propriedades de ActionTrigger
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -71,7 +78,7 @@ infraestrutura. O servidor registra o detalhe técnico para diagnóstico.
 | `action` | `SimpleContract<TInput, TData>` | | A SimpleAction do Opus — label, messages e confirm vêm do contrato. |
 | `input` | `TInput` | | O que a action recebe — geralmente { id }. |
 | `label` | `string` | `action.label` | Sobrepõe o texto do botão. |
-| `variant / size` | `variants do Button` | `'default' (ou 'destructive' se o confirm declarar) / 'default'` | Visual do botão — o destructive do ConfirmSpec já escolhe sozinho. |
+| `context / variant / size` | `do Button` | gatilho: `primary`/`solid`; `danger` quando a action é `destructive`; no modo ícone, `ghost` e `neutral` (ou `danger` se destrutiva) / `default` | Visual do gatilho; `context` explícito vence. O botão de confirmar é sempre `solid`: `danger` quando a action é `destructive`, senão a prop `context` do gatilho (ou `primary`). |
 | `confirm` | `{ title, description?, actionLabel?, cancelLabel? }` | | Confirmação via prop — sobrepõe o ConfirmSpec do contrato. |
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
 | `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza para o item. |

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

@@ -35,6 +35,12 @@ render(
 )
 ```
 
+## useViewAction
+
+`ActionView` é uma composição sobre `useViewAction(action, input)`, que devolve `data`, `error`,
+`isLoading` e `refetch` sob o `QueryClientProvider`. Use o hook direto quando o recurso alimenta
+mais de uma região da tela ou quando o carregamento precisa ser orquestrado por outro componente.
+
 ## Propriedades de ActionView
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -43,5 +49,6 @@ render(
 | `input` | `TInput` | | Geralmente { id } — mudou, recarrega. |
 | `children` | `(data: TData, refetch) => ReactNode` | | Conteúdo apresentado quando os dados estão disponíveis. `refetch` permite recarregar por código. |
 | `render` | `(data: TData, refetch) => ReactNode` | | Alias de compatibilidade de `children`; `children` tem precedência. |
-| `loading / empty` | `ReactNode` | `3 skeletons / nada` | Sobrescreve os estados padrão quando o contexto pedir. |
-| `error` | `(err, retry) => ReactNode` | `mensagem + Tentar de novo` | Sobrescreve o estado de erro padrão. |
+| `loading` | `ReactNode \| boolean` | `3 skeletons` | Sobrescreve o carregamento: um nó próprio, `true` para o padrão ou `false` para não renderizar nada enquanto carrega. |
+| `empty` | `ReactNode` | `nada` | Sobrescreve o estado vazio (200 sem dado). |
+| `error` | `(err, retry) => ReactNode` | `"Não foi possível carregar" + Tentar de novo` | Sobrescreve o estado de erro padrão. Sem ele, a frase do servidor só aparece quando é legível pela pessoa (`conflict`, `validation`, `not_found`, `authorization`, `authentication`); código técnico nunca vira título, e o botão de tentar de novo some quando o problema é de permissão ou sessão. |

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

@@ -29,3 +29,14 @@ render(
 ```
 
 Cada pergunta exige pelo menos uma opção válida selecionada **ou** texto livre não vazio. `busy` mostra o progresso no botão e trava os controles; `disabled` apenas trava a interação. A ordem de `answers` acompanha a ordem de `questions`, e o `header` de cada resposta é derivado de `question.header` (ou do próprio enunciado quando o header estiver vazio).
+
+## Propriedades de Ask
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `questions` | `AskQuestion[]` | | Uma a quatro perguntas do contrato de elicitação; fora dessa faixa o envio é bloqueado. |
+| `answers` | `AskAnswer[]` | | Respostas controladas, na mesma ordem de `questions`; entradas ausentes contam como vazias. |
+| `onChange` | `(answers: AskAnswer[]) => void` | | Recebe a lista completa a cada alteração. |
+| `onSubmit` | `(answers: AskAnswer[]) => void` | | Dispara somente quando toda pergunta tem uma opção ou texto livre. |
+| `disabled` | `boolean` | `false` | Trava as opções e o envio. |
+| `busy` | `boolean` | `false` | Envio em andamento: o botão mostra o spinner e desabilita. |

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/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

@@ -42,3 +42,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`). |
+| `meta` | `ReactNode` | | Forma curta: complemento ao lado do título, como uma contagem. |
+| `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` permanece só por compatibilidade da série 12. |
+
+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`.

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/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/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

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

@@ -53,3 +53,14 @@ render(
   />,
 )
 ```
+
+## Propriedades de IconPicker
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Nome do ícone selecionado (chave da paleta); `''` é nenhum. |
+| `onChange` | `(name: string) => void` | | Recebe o nome escolhido. |
+| `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Paleta nome → componente. |
+| `placeholder` | `string` | `'Selecione um ícone…'` | Texto do gatilho sem seleção. |
+| `disabled` | `boolean` | | Desabilita o gatilho. |
+| `id`, `aria-invalid`, `aria-describedby` | | | Integração com `Field`/`ActionForm`: o gatilho recebe a identidade e o estado de erro do campo. |

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

@@ -32,3 +32,10 @@ uma classe adicional.
   <Label htmlFor="archive-workspace">Arquivar o workspace</Label>
 </div>
 ```
+
+## Propriedades de Label
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `htmlFor` | `string` | | O `id` do controle rotulado; clicar no rótulo foca o controle. |
+| `className` | `string` | | Compõe sobre o estilo padrão; o rótulo esmaece com `peer-disabled` e dentro de `group[data-disabled]`. |

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

@@ -111,6 +111,12 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 | `context` | `'neutral' \| 'danger'` | `'neutral'` | `danger` sinaliza uma ação com consequência perigosa. |
 | `inset` | `boolean` | | Alinha um item sem ícone com os itens que possuem ícone. |
 
+## Propriedades de MenuGroup
+
+`MenuGroup` agrupa itens relacionados para leitores de tela (`role="group"`); combine com
+`MenuLabel` para nomear o grupo e `MenuSeparator` para separá-lo do próximo. Não tem props
+próprias além das de DOM.
+
 ## Propriedades de MenuContent
 
 | Propriedade | Tipo | Padrão | Descrição |

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

@@ -39,3 +39,16 @@ tecnologias assistivas. O contêiner da coleção continua responsável pela men
 ```tsx preview col
 <MetricCard loading />
 ```
+
+## Propriedades de MetricCard
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `label` | `ReactNode` | | O nome da medida. |
+| `value` | `ReactNode` | | O valor já formatado pelo consumidor. |
+| `loading` | `boolean` | `false` | Substitui rótulo e valor por skeletons e marca `aria-busy`. |
+| `labelAction` | `ReactNode` | | Controle ao lado do rótulo, como uma explicação em tooltip. |
+| `description` | `ReactNode` | | Contexto que explica recorte, proporção ou significado do valor. |
+| `icon` | `ReactNode` | | Ícone decorativo que identifica a natureza da medida. |
+| `context` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Contexto semântico do ícone; não altera a superfície do card. |
+| `action` | `ReactNode` | | Ação relacionada diretamente à medida. |

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

@@ -41,6 +41,14 @@ render(
 )
 ```
 
+## Ações no chrome do shell
+
+Quando o shell reserva uma barra própria para contexto e ações, envolva sua região de conteúdo com
+`PageActionsTarget` e passe o elemento de destino em `target`. As ações declaradas em `Page`
+continuam pertencendo semanticamente ao cabeçalho da página, mas são projetadas nesse elemento.
+Com `target={null}`, elas permanecem na posição padrão; isso permite montar o alvo por `ref` sem
+uma renderização intermediária inconsistente.
+
 ## Composição explícita
 
 Use os slots quando a página precisar compor o header diretamente. Não misture propriedades da

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

@@ -49,6 +49,12 @@ detalhes.
 | `open` | `boolean` | | Estado no modo controlado. |
 | `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado para permitir abertura ou fechamento por código. |
 
+## Propriedades de PopoverAnchor
+
+`PopoverAnchor` posiciona o painel em relação a um elemento que não é o gatilho — útil quando o
+clique acontece num item de linha, mas o painel deve alinhar-se ao contêiner. Aceita `asChild` para
+não introduzir um nó extra; sem ele, o `PopoverTrigger` é a âncora.
+
 ## Propriedades de PopoverContent
 
 | Propriedade | Tipo | Padrão | Descrição |

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

@@ -40,25 +40,21 @@ render(
 )
 ```
 
-## Altura e cor
+## Altura e contexto
 
-className compõe sobre o padrão: ajuste a altura no Progress e tinja o preenchimento mirando o slot do indicador (&_[data-slot=progress-indicator]) para sinalizar bom/atenção.
+`context` diz o que o andamento comunica — `success` para meta atingida, `warning` ou `danger`
+para atenção — e tinge trilha e preenchimento com a família semântica. `className` compõe sobre o
+padrão para ajustar a altura.
 
 ```tsx preview col
 <div className="w-full max-w-sm space-y-4">
   <div className="space-y-1.5">
     <span className="text-sm">Cobertura de testes</span>
-    <Progress
-      value={92}
-      className="h-1.5 [&_[data-slot=progress-indicator]]:bg-emerald-500"
-    />
+    <Progress value={92} context="success" className="h-1.5" />
   </div>
   <div className="space-y-1.5">
     <span className="text-sm">Skills cobertas pelo revisor</span>
-    <Progress
-      value={45}
-      className="h-3 [&_[data-slot=progress-indicator]]:bg-amber-500"
-    />
+    <Progress value={45} context="warning" className="h-3" />
   </div>
 </div>
 ```
@@ -68,4 +64,5 @@ className compõe sobre o padrão: ajuste a altura no Progress e tinja o preench
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `value` | `number \| null` | | O progresso de 0 a 100. O preenchimento anima a cada mudança; null/ausente deixa a barra vazia. |
-| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3) ou tinja o indicador via [&_[data-slot=progress-indicator]]:bg-*. |
+| `context` | `'neutral' \| 'primary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'primary'` | O que o andamento comunica; tinge trilha e preenchimento pela família `--context-*`. |
+| `className` | `string` | | Compõe sobre o padrão — ajuste a altura (h-1.5/h-3). |

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

@@ -40,7 +40,7 @@ render(
       id="issue"
       value={issue}
       onChange={setIssue}
-      placeholder="Buscar issue…"
+      placeholder="Buscar item…"
       options={[
         { value: '412', label: 'Ajustar microcopy do handoff', hint: 'SOF-412' },
         { value: '418', label: 'Preview da sessão cai após deploy', hint: 'SOF-418' },
@@ -69,7 +69,7 @@ render(
       id="agent-skills"
       value={skills}
       onChange={setSkills}
-      placeholder="Adicionar skill…"
+      placeholder="Adicionar habilidade…"
       options={[
         { value: 'clean-code', label: 'clean-code' },
         { value: 'code-style', label: 'code-style' },
@@ -181,7 +181,7 @@ render(
     icon={<Ticket />}
     value={task}
     onChange={setTask}
-    placeholder="Vincular task"
+    placeholder="Vincular tarefa"
     options={[
       { value: 'gra-2', label: 'Nova tela anotações', hint: 'GRA-2' },
       { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
@@ -227,8 +227,8 @@ function Demo() {
       value={values}
       onChange={setValues}
       options={[
-        { value: 'developer', label: 'Developer' },
-        { value: 'reviewer', label: 'Reviewer' },
+        { value: 'developer', label: 'Desenvolvedor' },
+        { value: 'reviewer', label: 'Revisor' },
         { value: 'designer', label: 'Designer' },
       ]}
       placeholder="Papéis…"

package/src/ui/docs/content/semantic-context.md

@@ -1,8 +1,8 @@
 ---
-title: Contexto & Variante
+title: Contexto e variante
 ---
 
-# Contexto & Variante
+# Contexto e variante
 
 Componentes semânticos separam significado de aparência. `context` responde por que o elemento
 recebe destaque; `variant` escolhe como esse significado aparece. Essa ordem evita que nomes como