@softize/opus 19.0.0 → 20.0.0

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

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

@@ -4,45 +4,71 @@ title: MCP
 
 # MCP
 
-Use o servidor MCP para disponibilizar actions `ai:enabled` a agentes que executam fora da
-aplicação. A chamada continua passando por `runtime.execute`, com a mesma validação, autorização e
-auditoria; o MCP fornece apenas o transporte.
+Use o servidor MCP do runtime para disponibilizar actions do app a agentes que executam fora da
+aplicação, como o Claude Desktop ou o agente de um parceiro. A chamada passa por `runtime.execute`,
+com a mesma validação, autorização e auditoria de qualquer outra; o MCP fornece apenas o transporte.
+
+Este servidor é diferente de `opus mcp`, que atende o agente que trabalha no código do projeto
+durante o desenvolvimento e não executa actions. Veja [CLI opus](/docs/cli).
 
 ## Montar
 
+`createOpusMcpServer` recebe o runtime e devolve um servidor MCP; o app escolhe o transporte e o
+conecta. `resolveContext` recebe os dados da requisição MCP e devolve o contexto do runtime, com
+usuário, tenant e `can`. No transporte HTTP do SDK MCP, os headers da requisição chegam em
+`requestInfo`, e o adapter de autenticação do app pode lê-los:
+
 ```ts
 import { createOpusMcpServer } from '@softize/opus/mcp'
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { jwtAuth } from '@softize/opus/auth/jwt'
+
+const auth = jwtAuth({
+  secret: process.env.JWT_SECRET!,
+  mapUser: (payload) => ({ id: String(payload.sub) }),
+})
+
+type McpRequestExtra = {
+  requestInfo?: { headers: Record<string, string | string[] | undefined> }
+}
 
 const server = createOpusMcpServer(runtime, {
   name: 'meu-app',
-  // Valida a identidade da requisição (IdP) → contexto do runtime. Sem isso, roda anônimo
-  // (sem usuário, só actions `public` rodam). Com isso, o agente age COMO O USUÁRIO.
-  resolveContext: async (extra) => auth.resolveFromMcp(extra),
+  resolveContext: async (extra) => {
+    const request = (extra as McpRequestExtra).requestInfo ?? { headers: {} }
+    const { user, tenantId, can } = await auth.resolveContext(request)
+    return { user, tenantId: tenantId ?? null, can }
+  },
 })
 
-await server.connect(new StdioServerTransport()) // local; HTTP/SSE para remoto
+await server.connect(transport) // StreamableHTTPServerTransport, por exemplo
 ```
 
-Só actions marcadas com `ai: { enabled: true }` ficam disponíveis, tanto para listar quanto para
-executar. `ListTools` devolve cada uma com `name` (identificador técnico), `title` (a `label`
-legível, quando existe), descrição, JSON Schema do input e, em `_meta`, os Produtos de Dados
-relacionados: `com.softize.opus/data-products` (identificadores) e
-`com.softize.opus/data-product-labels` (nome legível por identificador). `CallTool` recusa, com
-erro, qualquer nome fora dessa lista; os demais seguem pelo `runtime.execute` — validação,
-autorização e audit, tudo igual a uma chamada normal. Read-only? Marque só actions de leitura
-com `ai:enabled`: a marcação decide o que o cliente MCP pode executar, e a autorização do
-contexto continua valendo por cima.
+Sem `resolveContext`, a chamada é anônima: não há usuário, `can` nega tudo e só actions `public`
+executam. Com ele, o agente age como o usuário identificado. No transporte stdio não há headers;
+a identidade precisa vir do próprio processo, como um token de serviço lido do ambiente.
+
+## O que fica disponível
+
+Só actions expostas à IA ficam disponíveis, tanto para listar quanto para executar: as que declaram
+`ai: true` ou um objeto `ai` sem `enabled: false`. `ListTools` devolve cada uma com `name` (o
+identificador técnico), `title` (a `label` legível, quando existe), descrição e JSON Schema da
+entrada. Em `_meta`, cada tool traz os
+[Produtos de Dados](/docs/data-products) relacionados: `com.softize.opus/data-products` lista os
+identificadores e `com.softize.opus/data-product-labels`, o nome legível de cada um.
+
+`CallTool` recusa com erro qualquer nome fora dessa lista; os demais seguem por `runtime.execute`.
+A exposição declarada em `ai` decide o que o cliente MCP pode executar, e a autorização do contexto
+continua valendo sobre ela. Para um acesso somente de leitura, exponha apenas actions de leitura.
 
 ## Escolher entre integração interna e MCP
 
 - **Agente dentro da aplicação:** use `runtime.aiFor(base).run()` para chamar as actions no mesmo
-  processo.
-- **Agente em outro serviço:** use MCP para oferecer a mesma coleção de ferramentas por uma
-  interface interoperável.
+  processo. Veja [IA generativa](/docs/ai).
+- **Agente em outro serviço:** use o servidor MCP para oferecer a mesma coleção de ferramentas por
+  uma interface interoperável.
 
 ## Limites atuais
 
-O consumidor escolhe e monta o transporte, como stdio ou HTTP. A confirmação de actions destrutivas
-ainda não faz parte desta integração; até que esse fluxo exista, exponha somente operações de
-leitura.
+O servidor MCP não pede confirmação: uma action com `ai.destructive` ou `ai.requiresConfirmation`
+executa como qualquer outra ferramenta anunciada. Como a mesma exposição em `ai` alimenta o agente
+do app e o MCP, ao montar o servidor MCP exponha à IA somente operações de leitura.