@softize/opus 18.5.0 → 20.0.0

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

@@ -10,20 +10,18 @@ as ferramentas usam essas definições sem exigir schemas e tipos paralelos.
 
 ## O modelo
 
-> Comece pelo problema que o modelo compartilhado resolve antes de conhecer seus arquivos.
-
 As regras de uma aplicação costumam aparecer em vários lugares: validação, transporte, API,
-formulários e documentação. No Opus, entidades, dicts e contratos de action descrevem essas
+formulários e documentação. No Opus, entidades, dicionários e contratos de action descrevem essas
 regras uma vez. A API e a web consomem a mesma definição, enquanto runtime, adapters, UI, CLI
 e verificações ajudam a mantê-la consistente. Cada projeto acrescenta seu domínio sobre essa
 base versionada.
 
 ## Começar do zero
 
-> Projeto novo não se monta à mão: o esqueleto canônico sai do `opus create`, com os
-> pré-requisitos do protocolo, da UI e do preview já plugados — e os gates verdes.
+Para um projeto novo, use `opus create`: ele gera o app com os pré-requisitos do protocolo, da UI e
+do preview já configurados, e os gates passam desde o início.
 
-O Opus e a Base ficam no npm público: leitura não exige token nem configuração de escopo.
+O Opus e a Base ficam no npm público: a instalação não exige token nem configuração de escopo.
 Crie o projeto e materialize as duas camadas antes dos gates:
 
 ```bash
@@ -43,15 +41,21 @@ com `pnpm dlx @softize/opus@<versão> create meu-app` ou desative a quarentena a
 com `pnpm --config.minimum-release-age=0 dlx …`. Dentro do projeto, o workspace exclui Opus e Base
 da quarentena para preservar o par validado.
 
-Nasce com: `opus.config.ts` + domínio-exemplo canônico (0 violações, spec documentada),
-vite + react + tema do Opus (Tailwind v4 CSS-first), dev server na porta que o Maestro
-injeta no preview, `opus.json` (pin), instruções, skills e hooks gerenciados. A Base é
-dona do método geral, memória e revisão; o Opus acrescenta somente o conhecimento do SDK.
+O app criado inclui:
+
+- `opus.config.ts` e um domínio de exemplo documentado, sem violações no `opus check`;
+- Vite, React e o tema do Opus sobre Tailwind v4, configurado por CSS;
+- um dev server que respeita a variável `PORT`, para que um orquestrador de preview escolha a
+  porta;
+- `opus.json`, com a versão adotada, e as instruções, skills e hooks gerenciados.
+
+A Base cuida do método geral de trabalho, da memória e da revisão; o Opus acrescenta o conhecimento
+específico do SDK.
 
-**Monorepo:** a raiz nasce do `--monorepo` e cada app nasce dentro dela — o create
-detecta o `pnpm-workspace.yaml` e gera só o que é do app (sem workspace yaml aninhado),
-**avisando** o que a raiz precisa ter (glob de packages, allowBuilds e exclusões de
-quarentena para Opus/Base) sem tocar nos seus arquivos:
+Em um monorepo, crie primeiro a raiz com `--monorepo` e depois cada app dentro dela. O `create`
+detecta o `pnpm-workspace.yaml` e gera só os arquivos do app, sem um workspace aninhado. O que a raiz
+precisa ter, como o glob de packages, `allowBuilds` e as exclusões de quarentena para Opus e Base,
+aparece como aviso, sem alterar os arquivos da raiz:
 
 ```bash
 pnpm dlx @softize/opus create meu-cliente --monorepo   # a raiz do workspace
@@ -61,13 +65,10 @@ pnpm dlx @softize/opus create apps/portal              # o app (modo detectado)
 
 ## Carregar o Opus em um projeto existente
 
-> O `opus.json` registra a versão usada pelo projeto. Se o arquivo ainda não existe, o setup
-> cria a estrutura necessária antes das demais etapas.
-
-A versão do Opus fica pinada em `opus.json`. O `opus setup` é per-app: grava o marcador,
-o inventário de copy e as projeções específicas do SDK. O `base setup` materializa o
-método geral, memória, agentes e revisão na raiz do repositório. Os componentes vêm do
-barrel `@softize/opus/ui/react`; o tema, por CSS.
+O `opus.json` registra a versão do Opus adotada pelo app; se ele ainda não existe, o setup o cria.
+`opus setup` roda em cada app e grava o marcador, o inventário de copy e as projeções específicas do
+SDK. `base setup` materializa na raiz do repositório o método geral, a memória, os agentes e a
+revisão. Os componentes vêm de `@softize/opus/ui/react`, e o tema, de um arquivo CSS.
 
 ```bash
 # Bootstrap idempotente de um projeto existente.
@@ -78,39 +79,48 @@ pnpm exec base setup
 ```
 
 ```css
-/* index.css do app — o tema canônico + os componentes do Opus no scan do Tailwind. */
+/* index.css do app — o tema do Opus e os componentes do pacote no scan do Tailwind. */
 @import '@softize/opus/ui/theme.css';
 @source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
 ```
 
-## A stack do runtime
+## Montar o runtime
 
-> `createRuntime` compõe a stack a partir de adapters plugáveis. Cada capacidade (data, auth,
-> audit…) é um adapter — troca a implementação sem tocar o domínio.
+No servidor, `createRuntime` reúne as capacidades que o app usa. Cada capacidade, como banco,
+autenticação ou auditoria, é um adapter que pode ser trocado sem alterar o domínio. Os providers da
+interface estão em [Como consumir](/ui/como-consumir).
 
 ```ts
 import { createRuntime } from '@softize/opus/core'
+import { jwtAuth } from '@softize/opus/auth/jwt'
 import { kyselyData } from '@softize/opus/data/kysely'
 import { fastifyServer } from '@softize/opus/server/fastify'
 import { pgAudit } from '@softize/opus/audit/pg'
+import { workspaceDomain } from './domains/workspace/index.ts'
 
 const runtime = createRuntime({
   server: fastifyServer({ app }),
-  data: kyselyData({ db }),       // Kysely + Postgres
-  auth: makeAuthAdapter(),        // gate (IdP)
+  data: kyselyData({ db }),       // Kysely e Postgres
+  auth: jwtAuth({ secret: process.env.JWT_SECRET!, mapUser: (p) => ({ id: String(p.sub) }) }),
   audit: [pgAudit({ pool })],     // trilha de auditoria
   config: { env, i18n: { defaultLocale: 'pt-BR' } },
 })
 
-// Domínios = grupos de actions. Não registrado = não existe.
-runtime.register([workspacesDomain, agentsDomain, skillsDomain])
+// Só o que foi registrado existe para o runtime.
+runtime.register([workspaceDomain])
 await runtime.start()
 ```
 
-## Antes de mexer
+Cada capacidade e o registro de domínios estão detalhados em [Runtime & adapters](/docs/runtime).
+
+## Antes de alterar o projeto
 
-> O protocolo de leitura: a verdade local mora nos docs do repo, não nesta página.
+A documentação do próprio repositório descreve o que é específico dele; esta página cobre só o que
+vale para todo projeto Opus.
 
-- `CLAUDE.md` do repo e do app — o índice local: mapa, gates, gotchas.
-- As `description` das entidades/actions — a spec de negócio, projetada no manifest pelo `opus gen`.
-- Gate de build: `opus check` (convenções das actions e da UI) + `opus copy --check` e `base copy check` (inventário e política de copy) + `opus db check` (drift entidade ↔ banco). Rode antes de entregar.
+- O `CLAUDE.md` do repositório e de cada app reúne o mapa do código, os gates e os cuidados locais.
+- A `description` de entidades e actions registra a regra de negócio, que `opus gen` projeta no
+  manifest.
+- Antes de entregar, rode `opus check` (convenções das actions e da UI), `opus copy --check` e
+  `base copy check` (inventário e política de copy) e, com banco, `opus db check` (divergência entre
+  entidades e banco).

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

@@ -1,9 +1,9 @@
-Use `IconPicker` para selecionar um ícone por seu nome em kebab-case. O consumidor renderiza o
-valor com a mesma paleta, por exemplo `iconPickerIcons[name] ?? FallbackIcon`. Selecionar novamente o
-ícone atual limpa o valor.
-
 ## Escolher na paleta padrão
 
+Use `IconPicker` quando a pessoa puder escolher o ícone que identifica um registro, como um
+relatório ou um painel. A lista abre em um popover com busca, e o valor guardado é o nome do ícone em
+kebab-case, como `chart-line`. Selecionar novamente o ícone atual limpa o valor.
+
 ```tsx preview col md
 const [icon, setIcon] = useState('chart-line')
 
@@ -15,10 +15,11 @@ render(
 )
 ```
 
-## Renderizando o escolhido
+## Apresentar o ícone escolhido
 
-A paleta padrão é exportada como `iconPickerIcons`. Use a mesma coleção para apresentar o ícone
-salvo em listas, cards e árvores.
+O valor é somente um nome: quem apresenta o registro renderiza o ícone com a mesma paleta. A paleta
+padrão é exportada como `iconPickerIcons`; use-a em listas, cards e árvores, com um ícone de reserva
+para nomes que não existam mais, como em `iconPickerIcons[name] ?? FileText`.
 
 ```tsx preview col md
 const [icon, setIcon] = useState('store')
@@ -27,10 +28,14 @@ const SelectedIcon = iconPickerIcons[icon] ?? FileText
 render(
   <div className="flex items-center gap-3">
     <IconPicker value={icon} onChange={setIcon} className="w-56" />
-    <span className="flex items-center gap-2 rounded-md border px-3 py-2 text-sm">
-      <SelectedIcon className="size-4 text-muted-foreground" />
-      Painel comercial
-    </span>
+    <Item variant="outline" size="sm">
+      <ItemMedia variant="icon">
+        <SelectedIcon />
+      </ItemMedia>
+      <ItemHeader>
+        <ItemTitle>Painel comercial</ItemTitle>
+      </ItemHeader>
+    </Item>
   </div>,
 )
 ```
@@ -62,5 +67,6 @@ render(
 | `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. |
+| `disabled` | `boolean` | `false` | Desabilita o gatilho. |
+| `className` | `string` | | Classes do gatilho, em geral para ajustar a largura. Sem elas, o gatilho ocupa toda a largura disponível. |
+| `id`, `aria-invalid`, `aria-describedby` | `string`, `boolean`, `string` | | Integração com `Field` e `ActionForm`: o gatilho recebe a identidade do campo, o estado inválido e a mensagem associada. Com `aria-invalid`, a moldura assume o contexto de erro, como no `Input`. |

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

@@ -1,8 +1,8 @@
 ## Moldura decorativa para ícone
 
 Use `IconTile` quando um ícone precisar de uma pequena superfície para ganhar hierarquia em uma
-legenda, item ou resumo. O componente não é interativo; para uma ação, use `Button` com tamanho de
-ícone e um nome acessível.
+legenda, item ou resumo. O componente não é interativo; para uma ação, use [`Button`](/ui/button)
+com tamanho de ícone e um nome acessível.
 
 ```tsx preview row
 <IconTile size="xs"><UserRound /></IconTile>
@@ -16,7 +16,7 @@ uma classe `size-*` preserva a própria medida.
 ## Em uma legenda
 
 Slots de ícone não criam a moldura automaticamente. Componha `IconTile` somente quando ela fizer
-sentido para a superfície.
+sentido para a superfície, como na legenda de um [`Content`](/ui/content) emoldurado.
 
 ```tsx preview col md
 <Content
@@ -32,11 +32,16 @@ sentido para a superfície.
     </span>
   }
 >
-  <FieldGroup />
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="icon-tile-plate">Placa</FieldLabel>
+      <Input id="icon-tile-plate" />
+    </Field>
+  </FieldGroup>
 </Content>
 ```
 
-## Propriedades
+## Propriedades de IconTile
 
 | Propriedade | Tipo                                                                     | Padrão      | Descrição                                                     |
 | ----------- | ------------------------------------------------------------------------ | ----------- | ------------------------------------------------------------- |
@@ -45,3 +50,21 @@ sentido para a superfície.
 | `variant`   | `'subtle' \| 'outline'`                                                  | `'subtle'`  | Usa preenchimento tonal ou acrescenta borda.                  |
 
 As demais propriedades são as propriedades nativas de `span`.
+
+## Função iconTileVariants
+
+`iconTileVariants({ context, variant, size })` retorna as classes da moldura para um elemento que
+não é renderizado pelo `IconTile`. Os padrões são os mesmos do componente: `neutral`, `subtle` e
+`default`.
+
+```ts
+function iconTileVariants(options?: {
+  context?: IconTileContext | null
+  variant?: IconTileVariant | null
+  size?: IconTileSize | null
+}): string
+```
+
+`resolveIconTileStyle` continua exportado, mas está depreciado e sai em uma próxima versão maior. Ele
+só preenche os padrões acima, que `IconTile` e `iconTileVariants` já aplicam. Código novo usa um dos
+dois.

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

@@ -1,10 +1,15 @@
 ## Código em uma sequência
 
-`maxLength` define o comprimento do código. Cada `InputOTPSlot` recebe o índice de uma posição e
-`InputOTPGroup` mantém a sequência agrupada.
+Use `InputOTP` quando a pessoa precisar digitar um código curto recebido por outro canal, como a
+confirmação de acesso enviada por e-mail ou por um aplicativo autenticador. Cada caractere ocupa uma
+posição própria, e o foco avança sozinho durante a digitação ou ao colar o código inteiro.
+
+`maxLength` define o comprimento. Cada `InputOTPSlot` recebe o índice de uma posição, e
+`InputOTPGroup` reúne as posições em um bloco. `pattern` restringe os caracteres aceitos; no
+exemplo, somente dígitos.
 
 ```tsx preview
-<InputOTP maxLength={6}>
+<InputOTP maxLength={6} pattern="^\d+$">
   <InputOTPGroup>
     <InputOTPSlot index={0} />
     <InputOTPSlot index={1} />
@@ -40,14 +45,14 @@ Use `InputOTPSeparator` entre grupos para dividir visualmente o código. Os índ
 ## Controlado
 
 Use `value` e `onChange` quando o estado externo precisar validar o comprimento antes de liberar a
-próxima ação.
+próxima ação. `onComplete` é chamado quando todas as posições estão preenchidas.
 
 ```tsx preview col-start
 const [code, setCode] = useState('')
 
 render(
   <>
-    <InputOTP maxLength={6} value={code} onChange={setCode}>
+    <InputOTP maxLength={6} pattern="^\d+$" value={code} onChange={setCode}>
       <InputOTPGroup>
         <InputOTPSlot index={0} />
         <InputOTPSlot index={1} />
@@ -64,6 +69,41 @@ render(
 )
 ```
 
+## Código recusado
+
+Quando o código for recusado, declare `aria-invalid` no `InputOTP`, que o repassa ao campo que
+recebe a digitação, para que leitores de tela anunciem o erro. Declare-o também em cada
+`InputOTPSlot` para aplicar a borda de erro e explique o problema em um texto associado por
+`aria-describedby`. `disabled` no `InputOTP` bloqueia a digitação e
+esmaece o conjunto, por exemplo enquanto o código é conferido.
+
+```tsx preview col-start
+const [code, setCode] = useState('1234')
+
+render(
+  <>
+    <InputOTP
+      maxLength={4}
+      pattern="^\d+$"
+      value={code}
+      onChange={setCode}
+      aria-invalid
+      aria-describedby="otp-error"
+    >
+      <InputOTPGroup>
+        <InputOTPSlot index={0} aria-invalid />
+        <InputOTPSlot index={1} aria-invalid />
+        <InputOTPSlot index={2} aria-invalid />
+        <InputOTPSlot index={3} aria-invalid />
+      </InputOTPGroup>
+    </InputOTP>
+    <p id="otp-error" className="text-sm text-context-danger-emphasis">
+      Código expirado. Peça um novo código para continuar.
+    </p>
+  </>,
+)
+```
+
 ## Propriedades de InputOTP
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -72,11 +112,22 @@ render(
 | `value` | `string` | | Código no modo controlado. Use com `onChange`. |
 | `onChange` | `(value: string) => void` | | Chamado a cada entrada com o código acumulado. |
 | `onComplete` | `(value: string) => void` | | Chamado quando o código atinge `maxLength`. |
-| `pattern` | `string` | | Expressão regular que o código precisa satisfazer; entradas que não casam são descartadas. Sem `pattern`, qualquer caractere é aceito, inclusive letras. Para somente dígitos, use `'^\\d+$'`. |
-| `disabled` | `boolean` | `false` | Desabilita a digitação em todo o conjunto. |
+| `pattern` | `string` | | Expressão regular que o código precisa satisfazer; entradas que não casam são descartadas. Sem `pattern`, qualquer caractere é aceito, inclusive letras. Para somente dígitos, use `pattern="^\d+$"` em JSX; em uma string JavaScript, a barra é escapada: `'^\\d+$'`. |
+| `disabled` | `boolean` | `false` | Desabilita a digitação e esmaece todo o conjunto. |
+| `containerClassName` | `string` | | Classes do contêiner que alinha grupos e separadores. `className` vai para o campo de texto oculto que recebe a digitação. |
 
 ## Propriedades de InputOTPSlot
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `index` | `number` | | Posição do caractere, começando em zero. |
+| `aria-invalid` | `boolean` | | Aplica a borda de erro à posição. |
+
+## Propriedades de InputOTPGroup
+
+`InputOTPGroup` não tem propriedades próprias e aceita as props nativas de `<div>`.
+
+## Propriedades de InputOTPSeparator
+
+`InputOTPSeparator` desenha um traço com `role="separator"` entre grupos. Não tem propriedades
+próprias e aceita as props nativas de `<div>`.

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

@@ -99,8 +99,8 @@ Use `InputGroup` quando o campo precisar combinar vários adornos, prefixos, suf
 
 ### Com ícone e ação
 
-`InputGroupAddon` ancora os adornos nas extremidades. O clique em uma área inerte do addon transfere
-o foco para o campo.
+`InputGroupAddon` ancora os adornos nas extremidades. Um clique em uma área inerte do addon, fora
+dos botões, transfere o foco para o campo, seja `InputGroupInput` ou `InputGroupTextarea`.
 
 ```tsx preview col
 <InputGroup>
@@ -149,11 +149,30 @@ Com `InputGroupTextarea`, um addon em `block-end` forma uma região de ações a
 </InputGroup>
 ```
 
+### Estados do grupo
+
+`aria-invalid` no controle interno aplica o contexto de erro à moldura inteira. Para desabilitar,
+basta declarar `disabled` no controle: o campo esmaece pelo próprio estado e os addons acompanham.
+Um `InputGroupButton` desabilitado não apaga o grupo. Quando os addons precisarem esmaecer com o
+controle ativo, declare `data-disabled="true"` no `InputGroup`.
+
+```tsx preview col
+<InputGroup>
+  <InputGroupAddon><AtSign /></InputGroupAddon>
+  <InputGroupInput aria-invalid defaultValue="joao@" placeholder="E-mail do responsável" />
+</InputGroup>
+<InputGroup>
+  <InputGroupAddon><AtSign /></InputGroupAddon>
+  <InputGroupInput disabled defaultValue="joao@softize.com.br" />
+</InputGroup>
+```
+
 ### Propriedades de InputGroup
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `shape` | `'default' \| 'pill'` | `'default'` | Geometria da moldura compartilhada. |
+| `data-disabled` | `'true' \| 'false'` | | Com `true`, esmaece os addons mesmo com o controle ativo. Com o controle desabilitado, os addons já esmaecem sem ele. |
 
 ### Propriedades de InputGroupAddon
 
@@ -165,7 +184,7 @@ Com `InputGroupTextarea`, um addon em `block-end` forma uma região de ações a
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | O subconjunto da escala única que cabe num campo (1.5 · 2 · 1.5 · 1.75rem); os `icon-*` são quadrados. |
+| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` | O subconjunto da escala única que cabe em um campo (1.5 · 2 · 1.5 · 1.75rem); os `icon-*` são quadrados. |
 | `context` | `'neutral' \| 'primary' \| 'danger'` | `'neutral'` | Contexto semântico herdado de Button. Com `variant` `solid` ou `subtle` sem contexto declarado, o padrão passa a `'primary'`. |
 | `variant` | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'` | Tratamento visual; use `solid` quando a ação precisar de ênfase. |
 

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

@@ -1,7 +1,13 @@
 ## Linha composta
 
+Use `Item` para uma linha de lista que identifica algo — um repositório, uma pessoa, uma
+configuração — e oferece o que fazer com ele. Para dados em colunas comparáveis, use
+[`Table`](/ui/table); para uma coleção carregada por uma action `kind: 'list'`, use
+[`ActionList`](/ui/action-list).
+
 A composição completa usa `ItemMedia` à esquerda, `ItemHeader` (`ItemTitle` +
-`ItemDescription`) no meio e `ItemActions` à direita. Ícone e imagem mantêm uma moldura quadrada
+`ItemDescription`) no meio e `ItemActions` à direita. A descrição mostra no máximo duas linhas e
+termina em reticências quando passa disso. Ícone e imagem mantêm uma moldura quadrada
 alinhada ao topo, mesmo quando a descrição ocupa mais linhas. `variant="outline"` desenha a borda.
 O tamanho padrão usa corpo produtivo, `0.75rem` de padding e `0.75rem` entre regiões. `size="sm"`
 mantém o padding horizontal, reduz o padding vertical para `0.5rem` e o espaço entre regiões para
@@ -28,7 +34,10 @@ mantém o padding horizontal, reduz o padding vertical para `0.5rem` e o espaço
 
 ## Lista emoldurada
 
-`ItemGroup variant="framed"` aplica a superfície canônica. Os divisores continuam explícitos com `ItemSeparator`, tanto no modo `framed` quanto no `plain` — o padrão para listas de repositórios, agentes ou sessões.
+`ItemGroup variant="framed"` aplica a superfície canônica. Os divisores continuam explícitos com
+`ItemSeparator`, tanto no modo `framed` quanto no `plain` — o padrão para listas de repositórios,
+agentes ou sessões. O grupo é anunciado como lista, e cada `Item` dentro dele, como um item da
+lista.
 
 ```tsx preview col
 <ItemGroup variant="framed">
@@ -38,7 +47,7 @@ mantém o padding horizontal, reduz o padding vertical para `0.5rem` e o espaço
     </ItemMedia>
     <ItemHeader>
       <ItemTitle>empresa-x-web</ItemTitle>
-      <ItemDescription>Front do workspace Empresa X.</ItemDescription>
+      <ItemDescription>Frontend do workspace Empresa X.</ItemDescription>
     </ItemHeader>
     <ItemActions>
       <Badge context="success">Sincronizado</Badge>
@@ -62,7 +71,9 @@ mantém o padding horizontal, reduz o padding vertical para `0.5rem` e o espaço
 
 ## Clicável e compacto
 
-`asChild` funde o Item em um `<a>` — a linha inteira vira alvo (hover no fundo). `size="sm"` aperta o respiro; `ItemMedia` na variante padrão recebe um `Avatar`, que já traz a própria moldura.
+`asChild` funde o Item em um `<a>`: a linha inteira vira alvo e o fundo muda ao passar o ponteiro.
+`size="sm"` aperta o respiro; `ItemMedia` na variante padrão recebe um [`Avatar`](/ui/avatar), que
+já traz a própria moldura.
 
 ```tsx preview col
 <Item asChild size="sm" variant="outline">
@@ -103,6 +114,36 @@ Use `ItemBody` quando a linha também apresenta um valor ou controle que não pe
 `ItemContent` permanece exportado apenas por compatibilidade e está obsoleto. Código novo
 usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 
+## Rodapé
+
+`ItemFooter` ocupa uma linha inteira abaixo das demais regiões, com o conteúdo distribuído entre as
+pontas. Use-o para metadados ou estado que complementam a linha.
+
+```tsx preview col
+<Item variant="outline">
+  <ItemMedia variant="icon">
+    <FolderGit2 />
+  </ItemMedia>
+  <ItemHeader>
+    <ItemTitle>empresa-x-api</ItemTitle>
+    <ItemDescription>Repositório do backend do workspace Empresa X.</ItemDescription>
+  </ItemHeader>
+  <ItemActions>
+    <Button size="sm" variant="outline">Abrir</Button>
+  </ItemActions>
+  <ItemFooter>
+    <span className="text-xs text-muted-foreground">Atualizado há 2 horas</span>
+    <Badge context="success">Sincronizado</Badge>
+  </ItemFooter>
+</Item>
+```
+
+## Composições que lançam erro
+
+As partes conferem o próprio lugar ao renderizar. `ItemMedia`, `ItemHeader`, `ItemBody`,
+`ItemActions` e `ItemFooter` lançam erro fora de um `Item`; `ItemTitle` e `ItemDescription` lançam
+erro fora de um `ItemHeader` ou do `ItemContent` obsoleto. A mensagem nomeia o pai esperado.
+
 ## Propriedades de Item
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -117,12 +158,18 @@ usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 |---|---|---|---|
 | `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica moldura e superfície; os divisores permanecem explícitos nos dois modos. |
 
+O grupo renderiza um `div` com `role="list"` e aceita as props nativas desse elemento.
+
 ## Propriedades de ItemMedia
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'default' \| 'icon' \| 'image'` | `'default'` | Define mídia livre ou uma moldura quadrada para ícone ou imagem. |
 
+## Propriedades das demais partes
+
 `ItemHeader`, `ItemTitle`, `ItemDescription`, `ItemBody`, `ItemActions`, `ItemFooter` e
-`ItemSeparator` aceitam as props nativas dos respectivos elementos e não adicionam propriedades
-próprias. O `ItemContent` obsoleto preserva esse mesmo contrato por compatibilidade.
+`ItemSeparator` não têm props próprias. Cada um aceita as props nativas do elemento que renderiza:
+`div`, exceto `ItemDescription`, que renderiza `p`, e `ItemSeparator`, que aceita as props de
+[`Separator`](/ui/separator). O `ItemContent` obsoleto preserva esse mesmo contrato por
+compatibilidade.

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

@@ -1,7 +1,7 @@
 ## Uma tecla
 
 Use um `Kbd` para representar cada tecla. O componente apresenta o atalho; a captura do teclado
-continua no handler do aplicativo.
+continua no handler do aplicativo. Em um item de [`Menu`](/ui/menu), o atalho usa `MenuShortcut`.
 
 ```tsx preview
 <Kbd>Esc</Kbd>
@@ -29,6 +29,7 @@ reconhecível que o nome da tecla.
   <Kbd>
     <CommandIcon />
   </Kbd>
+  <span className="text-xs text-muted-foreground">+</span>
   <Kbd>
     <CornerDownLeft />
   </Kbd>
@@ -69,3 +70,6 @@ ação antes de informar seu atalho.
 |---|---|---|---|
 | `children` | `React.ReactNode` | | Teclas da combinação e conectores, como `+`, entre elas. |
 | `className` | `string` | | Classes adicionais aplicadas ao agrupador. |
+
+`KbdGroup` renderiza um `kbd` que envolve as teclas, a marcação HTML de uma combinação, e aceita as
+props desse elemento.

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

@@ -1,6 +1,8 @@
 ## Com campo de texto
 
-Associe `htmlFor` ao `id` do controle para que clicar no rótulo mova o foco para o campo.
+Use `Label` para nomear um controle de formulário. Associe `htmlFor` ao `id` do controle: o rótulo
+passa a ser o nome acessível do campo, e clicar nele move o foco para o controle. Em formulários
+com ajuda e erro, [`Field`](/ui/field) organiza o rótulo junto dos demais elementos.
 
 ```tsx preview col md
 <div className="grid gap-2">
@@ -23,8 +25,11 @@ também alterna a seleção.
 
 ## Par desabilitado
 
-Quando o controle está desabilitado, o rótulo associado acompanha o tratamento visual sem exigir
-uma classe adicional.
+O rótulo esmaece junto com um controle desabilitado quando é escrito logo depois dele, no mesmo
+contêiner, como nos pares com `Checkbox`, `Switch` e `RadioGroupItem`. Nessa posição, o estilo lê o
+estado do controle vizinho. Um rótulo escrito antes do controle, como acima de um `Input`, não
+acompanha o estado dessa forma; nesse caso, coloque o par em um [`Field`](/ui/field) com
+`data-disabled="true"`. `Label` e `FieldLabel` esmaecem com ele.
 
 ```tsx preview
 <div className="flex items-center gap-2">
@@ -38,4 +43,8 @@ uma classe adicional.
 | 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]`. |
+| `className` | `string` | | Classes somadas ao estilo padrão. |
+
+`Label` aceita as props nativas de `<label>`. Ele esmaece quando vem logo depois de um controle
+desabilitado, dentro de um `Field` com `data-disabled="true"` ou quando um ancestral com a classe
+`group` declara `data-disabled="true"`.

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

@@ -31,8 +31,8 @@ import { pinoLogger } from '@softize/opus/log/pino'
 const logger = pinoLogger({ logger: pino({ level: 'info' }) })
 ```
 
-O `pino` é seu (nível, transport, redact) — o driver só faz a ponte. Peer opcional: quem
-não usa o driver não instala o `pino`.
+O app configura o `pino` (nível, transport e redact), e o driver apenas o conecta ao runtime. `pino`
+é dependência opcional: só precisa ser instalado por quem usa o driver.
 
 ## No runtime
 
@@ -42,7 +42,7 @@ const runtime = createRuntime({
   logger,
 })
 
-// No handler: ctx.log já vem com o requestId/action injetados (via child()).
+// No handler: ctx.log já traz o request ID e a action, adicionados com child().
 handler: async (ctx, input) => {
   ctx.log.info('emitindo nota', { valor: input.valor })
   return repo.create(input)
@@ -51,5 +51,5 @@ handler: async (ctx, input) => {
 
 ## Limites atuais
 
-Superfície mínima de níveis + `child`. Sem sampling nem transports próprios — isso mora no
-`pino` que você passa. Drivers hoje: `pino`; outros entram por reincidência.
+O contrato cobre os níveis e `child`. Amostragem e transports ficam no `pino` que o app configura.
+O único driver disponível é o `pino`.

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

@@ -1,7 +1,8 @@
 ## Fonte e resultado
 
-Passe o texto em `content`. O exemplo mostra primeiro o resultado renderizado e, depois, o Markdown
-que o produziu.
+Use `Markdown` para exibir texto formatado que chega como Markdown, como a resposta de um agente
+no [`Chat`](/ui/chat) ou uma descrição escrita por uma pessoa. Passe o texto em `content`. O
+exemplo mostra primeiro o resultado renderizado e, depois, o Markdown que o produziu.
 
 ```tsx preview col 2xl
 const sample = [
@@ -38,5 +39,5 @@ render(<Markdown content={sample} />)
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `content` | `string` | | O markdown cru (CommonMark + tabela GFM, via markdown-it). HTML no fonte é **escapado**, não interpretado — por isso serve para texto vindo de gente ou de modelo. |
-| `className` | `string` | | Classes do wrapper. |
+| `content` | `string` | obrigatório | O texto em Markdown (CommonMark e tabelas do GFM, via markdown-it). HTML no texto é escapado, não interpretado, por isso o componente serve para texto escrito por pessoas ou gerado por modelos. Endereços soltos, como `https://…`, viram links. |
+| `className` | `string` | | Classes do contêiner. |