@softize/opus 18.5.0 → 20.0.0

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

@@ -1,16 +1,19 @@
 ## Notificação temporária
 
-Use `toast` para informar o resultado temporário de uma ação sem interromper o fluxo. Cada tipo usa o
-ícone correspondente do Opus. Escreva o título como rótulo, sem ponto final, e a descrição como uma
-frase. A moldura do ícone permanece quadrada e alinhada à primeira linha mesmo quando a descrição
-ocupa várias linhas. Corpo e padding seguem os mesmos `0.875rem` e `0.75rem` do Alert; os defaults
-internos do Sonner não definem a densidade da casa.
+Use `toast` para informar o resultado temporário de uma ação sem interromper o fluxo. A notificação
+some sozinha, então não use toast para algo que a pessoa precisa ler ou resolver depois; nesse caso,
+mantenha a mensagem na página com [`Alert`](/ui/alert).
+
+Cada tipo usa o ícone correspondente do Opus. Escreva o título como rótulo, sem ponto final, e a
+descrição como uma frase. A moldura do ícone permanece quadrada e alinhada à primeira linha mesmo
+quando a descrição ocupa várias linhas. Corpo e padding seguem os mesmos `0.875rem` e `0.75rem` do
+`Alert`.
 
 ```tsx preview
 <Button variant="outline" onClick={() => toast.success('Workspace criado')}>Sucesso</Button>
 <Button
   variant="outline"
-  onClick={() => toast.error('Falha no push', { description: 'O Multica não respondeu — tente de novo.' })}
+  onClick={() => toast.error('Falha no push', { description: 'O repositório remoto não respondeu. Tente de novo.' })}
 >
   Erro
 </Button>
@@ -52,7 +55,7 @@ oferecer uma ação.
   variant="outline"
   onClick={() =>
     toast.promise(new Promise((resolve) => setTimeout(resolve, 1800)), {
-      loading: 'Publicando no Multica…',
+      loading: 'Publicando agentes…',
       success: 'Agentes publicados',
       error: 'Falha ao publicar',
     })
@@ -62,6 +65,28 @@ oferecer uma ação.
 </Button>
 ```
 
+## Carregamento e mensagens neutras
+
+`toast.message`, como `toast`, exibe uma notificação sem ícone de tipo. `toast.loading` mostra o
+indicador de progresso e não expira sozinho: guarde o identificador que ele retorna e passe-o em
+`id` para trocar a mesma notificação pelo resultado. `toast.dismiss(id)` fecha uma notificação; sem argumento, fecha todas.
+
+```tsx preview
+<Button
+  variant="outline"
+  onClick={() => {
+    const id = toast.loading('Sincronizando workspace…')
+    setTimeout(() => toast.success('Workspace sincronizado', { id }), 1800)
+  }}
+>
+  Carregamento
+</Button>
+<Button variant="outline" onClick={() => toast.message('Rascunho salvo neste navegador')}>
+  Neutra
+</Button>
+<Button variant="ghost" onClick={() => toast.dismiss()}>Fechar todas</Button>
+```
+
 ## Toaster na raiz
 
 Monte um único `Toaster` na raiz do aplicativo. O tema vem da propriedade `theme`, cujo padrão é
@@ -80,11 +105,27 @@ Monte um único `Toaster` na raiz do aplicativo. O tema vem da propriedade `them
 | `theme` | `'light' \| 'dark' \| 'system'` | `'system'` | Define o tema das notificações; sem `next-themes`, a escolha pertence ao aplicativo. |
 | `position` | `'bottom-right' \| 'top-center' \| …` | `'bottom-right'` | Região da tela onde as notificações aparecem. |
 
+## Funções de toast
+
+As funções de notificação (`toast` e suas variantes de contexto, `message` e `loading`) recebem o
+título e as opções e retornam o identificador da notificação. `toast.promise` e `toast.dismiss` têm
+assinaturas próprias, indicadas na tabela.
+
+| Função | Descrição |
+|---|---|
+| `toast(title, options?)` | Notificação padrão, sem ícone de tipo. |
+| `toast.success`, `toast.info`, `toast.warning`, `toast.error` | Notificação com o ícone e a cor do contexto correspondente. |
+| `toast.message(title, options?)` | Equivale a `toast(title, options?)`: notificação sem ícone de tipo. |
+| `toast.loading(title, options?)` | Notificação com indicador de progresso que não expira sozinha. |
+| `toast.promise(promise, { loading, success, error })` | Acompanha a promessa e atualiza a mesma notificação. Não aceita `actions`. |
+| `toast.dismiss(id?)` | Fecha a notificação indicada ou, sem argumento, todas. |
+
 ## Opções de toast
 
 | Opção | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `description` | `React.ReactNode` | | Complemento exibido abaixo do título. |
+| `id` | `string \| number` | gerado | Identificador da notificação. Passe o de uma notificação existente para substituí-la, como depois de `toast.loading`. |
 | `actions` | `ToastAction[]` | | Coleção ordenada de ações; a última recebe destaque primário por padrão. |
 | `duration` | `number` | `4000` | Tempo de permanência da notificação, em milissegundos. O `Toaster` pode mudar o padrão, e `toast.loading` não expira sozinho. |
 

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

@@ -50,7 +50,7 @@ borda. `size` ajusta a altura.
 
 ## Desabilitado
 
-disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
+`disabled` esmaece o toggle e bloqueia o clique. O estado pressionado continua visível.
 
 ```tsx preview
 <Toggle disabled aria-label="Negrito">
@@ -66,10 +66,10 @@ disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `pressed` | `boolean` | | O estado ligado/desligado no modo controlado — parear com onPressedChange. |
+| `pressed` | `boolean` | | Estado no modo controlado. Use com `onPressedChange`. |
 | `onPressedChange` | `(pressed: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultPressed` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `variant` | `'default' \| 'outline'` | `'default'` | default não tem borda (fundo só quando ativo); outline carrega a borda. |
+| `variant` | `'default' \| 'outline'` | `'default'` | `default` não tem borda e só ganha fundo quando ativo; `outline` mantém a borda. |
 | `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
 | `shape` | `'default' \| 'pill'` | `'default'` | Geometria do controle; `pill` arredonda as extremidades. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |

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

@@ -4,9 +4,10 @@ title: Tokens e tema
 
 # Tokens e tema
 
-O tema canônico vive no Opus (`theme.css`): tokens com a cor inteira na var, mapeados para o
-Tailwind via `@theme inline`. Os swatches abaixo leem as vars **ao vivo** — troque o tema do app
-e a página acompanha.
+Use esta página para escolher a cor, a borda, a sombra, o texto ou o raio certo em uma tela e para
+saber quais variáveis sobrescrever ao aplicar a marca do projeto. Os tokens ficam em `theme.css`:
+cada variável guarda a cor inteira e é mapeada para as classes do Tailwind por `@theme inline`. Os
+exemplos leem as variáveis ao vivo; troque o tema do app e a página acompanha.
 
 ## Superfícies e intenções
 
@@ -210,24 +211,20 @@ render(
 
 ## Divergências declaradas vs shadcn
 
-> A regra anti-drift: o que não está declarado aqui (e no `theme.css`) é drift e deve ser
-> sincronizado — skill `build-opus-ui`.
+> Qualquer diferença em relação ao shadcn que não esteja declarada aqui (e no `theme.css`) é uma
+> divergência a sincronizar, conforme a skill `build-opus-ui`.
 
-1. Formato HSL nos tokens (o upstream migrou para oklch) — legibilidade e ferramentas nossas; os
-   valores acompanham o upstream, só o formato difere.
-2. Elevação no dark: `--card`/`--popover` ficam ACIMA de `--background` (10% vs 3.9%) — identidade
-   da casa; dialog e card "sobem" da página de verdade.
+1. Formato HSL nos tokens (o upstream migrou para oklch), escolhido pela legibilidade; os valores
+   acompanham o upstream, só o formato difere.
+2. Elevação no tema escuro: `--card` e `--popover` ficam acima de `--background` (`10%` contra `3.9%`
+   de luminosidade), para que dialog e card se destaquem de fato da página.
 3. Radius mapeado (`xs` a `2xl`) preservando o sentido pré-v4 dos utilitários `rounded-*`. Esse
    trecho derivado permanece monotônico quando a base muda; aplicações que também usam `3xl`
    precisam revisar a transição para esse degrau nativo ao customizar `--radius`.
-
 4. Escala `shadow-*` recomposta em duas camadas claras e difusas — preserva os degraus do
-   Tailwind e troca somente o peso visual. Os aliases antigos por papel foram removidos;
-   componentes e consumidores usam diretamente a escala.
-
-5. Bordas mais leves no light: `--border`/`--input` em 92.5% (upstream 89.8%) — par do canvas
+   Tailwind e troca somente o peso visual. Componentes e consumidores usam diretamente a escala.
+5. Bordas mais leves no tema claro: `--border`/`--input` em `92.5%` (upstream `89.8%`) — par do canvas
    quase-branco do body; superfícies elevadas usam essa mesma borda real.
-
 6. Radius base em `0.75rem` — superfícies principais ganham cantos mais presentes sem aproximar
    controles compactos de modais. A decisão detalhada acompanha o pacote em
    `docs/radius-scale.md`, com os defaults, o comportamento de superfícies aninhadas e as
@@ -235,14 +232,6 @@ render(
 
 ## Identidade por app
 
-> O tema do Opus é a base; cada app sobrescreve as vars para ter a própria identidade sem forkar componente.
-
-```css
-/* index.css do app — depois do import do tema. */
-@import '@softize/opus/ui/theme.css';
-
-:root {
-  --primary: hsl(262 83% 58%); /* A cor da marca do projeto. */
-  --ring: hsl(262 83% 58%);
-}
-```
+O tema do Opus é a base, e cada app sobrescreve as variáveis para ter a própria identidade sem
+copiar componentes. O passo a passo, com o exemplo de CSS, está em
+[Customização](/ui/customization).

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

@@ -2,7 +2,8 @@
 
 Use `Tooltip` para informação curta e complementar. Como a dica não está disponível em todas as
 formas de interação, ela não pode conter informação essencial. Botões somente com ícone continuam
-precisando de `aria-label`.
+precisando de `aria-label`. Para conteúdo que a pessoa precisa ler ou usar, como um formulário
+curto, use [`Popover`](/ui/popover).
 
 ```tsx preview
 <Tooltip>
@@ -62,7 +63,22 @@ default nos formulários.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `delayDuration` | `number` | `0` | Atraso antes da exibição, compartilhado pelos tooltips do aplicativo. |
+| `delayDuration` | `number` | `0` | Atraso antes da exibição, em milissegundos, compartilhado pelos tooltips do aplicativo. |
+
+## Propriedades de Tooltip
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `open` | `boolean` | | Estado da dica no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando a dica abre ou fecha. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
+| `delayDuration` | `number` | valor do `TooltipProvider` | Atraso antes da exibição desta dica, em milissegundos; substitui o do provider. |
+
+## Propriedades de TooltipTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Faz do filho (por exemplo, um `Button`) o gatilho, em vez de renderizar outro `<button>`. |
 
 ## Propriedades de TooltipContent
 

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

@@ -1,7 +1,8 @@
 ## Truncar somente quando necessário
 
 Use `Truncate` para limitar um texto a uma linha e mostrar a dica somente quando houver transbordo.
-O componente mede novamente o conteúdo quando o tamanho muda. Se o texto couber, não cria tooltip.
+O componente mede novamente o conteúdo quando o tamanho muda. Se o texto couber, não cria
+[tooltip](/ui/tooltip).
 
 ```tsx preview
 <div className="w-48 rounded-md border p-2">
@@ -34,8 +35,20 @@ escondido.
 Uma composição que precisa do esmaecimento sem o tooltip aplica a utilitária `truncate-fade`,
 que cobre o último `1.5rem` da caixa, e decide quando ligá-la com o hook `useOverflowing` — a
 mesma medição que este componente usa. A máscara pressupõe corte real: em texto que cabe
-inteiro, ela esmaeceria o fim de uma palavra visível. É assim que o rótulo do `SidebarItem`
-funciona.
+inteiro, ela esmaeceria o fim de uma palavra visível. É assim que o rótulo do `SidebarItem`, da
+[`Sidebar`](/ui/sidebar), funciona.
+
+```ts
+function useOverflowing<T extends HTMLElement>(content?: React.ReactNode): {
+  ref: React.RefObject<T | null>
+  overflowing: boolean
+}
+```
+
+Ligue `ref` ao elemento de uma linha que pode ser cortado. `overflowing` fica `true` quando o
+conteúdo é mais largo que a caixa. A medida é refeita quando a caixa muda de tamanho e quando
+`content` muda; passe nele o texto exibido, porque a troca de texto sem mudança de tamanho não é
+percebida de outra forma.
 
 ```tsx
 const { ref, overflowing } = useOverflowing<HTMLSpanElement>(label)
@@ -58,9 +71,26 @@ quando o texto completo ainda não oferecer contexto suficiente.
 </div>
 ```
 
-Requer `TooltipProvider` na raiz (o esqueleto do `opus create` já monta). Largura vem do
-container ou de `className` (`max-w-*`) — o span é `block` e corta em reticências (`truncate`); com
-`fade`, esmaece o fim da linha em vez das reticências.
+Requer `TooltipProvider` na raiz; o projeto criado por `opus create` já o monta. A largura vem do
+contêiner ou de `className` (`max-w-*`): o `span` é `block` e corta em reticências (`truncate`);
+com `fade`, esmaece o fim da linha em vez das reticências.
+
+## Acesso pelo teclado
+
+A dica abre quando o ponteiro passa sobre o texto ou quando o texto recebe o foco. Com o texto
+cortado, `Truncate` entra na ordem de tabulação e mostra o anel de foco dos controles, então quem
+navega pelo teclado alcança a dica com Tab. Sem corte, o texto fica fora da ordem de tabulação,
+porque não há nada escondido para revelar.
+
+Dentro de um link ou botão, o próprio controle já recebe o foco. Passe `tabIndex={-1}` ao
+`Truncate` para não criar uma segunda parada de tabulação no mesmo item. Nesse caso, a dica deixa de
+abrir pelo teclado: dê ao controle o nome completo, com `aria-label`, ou mostre o texto completo em
+outro lugar visível.
+
+Leitores de tela leem o texto completo do elemento, mesmo cortado na tela; o conteúdo próprio
+passado em `tooltip` só é anunciado enquanto a dica está aberta. Quando o texto completo for
+necessário para a tarefa, mostre-o também em um lugar que não dependa da dica, como o detalhe do
+registro.
 
 ## Propriedades de Truncate
 

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

@@ -5,53 +5,105 @@ title: Como consumir
 # Como consumir a UI
 
 Esta documentação é a referência visual e de uso de `@softize/opus/ui`. Os exemplos são renderizados
-com o tema e o contrato entregues aos aplicativos.
+com o mesmo tema e os mesmos componentes entregues aos aplicativos.
 
-## Por que esta doc existe
+## Por que esta documentação existe
 
-O catálogo do shadcn documenta seu próprio código e pode mostrar composições que não fazem parte do
+O catálogo do shadcn documenta o próprio código e pode mostrar composições que não fazem parte do
 Opus. Consulte estas páginas para conhecer os componentes, as variações e os comportamentos
 suportados pelo pacote.
 
 Cada página combina exemplos vivos, código e uma referência de propriedades por componente. A
-orientação inicial vem de `componentMeta`, a mesma fonte usada pelo catálogo e pelas ferramentas.
+orientação inicial de cada componente vem de `componentMeta`, a mesma fonte usada pelo catálogo e
+pelas ferramentas.
 
-## Como consumir
+## Importar componentes e tema
 
 Importe componentes e hooks de `@softize/opus/ui/react` e o tema por CSS. Não copie a implementação
 para o aplicativo quando a API pública já atender ao caso.
 
 ```tsx
-// Componentes e hooks — tudo do mesmo barrel.
+// Componentes e hooks vêm do mesmo ponto de entrada.
 import { Button, Dialog, useAction } from '@softize/opus/ui/react'
 ```
 
 ```css
-/* index.css — o tema canônico + os componentes do Opus no scan do Tailwind. */
+/* index.css — o tema do Opus e os componentes do pacote no scan do Tailwind. */
 @import '@softize/opus/ui/theme.css';
 @source '../node_modules/@softize/opus/src/ui/**/*.{ts,tsx}';
 ```
 
+## Montar os providers
+
+Os hooks de action e os componentes que executam actions dependem de três providers na raiz da
+aplicação. O app criado por `opus create` já nasce com eles:
+
+```tsx
+// main.tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { OpusProvider, TooltipProvider } from '@softize/opus/ui/react'
+import { fetchClient } from '@softize/opus/client/fetch'
+import { App } from './App.tsx'
+
+const queryClient = new QueryClient()
+// Mesma origem: as actions respondem em /api. Aponte baseUrl para outro servidor quando houver.
+const client = fetchClient({ baseUrl: '' })
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <OpusProvider client={client}>
+        <TooltipProvider>
+          <App />
+        </TooltipProvider>
+      </OpusProvider>
+    </QueryClientProvider>
+  </StrictMode>,
+)
+```
+
+- `QueryClientProvider` guarda o cache das consultas; `useListAction` e as invalidações entre
+  actions dependem dele.
+- `OpusProvider` informa como chamar as actions. Fora dele, os hooks de action lançam erro ao
+  montar.
+- `TooltipProvider` é exigido pelos tooltips da aplicação e por componentes do Opus que usam
+  tooltip, como `Dock` e `Truncate`.
+
+`fetchClient` chama cada action por HTTP em `<baseUrl><apiPrefix>`; `apiPrefix` tem padrão `/api`,
+o mesmo dos servidores do Opus. `headers` e `beforeRequest` acrescentam cabeçalhos fixos ou
+calculados a cada chamada, como um token de acesso.
+
+## Propriedades de OpusProvider
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `client` | `ClientAdapter` | obrigatório | Executa as actions chamadas pelos hooks e componentes; normalmente `fetchClient`. |
+| `dicts` | `Record<string, DictLike>` | `{}` | Dicionários por referência, usados por `options: { kind: 'dictionary', ref }` em campos e filtros. Sem registro, o campo usa os dados do `t.dict` que viajam no schema do contrato. |
+| `children` | `ReactNode` | obrigatório | A árvore que usa as actions. |
+
 ## Prebundle do Vite
 
-A entrada `@softize/opus/ui/react` é um `.tsx`, e o prebundle do Vite só considera entradas
-`.js`/`.ts`. Sem ajuste, o dev server avisa `Cannot optimize dependency` e serve a árvore do Opus
-arquivo a arquivo na carga fria. Há duas saídas, cada uma com um custo conhecido:
+A entrada `@softize/opus/ui/react` é um arquivo `.tsx`, e o prebundle do Vite só considera entradas
+`.js` e `.ts`. Sem ajuste, o dev server avisa `Cannot optimize dependency` e serve os arquivos do
+Opus um a um na primeira carga. Há duas saídas, cada uma com um custo conhecido:
 
 - `optimizeDeps.include: ['@softize/opus/ui/react']` com `extensions: ['.tsx']` pré-empacota o
-  Opus, mas pode duplicar `@tanstack/react-query` quando o app também o importa direto (dois
-  `QueryClient`, hooks fora do provider).
-- `optimizeDeps.exclude: ['@softize/opus/ui/react']` evita a duplicação e infla a carga fria.
+  Opus, mas pode duplicar `@tanstack/react-query` quando o app também o importa diretamente. O
+  resultado são dois `QueryClient` e hooks que não encontram o provider.
+- `optimizeDeps.exclude: ['@softize/opus/ui/react']` evita a duplicação e deixa a primeira carga
+  mais lenta.
 
-Escolha pelo sintoma que aparece no seu app e registre a decisão no `vite.config.ts`. A saída
-definitiva (entrada `.ts` no pacote) está no radar do Opus.
+Escolha pelo sintoma que aparece no seu app e registre a decisão no `vite.config.ts`. Uma entrada
+`.ts` no pacote, que resolveria os dois custos, ainda não existe.
 
-## Origem e anti-drift
+## Origem dos componentes
 
-> Cada componente declara de onde veio — e a regra de sincronização vem junto.
+Cada componente declara de onde veio, e essa origem define como ele acompanha mudanças:
 
-- **Origem shadcn** — port curado do shadcn (Radix + cmdk). Toda divergência do upstream é
-  DECLARADA no componente ou no tema — o que diverge sem declaração é drift e deve ser
-  sincronizado (skill `build-opus-ui`).
-- **Nativo do Opus** — nasceu aqui (os patterns de action). Não tem upstream para acompanhar; a
-  referência é esta doc.
+- **Origem shadcn:** adaptação do shadcn (Radix e cmdk). Toda divergência do original é declarada
+  no componente ou no tema. Uma divergência sem declaração deve ser sincronizada; a skill
+  `$build-opus-ui` orienta esse trabalho.
+- **Nativo do Opus:** criado no próprio Opus, como os componentes de action. Não há versão externa a
+  acompanhar; a referência é esta documentação.

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

@@ -4,74 +4,83 @@ title: Atualizar o Opus
 
 # Atualizar o Opus
 
-Use este fluxo para atualizar o Opus por uma ou várias versões. O changelog explica as mudanças e os
-gates apontam as adaptações necessárias no projeto.
+Use este fluxo para atualizar o Opus por uma ou várias versões. O [changelog](/changelog) explica
+as mudanças, e os gates apontam as adaptações necessárias no projeto. Em projetos que usam as
+skills do Opus, a skill `$upgrade-opus` conduz as mesmas etapas: lê o changelog, atualiza a
+dependência, materializa os artefatos e aplica as migrações.
 
-## 1. Identificar a versão disponível
+## 1. Atualizar a dependência
 
-O **Maestro** compara o pin (`opus.json`) com a versão instalada e com a fonte a cada
-sessão — o alerta no rodapé diz a distância (`v18.0.1 → v18.1.0`) e o **Atualizar** faz
-a parte mecânica: bump da dependência, re-materialização da camada de IA (skills,
-hooks, agentes) e re-sync do bloco gerenciado do CLAUDE.md.
-
-Fora do Maestro, faça essa parte à mão:
+A versão adotada pelo projeto fica no `package.json` e no `opus.json` de cada app. Compare-a com a
+versão publicada e atualize:
 
 ```bash
 pnpm outdated @softize/opus          # distância até a versão publicada
-pnpm -r up @softize/opus@<versão>    # em todo workspace que declara o Opus
-pnpm run setup                       # opus setup && base setup: re-materializa base.json e skills
+pnpm -r up @softize/opus@<versão>    # em todo pacote do workspace que declara o Opus
+pnpm run setup                       # opus setup && base setup: materializa base.json e skills
 ```
 
-Rode `setup` no diretório de cada app que tem `opus.json`; num monorepo criado por
+Rode `setup` no diretório de cada app que tem `opus.json`. Num monorepo criado por
 `opus create --monorepo`, a raiz não tem esse script, e `pnpm -r run setup` alcança todos os apps.
-O postinstall do pacote tenta materializar sozinho, mas é best-effort; se a camada materializada
-ainda corresponder à versão anterior, o `opus check` aborta com
+O postinstall do pacote tenta materializar os artefatos sozinho, mas não garante o resultado. Se a
+camada materializada ainda corresponder à versão anterior, o `opus check` para com
 `base.json: Opus aplicado X, instalado Y`.
 
+Interfaces de desenvolvimento podem mostrar a diferença entre a versão aplicada na
+sua cópia de trabalho e a adotada pela branch principal. Esse aviso não atualiza o pacote; a
+atualização continua sendo este fluxo.
+
 ## 2. Ler as mudanças acumuladas
 
-O changelog **viaja no pacote** — depois do bump, está em
-`node_modules/@softize/opus/CHANGELOG.md`. Uma entrada por versão; quando quebra,
-a seção **Breaking** diz a migração (o que renomeou, o que fazer no seu código).
-A esteira de release **recusa** publicar versão sem entrada — o arquivo não defasa.
+O changelog também acompanha o pacote: depois da atualização, ele está em
+`node_modules/@softize/opus/CHANGELOG.md`. Cada versão tem uma entrada, e a publicação é recusada
+quando a entrada falta. Quando uma versão quebra compatibilidade, a seção **Breaking** descreve o
+que mudou e como migrar o seu código.
 
-- **minor e patch** (18.0 → 18.1): leia todas as entradas intermediárias. Minors podem pedir ação,
-  como a troca de `PageHeader` por `PageIntro` no `PageShell` (17.2.0) ou o layout desktop fixo (18.1.0).
-- **major** (17.x → 18.0): além disso, aplique as seções Breaking de cada versão pulada, na ordem.
+- **Minor e patch** (18.0 → 18.5): leia todas as entradas intermediárias, porque elas também podem
+  mudar comportamento observável. Na 18.1.1, por exemplo, uma action que não é `public` passou a
+  exigir usuário antes de executar os `loads`.
+- **Major** (18.x → 19.0): além disso, aplique as seções Breaking de cada versão pulada, na ordem.
+  Na 19.0.0, por exemplo, os headers de `Card`, `Dialog` e `Drawer` passaram a aceitar somente os
+  slots da própria família.
 
 ## 3. Executar as verificações
 
-O Opus é publicado como código-fonte TypeScript: o que quebrou aparece com arquivo e linha.
-Rode, na ordem:
+O Opus é publicado como código-fonte TypeScript, então uma incompatibilidade aparece com arquivo e
+linha. Rode, na ordem:
 
 ```bash
-pnpm typecheck               # a API nova cobra os tipos
-pnpm exec opus check         # convenções (regras novas inclusas)
-pnpm exec opus copy --check  # inventário de copy em dia
-pnpm exec base copy check    # política de copy da base
+pnpm typecheck               # a API nova confere os tipos
+pnpm exec opus check         # convenções, inclusive regras novas
+pnpm exec opus copy --check  # inventário de copy atualizado
+pnpm exec base copy check    # política de copy da Base
 pnpm test                    # comportamento
-pnpm manifest:check          # a spec projetada ficou fresca?
+pnpm manifest:check          # o manifest projetado continua atualizado
 ```
 
-Num monorepo, `typecheck` e `test` existem na raiz, mas `manifest:check` é script de cada app:
-rode-o no diretório do app ou com `pnpm -r run manifest:check`. Nenhum desses comandos migra o
+Num monorepo, `typecheck` e `test` existem na raiz, mas `manifest:check` é um script de cada app:
+rode-o no diretório do app ou com `pnpm -r run manifest:check`. Nenhum desses comandos altera o
 banco. Se o projeto tiver testes de integração, eles usam o banco que o próprio projeto configurar.
 
 ## 4. Migrar o banco, se houver
 
 Se o `opus.config.ts` declara `database`, confira o schema e aplique a migração como uma etapa
-separada, contra o banco do ambiente que você pretende alterar:
+separada:
 
 ```bash
 pnpm exec opus db check      # compara entidades e banco, sem escrever
 pnpm exec opus db migrate    # aplica o schema idempotente; escreve no banco
 ```
 
-Com todas as verificações verdes, revise a atualização como qualquer outra mudança de código antes
-de entregá-la.
+Os comandos `opus db` carregam o `.env` que está ao lado do `opus.config.ts` antes de abrir a
+conexão, e uma variável já definida no ambiente vence o arquivo. Antes de migrar, confirme para
+qual banco a factory `database` vai apontar. Para migrar outro ambiente, informe a variável no
+próprio comando, como `DATABASE_URL=… pnpm exec opus db migrate` quando a factory lê essa variável.
+
+Com todas as verificações aprovadas, revise a atualização como qualquer outra mudança de código
+antes de entregá-la.
 
 ## Pulou muitas versões?
 
-O ritual não muda, só o volume: leia todas as entradas acumuladas, não só as seções Breaking
-(o changelog é uma lista, não um diff), aplique na ordem e deixe os gates validarem o conjunto.
-Não há caminho especial — é o mesmo laço, com mais iterações.
+O fluxo é o mesmo, com mais entradas para ler. Leia todas as entradas acumuladas, não só as seções
+Breaking, aplique as migrações na ordem das versões e deixe os gates validarem o conjunto.

package/src/ui/docs/plugin.ts

@@ -11,6 +11,11 @@
  * `mountDocs`. Importando o MESMO CSS do app, a doc herda identidade e utilitários de
  * graça. É dev-only (apply: 'serve') — nada vai pro bundle de produção.
  *
+ * O CSS entra por um entry CSS virtual que importa o do app e acrescenta um `@source` para
+ * as páginas `.md` da doc do Opus. Os exemplos ```tsx preview usam classes que só aparecem
+ * nesses `.md`, e o Tailwind do app não varre o pacote instalado. O `@source` fica só nesse
+ * entry: o CSS de produção do app não muda.
+ *
  * Uso (vite.config.ts do app):
  *   import { opusDocs } from '@softize/opus/ui/docs/plugin'
  *   export default defineConfig({ plugins: [react(), tailwindcss(), opusDocs()] })
@@ -36,6 +41,29 @@ const VIRTUAL_ID = 'virtual:opus-docs-entry'
 // O `/@id/` é como o vite serve módulos por id; o `\0` (convenção de virtual) vira `__x00__` na URL.
 const RESOLVED_ID = '\0' + VIRTUAL_ID
 const ENTRY_URL = '/@id/__x00__' + VIRTUAL_ID
+// A extensão `.css` faz o Vite e o @tailwindcss/vite tratarem o módulo virtual como folha de estilo.
+const VIRTUAL_CSS_ID = 'virtual:opus-docs-entry.css'
+const RESOLVED_CSS_ID = '\0' + VIRTUAL_CSS_ID
+
+/**
+ * Pasta das páginas `.md` da doc do Opus, ao lado deste arquivo. O Node carrega o plugin pelo
+ * caminho real (resolve o symlink do pnpm/workspace), então `import.meta.url` já aponta para
+ * onde o scanner do Tailwind encontra os arquivos.
+ *
+ * Sem builtins do Node: o arquivo mora em `ui/`, e o gate de fronteira proíbe `node:*` ali.
+ * Sem `new URL('./content', import.meta.url)`: o Vite reescreve esse padrão como asset.
+ */
+export function opusDocsContentDir(moduleUrl: string = import.meta.url): string {
+  const folder = moduleUrl.slice(0, moduleUrl.lastIndexOf('/'))
+  const path = decodeURIComponent(new URL(folder).pathname)
+  // No Windows o pathname vem como `/C:/…`; o Tailwind espera `C:/…`.
+  return (/^\/[A-Za-z]:\//.test(path) ? path.slice(1) : path) + '/content'
+}
+
+/** O CSS do entry virtual: o do app (tema + tailwind) + a varredura dos `.md` da doc. */
+export function opusDocsEntryCss(appCss: string, contentDir: string = opusDocsContentDir()): string {
+  return [`@import ${JSON.stringify(appCss)};`, `@source ${JSON.stringify(contentDir + '/*.md')};`].join('\n')
+}
 
 export function opusDocs(options: opusDocsOptions = {}): Plugin {
   const basePath = options.basePath ?? '/__docs'
@@ -48,12 +76,18 @@ export function opusDocs(options: opusDocsOptions = {}): Plugin {
     apply: 'serve',
     resolveId(id) {
       if (id === VIRTUAL_ID) return RESOLVED_ID
+      if (id === VIRTUAL_CSS_ID) return RESOLVED_CSS_ID
       return undefined
     },
-    load(id) {
+    async load(id) {
+      if (id === RESOLVED_CSS_ID) {
+        // O `@import` do entry virtual não tem pasta de referência: vai com o caminho resolvido.
+        const resolved = await this.resolve(css)
+        return opusDocsEntryCss(resolved?.id ?? css)
+      }
       if (id !== RESOLVED_ID) return undefined
       // Sempre importa o CSS do app (tema + tailwind) antes de subir a doc.
-      const head = `import ${JSON.stringify(css)}`
+      const head = `import ${JSON.stringify(VIRTUAL_CSS_ID)}`
       if (source === undefined || source === '') {
         // Sem `source`: a doc do próprio Opus (DOC_SECTIONS), como sempre.
         return [head, `import { mountDocs } from '@softize/opus/ui/docs/standalone'`, `mountDocs({ basePath: ${JSON.stringify(basePath)} })`].join('\n')

package/src/ui/docs/registry.tsx

@@ -37,6 +37,7 @@ import executionsMd from "./content/executions.md?raw";
 import schedulerMd from "./content/scheduler.md?raw";
 import actionsMd from "./content/actions.md?raw";
 import dataMd from "./content/data.md?raw";
+import dataProductsMd from "./content/data-products.md?raw";
 import storageMd from "./content/storage.md?raw";
 import aiMd from "./content/ai.md?raw";
 import mcpMd from "./content/mcp.md?raw";
@@ -125,6 +126,7 @@ import actionSearchDialogMd from "./content/action-list-dialog.md?raw";
 import pageMd from "./content/page.md?raw";
 import presentationMd from "./content/presentation.md?raw";
 import contentMd from "./content/content.md?raw";
+import paneMd from "./content/pane.md?raw";
 import sidebarMd from "./content/sidebar.md?raw";
 import splitMd from "./content/split.md?raw";
 import routerMd from "./content/router.md?raw";
@@ -275,6 +277,11 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
             render: doc(runtimeMd),
           },
           { slug: "data", title: "Camada de dados", render: doc(dataMd) },
+          {
+            slug: "data-products",
+            title: "Produtos de Dados",
+            render: doc(dataProductsMd),
+          },
           {
             slug: "testing",
             title: "Testes de action",
@@ -418,8 +425,13 @@ export const UI_SECTIONS: DocSection[] = [
         pages: [
           {
             slug: "split",
-            title: "Split & Pane",
-            render: pattern("Split & Pane", "split", splitMd),
+            title: "Split",
+            render: pattern("Split", "split", splitMd),
+          },
+          {
+            slug: "pane",
+            title: "Pane",
+            render: pattern("Pane", "pane", paneMd),
           },
           {
             slug: "sidebar",