@softize/opus 19.0.0 → 20.0.0

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

@@ -10,12 +10,13 @@ superfície, e a escolha entre regiões seccionadas e contínuas pertence a quem
 Quando a própria região precisar de uma fronteira visível, use `framed`, descrito adiante. Pelo
 mesmo motivo o `Content` não tem rodapé: um rodapé pertence à superfície que a hospeda.
 
-No caso comum, prefira o shorthand:
+No caso comum, prefira o shorthand. `count` mostra o total de itens ao lado do título:
 
 ```tsx preview col
 render(
   <Content
     title="Dispositivos conectados"
+    count={3}
     description="Sessões com acesso à sua conta."
     actions={<Button variant="outline">Encerrar outras sessões</Button>}
   >
@@ -132,13 +133,33 @@ do pai correto, filhos estruturais indiretos e a mistura de shorthand com compos
 ## Coleção nomeada
 
 Quando a região principal da página é uma coleção, `Content` nomeia e governa essa coleção, enquanto
-`ActionList` executa a consulta. Coloque criar, importar e outras ações sobre o conjunto completo em
+[`ActionList`](/ui/action-list) executa a consulta. Coloque criar, importar e outras ações sobre o conjunto completo em
 `ContentActions`. Busca, filtros, atualização e operações dependentes do recorte atual permanecem na
 toolbar da lista. Essa divisão aproxima cada comando do objeto que ele afeta sem criar uma família
-paralela de componentes `List*`. Na variante `page`, as ações ficam no extremo oposto ao título. A
-criação usa um `Button` textual na variante padrão (`solid`) e no tamanho `default`, sem ícone,
-nomeado `Criar recurso`; o diálogo aberto pelo
-gatilho repete esse título e a edição usa `Editar recurso`.
+paralela de componentes `List*`.
+
+Quando a coleção é o assunto da página, use `variant="page"` com `level={1}`: o `Content` assume a
+escala do cabeçalho de [`Page`](/ui/page) e passa a ser o heading principal. As ações ficam no
+extremo oposto ao título, como em qualquer variante.
+
+```tsx preview col
+render(
+  <Content level={1} variant="page" title="Clientes" actions={<Button>Criar cliente</Button>}>
+    <div className="rounded-lg border border-border p-4 text-sm text-muted-foreground">
+      A lista de clientes ocupa o corpo.
+    </div>
+  </Content>,
+);
+```
+
+A criação usa um `Button` textual na variante padrão (`solid`) e no tamanho `default`, sem ícone,
+nomeado `Criar {recurso}` (por exemplo, `Criar cliente`); o diálogo aberto pelo gatilho repete esse
+título, e a edição usa `Editar {recurso}`.
+
+Em uma [`Page`](/ui/page) com `layout="fill"`, a coleção pode ocupar a altura da página e rolar só os
+resultados. `Content` e `ContentBody` repassam a altura até a [`ActionList`](/ui/action-list) sem
+classes adicionais; um `Content` irmão, sem lista, mantém a altura do próprio conteúdo. A seção
+“Ocupar a altura disponível” da `ActionList` mostra a composição completa.
 
 ## Propriedades de Content
 
@@ -147,12 +168,15 @@ gatilho repete esse título e a edição usa `Editar recurso`.
 | `title`        | `ReactNode`                  |             | Forma curta: título da região (vira o heading ligado à `section`).                                                      |
 | `count`        | `number`                     |             | Forma curta: total de itens ao lado do título da região.                                                                |
 | `description`  | `ReactNode`                  |             | Forma curta: frase de apoio sob o título.                                                                               |
-| `actions`      | `ReactNode`                  |             | Forma curta: ações sobre a região inteira; em `page`, ficam no extremo oposto ao título.                                |
+| `actions`      | `ReactNode`                  |             | Forma curta: ações sobre a região inteira, no extremo oposto ao título.                                                 |
 | `level`        | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2`         | Nível semântico do heading, independente do destaque visual.                                                            |
 | `variant`      | `'page' \| 'section'`        | `'section'` | Hierarquia visual: `page` reproduz o cabeçalho de `Page`; `section` é a região dentro de uma superfície.                |
 | `as`           | `'section' \| 'fieldset'`    | `'section'` | Usa uma região com heading ou um grupo de campos cujo título é a legenda nativa.                                        |
 | `framed`       | `boolean`                    | `false`     | Envolve o header e o body com a moldura estrutural da região.                                                           |
 | `frameVariant` | `'default' \| 'legend'`      | `'default'` | Em `fieldset` com moldura, mantém a borda contínua ou integra visualmente a legenda à borda. Não altera a semântica.    |
+| `children`     | `ReactNode`                  |             | Corpo da região na forma curta, ou `ContentHeader` e `ContentBody` na composição explícita.                             |
+
+As demais propriedades são as nativas de `section` ou, com `as="fieldset"`, de `fieldset`.
 
 Na composição explícita, `ContentHeader` recebe `ContentTitle`, `ContentMeta`, `ContentDescription` e
 `ContentActions`, e `ContentBody` recebe o conteúdo; nenhum desses slots aceita `title` ou `level`

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

@@ -1,6 +1,9 @@
 ## Copiar por ícone
 
-Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5s. Bom para toolbar ou célula estreita, ao lado de um ID/token/slug.
+Use `Copyable` para que a pessoa copie um valor exato com um clique, como um identificador, uma
+chave ou um endereço. Sem filhos, ele é um botão só com ícone: copia `value` e troca o ícone por um
+check durante 1,5 segundo. Essa forma cabe em barras de ferramentas e células estreitas, ao lado do
+valor exibido.
 
 ```tsx preview
 <Copyable value="opus_sk_1a2b3c4d5e6f" className="text-muted-foreground hover:text-foreground" />
@@ -8,7 +11,8 @@ Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5
 
 ## Com rótulo
 
-Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar no conjunto copia. Componha o chrome (borda, mono) por fora, via `className`.
+Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar no conjunto copia. Borda,
+fonte monoespaçada e demais detalhes visuais entram por `className`.
 
 ```tsx preview
 <Copyable
@@ -19,21 +23,48 @@ Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar n
 </Copyable>
 ```
 
+## Nome acessível
+
+Com rótulo visível, o nome do botão é o próprio texto dos filhos. Quem usa comando de voz aciona o
+botão dizendo o que vê, e o nome não muda durante a confirmação. Sem filhos, o botão se chama
+“Copiar” e, durante a confirmação, “Copiado”.
+
+A confirmação também é anunciada por leitores de tela: uma região de status, invisível na tela e
+fora do botão, diz “Copiado” sem interromper a leitura em andamento.
+
+Quando houver mais de um botão só com ícone na mesma tela, passe `aria-label` para distinguir o que
+cada um copia, como “Copiar o ID do pedido”. Com rótulo visível, o `aria-label` raramente é
+necessário; se usá-lo, comece pelo texto que a pessoa vê. Um `aria-label` próprio substitui os nomes
+padrão, inclusive o “Copiado”, e o anúncio da confirmação continua.
+
 ## Duração do feedback
 
-`feedbackMs` ajusta por quanto tempo a confirmação aparece; o padrão é 1500 milissegundos. Se a
-área de transferência não estiver disponível, a ação não produz efeito.
+`feedbackMs` ajusta por quanto tempo a confirmação aparece; o padrão é 1500 milissegundos.
 
 ```tsx preview
-<Copyable value="copiado devagar" feedbackMs={3000} className="text-muted-foreground hover:text-foreground">
-  copiar (3s)
+<Copyable
+  value="https://opus.softize.dev/w/empresa-x"
+  feedbackMs={3000}
+  className="text-muted-foreground hover:text-foreground"
+>
+  Copiar link
 </Copyable>
 ```
 
+A confirmação só aparece depois que a área de transferência aceita o texto. Se ela não estiver
+disponível, como em uma página sem HTTPS, ou recusar a escrita, o ícone não muda.
+
 ## Propriedades de Copyable
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `value` | `string` | | O texto que vai para a área de transferência no clique. |
+| `value` | `string` | obrigatório | O texto que vai para a área de transferência no clique. |
 | `feedbackMs` | `number` | `1500` | Duração do estado “copiado”, em milissegundos. |
-| `children` | `ReactNode` | | Rótulo ao lado do ícone; sem ele, o controle é só o ícone com nome acessível. |
+| `children` | `ReactNode` | | Rótulo visível ao lado do ícone. Quando presente, é o nome acessível do botão. |
+| `aria-label` | `string` | sem filhos, `'Copiar'`, ou `'Copiado'` durante a confirmação | Nome acessível do botão. Substitui o nome vindo dos filhos e os nomes padrão. |
+
+Os demais atributos vão para o elemento `button`. Um `onClick` próprio roda antes da cópia. O
+botão é o único elemento que o Copyable coloca no contêiner: a região de status fica no fim do
+`body`, visível apenas para leitores de tela, e é uma só para todos os Copyable da página. Ela
+aparece com o primeiro Copyable montado e sai com o último, então uma tabela com um botão de copiar
+por linha não multiplica regiões.

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

@@ -4,15 +4,16 @@ title: Customização
 
 # Customização
 
-Cinco alavancas, do global ao pontual — e um limite de propósito. O caminho previsto é compor
-e configurar, nunca forkar componente: o que não cabe nas alavancas evolui no Opus (com
-divergência declarada), para valer para casa toda.
+Quando a aplicação precisa de outra marca, outra largura ou outro comportamento, o Opus oferece
+cinco alavancas, da mais global à mais pontual. Todas partem de compor e configurar os componentes
+existentes; nenhuma exige copiar um componente para dentro do projeto e mantê-lo à parte. O que não
+couber nelas evolui no próprio Opus, para valer em todos os projetos.
 
 ## 1 · Identidade por tokens
 
-> O jeito canônico de vestir a marca. Sobrescreva as vars no `:root` depois de importar o
-> `theme.css` — todos os componentes acompanham, sem forkar nada. Dark incluso (a classe `.dark`
-> re-declara as vars).
+Para aplicar a marca, sobrescreva as variáveis CSS em `:root` depois de importar `theme.css`. Todos
+os componentes acompanham a mudança, e o tema escuro também: a classe `.dark` redeclara as mesmas
+variáveis.
 
 ```css
 /* index.css do app — depois do import do tema. */
@@ -26,27 +27,20 @@ divergência declarada), para valer para casa toda.
 ```
 
 O Opus deriva de `rounded-xs` a `rounded-2xl` dessa base. Assim, a marca muda a presença dos
-cantos sem substituir as utilities escolhidas pelos componentes nem criar tokens por papel.
+cantos sem substituir as utilities escolhidas pelos componentes nem criar tokens por papel. A lista
+completa de variáveis está em [Tokens](/ui/tokens).
 
 O tema não define `font-size` em `html`: a fonte raiz pertence ao navegador e à aplicação.
 Quando o produto precisa de outra densidade, declare essa escolha no CSS do app. Por exemplo,
-`html { font-size: 93.75%; }` conserva a proporção que uma raiz de 15 teria sobre a base usual
-de 16, sem transformar esse valor em uma regra da biblioteca.
-
-## Layout desktop
-
-O Opus oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
-Classes de tamanho, como `size="sm"`, escolhem a densidade do componente; não representam
-breakpoints. Overflow e limites contra a janela continuam protegendo o conteúdo.
-
-Não adicione uma adaptação isolada por viewport ou container em `className`. Uma futura
-responsividade precisa começar pelo shell e formar um contrato comum para navegação, splits,
-tabelas e componentes.
+`html { font-size: 93.75%; }` reduz a raiz a 15/16 da fonte que o navegador oferece, e tudo que o
+Opus mede em `rem` acompanha a proporção. O valor continua sendo uma escolha do app, não uma regra
+da biblioteca.
 
 ## 2 · className em tudo
 
-> Todo componente termina em `cn(base, className)` com tailwind-merge: o utilitário do consumidor
-> vence o conflito. Para layout local (largura, margem, grid) — não para repintar o visual da casa.
+Todo componente aceita `className` e o combina com as próprias classes por tailwind-merge: quando
+duas classes disputam a mesma propriedade, a do consumidor vence. Use essa alavanca para o layout
+local, como largura, margem e grid, e não para repintar o visual dos componentes.
 
 ```tsx
 <Button className="w-full">Continuar</Button>
@@ -56,73 +50,88 @@ tabelas e componentes.
 
 ## 3 · Recomposição estrutural
 
-> Os componentes são explodidos em slots. `asChild` (Radix Slot) renderiza como outro elemento
-> mantendo estilo e comportamento; os `*Variants` aplicam a cara da casa em um elemento arbitrário.
+Os componentes são divididos em partes nomeadas, como `CardHeader` e `CardBody`, e a tela usa só as
+que precisa. `asChild` faz o filho assumir o estilo e o comportamento do componente, e as funções
+`*Variants` aplicam o visual de um componente a um elemento qualquer.
 
 ```tsx preview
 <Button asChild variant="outline">
-  <a href="#" onClick={(e) => e.preventDefault()}>Âncora com cara de botão</a>
+  <a href="#" onClick={(e) => e.preventDefault()}>Link com aparência de botão</a>
 </Button>
 ```
 
 ```tsx
-// Slots: só o que a tela pede.
+// Partes: só o que a tela pede.
 <Card>
   <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
   <CardBody>…</CardBody>
 </Card>
 
-// asChild: o filho VIRA o botão (sem forkar estilo).
+// asChild: o link assume o estilo e o comportamento do botão.
 <Button asChild><a href="/docs">Abrir documentação</a></Button>
 
-// buttonVariants: a cara da casa em um elemento qualquer.
+// buttonVariants: o visual do botão em outro elemento.
 <a className={buttonVariants({ variant: 'outline' })}>Link estilizado</a>
 ```
 
 ## 4 · Comportamento por props
 
-> Modo controlado em tudo que abre ou seleciona (`open`/`onOpenChange`, `value`/`onValueChange`),
-> posicionamento (`align`/`side`/`sideOffset`), `showCloseButton`, `delayDuration`… A orquestração
-> é do implementador; o visual continua o da casa.
+Tudo o que abre ou seleciona aceita modo controlado (`open` e `onOpenChange`, `value` e
+`onValueChange`). Posicionamento (`align`, `side`, `sideOffset`) e tempos (`delayDuration`) também
+são props. A orquestração fica com a aplicação; o visual continua o dos componentes.
 
 ```tsx
 const [open, setOpen] = useState(false)
 
 <Dialog open={open} onOpenChange={setOpen}>…</Dialog>
-<DialogContent showCloseButton={false} />     {/* modal que exige ação */}
+<Dialog mode="alert">…</Dialog>                {/* exige uma resposta explícita */}
 <PopoverContent align="start" sideOffset={8} />
 <TooltipProvider delayDuration={200}>…
 ```
 
+Para exigir uma resposta, use `Dialog mode="alert"`: ele não fecha pelo clique externo e não mostra
+o botão de fechar. Apenas esconder o botão com `showCloseButton={false}` não impede o fechamento por
+Esc nem pelo clique externo. Veja [Dialog](/ui/dialog).
+
 ## 5 · Nos patterns, o contrato é a customização
 
-> Os patterns (ActionForm/Search/View/Trigger): o spec dirige. `fields`/`widget`/`showWhen`/
-> `fieldOptions` no form, `columns` no search, render prop no view. O caminho previsto é a feature
-> EMBRULHAR o pattern — nunca forkar.
+Nos patterns — [`ActionForm`](/ui/action-form), [`ActionList`](/ui/action-list),
+[`ActionView`](/ui/action-view) e [`ActionTrigger`](/ui/action-trigger) —, o contrato da action
+determina campos, colunas e estados. A tela ajusta o que é dela: `fieldOptions` no formulário,
+`columns` na lista, a função de render no `ActionView`. Para ir além, envolva o pattern em um
+componente da feature em vez de copiá-lo.
 
 ```tsx
-// O form NASCE do contrato; a tela só ajusta o que é seu.
+// O formulário vem do contrato; a tela só fornece as opções que conhece.
 <ActionForm
   action={workspaceCreateContract}
-  fieldOptions={{ skillIds: skillsDoWorkspace }}
+  fieldOptions={{ ownerId: workspaceMembers }}
   onSuccess={(d) => navigate(`/workspaces/${d.id}`)}
 />
 
-// O search recebe as colunas; a célula é render livre.
+// A lista recebe as colunas; a célula é render livre.
 <ActionList action={listAction} input={{ q }} columns={[
   { key: 'name', header: 'Workspace', cell: (w) => w.name },
 ]} />
 ```
 
-## O limite — de propósito
+## Largura mínima e densidade
 
-> O look curado não é customizável no app: rodapé-faixa do dialog, elevação no dark, `active:brightness-90`
-> do botão, a seta do tooltip — é identidade da casa, igual em todo projeto.
+O Opus oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
+Props de tamanho, como `size="sm"`, escolhem a densidade do componente; não representam
+breakpoints. Overflow e limites contra a janela continuam protegendo o conteúdo.
 
-```tsx preview
-<Badge context="success">Cabe nas alavancas</Badge>
-```
+Não adicione em `className` uma adaptação isolada por viewport ou container. Uma responsividade
+futura precisa começar pelo shell e formar um contrato comum para navegação, splits, tabelas e
+componentes.
+
+## O que fica fora das alavancas
+
+Alguns detalhes fazem parte da identidade visual do Opus e são iguais em todo projeto: a faixa do
+rodapé do dialog, a elevação no tema escuro, o escurecimento do botão ao ser pressionado
+(`active:brightness-90`) e a seta do tooltip. Eles não são configuráveis pela aplicação.
 
-Se uma necessidade real não cabe nas alavancas (tokens · className · slots/asChild · props ·
-contrato), o movimento não é dialeto local: é evoluir o componente **no Opus**, com a divergência
-declarada (skill `build-opus-ui`) — assim a mudança vale para casa toda, e esta doc passa a mostrá-la.
+Se uma necessidade real não cabe nas alavancas (tokens, `className`, partes e `asChild`, props e
+contrato), não crie uma variação local. Proponha a evolução do componente no Opus, com a
+divergência declarada conforme a skill `build-opus-ui`; assim a mudança vale para todos os projetos
+e passa a aparecer nesta documentação.

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

@@ -1,36 +1,51 @@
+---
+title: Evolução contínua
+---
+
 # Evolução contínua
 
-O Opus cresce por **reincidência, nunca por especulação**. Quando o mesmo comportamento genérico reaparece em mais de um projeto, ele vira candidato a peça do Opus — e o projeto troca a implementação local pelo import. Estilo e conveniência não entram; comportamento que se repete, sim.
+Use este fluxo quando o seu projeto precisar de algo que o Opus ainda não oferece ou encontrar um
+defeito nele. O Opus incorpora um comportamento quando ele se repete em mais de um projeto; então o
+projeto troca a implementação local pelo import. Preferência de estilo e conveniência isolada não
+são motivo para incorporar uma peça.
 
-## Onde você aponta
+## Registrar um apontamento
 
-Cada apontamento vira uma Issue no repositório do Opus. Antes de abrir, procure uma Issue existente para o mesmo comportamento e comente nela. Dois tipos:
+Cada apontamento vira uma Issue em
+[github.com/softize-dev/opus](https://github.com/softize-dev/opus/issues). Antes de abrir uma nova,
+procure uma Issue sobre o mesmo comportamento e comente nela. Há dois tipos:
 
-- **`enhancement`** — código genérico que o Opus deveria ganhar (serviria a qualquer projeto). Antes de apontar, confira o que o Opus já tem (o inventário de componentes, os exports, esta doc): se já existe, use.
-- **`bug`** — um defeito ou limitação no próprio Opus, achado usando-o.
+- **`enhancement`:** código genérico que serviria a qualquer projeto. Antes de apontar, confira se o
+  Opus já oferece o recurso no inventário de componentes, nos exports ou nesta documentação; se
+  oferecer, use-o.
+- **`bug`:** defeito ou limitação do próprio Opus, encontrado durante o uso.
 
-Descreva cada apontamento com estes campos — um exemplo de cada tipo:
+Descreva cada apontamento com estes campos, como nos exemplos:
 
 ```text
 {"type": "enhancement", "behavior": "o comportamento em uma frase.", "file": "src/onde-vive.ts", "kind": "ui|sdk|driver|infra"}
-{"type": "bug", "behavior": "o que quebra ou falta.", "file": "onde se manifesta.", "note": "repro + o workaround aplicado."}
+{"type": "bug", "behavior": "o que quebra ou falta.", "file": "onde se manifesta.", "note": "como reproduzir e o contorno aplicado."}
 ```
 
-## Não trave esperando
+O pacote não coleta apontamentos do seu projeto automaticamente.
 
-O ponto do ciclo é **não bloquear a entrega**. Bateu em um gap ou em um bug do Opus:
+## Seguir sem esperar a correção
 
-1. **Contorne local** — componha um wrapper no seu projeto. O Opus entrega _source_, então dá para embrulhar qualquer superfície dele. Nunca edite `node_modules` (some no próximo install).
-2. **Entregue** a feature com o workaround.
-3. **Aponte** na Issue e siga em frente.
+Uma lacuna ou um defeito do Opus não precisa bloquear a entrega:
 
-O "depois" — o conserto no Opus — corre em paralelo. Ele não segura o seu trabalho; o único custo de demorar é o workaround viver um pouco mais.
+1. **Contorne no projeto:** componha um wrapper local. O Opus é distribuído como código-fonte, então
+   qualquer superfície dele pode ser envolvida. Não edite `node_modules`, porque a alteração se
+   perde na próxima instalação.
+2. **Entregue** a funcionalidade com o contorno.
+3. **Registre** o apontamento na Issue.
 
-## Como fecha
+A correção no Opus acontece em paralelo. Enquanto ela não sai, o contorno continua no projeto.
 
-A triagem acontece em uma **Issue em [github.com/softize-dev/opus](https://github.com/softize-dev/opus/issues)**; procure uma existente antes de abrir. O pacote não coleta apontamentos do seu projeto por conta própria. O desfecho depende do tipo:
+## Como o apontamento termina
 
-- **Enhancement** aceito (com reincidência) → implementado no Opus → sai em um _bump_ → seu projeto [atualiza o Opus](upgrading) e troca o workaround pelo import.
-- **Bug** → vira _fix_ + entrada no `CHANGELOG` → no _bump_, o workaround sai.
+- Um **enhancement** aceito é implementado no Opus e publicado em uma nova versão. Ao
+  [atualizar o Opus](/docs/upgrading), o projeto troca o contorno pelo import.
+- Um **bug** vira uma correção com entrada no `CHANGELOG`; na atualização, o contorno sai.
 
-A régua e a decisão ficam com quem mantém o Opus — hoje, a **Softize**. O registro curado das promoções vive no `PROMOTED.md` do pacote.
+A decisão sobre o que entra no Opus fica com a Softize, que mantém o pacote. O registro das peças
+incorporadas está no `PROMOTED.md` do pacote.

package/src/ui/docs/content/data-products.md

@@ -0,0 +1,115 @@
+---
+title: Produtos de Dados
+---
+
+# Produtos de Dados
+
+Use um Produto de Dados quando um conjunto de dados precisar de identidade estável para catálogos,
+agentes e revisão, independentemente da action que o entrega. A declaração diz o que o conjunto
+representa, de onde vem, quem responde por ele e quais actions o disponibilizam. Ela não é uma
+consulta, uma tabela nem uma view, e não executa nada: cada action continua sendo a fronteira de
+execução, recorte e autorização.
+
+## Declarar e registrar
+
+`defineDataProduct` declara o produto e valida seus campos no momento em que roda. O domínio o
+registra em `dataProducts`, ao lado das actions e entidades citadas:
+
+```ts
+import { defineDataProduct, defineDomain } from '@softize/opus/core'
+import { LeadEntity } from './entity.ts'          // defineEntity({ name: 'lead', … })
+import { leadList } from './actions/list.ts'      // action 'lead.list'
+import { leadFunnel } from './actions/funnel.ts'  // action 'lead.funnel'
+
+export const salesLeads = defineDataProduct({
+  id: 'sales.leads',
+  version: 1,
+  label: 'Leads comerciais',
+  description: 'Leads e seus resultados comerciais.',
+  owner: 'Vendas',
+  grain: 'Um lead.',
+  classification: 'internal',
+  nature: 'real',
+  sources: [{ id: 'crm', label: 'CRM comercial' }],
+  entities: ['lead'],
+  access: {
+    permissionContexts: ['sales'],
+    organizationalScopes: ['unit', 'team'],
+  },
+  interfaces: ['lead.list', 'lead.funnel'],
+})
+
+export const leadDomain = defineDomain({
+  name: 'lead',
+  entities: { LeadEntity },
+  actions: { leadList, leadFunnel },
+  dataProducts: { salesLeads },
+})
+```
+
+`interfaces` e `entities` usam os nomes declarados em `bindAction`/`defineContract` e em
+`defineEntity`, não nomes de arquivo ou de tabela. `sources` identifica os sistemas ou conjuntos de
+origem; uma fonte não precisa ser uma entidade do Opus.
+
+## Verificações
+
+A declaração é conferida em três momentos:
+
+- `defineDataProduct` lança `TypeError` quando o `id` não tem namespace (como `sales.leads`), a
+  `version` não é um inteiro positivo, falta texto obrigatório, `sources` ou `interfaces` estão
+  vazias ou há itens repetidos.
+- `defineDomain` recusa um produto duplicado no domínio e referências a actions ou entidades que o
+  domínio não declara (`domain.data_product_interface_not_found` e
+  `domain.data_product_entity_not_found`).
+- `opus check` lê o código sem executá-lo e confere exportação, `id`, `version`, duplicidade e as
+  referências a actions e entidades do projeto, com as regras de prefixo `data-product`. Para isso,
+  o produto precisa ser `export const` e usar valores literais.
+
+## Acesso e segurança
+
+`access` documenta o alcance esperado de forma verificável. Ele ajuda o catálogo e a revisão a
+perceber, por exemplo, que uma interface deveria respeitar unidade e equipe. `access` não é RLS nem
+autorização automática: cada action listada em `interfaces` precisa aplicar o próprio `authorize` e
+os recortes no handler ou no repositório, inclusive quando chamada por IA ou por
+[MCP](/docs/mcp).
+
+`permissionContexts` nomeia chaves do vocabulário de permissão do projeto. Ele não descreve área,
+departamento nem contexto de tela; um projeto que não usa essa dimensão declara uma lista vazia.
+O nome antigo `contexts` ainda é aceito e projetado para compatibilidade, mas declarações novas usam
+`permissionContexts`.
+
+## Onde o produto aparece
+
+- `opus gen` publica os produtos no `.opus/manifest.json`, e `opus introspect` os inclui no modelo
+  do projeto. Veja [CLI opus](/docs/cli).
+- Em `runtime.aiTools()`, cada action exposta à IA traz em `metadata.dataProducts` os IDs dos
+  produtos relacionados e, em `metadata.dataProductLabels`, o `label` de cada ID. Veja
+  [IA generativa](/docs/ai).
+- No servidor MCP, as mesmas informações aparecem em `_meta['com.softize.opus/data-products']` e
+  `_meta['com.softize.opus/data-product-labels']`.
+
+Esses metadados servem a quem hospeda o agente: mostre o `label` às pessoas e use o ID na execução e
+na auditoria. Eles não entram no prompt e não concedem acesso. Nenhuma dessas projeções é a fonte
+da verdade: para mudar um produto, corrija a declaração e gere de novo.
+
+## Evoluir um produto
+
+Incremente `version` quando a forma observável do produto mudar. Para substituí-lo, mantenha a
+declaração anterior com `status: 'deprecated'` e `replacedBy` apontando para o novo ID durante a
+migração. Um produto ativo não declara `replacedBy`.
+
+## Referência de DataProductConfig
+
+| Campo | Contrato |
+| --- | --- |
+| `id` | Identidade estável com namespace, como `sales.leads`. |
+| `version` | Inteiro positivo; muda com a forma observável do produto. |
+| `label`, `description` | Nome e descrição para pessoas. |
+| `owner` | Responsável técnico ou de negócio. |
+| `grain` | O que uma linha ou observação representa. |
+| `classification`, `nature` | Classificação (como `internal` ou `personal`) e natureza (como `real`, `demo` ou `synthetic`) definidas pelo projeto. |
+| `sources` | Pelo menos uma fonte `{ id, label, description? }`, sem `id` repetido. |
+| `entities` | Nomes das entidades Opus que estruturam o produto; pode ser vazia. |
+| `access` | `permissionContexts` e `organizationalScopes`, ambos listas de texto. |
+| `interfaces` | Nomes das actions que disponibilizam o produto; pelo menos uma. |
+| `status`, `replacedBy` | `active` (padrão) ou `deprecated`; um produto `deprecated` exige `replacedBy`. |

package/src/ui/docs/content/data-state.md

@@ -1,11 +1,25 @@
 ## Estados
 
-Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta. As
-superfícies são as mesmas de `PageState`, na escala de uma seção: o carregamento é um contêiner
-`role="status"` com o `Spinner`; o vazio compõe `Empty` com moldura sólida e `emptyMessage` como
-título; o erro é um `Alert` de contexto `danger` com uma mensagem segura, sem expor detalhes
-técnicos, e uma ação `ghost` só com ícone quando há `onRetry`. `retryLabel` fornece o nome acessível
-e o tooltip dessa ação. Para uma ação em andamento depois do clique, use `busy` em `Button`.
+Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta, na escala
+de uma seção. Para o estado da página inteira, use `PageState`, descrito em [`Page`](/ui/page); para
+uma coleção carregada por uma action `kind: 'list'`, [`ActionList`](/ui/action-list) já trata esses
+estados.
+
+Cada estado tem uma apresentação fixa:
+
+- **Carregando:** um contêiner `role="status"` com o [`Spinner`](/ui/spinner) centralizado. Quando o
+  formato do conteúdo já é conhecido, em vez de passar `loading`, renderize o
+  [`Skeleton`](/ui/skeleton) durante a espera: ele reproduz esse formato e evita o salto de layout.
+- **Vazio:** um [`Empty`](/ui/empty) com moldura sólida e `emptyMessage` como frase discreta.
+- **Erro:** um [`Alert`](/ui/alert) de contexto `danger` com a mensagem segura de `errorMessage`,
+  sem expor o texto técnico de `error`. Com `onRetry`, o aviso ganha uma ação `ghost` só com ícone,
+  e `retryLabel` fornece o nome acessível e o tooltip dessa ação.
+
+Quando mais de uma condição vale ao mesmo tempo, vence a primeira desta ordem: erro, carregando,
+vazio. O conteúdo aparece somente quando nenhuma delas vale. Assim, uma nova tentativa com
+`loading` e `error` ativos continua mostrando o erro até que `error` volte a `null`.
+
+Para uma ação em andamento depois do clique, use `busy` em [`Button`](/ui/button).
 
 ```tsx preview col
 <div className="w-full space-y-3">

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

@@ -32,9 +32,9 @@ export const SkillEntity = defineEntity({
 
 ## Código em camelCase, banco em snake_case
 
-O schema tipado do Kysely e todas as consultas usam camelCase
-(`workspaceId`, `ghRepo`). O banco é snake (a DDL no schema idempotente — `db/schema.sql`).
-`CamelCasePlugin` converte nomes nas consultas e nos resultados. Um sink que não usa o Kysely com o
+O schema tipado do Kysely e todas as consultas usam camelCase (`workspaceId`, `ghRepo`). O banco
+usa snake_case, definido na DDL do schema idempotente, como `db/schema.sql`. `CamelCasePlugin`
+converte os nomes nas consultas e nos resultados. Um sink que não usa o Kysely com o
 plugin, como `audit_log`, mantém os nomes do banco.
 
 ```ts
@@ -52,19 +52,20 @@ await db.selectFrom('agents').select(['isDefault', 'roleId']).where('workspaceId
 
 Cada etapa possui um papel diferente:
 
-- `opus db migrate` — aplica o **schema idempotente** (`config.schema`, um script SQL
-  evolutivo: `IF NOT EXISTS` + guards cobrem nascer do zero e upgrade no mesmo artefato)
-  e roda o drift-check entidade ↔ banco na sequência (exit ≠ 0 se divergir).
-- `opus seed` — aplica datasets de desenvolvimento e teste declarados com `defineSeed` e registrados
-  no `opus.config.ts`; só conecta com `NODE_ENV=development` ou `test`. Ver [CLI opus](cli).
+- `opus db migrate` aplica o schema idempotente (`config.schema`), um único script SQL em que
+  `IF NOT EXISTS` e condições de guarda cobrem tanto o banco novo quanto a atualização. Em seguida,
+  compara entidades e banco e encerra com exit ≠ 0 quando há divergência.
+- `opus seed` aplica datasets de desenvolvimento e teste declarados com `defineSeed` e registrados no
+  `opus.config.ts`. Ele só conecta com `NODE_ENV=development` ou `test`. Veja
+  [CLI opus](/docs/cli).
 
 ## Campos JSON
 
-`kyselyRepo` serializa campos `t.json()` na escrita (`insert` e `update`), guiado pela
-declaração. Sem isso, o pg até stringifica objeto plano — mas **array vira literal de
-array do PG** (errado para jsonb) sem quebrar typecheck. String passa direto (quem já
-mandava pré-serializado segue valendo); na leitura o pg devolve objeto. Query à mão
-(fora do repo) continua responsável pelo próprio stringify.
+`kyselyRepo` serializa os campos `t.json()` na escrita (`insert` e `update`), guiado pela
+declaração da entidade. Sem essa etapa, o driver `pg` converte um objeto simples, mas transforma um
+array em literal de array do Postgres, o que é inválido para `jsonb` e não aparece no typecheck.
+Uma string passa sem alteração, o que preserva valores já serializados; na leitura, o `pg` devolve
+o objeto. Uma consulta escrita fora do repositório continua responsável pela própria serialização.
 
 ## SQL gerado por modelo
 
@@ -79,13 +80,13 @@ const bi = readOnlyContextPool({ pool: new Pool({ connectionString, max: 4 }) })
 const { rows } = await bi.query(sqlDoLlm, { role: roleFor(ctx) })
 ```
 
-1. **Pool com limite** (`max` e/ou `maxConcurrent`) — impede que as consultas consumam todas as
+1. **Pool com limite** (`max`, `maxConcurrent` ou ambos): impede que as consultas consumam todas as
    conexões do aplicativo.
-2. **`BEGIN TRANSACTION READ ONLY`** — o servidor rejeita tentativas de escrita;
-3. **`SET LOCAL ROLE` por transação** — o alcance é definido pelo contexto (crie os roles com grants
-   default-fechado nas suas migrações: sem isso, `sales_read` leria `hr_employees`);
-4. **Protocolo estendido** — o SQL sempre recebe os valores separadamente; múltiplas instruções
-   (`SELECT 1; DROP …`) é recusada pelo próprio protocolo.
+2. **`BEGIN TRANSACTION READ ONLY`:** o servidor rejeita tentativas de escrita.
+3. **`SET LOCAL ROLE` por transação:** o contexto define o alcance da consulta. Crie os roles nas
+   suas migrações com grants fechados por padrão; sem isso, `sales_read` leria `hr_employees`.
+4. **Protocolo estendido:** o SQL sempre recebe os valores separadamente, e múltiplas instruções
+   (`SELECT 1; DROP …`) são recusadas pelo próprio protocolo.
 
 Ao terminar, `DISCARD ALL` limpa a conexão. Se a limpeza falhar, a conexão é descartada em vez de
 voltar ao pool. `statement_timeout`, aplicado por transação, limita consultas demoradas; o padrão é