@softize/opus 18.5.0 → 20.0.0

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 é

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

@@ -1,6 +1,6 @@
 Use `DetailGroup` para organizar dados somente leitura como pares de rótulo e valor.
 `DetailField` representa cada par e aceita conteúdo React em `label` e `value`. Para entrada e
-validação, use `Field`.
+validação, use [`Field`](/ui/field).
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -27,7 +27,8 @@ validação, use `Field`.
 
 `null`, `undefined`, string vazia ou só com espaços mostram um travessão; a leitura assistiva
 recebe “Não informado”. Uma string em `empty` troca esse significado no domínio, enquanto um nó
-React substitui a apresentação. `0` e `false` seguem como valores. Ver `EmptyValue`.
+React substitui a apresentação. `0` e `false` seguem como valores. A regra é a mesma de
+[`EmptyValue`](/ui/empty-value).
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -64,15 +65,21 @@ começam depois da mesma coluna de rótulo, com largura padrão de `7rem` em gru
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `variant` | `'plain' \| 'framed'` | `'plain'` | `framed` aplica a moldura canônica ao conjunto, com fundo transparente; na orientação horizontal, a coluna de rótulos recebe fundo sutil. |
-| `dividers` | `boolean` | `false` | Hairlines somente entre os campos, sem exigir moldura externa. |
+| `dividers` | `boolean` | `false` | Linhas finas somente entre os campos, sem exigir moldura externa. |
 | `columns` | `1 \| 2 \| 3 \| 4 \| 'auto'` | `1` | Número fixo de colunas ou distribuição automática por largura mínima. |
 | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Chave sobre o valor ou ao lado dele em cada campo. |
 
+O grupo renderiza uma lista de definições (`<dl>`); os demais atributos, como `className`, vão para
+ela.
+
 ## Propriedades de DetailField
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `label` | `ReactNode` | | A chave do par. |
-| `value` | `ReactNode` | | O valor; `null`, `undefined` e string vazia renderizam a ausência, `0` e `false` seguem como valores. |
+| `label` | `ReactNode` | obrigatório | A chave do par. |
+| `value` | `ReactNode` | obrigatório | O valor; `null`, `undefined` e string vazia renderizam a ausência, `0` e `false` seguem como valores. |
 | `icon` | `ReactNode` | | Ícone decorativo antes do par chave/valor. |
 | `empty` | `ReactNode` | `“Não informado”` | Uma string dá significado acessível ao travessão; um nó próprio substitui a apresentação. |
+
+Os demais atributos, como `className`, vão para o contêiner do par. `DetailField` não aceita
+`children`: o conteúdo entra por `value`.