@softize/opus 19.0.0 → 20.1.0

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.

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

@@ -17,13 +17,58 @@ direita; separe ações perigosas e declare `context="danger"` nelas.
 </Menu>
 ```
 
+`MenuShortcut` só exibe o atalho. Registre a tecla no aplicativo; o menu não a escuta.
+
+## Executar a ação do item
+
+`onSelect` recebe a escolha feita por clique ou teclado. Depois dele, o menu fecha. Para manter o
+painel aberto, como em uma alternância que a pessoa pode repetir, chame `event.preventDefault()` no
+handler. `disabled` mantém o item visível, mas impede a seleção.
+
+```tsx preview
+const [pinned, setPinned] = useState(false)
+const [last, setLast] = useState('Nenhuma ação ainda.')
+
+render(
+  <div className="flex items-center gap-4">
+    <Menu>
+      <MenuTrigger asChild>
+        <Button variant="outline">Sessão <ChevronDown /></Button>
+      </MenuTrigger>
+      <MenuContent align="start">
+        <MenuItem onSelect={() => setLast('Link copiado.')}><Link /> Copiar link</MenuItem>
+        <MenuItem
+          onSelect={(event) => {
+            event.preventDefault()
+            setPinned((current) => !current)
+          }}
+        >
+          {pinned ? <PinOff /> : <Pin />} {pinned ? 'Desafixar' : 'Fixar'}
+        </MenuItem>
+        <MenuItem disabled><Share2 /> Compartilhar</MenuItem>
+      </MenuContent>
+    </Menu>
+    <p className="text-sm text-muted-foreground">{last}</p>
+  </div>,
+)
+```
+
+Para navegar em vez de executar, use `asChild` com um link: o item passa a renderizar o `<a>`,
+com o estilo e a navegação por teclado do menu.
+
+```tsx
+<MenuItem asChild>
+  <a href="/sessoes/42">Abrir sessão</a>
+</MenuItem>
+```
+
 ## Abrir pelo menu de contexto
 
 Para abrir pelo clique direito, controle o estado do menu e use a posição do ponteiro como âncora.
-Esse padrão substitui o antigo `ContextMenu` sem introduzir outra família de componentes.
+Não há componente separado para menu de contexto; use `Menu` controlado.
 
 ```tsx preview
-const [pos, setPos] = useState(null)
+const [pos, setPos] = useState<{ x: number; y: number } | null>(null)
 
 render(
   <div>
@@ -34,7 +79,7 @@ render(
       }}
       className="flex h-28 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground select-none"
     >
-      clique direito aqui
+      Clique com o botão direito aqui
     </div>
     <Menu open={pos !== null} onOpenChange={(open) => { if (!open) setPos(null) }}>
       <MenuTrigger asChild>
@@ -83,7 +128,8 @@ render(
 
 ## Submenu e inset
 
-MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
+`MenuSub` aninha um nível: `MenuSubTrigger` abre o painel `MenuSubContent` ao lado do item. `inset`
+alinha itens sem ícone com os que têm.
 
 ```tsx preview
 <Menu>
@@ -93,7 +139,7 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
   <MenuContent align="start">
     <MenuItem><ExternalLink /> Abrir preview</MenuItem>
     <MenuSub>
-      <MenuSubTrigger><ArrowDownAZ /> Mover para</MenuSubTrigger>
+      <MenuSubTrigger><FolderInput /> Mover para</MenuSubTrigger>
       <MenuSubContent>
         <MenuItem>Empresa X</MenuItem>
         <MenuItem>Softize</MenuItem>
@@ -104,6 +150,10 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 </Menu>
 ```
 
+`MenuContent` já renderiza o painel em um portal, fora do fluxo da página. `MenuPortal` continua
+exportado, mas está depreciado e sai em uma próxima versão maior: envolver o conteúdo com ele não
+muda onde o painel aparece. Código novo usa só `MenuContent`.
+
 ## Propriedades de Menu
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -112,10 +162,26 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 | `onOpenChange` | `(open: boolean) => void` | | Chamado quando o painel abre ou fecha. |
 | `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
 
+## Propriedades de MenuTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Usa o filho, como um `Button`, como gatilho em vez de renderizar outro `<button>`. |
+
+## Propriedades de MenuContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
+| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+
 ## Propriedades de MenuItem
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
+| `onSelect` | `(event: Event) => void` | | Chamado quando a pessoa escolhe o item por clique ou teclado. `event.preventDefault()` mantém o menu aberto. |
+| `disabled` | `boolean` | `false` | Mantém o item visível e impede a seleção. |
+| `asChild` | `boolean` | `false` | Renderiza o filho, como um `<a>`, com o comportamento de item de menu. |
 | `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. |
 
@@ -125,12 +191,11 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 `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
+## Propriedades de MenuLabel
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
-| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+| `inset` | `boolean` | | Alinha o rótulo com itens que possuem ícone. |
 
 ## Propriedades de MenuCheckboxItem
 
@@ -153,14 +218,34 @@ próprias além das de DOM.
 | `value` | `string` | | Valor que o item entrega ao `MenuRadioGroup` quando é selecionado. |
 | `disabled` | `boolean` | `false` | Impede a seleção do item. |
 
-## Propriedades de MenuLabel
+## Propriedades de MenuSeparator
+
+`MenuSeparator` desenha a linha entre grupos de itens. Não tem props próprias; aceita as de um
+elemento `div`, como `className`.
+
+## Propriedades de MenuShortcut
+
+`MenuShortcut` exibe o atalho no extremo direito do item. Não tem props próprias; aceita as de um
+elemento `span`, como `className`.
+
+## Propriedades de MenuSub
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `inset` | `boolean` | | Alinha o rótulo com itens que possuem ícone. |
+| `open` | `boolean` | | Estado do submenu no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando o submenu abre ou fecha. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
 
 ## Propriedades de MenuSubTrigger
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `inset` | `boolean` | | Alinha o gatilho do submenu sem ícone com os itens que possuem ícone. |
+| `disabled` | `boolean` | `false` | Impede que o submenu abra. |
+
+## Propriedades de MenuSubContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `sideOffset` | `number` | `0` | Distância entre o item que abre o submenu e o painel. |
+| `alignOffset` | `number` | `0` | Deslocamento do painel ao longo do item que o abre. |

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

@@ -1,6 +1,6 @@
-MetricCard apresenta uma medida resumida com hierarquia e espaçamento consistentes. Passe o
-valor já calculado e formatado; busca de dados, recorte e regras de negócio permanecem no
-consumidor.
+Use `MetricCard` para apresentar uma medida resumida, como um total ou uma contagem, com rótulo,
+valor e contexto em hierarquia consistente. Passe o valor já calculado e formatado; busca de dados,
+recorte e regras de negócio permanecem no consumidor.
 
 ```tsx preview col
 <MetricCard
@@ -101,6 +101,11 @@ render(
 `active`, `activationLabel` e `onActivate` formam uma capacidade única: informe as três propriedades
 para tornar o card ativável. O consumidor continua responsável pelo estado e pelo recorte aplicado.
 
+O card ativo recebe a borda na cor primária. Ao passar o ponteiro, a borda se destaca, e o foco de
+teclado desenha um anel por dentro da borda. Com ativação, use `onActivate` em vez de `onClick`: o
+tipo recusa `onClick`, porque um clique genérico no card também dispararia ao usar `labelAction` ou
+`action`. Enquanto `loading` estiver ativo, a ativação fica desabilitada.
+
 ## Carregamento
 
 `loading` preserva a geometria do card com placeholders e marca a superfície como ocupada para
@@ -125,7 +130,10 @@ tecnologias assistivas. O contêiner da coleção continua responsável pela men
 | `action`          | `ReactNode`                                                 |             | Ação relacionada diretamente à medida.                                                             |
 | `active`          | `boolean`                                                   |             | Indica se a medida controla o recorte atualmente aplicado. Exige `activationLabel` e `onActivate`. |
 | `activationLabel` | `string`                                                    |             | Nome acessível da ativação. Exige `active` e `onActivate`.                                         |
-| `onActivate`      | `() => void`                                                |             | Ativa a medida como recorte ou seleção. Exige `active` e `activationLabel`.                        |
+| `onActivate`      | `() => void`                                                |             | Ativa a medida como recorte ou seleção. Exige `active` e `activationLabel`; não combina com `onClick`. Desabilitada durante `loading`. |
+| `className`       | `string`                                                    |             | Ajusta o card, ou o contêiner quando há ativação ou medida complementar.                           |
+
+As demais propriedades são as nativas de `div`.
 
 ## Propriedades de MetricCardSecondaryMetric
 

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

@@ -37,20 +37,21 @@ global. Um `Tracer` também pode ser injetado para testes ou providers não glob
 
 ## Semântica
 
-- nomes de span: `opus.action <action>` e `opus.reaction <reaction>`;
-- parent vem de `ContextBase.trace` ou do evento recebido;
-- actions usam `ActionResult.ok` para status; reactions usam resolve/reject;
-- somente atributos allowlisted de baixa cardinalidade são anexados;
-- input, output, actor, tenant, request ID, error code/message e baggage não entram no span;
+- Os spans se chamam `opus.action <action>` e `opus.reaction <reaction>`.
+- O span pai vem de `ContextBase.trace` ou do evento recebido.
+- Actions usam `ActionResult.ok` para o status; reactions usam a resolução ou a rejeição da Promise.
+- Somente atributos de baixa cardinalidade, de uma lista fixa, são anexados.
+- Input, output, ator, tenant, request ID, código e mensagem de erro e baggage não entram no span.
 - `TraceContext` devolve apenas `traceId`, `spanId`, `traceFlags` e `traceState`.
 
 ## Fronteira HTTP W3C
 
-Os drivers Fastify e Node oferecem propagação explícita, desativada por default:
+Os drivers Fastify e Node oferecem propagação explícita, desativada por padrão:
 
 ```ts
-fastifyServer({ app, traceContext: 'w3c' })
-nodeServer({ traceContext: 'w3c' })
+const server = fastifyServer({ app, traceContext: 'w3c' })
+// nodeServer devolve { adapter, handler, hasRoute }; o runtime recebe `adapter`.
+const node = nodeServer({ traceContext: 'w3c' })
 ```
 
 O opt-in extrai um `traceparent` v00 válido (e `tracestate` limitado) para
@@ -65,7 +66,7 @@ O driver OpenTelemetry não instrumenta HTTP automaticamente e não oferece back
 Use o opt-in dos drivers Fastify/Node acima ou forneça `ContextBase.trace` na instrumentação
 de outro transporte. A fronteira implementa somente `traceparent` v00 e uma validação
 defensiva limitada de `tracestate`; não é um propagator OTel genérico.
-Health do exporter/Collector só é reportado quando o app injeta `healthCheck`; o default
+A saúde do exporter e do Collector só é reportada quando o app injeta `healthCheck`; o padrão
 confirma apenas que a API do driver está configurada.
 Sem um provider que produza spans válidos, o driver falha antes do callback e o runtime aplica
 a degradação lenient — executa a action uma vez, sem trace — em vez de propagar IDs inválidos.

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

@@ -13,9 +13,8 @@ A forma curta é o padrão para páginas comuns. Fora de `PageShell`, ela cria `
 `PageBody`. Dentro dele, cria `PageHeader` para as ações, `PageIntro` para o título e `PageBody`.
 A forma explícita exige exatamente um heading principal. Use `PageTitle` no header ou intro,
 `Content level={1}` no body, ou deixe um `PageState` ativo assumir esse papel. Assim, header e
-introdução podem ser omitidos quando o próprio conteúdo nomeia a página.
-Contadores e outros indicadores pertencem ao
-conteúdo que os explica.
+introdução podem ser omitidos quando o próprio conteúdo nomeia a página. Contadores e outros
+indicadores pertencem ao conteúdo que os explica.
 
 A `Page` é contínua por definição: separar o chrome do conteúdo é trabalho do shell, e não há
 divisores entre regiões para declarar. O `layout` da `Page` não é a anatomia de superfície de
@@ -51,7 +50,8 @@ render(
 
 Use `PageBack` em uma subpágina simples. O destino é explícito para continuar correto após refresh ou
 acesso por link direto; não derive esse retorno do histórico do navegador. No header padrão, o
-controle aparece antes do título como ícone com nome acessível e tooltip derivados do destino.
+controle aparece antes do título como ícone; o nome acessível e a dica nativa do navegador (atributo
+`title`) derivam do destino.
 
 ```tsx preview col
 <Page>
@@ -64,8 +64,30 @@ controle aparece antes do título como ícone com nome acessível e tooltip deri
 ```
 
 Não combine `PageBack` com breadcrumb. Use o retorno para um único pai conhecido. Quando houver
-mais de um ancestral relevante, envolva o `Breadcrumb` em `PageNavigation`; ele ocupa a mesma
-posição introdutória sem transformar a trilha em ação.
+mais de um ancestral relevante, envolva o [`Breadcrumb`](/ui/breadcrumb) em `PageNavigation`; ele
+ocupa a mesma posição introdutória sem transformar a trilha em ação.
+
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageNavigation>
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>Vendas</BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>Clientes</BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbPage>Carla Souza</BreadcrumbPage>
+        </BreadcrumbList>
+      </Breadcrumb>
+    </PageNavigation>
+  </PageHeader>
+  <PageIntro>
+    <PageTitle>Carla Souza</PageTitle>
+  </PageIntro>
+  <PageBody>Dados do cliente.</PageBody>
+</Page>
+```
 
 ## Barra persistente do shell
 
@@ -149,8 +171,87 @@ render(
 
 Fora de `PageShell`, use `PageIntro` quando o conteúdo precisar de uma introdução separada do
 chrome. Dentro do shell, ele pode ser combinado com `PageHeader`: o primeiro permanece no conteúdo
-e o segundo alimenta a barra. Em uma página de listagem, `Content` pode fornecer o título e as ações
-da coleção, deixando `Page` apenas com `PageBody`.
+e o segundo alimenta a barra. Em uma página de listagem, [`Content`](/ui/content) pode fornecer o
+título e as ações da coleção, deixando `Page` apenas com `PageBody`.
+
+## Ações de etapa no rodapé
+
+Use `PageFooter` quando a página for uma etapa de um fluxo e a decisão precisar ficar ao alcance ao
+fim do conteúdo, como confirmar uma importação. O rodapé fica depois do body, com a mesma altura da
+barra e as ações alinhadas no fim da linha.
+
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageTitle>Importar clientes</PageTitle>
+  </PageHeader>
+  <PageBody>Revise os 128 registros antes de confirmar.</PageBody>
+  <PageFooter>
+    <ButtonGroup mode="spaced">
+      <Button variant="ghost">Cancelar</Button>
+      <Button>Importar</Button>
+    </ButtonGroup>
+  </PageFooter>
+</Page>
+```
+
+## Ocupar a altura disponível
+
+Use `layout="fill"` quando uma região interna, como uma tabela longa ou um split, precisar rolar
+dentro da página em vez de a página inteira rolar. A página passa a ocupar exatamente a altura do
+contêiner. Para uma região que você mesmo compõe, dê `min-h-0 flex-1` à que assume a folga e a
+rolagem, como o `PageBody` do exemplo.
+
+```tsx preview col
+render(
+  <div className="h-72 overflow-hidden rounded-lg border border-border">
+    <Page layout="fill">
+      <PageHeader>
+        <PageTitle>Ordens de serviço</PageTitle>
+      </PageHeader>
+      <PageBody className="min-h-0 flex-1 space-y-2 overflow-y-auto">
+        {['OS-1842', 'OS-1839', 'OS-1835', 'OS-1830', 'OS-1827', 'OS-1821', 'OS-1818'].map((id) => (
+          <div key={id} className="rounded-md border border-border p-3 text-sm">
+            {id}
+          </div>
+        ))}
+      </PageBody>
+    </Page>
+  </div>,
+);
+```
+
+Uma [`ActionList`](/ui/action-list) não precisa dessas classes. Filha de `PageBody`, ou de um
+[`Content`](/ui/content) dentro dele, ela recebe a altura da página e assume `layout="fill"`
+sozinha: `PageBody`, `Content` e `ContentBody` passam a repassar a altura até ela, o cabeçalho da
+tabela fica fixo e só os resultados rolam. As demais seções do `PageBody` mantêm a altura do
+próprio conteúdo, e uma página `fill` sem lista não muda.
+
+## Levar as ações para outra barra
+
+`PageShell` já projeta as ações na barra persistente. Use `PageActionsTarget` somente quando um
+hospedeiro próprio tiver outra barra para elas: as `PageActions` da árvore interna passam a ser
+renderizadas no elemento indicado em `target`. Enquanto `target` for `null`, fora de um shell, as
+ações continuam no cabeçalho da página.
+
+```tsx preview col
+function Example() {
+  const [target, setTarget] = useState<HTMLElement | null>(null)
+
+  return (
+    <div className="space-y-3">
+      <div ref={setTarget} className="flex justify-end rounded-lg border border-border p-2" />
+      <PageActionsTarget target={target}>
+        <Page title="Clientes" actions={<Button variant="outline">Exportar</Button>}>
+          Conteúdo da listagem.
+        </Page>
+      </PageActionsTarget>
+    </div>
+  )
+}
+
+render(<Example />)
+```
 
 ## Estados integrais
 
@@ -195,7 +296,8 @@ e, sem `title`, valem `errorMessage` e `emptyMessage`.
 ```
 
 Não use `PageState` para uma falha parcial. Se outra parte da página continua utilizável, mantenha o
-estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert`.
+estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui/action-view),
+[`ActionList`](/ui/action-list) ou [`Alert`](/ui/alert).
 
 ## Propriedades de Page
 
@@ -203,9 +305,10 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
 | `title`     | `ReactNode` |             | O h1 da página.                                                                                 |
 | `actions`   | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho. |
-| `layout`    | `'flow' \| 'fill'` | `'flow'` | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role. |
+| `layout`    | `'flow' \| 'fill'` | `'flow'` | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role e leva essa altura até uma `ActionList` composta em `PageBody`. |
 | `className` | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`  | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
+| demais      | Atributos de `HTMLElement` |  | Atributos nativos repassados ao elemento `main`, como `id` ou `aria-label`. `className` vai para o container interno. |
 
 ## Propriedades de PageShell
 
@@ -242,7 +345,7 @@ que o shell projeta na barra, e ignora `className` e os demais atributos.
 | Propriedade  | Tipo                                   | Padrão                   | Descrição                                                                                  |
 | ------------ | -------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
 | `href`       | `string`                               | obrigatório              | Destino explícito da página pai. Sem ele o retorno não é tabulável nem tem nome acessível. |
-| `children`   | `ReactNode`                            | obrigatório              | Nome do destino pai usado no rótulo acessível e no tooltip.                                |
+| `children`   | `ReactNode`                            | obrigatório              | Nome do destino pai usado no rótulo acessível e na dica nativa (`title`).                   |
 | `aria-label` | `string`                               | `Voltar para {children}` | Nome acessível; informe-o quando `children` não for texto simples.                         |
 | `onClick`    | `MouseEventHandler<HTMLAnchorElement>` |                          | Integração opcional com o roteador do consumidor, junto do `href`, nunca no lugar dele.    |
 | `className`  | `string`                               |                          | Classes adicionais do link renderizado como botão `ghost`.                                 |
@@ -259,7 +362,7 @@ que o shell projeta na barra, e ignora `className` e os demais atributos.
 
 | Propriedade | Tipo                              | Descrição                                       |
 | ----------- | --------------------------------- | ----------------------------------------------- |
-| `children`  | `ReactNode`                       | Título principal `h1`; ampliado em `PageIntro`. |
+| `children`  | `ReactNode`                       | Título principal `h1`, com a mesma escala em `PageHeader` e `PageIntro`. |
 | `className` | `string`                          | Classes adicionais do título.                   |
 | demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.        |
 
@@ -287,6 +390,9 @@ que o shell projeta na barra, e ignora `className` e os demais atributos.
 | `className` | `string`                      | Classes adicionais da região principal.    |
 | demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container. |
 
+Em uma `Page` com `layout="fill"`, o `PageBody` vira coluna flexível sozinho quando contém uma `ActionList` que
+ocupa a altura.
+
 ## Propriedades de PageActionsTarget
 
 | Propriedade | Tipo                  | Descrição                                                    |