@softize/opus 12.10.0 → 13.0.0

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

@@ -1,6 +1,7 @@
 ## Lista filtrável inline
 
-Digite pra filtrar — navegação por teclado, grupos e CommandEmpty de graça (cmdk). É a base do Select buscável; pra escolha em form, use o Select.
+Digite para filtrar uma coleção com navegação por teclado, grupos e estado vazio. Command é a base
+do Select pesquisável; para uma escolha em formulário, use Select.
 
 ```tsx preview
 <Command className="max-w-sm rounded-lg border border-border">
@@ -22,7 +23,7 @@ Digite pra filtrar — navegação por teclado, grupos e CommandEmpty de graça
 
 ## Palette modal (CommandDialog)
 
-O Command embrulhado num Dialog, com header sr-only pra a11y. O atalho ⌘K (keydown no app) só troca o open — o conteúdo é o mesmo do inline.
+O Command embrulhado em um Dialog, com header sr-only para a11y. O atalho ⌘K (keydown no app) só troca o open — o conteúdo é o mesmo do inline.
 
 ```tsx preview
 const [open, setOpen] = useState(false)
@@ -46,11 +47,18 @@ render(
 )
 ```
 
-## Props
+## Propriedades de CommandDialog
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `CommandDialog.open / onOpenChange` | `boolean / (open: boolean) => void` | | Controle do modal — ligue ao atalho de teclado do app. |
-| `CommandDialog.title / description` | `string` | `'Comandos' / 'Busque um comando pra executar.'` | Texto sr-only do header (a11y do Dialog) — não aparece na tela. |
-| `CommandDialog.showCloseButton` | `boolean` | `true` | Mostra o X do Dialog — desligue se o Esc/clique fora bastarem. |
-| `CommandItem.onSelect` | `(value: string) => void` | | Dispara ao escolher (Enter ou clique) — feche o palette aqui. |
+| `open` | `boolean` | | Estado do modal no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Atualiza o estado do modal; pode ser conectado ao atalho do aplicativo. |
+| `title` | `string` | `'Comandos'` | Nome acessível do diálogo, disponível para leitura assistiva. |
+| `description` | `string` | `'Busque um comando para executar.'` | Descrição acessível do diálogo. |
+| `showCloseButton` | `boolean` | `true` | Exibe o botão de fechamento. |
+
+## Propriedades de CommandItem
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `onSelect` | `(value: string) => void` | | Chamado ao selecionar o item por clique ou teclado. |

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

@@ -1,6 +1,6 @@
-## Básico
+## Envio de texto
 
-A caixa de escrever da casa: textarea numa pílula elevada (`rounded-xl` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/components/chat) extraído — use SOZINHO quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse dono consuma **↑/↓**; sem eles, as setas mantêm o comportamento nativo da textarea.
+A caixa de escrever da casa: textarea em uma pílula elevada (`rounded-xl` + `border` + `shadow-sm`), **Enter** envia / **Shift+Enter** quebra linha, enviar dentro. É o composer do [Chat](/components/chat) extraído — use sozinho quando há entrada de texto mas não um chat (ex.: criar uma sessão). Controlado: o dono do texto é você. Os callbacks opcionais `onHistoryPrevious` e `onHistoryNext` permitem que esse dono consuma **↑/↓**; sem eles, as setas mantêm o comportamento nativo da textarea.
 
 ```tsx preview col
 const [text, setText] = React.useState('')

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

@@ -0,0 +1,44 @@
+## Região de conteúdo
+
+Use `Content` para dar título e estrutura a uma região dentro de `PageBody`, `CardBody`,
+`DialogBody` ou outra superfície. Ele renderiza uma `section` ligada ao próprio título e mantém o
+espaçamento entre header e body. `ContentHeader` pertence sempre a essa estrutura; não o use solto.
+
+No caso comum, prefira o shorthand:
+
+```tsx preview col
+render(
+  <Content
+    title="Dispositivos conectados"
+    description="Sessões com acesso à sua conta."
+    actions={<Button variant="outline">Encerrar outras sessões</Button>}
+  >
+    <div className="rounded-lg border border-border p-4">MacBook Para o · ativo agora</div>
+  </Content>,
+)
+```
+
+## Composição explícita
+
+Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
+`ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
+uma descrição, um metadado e uma região de ações.
+
+```tsx preview col
+render(
+  <Content level={2}>
+    <ContentHeader>
+      <ContentTitle>Dispositivos conectados</ContentTitle>
+      <ContentMeta>3</ContentMeta>
+      <ContentDescription>Sessões com acesso à sua conta.</ContentDescription>
+      <ContentActions><Button variant="outline">Atualizar</Button></ContentActions>
+    </ContentHeader>
+    <ContentBody>
+      <div className="rounded-lg border border-border p-4">MacBook Para o · ativo agora</div>
+    </ContentBody>
+  </Content>,
+)
+```
+
+As duas formas geram os mesmos elementos, estilos e `data-slot`. `opus check` reprova slots fora
+do pai correto, filhos estruturais indiretos e a mistura de shorthand com composição explícita.

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

@@ -1,6 +1,6 @@
-## Básico
+## Copiar por ícone
 
-Sem filhos, é um botão-ícone: copia `value` e o ícone vira um check por ~1.5s. Bom pra toolbar ou célula estreita, ao lado de um ID/token/slug.
+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.
 
 ```tsx preview
 <Copyable value="opus_sk_1a2b3c4d5e6f" className="text-muted-foreground hover:text-foreground" />
@@ -21,7 +21,8 @@ Com filhos, o valor visível fica à esquerda e o ícone à direita — clicar n
 
 ## Duração do feedback
 
-`feedbackMs` ajusta quanto o check dura (default 1500). Some no-op silencioso se o clipboard não existir (contexto inseguro/SSR).
+`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.
 
 ```tsx preview
 <Copyable value="copiado devagar" feedbackMs={3000} className="text-muted-foreground hover:text-foreground">

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

@@ -6,7 +6,7 @@ title: 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), pra valer pra casa toda.
+divergência declarada), para valer para casa toda.
 
 ## 1 · Identidade por tokens
 
@@ -36,7 +36,7 @@ de 16, sem transformar esse valor em 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. Pra layout local (largura, margem, grid) — não pra repintar o visual da casa.
+> vence o conflito. Para layout local (largura, margem, grid) — não para repintar o visual da casa.
 
 ```tsx
 <Button className="w-full">Continuar</Button>
@@ -47,7 +47,7 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 ## 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 num elemento arbitrário.
+> mantendo estilo e comportamento; os `*Variants` aplicam a cara da casa em um elemento arbitrário.
 
 ```tsx preview
 <Button asChild variant="outline">
@@ -59,13 +59,13 @@ de 16, sem transformar esse valor em uma regra da biblioteca.
 // Slots: só o que a tela pede.
 <Card>
   <CardHeader><CardTitle>Workspace</CardTitle></CardHeader>
-  <CardContent>…</CardContent>
+  <CardBody>…</CardBody>
 </Card>
 
 // asChild: o filho VIRA o botão (sem forkar estilo).
 <Button asChild><a href="/docs">Abrir documentação</a></Button>
 
-// buttonVariants: a cara da casa num elemento qualquer.
+// buttonVariants: a cara da casa em um elemento qualquer.
 <a className={buttonVariants({ variant: 'outline' })}>Link estilizado</a>
 ```
 
@@ -110,9 +110,9 @@ const [open, setOpen] = useState(false)
 > do botão, a seta do tooltip — é identidade da casa, igual em todo projeto.
 
 ```tsx preview
-<Badge variant="success">Cabe nas alavancas</Badge>
+<Badge context="success">Cabe nas alavancas</Badge>
 ```
 
 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 pra casa toda, e esta doc passa a mostrá-la.
+declarada (skill `build-opus-ui`) — assim a mudança vale para casa toda, e esta doc passa a mostrá-la.

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

@@ -16,9 +16,9 @@ No seu projeto, uma linha por apontamento em `.opus/issues.jsonl` na raiz do rep
 
 ## Não trave esperando
 
-O ponto do ciclo é **não bloquear a entrega**. Bateu num gap ou num bug do Opus:
+O ponto do ciclo é **não bloquear a entrega**. Bateu em um gap ou em um bug do Opus:
 
-1. **Contorne local** — componha um wrapper no seu projeto. O Opus entrega _source_, então dá pra embrulhar qualquer superfície dele. Nunca edite `node_modules` (some no próximo install).
+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** no `.opus/issues.jsonl` e siga em frente.
 
@@ -28,7 +28,7 @@ O "depois" — o conserto no Opus — corre em paralelo. Ele não segura o seu t
 
 O apontamento é colhido e abre uma **Issue no repositório do Opus**, onde a triagem acontece (deduplicada — re-apontar o mesmo é idempotente):
 
-- **Enhancement** aceito (com reincidência) → implementado no Opus → sai num _bump_ → seu projeto atualiza o pin (`opus.json`) e troca o workaround pelo import.
+- **Enhancement** aceito (com reincidência) → implementado no Opus → sai em um _bump_ → seu projeto atualiza o pin (`opus.json`) e troca o workaround pelo import.
 - **Bug** → vira _fix_ + entrada no `CHANGELOG` → no _bump_, o workaround 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.

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

@@ -1,9 +1,9 @@
 ## Estados
 
-Um lugar só pro erro/carregando/vazio/conteúdo de uma carga. Carregando = Spinner centralizado;
-vazio = texto em uma moldura sólida no modo bloco; erro = aviso calmo (a mensagem técnica não vai
-pra tela). É o "antes" do conteúdo —
-pro "depois" (ação em andamento), use o busy do Button.
+Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mesma consulta. O
+carregamento usa `Spinner`; o vazio preserva uma moldura sólida; e o erro apresenta uma mensagem
+segura, sem expor detalhes técnicos. Para uma ação em andamento depois do clique, use `busy` em
+`Button`.
 
 ```tsx preview col
 <div className="w-full space-y-3">
@@ -19,12 +19,11 @@ pro "depois" (ação em andamento), use o busy do Button.
 </div>
 ```
 
-## Em tabela (colSpan)
+## Dentro de uma tabela
 
-Em lista ou tabela já emoldurada, passe colSpan: o estado vira UMA linha de largura cheia
-(`<tr><td colSpan>`) que cabe direto no `<tbody>`; o conteúdo são as `<tr>` dos itens. A tabela
-continua dona da borda, sem uma segunda moldura no vazio. Para uma região disponível para criação
-ou vínculo, com título, descrição ou ação, use `Empty`, cuja moldura é tracejada.
+Em uma tabela já emoldurada, passe `colSpan` para ocupar uma linha inteira dentro de `<tbody>`. A
+tabela continua responsável pela borda, evitando uma segunda moldura no estado vazio. Para uma
+região disponível para criação ou vínculo, use `Empty`.
 
 ```tsx preview col
 <table className="w-full overflow-hidden rounded-lg border border-border text-sm">
@@ -38,13 +37,13 @@ ou vínculo, com título, descrição ou ação, use `Empty`, cuja moldura é tr
 </table>
 ```
 
-## Props
+## Propriedades de DataState
 
-| Prop | Tipo | Default | Descrição |
+| Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `loading` | `boolean` | | Carregando (antes do conteúdo) — mostra o Spinner centralizado. |
 | `empty` | `boolean` | | Sem itens — mostra o emptyText. |
 | `emptyText` | `string` | | Texto do vazio (pt-BR, ex.: "Nenhum papel."). |
-| `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica NÃO vai pra tela (use errorText). |
+| `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica não vai para tela (use errorText). |
 | `errorText` | `string` | `'Não foi possível carregar.'` | Aviso de erro, orientado ao usuário. |
 | `colSpan` | `number` | | Em tabela: renderiza o estado como `<tr><td colSpan>` (cabe direto no tbody). |

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

@@ -4,15 +4,15 @@ title: Camada de dados
 
 # Camada de dados
 
-A entidade é a spec do armazenamento; o manifest a projeta. As queries falam Kysely tipado.
-Uma regra firme atravessa tudo: o código fala camelCase, o banco fala snake — e o
-`CamelCasePlugin` faz a ponte.
+As entidades descrevem o armazenamento que o manifest projeta, enquanto o Kysely mantém as
+consultas tipadas. No código, nomes usam camelCase; no banco, snake_case. `CamelCasePlugin` faz essa
+conversão nos dois sentidos.
 
 ## Entidade e manifest
 
-> `defineEntity` declara o storage (campos + tipos lógicos `t.*`). A `description` de cada
-> entidade/action é a spec de negócio, projetada no manifest pelo `opus gen`; `opus db check`
-> acusa drift entidade ↔ banco.
+`defineEntity` declara campos e tipos lógicos `t.*`. A `description` de cada entidade e action
+registra o significado de negócio projetado no manifest por `opus gen`. Use `opus db check` para
+detectar divergências entre a entidade e o banco.
 
 ```ts
 import { defineEntity } from '@softize/opus/schema'
@@ -30,16 +30,12 @@ export const SkillEntity = defineEntity({
 })
 ```
 
-## Código camelCase, banco snake
+## Código em camelCase, banco em snake_case
 
-> Regra dura do protocolo: uma camada em snake e outra em camel é defeito — não tem meio-termo.
-
-O schema tipado do Kysely e **toda** query (select/insert/update/where) usam camelCase
+O schema tipado do Kysely e todas as consultas usam camelCase
 (`workspaceId`, `ghRepo`). O banco é snake (a DDL no schema idempotente — `db/schema.sql`).
-O `CamelCasePlugin` no runtime faz a ponte camel↔snake nas queries E nos resultados — o
-mesmo que o prepare já faz.
-Única exceção: um sink escrito por fora do Kysely-com-plugin (ex.: o `audit_log` do Opus, pelo
-pool) fica snake.
+`CamelCasePlugin` converte 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
 import { CamelCasePlugin, Kysely, PostgresDialect } from 'kysely'
@@ -52,31 +48,28 @@ const db = new Kysely<AdminDB>({
 await db.selectFrom('agents').select(['isDefault', 'roleId']).where('workspaceId', '=', id).execute()
 ```
 
-## Migrações · prepare · seed
+## Migrações, preparação e seeds
 
-> Três coisas distintas — não confundir o que roda em prod.
+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).
 - `prepare` — backfill estrutural, prod-safe e idempotente; roda no deploy (depois do migrate).
-- `seed` — fixtures de desenvolvimento. **Não** roda em prod.
-
-## Campo `t.json()`: objeto entra, objeto sai
+- `seed` — cria dados de desenvolvimento e teste. Não é executado em produção.
 
-> A dupla `ColumnType<unknown, string, never>` + `JSON.stringify` na mão está aposentada
-> no caminho do `kyselyRepo`.
+## Campos JSON
 
-O `kyselyRepo` serializa campo `t.json()` na ESCRITA (insert/update), guiado pela
+`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 pra jsonb) sem quebrar typecheck. String passa direto (quem já
+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.
 
-## SQL escrito por LLM: `readOnlyContextPool`
+## SQL gerado por modelo
 
-> Action `ai: true` que executa SQL livre precisa das **quatro defesas** — todas no
-> BANCO, nenhuma em regex sobre o texto da query.
+Uma action `ai: true` que executa SQL livre precisa de quatro proteções no banco. Validar o texto
+com expressão regular não substitui nenhuma delas:
 
 ```ts
 import { Pool } from 'pg'
@@ -86,14 +79,14 @@ const bi = readOnlyContextPool({ pool: new Pool({ connectionString, max: 4 }) })
 const { rows } = await bi.query(sqlDoLlm, { role: roleFor(ctx) })
 ```
 
-1. **Pool com teto** (`max` do pool e/ou `maxConcurrent`) — query de LLM não esgota as
-   conexões do app;
+1. **Pool com limite** (`max` e/ou `maxConcurrent`) — 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 é do CONTEXTO (crie os roles com grants
+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 roda sempre com array de valores; multi-sentença
+4. **Protocolo estendido** — o SQL sempre recebe os valores separadamente; múltiplas instruções
    (`SELECT 1; DROP …`) é recusada pelo próprio protocolo.
 
-Saindo, `DISCARD ALL` devolve a conexão limpa; se a limpeza falhar, a conexão é
-destruída — nunca volta suja pro pool. `statement_timeout` local por transação
-(default 15s) segura a query fugitiva.
+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 é
+15 segundos.

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

@@ -1,6 +1,6 @@
-DetailGroup organiza dados somente leitura como uma lista semântica de pares chave/valor.
-DetailField representa cada par e aceita conteúdo React rico em `label` e `value`. Use Field
-para entrada e validação; use DetailField quando a pessoa apenas consulta um valor.
+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`.
 
 ```tsx preview col
 <DetailGroup columns={2}>
@@ -9,7 +9,7 @@ para entrada e validação; use DetailField quando a pessoa apenas consulta um v
     label="Estágio"
     value={
       <DictionaryValue
-        dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', tone: 'success' } }, presentation: 'stage' }}
+        dict={{ keys: ['prospect', 'customer'], entries: { prospect: { label: 'Prospect' }, customer: { label: 'Cliente', context: 'success' } }, presentation: 'stage' }}
         value="prospect"
       />
     }
@@ -39,7 +39,10 @@ significado no domínio. `0` e `false` seguem como valores. Ver `EmptyValue`.
 
 `variant="framed"` adiciona a superfície e a borda externa. `dividers` desenha apenas as
 divisórias internas; as duas opções são independentes e podem ser combinadas. `orientation`
-define se a chave fica sobre o valor ou ao lado dele.
+define se a chave fica sobre o valor ou ao lado dele. Na orientação horizontal, todos os valores
+começam depois da mesma coluna de rótulo, com largura padrão de `7rem`. Quando a superfície exigir
+mais espaço para os rótulos, ajuste a variável no grupo, por exemplo com
+`className="[--detail-label-width:9rem]"`.
 
 ```tsx preview col
 <DetailGroup columns={2} orientation="horizontal" variant="framed" dividers>