@softize/opus 18.1.0 → 18.2.0

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

@@ -22,13 +22,13 @@ salvo em listas, cards e árvores.
 
 ```tsx preview col md
 const [icon, setIcon] = useState('store')
-const Icon = iconPickerIcons[icon] ?? FileText
+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">
-      <Icon className="size-4 text-muted-foreground" />
+      <SelectedIcon className="size-4 text-muted-foreground" />
       Painel comercial
     </span>
   </div>,

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

@@ -71,6 +71,8 @@ render(
 | `maxLength` | `number` | | Quantidade de posições do código. Defina um `InputOTPSlot` para cada posição. |
 | `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. |
 
 ## Propriedades de InputOTPSlot

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

@@ -21,7 +21,6 @@ como calendário em uma data; o `Label` continua responsável pelo nome acessív
 
 Quando o campo precisar combinar vários adornos, prefixos ou botões, use `InputGroup`.
 
-
 ## Ação no fim do campo (trailing)
 
 `trailing` posiciona no fim do campo uma ação relacionada ao valor, como limpar ou mostrar uma
@@ -37,7 +36,7 @@ function Demo() {
       onChange={(e) => setQ(e.target.value)}
       trailing={
         q ? (
-          <Button variant="ghost" size="icon-xs" onClick={() => setQ('')}>
+          <Button variant="ghost" size="icon-xs" aria-label="Limpar busca" onClick={() => setQ('')}>
             <X />
           </Button>
         ) : undefined
@@ -167,7 +166,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. |
-| `context` | `'neutral' \| 'primary' \| 'danger'` | `'primary'` | Contexto semântico herdado de Button. |
+| `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. |
 
 ### Propriedades de InputGroupInput

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

@@ -4,7 +4,8 @@ A composição completa usa `ItemMedia` à esquerda, `ItemHeader` (`ItemTitle` +
 `ItemDescription`) no meio e `ItemActions` à direita. Í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 alinhamento horizontal e reduz o padding vertical para `0.5rem` em listas densas.
+mantém o padding horizontal, reduz o padding vertical para `0.5rem` e o espaço entre regiões para
+`0.625rem` em listas densas.
 
 ```tsx preview col
 <Item variant="outline">
@@ -61,7 +62,7 @@ mantém o alinhamento horizontal e reduz o padding vertical para `0.5rem` em lis
 
 ## 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 variant=image ancora um avatar.
+`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.
 
 ```tsx preview col
 <Item asChild size="sm" variant="outline">
@@ -99,7 +100,7 @@ Use `ItemBody` quando a linha também apresenta um valor ou controle que não pe
 </Item>
 ```
 
-`ItemContent` permanece exportado somente para compatibilidade durante a versão 12. Código novo
+`ItemContent` permanece exportado apenas por compatibilidade e está obsoleto. Código novo
 usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 
 ## Propriedades de Item
@@ -124,4 +125,4 @@ usa `ItemHeader` ou `ItemBody` conforme o papel do conteúdo.
 
 `ItemHeader`, `ItemTitle`, `ItemDescription`, `ItemBody`, `ItemActions`, `ItemFooter` e
 `ItemSeparator` aceitam as props nativas dos respectivos elementos e não adicionam propriedades
-próprias. `ItemContent` preserva esse mesmo contrato somente durante a migração da versão 12.
+próprias. O `ItemContent` obsoleto preserva esse mesmo contrato por compatibilidade.

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

@@ -27,7 +27,7 @@ reconhecível que o nome da tecla.
 ```tsx preview col-start
 <KbdGroup>
   <Kbd>
-    <Command />
+    <CommandIcon />
   </Kbd>
   <Kbd>
     <CornerDownLeft />
@@ -49,6 +49,7 @@ ação antes de informar seu atalho.
     Buscar workspace
     <KbdGroup>
       <Kbd>⌘</Kbd>
+      <span>+</span>
       <Kbd>K</Kbd>
     </KbdGroup>
   </TooltipContent>

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

@@ -17,16 +17,22 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 const server = createOpusMcpServer(runtime, {
   name: 'meu-app',
   // Valida a identidade da requisição (IdP) → contexto do runtime. Sem isso, roda anônimo
-  // (o `can` nega → só actions públicas). Com isso, o agente age COMO O USUÁRIO.
+  // (sem usuário, só actions `public` rodam). Com isso, o agente age COMO O USUÁRIO.
   resolveContext: async (extra) => auth.resolveFromMcp(extra),
 })
 
 await server.connect(new StdioServerTransport()) // local; HTTP/SSE para remoto
 ```
 
-`ListTools` devolve as actions `ai:enabled` (nome + descrição + JSON Schema do input);
-`CallTool` executa a action pelo `runtime.execute` — validação, auth (`ctx.can`) e audit,
-tudo igual a uma chamada normal. Read-only? Marque só actions de leitura com `ai:enabled`.
+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.
 
 ## Escolher entre integração interna e MCP
 

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

@@ -104,6 +104,14 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 </Menu>
 ```
 
+## Propriedades de Menu
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Estado do painel no modo controlado, como no menu de contexto. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando o painel abre ou fecha. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
+
 ## Propriedades de MenuItem
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -137,3 +145,22 @@ próprias além das de DOM.
 |---|---|---|---|
 | `value` | `string` | | Valor selecionado no grupo. |
 | `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outro `MenuRadioItem`. |
+
+## Propriedades de MenuRadioItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `value` | `string` | | Valor que o item entrega ao `MenuRadioGroup` quando é selecionado. |
+| `disabled` | `boolean` | `false` | Impede a seleção do item. |
+
+## Propriedades de MenuLabel
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `inset` | `boolean` | | Alinha o rótulo com itens que possuem ícone. |
+
+## Propriedades de MenuSubTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `inset` | `boolean` | | Alinha o gatilho do submenu sem ícone com os itens que possuem ícone. |

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

@@ -92,7 +92,17 @@ Na composição explícita, combine somente as regiões necessárias. Este exemp
 uma ação global e o intro para o título:
 
 ```tsx preview col
-<PageShell navigation={<Breadcrumb>...</Breadcrumb>}>
+<PageShell
+  navigation={
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>Vendas</BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbPage>Clientes</BreadcrumbPage>
+      </BreadcrumbList>
+    </Breadcrumb>
+  }
+>
   <Page>
     <PageHeader>
       <PageActions>
@@ -172,7 +182,7 @@ e, sem `title`, valem `errorMessage` e `emptyMessage`.
     status="empty"
     title="Nenhum relatório"
     description="Crie o primeiro relatório para começar."
-    action={<Button>Novo relatório</Button>}
+    action={<Button>Criar relatório</Button>}
   />
 </Page>
 ```
@@ -204,7 +214,7 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo                          | Descrição                                                             |
 | ----------- | ----------------------------- | --------------------------------------------------------------------- |
-| `children`  | `ReactNode`                   | Título introdutório e, quando necessário, ações ligadas à introdução. |
+| `children`  | `ReactNode`                   | `PageBack` ou `PageNavigation`, título introdutório e, quando necessário, ações ligadas à introdução. |
 | `className` | `string`                      | Classes adicionais da região introdutória.                            |
 | demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região introdutória.                   |
 
@@ -212,15 +222,19 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade | Tipo        | Descrição                                                                                |
 | ----------- | ----------- | ---------------------------------------------------------------------------------------- |
-| `className` | `string`    | Classes adicionais da região externa do cabeçalho.                                       |
+| `className` | `string`    | Classes adicionais da região externa do cabeçalho, fora de `PageShell`.                  |
 | `children`  | `ReactNode` | `PageBack` ou `PageNavigation`, `PageActions` e, fora do shell, um `PageTitle` opcional. |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à região externa do cabeçalho, fora de `PageShell`. |
+
+Dentro de `PageShell`, `PageHeader` não renderiza uma região própria: devolve somente os filhos,
+que o shell projeta na barra, e ignora `className` e os demais atributos.
 
 ## Propriedades de PageBack
 
 | 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`                            |                          | 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 no tooltip.                                |
 | `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`.                                 |

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

@@ -131,7 +131,7 @@ render(
 | `page` | `number` | | Número usado como conteúdo, quando `children` não é informado, e no nome acessível “Página N”. |
 | `isActive` | `boolean` | `false` | Marca a página atual com `aria-current="page"` e tratamento `outline`. |
 | `href` | `string` | | Renderiza um `<a>`. Sem `href`, o componente usa `<button>` e aceita `onClick` e `disabled`. |
-| `size` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. A largura mínima cresce para acomodar números longos; os `icon-*` são quadrados. |
+| `size` | `ButtonProps['size']` | `'default'` | A escala única, via `Button`. Os `icon-*` são quadrados. Nos tamanhos textuais, a altura fica fixa em 2.25rem com largura mínima quadrada que cresce para números longos, então `size="sm"` não reduz a altura; para uma barra mais baixa, use um `icon-*` ou ajuste por `className` (ex.: `h-7 min-w-7 text-xs`). |
 
 ## Propriedades de PaginationPrevious e PaginationNext
 
@@ -139,5 +139,12 @@ render(
 |---|---|---|---|
 | `label` | `string` | `'Página anterior'` ou `'Próxima página'` | Nome acessível e texto visível da ação. |
 | `iconOnly` | `boolean` | `false` | Exibe somente a seta; `label` continua disponível para leitura assistiva. |
-| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. |
+| `size` | `ButtonProps['size']` | `'default'`; `'icon'` com `iconOnly` | A escala única; `icon-sm` para o rodapé denso. Sem `iconOnly`, a altura permanece 2.25rem em qualquer tamanho textual, como em `PaginationLink`. |
 | `iconClassName` | `string` | | Classes aplicadas ao ícone da seta, quando o glifo da escala não servir. |
+
+## Propriedades de PaginationEllipsis
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `size` | `'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'icon'` | Quadrado da escala única; use o mesmo tamanho das setas ao lado. |
+| `className` | `string` | | Classes adicionais aplicadas à elipse. |

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

@@ -29,13 +29,13 @@ detalhes.
 
 ```tsx preview
 <Popover>
-  <PopoverTrigger asChild><Button variant="ghost">start</Button></PopoverTrigger>
+  <PopoverTrigger asChild><Button variant="ghost">Início</Button></PopoverTrigger>
   <PopoverContent align="start" className="w-56">
     <PopoverDescription>Alinhado à borda esquerda do gatilho.</PopoverDescription>
   </PopoverContent>
 </Popover>
 <Popover>
-  <PopoverTrigger asChild><Button variant="ghost">end</Button></PopoverTrigger>
+  <PopoverTrigger asChild><Button variant="ghost">Fim</Button></PopoverTrigger>
   <PopoverContent align="end" className="w-56">
     <PopoverDescription>Alinhado à borda direita do gatilho.</PopoverDescription>
   </PopoverContent>

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

@@ -9,8 +9,10 @@ uma etapa de navegação. Formulários modais dimensionam o footer pelo conteúd
 `ghost` e a ação principal sólida.
 Em Page hospedada por `PageShell`, a barra concentra navegação e ações globais. Uma Presentation
 de listagem materializa título e comandos de header no `Content` que envolve o `ActionList`; assim
-a criação permanece próxima da coleção. Esses comandos usam `default`. Nas demais Presentations, o
-título abre o conteúdo em `PageIntro` e comandos da superfície usam `default`.
+a criação permanece próxima da coleção. Esses comandos usam o tamanho `default`: o que abre outra
+Presentation é um `Button` na variante padrão (`solid`), e uma action `simple` vira um
+`ActionTrigger` na variante `ghost`. Nas demais Presentations, o título abre o conteúdo em
+`PageIntro` e os comandos da superfície seguem a mesma regra.
 
 Use esse padrão quando uma lista puder abrir um detalhe lateral, quando a mesma edição precisar
 funcionar em modal e em rota própria ou quando um fluxo começar compacto e crescer sem ganhar uma
@@ -22,25 +24,29 @@ compõe `PageBody` e, quando necessário, `PageFooter`. Para uma action `list`,
 `Content + ActionList`; o header da coleção recebe o título e os comandos declarados no placement
 `header`. Dialog e Drawer continuam usando o header da própria superfície.
 Os comandos da coleção ficam no extremo oposto ao título e permanecem textuais, mesmo quando a
-action declara um ícone. A criação usa `Criar recurso`, sem ícone, em um botão `default`.
+action declara um ícone. A criação usa `Criar recurso`, sem ícone, em um `Button` na variante
+padrão (`solid`) e no tamanho `default`.
 Não envolva a Presentation em um card para simular a página; valide proporção, rolagem e ações no
 shell que efetivamente hospeda a rota.
 
-```tsx live
-const workspaceUpdate = defineContract({
-  name: "workspace.update",
-  kind: "form",
-  label: "Editar workspace",
-  input: z.object({ name: z.string() }),
-  output: z.object({ id: z.string() }),
-  fields: { name: { label: "Nome" } },
-});
+O exemplo declara a Presentation sobre um contrato de formulário e alterna a superfície. O
+`DocBrowserActionProvider` simula o cliente de actions; na aplicação, esse papel é do provider real.
 
+Quando o recurso aceita assistência contextual, declare somente o gatilho serializável em
+`assistant`. O renderer coloca esse gatilho no cabeçalho e abre o painel à direita do body da
+própria Page, Dialog ou Drawer. Cabeçalho e rodapé continuam ocupando toda a largura da superfície;
+enquanto o painel está aberto, o gatilho sai do cabeçalho e o próprio painel assume sua identidade
+visual. O dado vivo do recurso não entra na definição: a página que o carregou fornece
+`assistant.render`, captura identidade, nome e demais dados autorizados e monta o chat. Assim,
+contexto de conversa não vira autorização nem dado persistido no manifest.
+
+```tsx live
 const workspacePresentation = definePresentation({
   schemaVersion: 1,
-  id: "workspace.update",
-  title: "Editar workspace",
-  body: { action: workspaceUpdate.name },
+  id: "workspace.create",
+  title: "Criar workspace",
+  assistant: { triggerLabel: "Conversar sobre este workspace" },
+  body: { action: docWorkspaceCreate.name },
 });
 
 function Example() {
@@ -55,36 +61,54 @@ function Example() {
   );
 
   return (
-    <div className="space-y-4">
-      <ButtonGroup mode="spaced">
-        {["page", "dialog", "drawer"].map((value) => (
-          <Button
-            key={value}
-            size="sm"
-            variant={invocation.surface === value ? "solid" : "outline"}
-            onClick={() => {
-              setInvocation({ ...invocation, surface: value });
-              setOpen(true);
-            }}
-          >
-            {value}
-          </Button>
-        ))}
-      </ButtonGroup>
-
-      <Presentation
-        definition={workspacePresentation}
-        definitions={[workspacePresentation]}
-        actions={{ [workspaceUpdate.name]: workspaceUpdate }}
-        invocation={invocation}
-        open={invocation.surface === "page" || open}
-        onOpenChange={setOpen}
-        onInvocationChange={(next) => {
-          if (next) setInvocation(next);
-          else setOpen(false);
-        }}
-      />
-    </div>
+    <DocBrowserActionProvider>
+      <div className="space-y-4">
+        <ButtonGroup mode="spaced">
+          {["page", "dialog", "drawer"].map((value) => (
+            <Button
+              key={value}
+              size="sm"
+              variant={invocation.surface === value ? "solid" : "outline"}
+              onClick={() => {
+                setInvocation({ ...invocation, surface: value });
+                setOpen(true);
+              }}
+            >
+              {value}
+            </Button>
+          ))}
+        </ButtonGroup>
+
+        <Presentation
+          definition={workspacePresentation}
+          definitions={[workspacePresentation]}
+          actions={{ [docWorkspaceCreate.name]: docWorkspaceCreate }}
+          invocation={invocation}
+          open={invocation.surface === "page" || open}
+          onOpenChange={setOpen}
+          onInvocationChange={(next) => {
+            if (next) setInvocation(next);
+            else setOpen(false);
+          }}
+          assistant={{
+            render: ({ close }) => (
+              <div className="flex h-full flex-col p-3">
+                <p className="text-sm">
+                  Conversa vinculada ao workspace carregado pela página.
+                </p>
+                <Button
+                  className="mt-3 self-start"
+                  variant="ghost"
+                  onClick={close}
+                >
+                  Fechar
+                </Button>
+              </div>
+            ),
+          }}
+        />
+      </div>
+    </DocBrowserActionProvider>
   );
 }
 
@@ -165,19 +189,22 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 
 ## Propriedades de Presentation
 
-| Propriedade          | Tipo                                             | Padrão | Descrição                                              |
-| -------------------- | ------------------------------------------------ | ------ | ------------------------------------------------------ |
-| `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.              |
-| `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno. |
-| `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato. |
-| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.              |
-| `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.   |
-| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                |
-| `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.           |
-| `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                 |
-| `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.    |
-| `className`          | `string`                                         |        | Classes adicionais da superfície.                      |
-| `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.   |
+| Propriedade          | Tipo                                             | Padrão | Descrição                                                                                           |
+| -------------------- | ------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------- |
+| `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.                                                           |
+| `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno.                                              |
+| `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato.                                              |
+| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.                                                           |
+| `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.                                                |
+| `assistant`          | `PresentationAssistantRuntime`                   |        | Painel contextual fornecido pela superfície hospedeira.                                             |
+| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                                                             |
+| `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.                                                        |
+| `listState`          | `ActionListState`                                |        | Recorte controlado da action `list` do body, quando a aplicação o sincroniza com a URL.             |
+| `onListStateChange`  | `(state: ActionListState) => void`               |        | Recebe cada mudança de recorte ou exibição da lista do body, como busca, filtros, período e página. |
+| `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                                                              |
+| `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.                                                 |
+| `className`          | `string`                                         |        | Classes adicionais da superfície.                                                                   |
+| `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.                                                |
 
 ## Propriedades de PresentationInspector
 

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

@@ -29,13 +29,9 @@ render(
       <span className="text-muted-foreground">{step}%</span>
     </div>
     <Progress value={step} />
-    <button
-      type="button"
-      onClick={advance}
-      className="rounded-md border px-3 py-1.5 text-sm hover:bg-muted"
-    >
+    <Button variant="outline" size="sm" onClick={advance}>
       Avançar etapa
-    </button>
+    </Button>
   </div>,
 )
 ```

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

@@ -38,16 +38,17 @@ await runtime.start()
 
 | Capacidade | Fornece | Driver pronto |
 |---|---|---|
-| `server` | monta as actions (HTTP) | `fastifyServer` — `@softize/opus/server/fastify` |
+| `server` | monta as actions (HTTP) | `fastifyServer` — `@softize/opus/server/fastify` · `nodeServer` — `…/server/node` |
 | `data` | `ctx.db` + drift-check + CRUD | `kyselyData`, `kyselyRepo`, `crudActions` — `@softize/opus/data/kysely` |
 | `auth` | `user`/`tenantId`/`can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
 | `audit` | trilha por execução de action | `pgAudit` — `…/audit/pg` · `consoleAudit` — `…/audit/console` |
-| `log` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
-| `observability` | span ativo + propagação de trace | porta no core; driver opt-in |
+| `logger` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
+| `observability` | span ativo + propagação de trace | `openTelemetryObservability` — `@softize/opus/observability/opentelemetry` |
 | `eventBus` | `ctx.emit` + **reactions** | `mittEvents` — `@softize/opus/events/mitt` |
 | `queue` | jobs em background | `bullmqQueue` — `@softize/opus/queue/bullmq` |
 | `scheduler` | **schedules** (cron/intervalo) | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
 | `storage` | `ctx.storage` (arquivos) | `fsStorage` — `…/storage/fs` · `s3Storage` — `…/storage/s3` |
+| `cache` | `ctx.cache` (leitura, experimental) | `memoryCache` — `@softize/opus/cache/memory` |
 | `ai` | `ctx.ai` (complete/extract) | `anthropicAi` — `@softize/opus/ai/anthropic` |
 | `client` | chamar actions de fora (stubs) | `fetchClient` — `@softize/opus/client/fetch` |
 
@@ -61,7 +62,7 @@ Fora do runtime, mas parte do protocolo: o harness de teste (`runAction`/`testCo
 > e o handler decide como degradar.
 
 `user`/`tenantId`/`can` (auth) · `db` (data) · `log` (logger) · `emit` (eventBus) ·
-`storage` (storage) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
+`storage` (storage) · `cache` (cache) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
 reaction…) · `trace` (quando configurado) · `meta`.
 
 O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions
@@ -85,7 +86,9 @@ representa span de erro. Reactions usam `resultKind: 'void'` e rejeitam em falha
 > tempo dispara schedule (que executa uma action, com provenance própria).
 
 Declarados como as actions e registrados no mesmo `runtime.register` — o manifest
-projeta os três (o Maestro mostra o wiring em Visão geral).
+projeta os três. `opus introspect` lista reactions, schedules e o wiring entre eles, mas por
+enquanto só reconhece actions declaradas com `defineAction`: as do split `defineContract` +
+`bindAction` ficam de fora do modelo que ele monta.
 
 ## Referência profunda
 

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

@@ -19,7 +19,7 @@ interface ScheduleDef {
   action: string              // action do registry, executada quando dispara
   cron?: string               // '0 9 * * *' (9h todo dia)
   every?: string              // '1h', '30m', '15s' — atalho de intervalo
-  timezone?: string           // IANA, ex.: 'America/Sao_Paulo' (default UTC)
+  timezone?: string           // IANA, ex.: 'America/Sao_Paulo' (sem ele: hora local do processo)
   input?: unknown | (() => unknown | Promise<unknown>)   // estático ou dinâmico
   enabled?: boolean
 }

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

@@ -26,8 +26,9 @@ render(
 
 ## Lista pesquisável
 
-Use `searchable` quando a quantidade ou os rótulos dificultarem encontrar uma opção. O próprio
-campo passa a filtrar `label`, `hint` e `value` com a busca do cmdk.
+Use `searchable` quando a quantidade ou os rótulos dificultarem encontrar uma opção. O gatilho
+continua exibindo a escolha; a busca aparece em uma linha no topo da lista e filtra `label`, `hint`
+e `value`.
 
 ```tsx preview col md
 const [issue, setIssue] = useState('')
@@ -40,7 +41,7 @@ render(
       id="issue"
       value={issue}
       onChange={setIssue}
-      placeholder="Buscar item…"
+      placeholder="Selecione a issue"
       options={[
         { value: '412', label: 'Ajustar microcopy do handoff', hint: 'SOF-412' },
         { value: '418', label: 'Preview da sessão cai após deploy', hint: 'SOF-418' },
@@ -323,7 +324,7 @@ render(
       { value: 'gra-7', label: 'Filtro por filial', hint: 'GRA-7' },
     ]}
     trailing={
-      <Button variant="ghost" size="icon-xs">
+      <Button variant="ghost" size="icon-xs" aria-label="Abrir tarefa">
         <FileText />
       </Button>
     }
@@ -338,12 +339,12 @@ render(
 | `options` | `SelectOption[]` | | As opções: `{ value, label, hint?, content?, triggerLabel?, group?, disabled? }`. |
 | `value` | `string \| string[]` | | O selecionado: string no single, string[] no multiple. |
 | `onChange` | `(value: string) => void \| (value: string[]) => void` | | Chamado ao escolher (e ao remover chip, no multiple) — a assinatura segue o modo. |
-| `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, multi e ghost (o browser é quem desenha a lista). |
-| `searchable` | `boolean` | `false` | O campo vira busca: filtra a lista enquanto digita. |
+| `native` | `boolean` | `false` | Renderiza o `<select>` do sistema. Exclui busca, seleção múltipla e variantes visuais (o browser é quem desenha a lista). |
+| `searchable` | `boolean` | `false` | Acrescenta uma linha de busca no topo da lista, que filtra as opções enquanto a pessoa digita. O gatilho continua exibindo a escolha. |
 | `multiple` | `boolean` | `false` | Chips removíveis, lista que permanece aberta e Selecionar tudo. |
-| `variant` | `'default' \| 'ghost'` | `'default'` | `ghost` = sem moldura, para barra do composer. |
+| `variant` | `'default' \| 'outline' \| 'ghost'` | `'default'` | `outline` = compacto com borda; `ghost` = compacto sem borda nem fundo, para barra do composer. |
 | `placeholder` | `string` | `'Selecione…'` | Texto do campo vazio. |
-| `searchPlaceholder` | `string` | | Placeholder enquanto busca; cai para o `placeholder` se ausente. |
+| `searchPlaceholder` | `string` | `'Buscar…'` | Placeholder da linha de busca dentro da lista. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
 | `onSearch` | `(query: string) => void` | | Busca server-side (debounced, ao abrir e ao digitar): desliga o filtro do cmdk — o pai atualiza `options`. |
 | `loading` | `boolean` | | Mostra Buscando… enquanto o fetch corre (use com `onSearch`). |
@@ -351,6 +352,10 @@ render(
 | `icon` | `React.ReactNode` | | Ícone leading DENTRO do controle (decorativo) — herda `size-4` e o tom muted. |
 | `trailing` | `React.ReactNode` | | Ação custom no FIM do controle (antes do chevron) — o clique não abre a lista. |
 | `size` | `'default' \| 'sm'` | `'default'` | Altura: default (h-9, a do Input e do Button) ou sm (h-8) para toolbar densa. |
+| `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades e preserva a variante visual. |
 | `disabled` | `boolean` | `false` | Esmaece e trava o controle. |
 | `id` | `string` | | Vai para o campo — para parear com o `htmlFor` do Label. |
+| `aria-label` | `string` | | Nome acessível quando não há `Label` associado. |
+| `aria-invalid` | `boolean` | | Comunica e apresenta o estado inválido. |
+| `aria-describedby` | `string` | | Liga o controle a uma ajuda ou mensagem de erro. |
 | `className` | `string` | | Classes da raiz do controle, incluindo campo, ícones e ações, em todos os modos. |

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

@@ -63,7 +63,7 @@ uma sidebar fixa, redimensionável ou recolhida.
 | `PaneFooter` | Mantém ações persistentes no rodapé. |
 | `SidebarNav` | Apresenta e controla os destinos de navegação. |
 
-`PaneContent` permanece como alias temporário de `PaneBody` durante a versão 12. Código novo usa
+`PaneContent` continua exportado como alias depreciado de `PaneBody`. Código novo usa
 `PaneBody`.
 
 ## Escolher a navegação
@@ -138,7 +138,8 @@ páginas são folhas. Um grupo começa aberto e volta a abrir quando contém a p
 
 `collapsed` pertence à `Sidebar`. Nesse estado, `SidebarItem` e `SidebarNav` mantêm
 somente os ícones e expõem os rótulos em tooltips. Por isso, todo destino que aparece no modo
-recolhido precisa de um ícone reconhecível e de um `label` completo.
+recolhido precisa de um ícone reconhecível e de um `label` completo. `SidebarNav` já monta o
+`TooltipProvider`; um `SidebarItem` recolhido fora dele depende do provider na raiz do aplicativo.
 
 O slot de ícone do `SidebarItem` ocupa `1rem` nos dois estados e normaliza SVGs para essa medida.
 O consumidor escolhe o símbolo e sua cor sem precisar repetir largura ou altura em ícones SVG.

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

@@ -15,7 +15,7 @@ avatares e barras com dimensões próximas às linhas de texto esperadas.
 
 ## Card em carregamento
 
-O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para tela não pular quando os dados chegarem.
+O esqueleto reproduz o layout final do card — título, descrição, conteúdo e ações — para a tela não pular quando os dados chegarem.
 
 ```tsx preview col
 <Card>