@softize/opus 12.11.0 → 13.1.0

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

@@ -1,6 +1,6 @@
-## Básico
+## Um slide por vez
 
-Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext pra navegar. As setas ficam fora do trilho (-left-12/-right-12), então reserve a margem lateral no entorno.
+Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext para navegar. As setas ficam fora do trilho (-left-12/-right-12), então reserve a margem lateral no entorno.
 
 ```tsx preview
 <Carousel className="mx-12 w-full max-w-xs">
@@ -28,7 +28,7 @@ Compõe Carousel>CarouselContent>CarouselItem, com CarouselPrevious/CarouselNext
 
 ## Vários por vista
 
-O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três slides por vez. Bom pra galeria de workspaces ou repositórios.
+O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três slides por vez. Bom para galeria de workspaces ou repositórios.
 
 ```tsx preview
 <Carousel className="mx-12 w-full max-w-sm" opts={{ align: 'start' }}>
@@ -48,7 +48,7 @@ O basis do CarouselItem decide quantos cabem na vista — basis-1/3 mostra três
 
 ## Vertical
 
-orientation=vertical empilha os slides; as setas migram pra cima e pra baixo (-top-12/-bottom-12). Dê uma altura ao CarouselContent pra delimitar a vista.
+orientation=vertical empilha os slides; as setas migram para cima e para baixo (-top-12/-bottom-12). Dê uma altura ao CarouselContent para delimitar a vista.
 
 ```tsx preview
 <Carousel className="w-full max-w-xs" orientation="vertical">
@@ -74,12 +74,17 @@ orientation=vertical empilha os slides; as setas migram pra cima e pra baixo (-t
 </Carousel>
 ```
 
-## Props
+## Propriedades de Carousel
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `orientation (Carousel)` | `'horizontal' \| 'vertical'` | `'horizontal'` | Eixo do deslize — vertical empilha os slides e gira as setas pro topo/base. |
-| `opts (Carousel)` | `CarouselOptions` | | Opções do embla (ex.: { loop: true }, { align: "start" }). Repassadas direto pro motor. |
-| `setApi (Carousel)` | `(api: CarouselApi) => void` | | Recebe a instância do embla pra controlar de fora (scrollTo, ler o slide ativo). |
-| `plugins (Carousel)` | `CarouselPlugin` | | Plugins do embla (ex.: autoplay) anexados ao carousel. |
-| `className (CarouselItem)` | `string` | | O basis decide quantos slides cabem na vista (basis-full, basis-1/2, basis-1/3). |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Eixo do deslocamento. No modo vertical, os slides são empilhados e as setas apontam para cima e para baixo. |
+| `opts` | `CarouselOptions` | | Opções repassadas ao Embla, como `{ loop: true }` ou `{ align: 'start' }`. |
+| `setApi` | `(api: CarouselApi) => void` | | Recebe a instância para controle externo, como navegar com `scrollTo` ou ler o slide ativo. |
+| `plugins` | `CarouselPlugin[]` | | Plugins do Embla associados ao carrossel, como autoplay. |
+
+## Propriedades de CarouselItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `className` | `string` | | Classes de dimensão; a base define quantos slides cabem na área visível. |

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

@@ -1,6 +1,6 @@
-## Básico
+## Conversa com resposta integral
 
-Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por dentro (estado, loading, auto-scroll; **Enter** envia, **Shift+Enter** quebra linha) — a inteligência vem da prop `send`. Com o composer vazio, **↑** recupera as mensagens anteriores do usuário e **↓** volta em direção ao rascunho; durante a edição, as setas continuam movendo o cursor normalmente. O `greeting` é o estado vazio (centrado; some quando a conversa começa e NÃO entra no transcript). Dê altura ao container.
+Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por dentro (estado, loading, auto-scroll; **Enter** envia, **Shift+Enter** quebra linha) — a inteligência vem da prop `send`. Com o composer vazio, **↑** recupera as mensagens anteriores do usuário e **↓** volta em direção ao rascunho; durante a edição, as setas continuam movendo o cursor normalmente. O `greeting` é o estado vazio (centrado; some quando a conversa começa e não entra no transcript). Dê altura ao container.
 
 ```tsx preview
 <div className="h-96 rounded-lg border">
@@ -9,7 +9,7 @@ Um chat mínimo: lista de mensagens + composer. A conversa é gerenciada por den
     send={async (messages) => {
       await new Promise((r) => setTimeout(r, 500))
       const last = messages[messages.length - 1]
-      return `Você disse: "${last.content}". (Num app real, aqui rodaria o agente.)`
+      return `Você disse: "${last.content}". (Em um app real, aqui rodaria o agente.)`
     }}
   />
 </div>
@@ -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/checkbox.md

@@ -1,6 +1,6 @@
-## Básico
+## Escolha booleana
 
-Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defaultChecked pro modo não controlado.
+Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defaultChecked para o modo não controlado.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -11,7 +11,7 @@ Sempre em par com Label (htmlFor↔id) — clicar no texto alterna a caixa. defa
 
 ## Controlado
 
-onCheckedChange recebe boolean | 'indeterminate' — compare com true pra guardar um boolean.
+onCheckedChange recebe boolean | 'indeterminate' — compare com true para guardar um boolean.
 
 ```tsx preview
 const [autoReview, setAutoReview] = useState(true)
@@ -30,7 +30,7 @@ render(
 
 ## Lista de opções
 
-Várias caixas, um estado: o conjunto marcado é a lista de valores — o padrão pra anexar skills a um agente.
+Várias caixas, um estado: o conjunto marcado é a lista de valores — o padrão para anexar skills a um agente.
 
 ```tsx preview col-start
 const [skills, setSkills] = useState(['clean-code', 'test'])
@@ -65,11 +65,11 @@ disabled esmaece a caixa e o rótulo em par (peer-disabled no Label) — marcado
 </div>
 ```
 
-## Props
+## Propriedades de Checkbox
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `checked` | `boolean \| 'indeterminate'` | | O estado, no modo controlado — parear com onCheckedChange. |
-| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | | Chamado a cada alternância. Pra guardar um boolean, compare com true. |
+| `onCheckedChange` | `(checked: boolean \| 'indeterminate') => void` | | Chamado a cada alternância. Para guardar um boolean, compare com true. |
 | `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |

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 pros 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,43 +52,74 @@ 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
 
 > As declarações (`description` de entidades/actions) são a fonte; o `gen` as projeta. O manifest
-> é um lockfile commitado — diff de manifest é ouro pra review.
+> é 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 pro 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
 configura) e nasce com os gates verdes: domínio-exemplo canônico, teste, manifest e o dev
-server pronto pro preview do Maestro. O método geral, a memória e a revisão vêm da Base
+server pronto para o preview do Maestro. O método geral, a memória e a revisão vêm da Base
 depois de `pnpm run setup`. Dois modos, por detecção:
 repo standalone (template inteiro) ou **app em monorepo** (dentro de um workspace pnpm:
 só os arquivos do app; o que a raiz precisa ter vira aviso, sem clobber).
 
-## MCP — estado vivo pros agentes
+## MCP — estado vivo para os agentes
 
 > O server MCP expõe introspecção, check e scaffold de action. É como um agente lê a estrutura e cria
 > action no formato canônico sem decorar convenção.

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

@@ -1,4 +1,4 @@
-## Básico
+## Seção recolhível
 
 CollapsibleTrigger alterna o CollapsibleContent — o Trigger já é o <button>. defaultOpen deixa o estado com o componente.
 
@@ -18,7 +18,7 @@ CollapsibleTrigger alterna o CollapsibleContent — o Trigger já é o <button>.
 
 ## Controlado
 
-open + onOpenChange põem o estado nas suas mãos — dá pra refletir no gatilho (aqui o chevron gira) ou guardar a preferência.
+open + onOpenChange põem o estado nas suas mãos — dá para refletir no gatilho (aqui o chevron gira) ou guardar a preferência.
 
 ```tsx preview col
 const [open, setOpen] = useState(false)
@@ -54,11 +54,11 @@ disabled no Collapsible trava o gatilho — a seção fica fixa no estado atual
 </Collapsible>
 ```
 
-## Props
+## Propriedades de Collapsible
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `defaultOpen (Collapsible)` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `open (Collapsible)` | `boolean` | | Estado no modo controlado — pareie com onOpenChange. |
-| `onOpenChange (Collapsible)` | `(open: boolean) => void` | | Chamado a cada abertura ou fechamento. |
-| `disabled (Collapsible)` | `boolean` | `false` | Trava o gatilho — a seção fica presa no estado atual. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
+| `open` | `boolean` | | Estado no modo controlado. Use com `onOpenChange`. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado a cada abertura ou fechamento. |
+| `disabled` | `boolean` | `false` | Bloqueia o gatilho e mantém a seção no estado atual. |

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

@@ -1,6 +1,7 @@
 ## Lista filtrável inline
 
-Digite pra filtrar — navegação por teclado, grupos e CommandEmpty de graça (cmdk). É a base do Select buscável; pra escolha em form, use o Select.
+Digite para filtrar uma coleção com navegação por teclado, grupos e estado vazio. Command é a base
+do Select pesquisável; para uma escolha em formulário, use Select.
 
 ```tsx preview
 <Command className="max-w-sm rounded-lg border border-border">
@@ -22,7 +23,7 @@ Digite pra filtrar — navegação por teclado, grupos e CommandEmpty de graça
 
 ## Palette modal (CommandDialog)
 
-O Command embrulhado num Dialog, com header sr-only pra a11y. O atalho ⌘K (keydown no app) só troca o open — o conteúdo é o mesmo do inline.
+O Command embrulhado em um Dialog, com header sr-only para a11y. O atalho ⌘K (keydown no app) só troca o open — o conteúdo é o mesmo do inline.
 
 ```tsx preview
 const [open, setOpen] = useState(false)
@@ -46,11 +47,18 @@ render(
 )
 ```
 
-## Props
+## Propriedades de CommandDialog
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `CommandDialog.open / onOpenChange` | `boolean / (open: boolean) => void` | | Controle do modal — ligue ao atalho de teclado do app. |
-| `CommandDialog.title / description` | `string` | `'Comandos' / 'Busque um comando pra executar.'` | Texto sr-only do header (a11y do Dialog) — não aparece na tela. |
-| `CommandDialog.showCloseButton` | `boolean` | `true` | Mostra o X do Dialog — desligue se o Esc/clique fora bastarem. |
-| `CommandItem.onSelect` | `(value: string) => void` | | Dispara ao escolher (Enter ou clique) — feche o palette aqui. |
+| `open` | `boolean` | | Estado do modal no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado do modal; pode ser conectado ao atalho do aplicativo. |
+| `title` | `string` | `'Comandos'` | Nome acessível do diálogo, disponível para leitura assistiva. |
+| `description` | `string` | `'Busque um comando para executar.'` | Descrição acessível do diálogo. |
+| `showCloseButton` | `boolean` | `true` | Exibe o botão de fechamento. |
+
+## Propriedades de CommandItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `onSelect` | `(value: string) => void` | | Chamado ao selecionar o item por clique ou teclado. |

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

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

@@ -13,7 +13,7 @@ render(
     description="Sessões com acesso à sua conta."
     actions={<Button variant="outline">Encerrar outras sessões</Button>}
   >
-    <div className="rounded-lg border border-border p-4">MacBook Pro · ativo agora</div>
+    <div className="rounded-lg border border-border p-4">MacBook Para o · ativo agora</div>
   </Content>,
 )
 ```
@@ -34,7 +34,7 @@ render(
       <ContentActions><Button variant="outline">Atualizar</Button></ContentActions>
     </ContentHeader>
     <ContentBody>
-      <div className="rounded-lg border border-border p-4">MacBook Pro · ativo agora</div>
+      <div className="rounded-lg border border-border p-4">MacBook Para o · ativo agora</div>
     </ContentBody>
   </Content>,
 )
@@ -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

@@ -1,6 +1,6 @@
-## Básico
+## Copiar por ícone
 
-Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5s. Bom pra toolbar ou célula estreita, ao lado de um ID/token/slug.
+Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5s. Bom para toolbar ou célula estreita, ao lado de um ID/token/slug.
 
 ```tsx preview
 <Copyable value="opus_sk_1a2b3c4d5e6f" className="text-muted-foreground hover:text-foreground" />
@@ -21,10 +21,19 @@ Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar n
 
 ## Duração do feedback
 
-`feedbackMs` ajusta quanto o check dura (default 1500). Some no-op silencioso se o clipboard não existir (contexto inseguro/SSR).
+`feedbackMs` ajusta por quanto tempo a confirmação aparece; o padrão é 1500 milissegundos. Se a
+área de transferência não estiver disponível, a ação não produz efeito.
 
 ```tsx preview
 <Copyable value="copiado devagar" feedbackMs={3000} className="text-muted-foreground hover:text-foreground">
   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/customization.md

@@ -6,7 +6,7 @@ title: Customização
 
 Cinco alavancas, do global ao pontual — e um limite de propósito. O caminho previsto é compor
 e configurar, nunca forkar componente: o que não cabe nas alavancas evolui no Opus (com
-divergência declarada), pra valer pra casa toda.
+divergência declarada), para valer para casa toda.
 
 ## 1 · Identidade por tokens
 
@@ -36,7 +36,7 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 ## 2 · className em tudo
 
 > Todo componente termina em `cn(base, className)` com tailwind-merge: o utilitário do consumidor
-> vence o conflito. Pra layout local (largura, margem, grid) — não pra repintar o visual da casa.
+> vence o conflito. Para layout local (largura, margem, grid) — não para repintar o visual da casa.
 
 ```tsx
 <Button className="w-full">Continuar</Button>
@@ -47,7 +47,7 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 ## 3 · Recomposição estrutural
 
 > Os componentes são explodidos em slots. `asChild` (Radix Slot) renderiza como outro elemento
-> mantendo estilo e comportamento; os `*Variants` aplicam a cara da casa num elemento arbitrário.
+> mantendo estilo e comportamento; os `*Variants` aplicam a cara da casa em um elemento arbitrário.
 
 ```tsx preview
 <Button asChild variant="outline">
@@ -65,7 +65,7 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 // asChild: o filho VIRA o botão (sem forkar estilo).
 <Button asChild><a href="/docs">Abrir documentação</a></Button>
 
-// buttonVariants: a cara da casa num elemento qualquer.
+// buttonVariants: a cara da casa em um elemento qualquer.
 <a className={buttonVariants({ variant: 'outline' })}>Link estilizado</a>
 ```
 
@@ -115,4 +115,4 @@ const [open, setOpen] = useState(false)
 
 Se uma necessidade real não cabe nas alavancas (tokens · className · slots/asChild · props ·
 contrato), o movimento não é dialeto local: é evoluir o componente **no Opus**, com a divergência
-declarada (skill `build-opus-ui`) — assim a mudança vale pra casa toda, e esta doc passa a mostrá-la.
+declarada (skill `build-opus-ui`) — assim a mudança vale para casa toda, e esta doc passa a mostrá-la.

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

@@ -16,9 +16,9 @@ No seu projeto, uma linha por apontamento em `.opus/issues.jsonl` na raiz do rep
 
 ## Não trave esperando
 
-O ponto do ciclo é **não bloquear a entrega**. Bateu num gap ou num bug do Opus:
+O ponto do ciclo é **não bloquear a entrega**. Bateu em um gap ou em um bug do Opus:
 
-1. **Contorne local** — componha um wrapper no seu projeto. O Opus entrega _source_, então dá pra embrulhar qualquer superfície dele. Nunca edite `node_modules` (some no próximo install).
+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.
 
@@ -28,7 +28,7 @@ O "depois" — o conserto no Opus — corre em paralelo. Ele não segura o seu t
 
 O apontamento é colhido e abre uma **Issue no repositório do Opus**, onde a triagem acontece (deduplicada — re-apontar o mesmo é idempotente):
 
-- **Enhancement** aceito (com reincidência) → implementado no Opus → sai num _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 pin (`opus.json`) 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

@@ -1,9 +1,9 @@
 ## Estados
 
-Um lugar só pro erro/carregando/vazio/conteúdo de uma carga. Carregando = Spinner centralizado;
-vazio = texto em uma moldura sólida no modo bloco; erro = aviso calmo (a mensagem técnica não vai
-pra tela). É o "antes" do conteúdo —
-pro "depois" (ação em andamento), use o busy do Button.
+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`.
 
 ```tsx preview col
 <div className="w-full space-y-3">
@@ -19,12 +19,11 @@ pro "depois" (ação em andamento), use o busy do Button.
 </div>
 ```
 
-## Em tabela (colSpan)
+## Dentro de uma tabela
 
-Em lista ou tabela já emoldurada, passe colSpan: o estado vira UMA linha de largura cheia
-(`<tr><td colSpan>`) que cabe direto no `<tbody>`; o conteúdo são as `<tr>` dos itens. A tabela
-continua dona da borda, sem uma segunda moldura no vazio. Para uma região disponível para criação
-ou vínculo, com título, descrição ou ação, use `Empty`, cuja moldura é tracejada.
+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`.
 
 ```tsx preview col
 <table className="w-full overflow-hidden rounded-lg border border-border text-sm">
@@ -38,13 +37,13 @@ ou vínculo, com título, descrição ou ação, use `Empty`, cuja moldura é tr
 </table>
 ```
 
-## Props
+## Propriedades de DataState
 
-| Prop | Tipo | Default | Descrição |
+| 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 pra tela (use errorText). |
+| `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. |
 | `colSpan` | `number` | | Em tabela: renderiza o estado como `<tr><td colSpan>` (cabe direto no tbody). |