@softize/opus 13.0.0 → 14.0.0

package/CHANGELOG.md

@@ -7,6 +7,87 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 14.0.0 — 2026-09-09
+
+Estados vazio, carregando e erro passam a uma composição só. `DataState` compõe `Empty` (moldura
+sólida, `bare` dentro de tabela) e o mesmo `Alert` de contexto `danger` com botão de recuperação
+que `PageState` já usava; o `Spinner` vira decorativo e o contêiner carrega o único `role="status"`.
+As props de estado têm um nome só em `DataState`, `PageState`, `ActionList` e `ActionListDialog`:
+`emptyMessage`, `errorMessage`, `retryLabel`; `PageState` ganha `onRetry` e `ActionView` ganha
+`emptyMessage` como atalho. `ContentHeader` e `PageHeader` renderizam a mesma anatomia
+(`surface-header.tsx`), e `Content` passa a usar `count`, como `Page`.
+
+A escala de `size` é uma só (`primitives/control.ts`): `xs`, `sm`, `default`, `lg` (1.5, 2, 2.25
+e 2.5rem) e `icon-xs`, `icon-sm`, `icon`, `icon-lg` (1.5, 1.75, 2.25 e 2.5rem), consumida por
+Button, InputGroupButton, Toggle, Select, Tabs, Switch, Item, Avatar, Spinner, Pagination e
+ActionTrigger. O degrau de 1.75rem que os consumidores forçavam por classe agora é `icon-sm`.
+`Button.icon` recebe um nó (`icon={<Plus />}`), como todos os outros componentes. `LabelHelp` é
+exportado pelo barrel e documentado em `form.md`.
+
+O extrator de copy alcança o que antes escapava do inventário: chamadas imperativas de diálogo
+(`dialog.confirm`, `alert`, `prompt`, `choose` — título, descrição e rótulos das ações),
+`TooltipContent`, rótulos em arrays literais locais percorridos por `map`, o `help` de
+`LabelHelp` e elementos JSX com genérico (`<ActionList<A, B>>`). Os campos de estado seguem os
+nomes novos (`emptyMessage`, `errorMessage`, `retryLabel`).
+
+**Breaking:** renomeie `emptyText`, `errorText` e `retryText` para `emptyMessage`,
+`errorMessage` e `retryLabel` em `DataState`, `PageState` e `ActionListDialog`
+(`Select.emptyText` não muda). Troque `Content.meta` por `count`; `ContentHeader` só existe
+dentro de `Content`. `icon-sm` passa a medir 1.75rem e `Avatar` segue a escala (`sm` antigo é
+`xs`; `default` cresce para 2.25rem); classes `size-7` forçadas viram `size="icon-sm"`.
+`Button.icon` deixa de aceitar componente: `icon={Trash}` vira `icon={<Trash />}`. Removidos:
+`TbdlibProvider` (use `OpusProvider`), `ShellNav*` (use `SidebarNav`), `confirm()` e `ConfirmHost`
+(use `dialog.confirm` e `DialogHost`), `FieldSpec.hint` (use `help`) e as variantes semânticas
+legadas de Button, Badge, Alert, Dot e MenuItem — declare `context` e `variant`. Testes que
+liam o markup do vazio de `DataState` passam a olhar `[data-slot=empty]`.
+
+## 13.1.0 — 2026-09-08
+
+Erros deixam de falar inglês e de vazar detalhe interno. `normalizeError` devolve a microcopy fixa
+"Não foi possível concluir a operação. Tente novamente." em `internal.unhandled`; o texto da
+exceção original vai para o logger do runtime e para `cause`, e o servidor não serializa `cause` de
+erro interno na resposta. Todas as mensagens de `ActionError` do runtime, do harness de `testing`,
+dos drivers `node` e `fetch`, do `AuditEmitter`, do scheduler, da DSL e do modo design passam a
+pt-BR com os códigos inalterados; o OpenAPI descreve as respostas como "Sucesso", "Erro do cliente"
+e "Erro do servidor". Na UI, `humanizeActionError` (`lib/action-errors.ts`) concentra a allowlist
+de erros de negócio que `ActionTrigger` já usava e passa a valer em `ActionForm` e `ActionView`:
+o código técnico não aparece mais como título, e as mensagens Zod em pt-BR cobrem todos os códigos
+do zod v3.
+
+Button sem `context` resolve `neutral` para `outline`, `ghost` e `link` (e `primary` para `solid` e
+`subtle`), o que devolve ao `ghost` a cor de texto que ele tinha antes da migração semântica.
+`Calendar` nasce em pt-BR (locale, dropdown de mês e rótulos de navegação). `Progress` e
+`SurfaceStatus` aceitam `context`; `ActionView.loading` aceita boolean. O anel de foco é um só
+(`focusRing`), os tokens `*-destructive` deram lugar à família `context-danger` nos controles de
+formulário, Dialog e Drawer compartilham o overlay e o thumb do Slider usa `bg-background`.
+Textos em inglês de Command, Drawer, Breadcrumb, Carousel, do site e dos exemplos foram
+traduzidos; o site deixa de sobrescrever o fundo do tema. Breadcrumb, carousel, progress,
+resizable e slider passam a ejetados no `registry.lock.json`.
+
+Descontinuados, com aviso no editor e sem mudança de comportamento: as variantes legadas
+(`default`, `secondary`, `destructive`, `success`, `warning`, `info`), `confirm()`, `ConfirmHost`,
+`FieldSpec.hint` (use `help`), `ShellNav*` (use `SidebarNav`) e `TbdlibProvider`, renomeado para
+`OpusProvider`. `'danger'` deixa de ser aceito como *variante* legada de Badge e Alert no tipo (era
+um contexto disfarçado): declare `context="danger"`. O botão de confirmar do `ActionTrigger` passa a
+ser sempre `solid` — `danger` quando a action é `destructive`, senão o `context` do gatilho — e não
+herda mais o `variant` do gatilho; a permissão negada (`authorization`/`authentication`) entra na
+allowlist de erros legíveis e o `ActionView` não oferece "Tentar de novo" nesses casos. `openapiInfo` default passa a `{ title: 'Opus API', version }` com a versão do
+pacote, e o servidor MCP reporta a versão real; a marca `tbdlib` saiu do código.
+
+O CLI perde os comandos `add` e `list`, mortos desde que os componentes viraram biblioteca, e
+ganha um `--help` fiel ao dispatch: subcomandos de `db` (`check`, `migrate`, `scaffold`), flags
+`--json` e `--monorepo`, `check --help` com as nove regras e `pre-push --help`. `gen`, `db` e
+`seed` compartilham `bin/lib/cli-shared.mjs`, e `opus.config.ts` ausente produz a mesma mensagem
+nos três. A documentação de `cli.md` cobre `opus copy`, o hook de pré-push e as flags; quinze
+páginas de componentes ganham tabela de propriedades e os hooks `useListAction`,
+`useFormAction`, `useViewAction`, `useTriggerAction` e `useDicts` aparecem nas páginas que os
+usam. `PROMOTED.md` viaja no pacote.
+
+**Atenção:** a peer `react`/`react-dom` passa a `^19.0.0`. O suporte a React 18 nunca funcionou
+de fato, porque os componentes dependem de `ref` como prop; consumidores em 19 não precisam
+fazer nada. O default de `ghost` sem `context` muda de cor: quem quiser o azul de antes declara
+`context="primary"`.
+
 ## 13.0.0 — 2026-09-07
 
 Dialogs passam a formar uma única família. `Dialog mode="alert"` oferece a semântica de

package/PROMOTED.md

@@ -0,0 +1,46 @@
+# Enhancements promovidas ao Opus
+
+O registro CURADO da régua "o Opus cresce por reincidência". O fluxo vivo NÃO passa por
+edição manual deste arquivo: o agente no projeto aponta em `.opus/issues.jsonl` do repo
+dele (instrução na skill `implement-opus-change`; `type` **enhancement** ou **bug**) →
+o Maestro colhe no boot da sessão e abre a **Issue no repo do Opus**
+(`github.com/softize-dev/opus`, dedup por hash + ledger), onde a triagem e a decisão
+acontecem (aberta = pendente, fechada = decidida). Enhancement aceita com **n ≥ 2**
+ocorrências reais — comportamento se paga na reincidência; estilo e conveniência não.
+Bug (defeito NO Opus) aciona com n=1: vira fix + CHANGELOG, **não** entra neste ledger.
+
+Aqui fica só o DECIDIDO e a espera triada: entrada nova/movida entra **no PR que
+implementa a promoção** (git write só pega carona em trabalho que já é git — nenhum
+serviço escreve em repo). Rejeitadas ficam fechadas no GitHub com o motivo; rejeição que
+vira REGRA vai pra skill, não pra cá.
+
+## Em espera
+
+### Truncate (UI)
+Texto truncado com tooltip SÓ quando transborda (medição via ResizeObserver).
+- n = 2 — admin (listas com célula estreita) e maestro (`Ai.tsx`: `truncate` + `title`
+  sempre presente, hooks e MCP). Apontado como issue #2 em `softize-dev/opus`. Jul/2026.
+
+### Driver ai via CLI `claude` (SDK)
+`complete()` one-shot spawnando o CLI headless com a credencial da ASSINATURA do host
+(OAuth), em vez de API key — quando o consumidor já vive numa máquina com Claude Code
+e não quer cobrança por token à parte. Viraria um `@softize/opus/ai/claude-cli` ao
+lado do `ai/anthropic` (mesmo contrato `AiAdapter`, outra credencial/custo).
+- n = 1 — maestro (`src/naming.ts`: título de sessão por IA; escolha DELIBERADA pelo
+  CLI, comentada no arquivo). Jul/2026.
+
+## Promovidas
+
+### Copyable (UI) — 2.15.0
+Clicar-pra-copiar com feedback (ícone check ~1.5s), pra IDs/tokens/slugs/URLs. Botão-ícone
+sem filhos; rótulo + ícone com filhos. Exportado de `@softize/opus/ui/react`.
+Apontado no exercício e2e do fluxo GitHub Issues (jul/2026): o agente precisou de "copiar
+link" na toolbar do preview do Maestro, compôs um `CopyButton` local (workaround), filou o
+enhancement → issue #4 em `softize-dev/opus`, aceita na triagem. O workaround local sai no
+bump que consome a 2.15.0.
+
+### Átomos t.* como schema de input de action (sdk) — 2.14.0
+Apontada pelo projeto `fieldnotes` (exercício e2e, jul/2026; aceita na triagem). Veredito:
+a capacidade JÁ EXISTIA — `t.slug().zod()` devolve o schema zod do tipo lógico — e o
+buraco real era descoberta. Promovida como CONTRATO: doc de actions mostra o uso e um
+teste trava `.zod()` como superfície pública (não re-escreva regex do que o Opus valida).

package/README.md

@@ -2,7 +2,7 @@
 
 > **Status:** v0 — pacote único `@softize/opus` com subpath exports (core + adapters). Uma versão, sem semver por módulo.
 
-End-to-end action protocol for TypeScript. Declare once — input, authorization, execution, audit, feedback — and let adapters materialize it across UI, client, server, and log.
+Protocolo de actions de ponta a ponta para TypeScript. Declare uma vez — input, autorização, execução, auditoria, feedback — e deixe os adapters materializarem a action na interface, no cliente, no servidor e no log.
 
 **O Opus não é framework.** Não tem ciclo de vida próprio. É o contrato comum que todas as camadas falam.
 
@@ -15,7 +15,7 @@ End-to-end action protocol for TypeScript. Declare once — input, authorization
 - **Contrato, não feature.** Tudo que entra no core padroniza forma; tudo que faz trabalho usa lib externa.
 - **Fail-closed por default.** Action sem `authorize` é negada. Audit default-on.
 - **Adapters plugáveis.** Cada categoria é uma superfície (subpath) com interface fechada e drivers trocáveis.
-- **Doc é fonte da verdade.** `docs/protocol.md` — 16 seções fechadas (15 + glossário).
+- **Declaração é a fonte; doc é projeção.** As declarações (`defineContract`, `bindAction`, `defineEntity`) são a fonte dos contratos; manifest, OpenAPI e a doc gerada são projeções. `docs/protocol.md` descreve o protocolo em 16 seções (15 + glossário).
 
 ## Superfícies
 
@@ -23,21 +23,29 @@ Um pacote (`@softize/opus`), uma versão. Cada categoria abaixo é um **subpath
 
 | Superfície | Drivers | Propósito |
 |---|---|---|
-| `@softize/opus` (core) | — | Protocolo, `defineAction`, `defineEntity`, runtime |
-| `@softize/opus/schema` | `/zod`, `/openapi` | Logical types (`t.*`) + OpenAPI generator |
-| `@softize/opus/server` | `/fastify` | HTTP transport + endpoint mount |
-| `@softize/opus/client` | `/fetch` | Client adapter pra invocar actions |
-| `@softize/opus/ui` | `/react` | Componentes + Provider + hooks (`useAction`, `useListAction`) |
-| `@softize/opus/data` | `/kysely` | Data adapter (`ctx.db`, `ctx.repo`) |
-| `@softize/opus/auth` | `/jwt`, `/better-auth` | Auth adapter (`ctx.user`, `ctx.can`) |
-| `@softize/opus/audit` | `/console`, `/pg` | Audit sinks |
-| `@softize/opus/log` | `/pino` | Logger adapter (console default no core) |
-| `@softize/opus/queue` | `/bullmq` | Background job execution |
-| `@softize/opus/events` | `/mitt` | EventBus (in-process) |
-| `@softize/opus/scheduler` | `/node-cron` | Schedule adapter (ação iniciada por tempo) |
+| `@softize/opus` (core) | — | Protocolo, `defineContract`, `bindAction`, `defineAction`, `defineEntity`, runtime |
+| `@softize/opus/schema` | `/zod`, `/openapi` | Tipos lógicos (`t.*`) e gerador de OpenAPI |
+| `@softize/opus/server` | `/fastify`, `/node` | Transporte HTTP e montagem de endpoints |
+| `@softize/opus/client` | `/fetch` | Adapter de cliente para invocar actions |
+| `@softize/opus/ui` | `/react`, `/meta`, `/docs` | Componentes, Provider e hooks (`useAction`, `useListAction`) |
+| `@softize/opus/data` | `/kysely`, `/readonly-pool` | Adapter de dados (`ctx.db`, `ctx.repo`) |
+| `@softize/opus/auth` | `/jwt`, `/better-auth` | Adapter de autenticação (`ctx.user`, `ctx.can`) |
+| `@softize/opus/audit` | `/console`, `/pg` | Destinos de auditoria |
+| `@softize/opus/log` | `/pino` | Adapter de log (console é o default no core) |
+| `@softize/opus/queue` | `/bullmq` | Execução de jobs em segundo plano |
+| `@softize/opus/events` | `/mitt` | EventBus em processo |
+| `@softize/opus/scheduler` | `/node-cron` | Adapter de agendamento (ação iniciada por tempo) |
+| `@softize/opus/storage` | `/fs`, `/s3` | Armazenamento de arquivos (experimental) |
+| `@softize/opus/cache` | `/memory` | Cache de leitura para handlers (experimental) |
+| `@softize/opus/ai` | `/anthropic` | Capability de IA generativa: `complete` e `extract` (experimental) |
+| `@softize/opus/mcp` | — | Expõe actions `ai:enabled` como tools MCP para agentes externos |
+| `@softize/opus/observability` | `/opentelemetry` | Traces e contexto de execução, com porta vendor-neutral no core |
+| `@softize/opus/testing` | — | Harness de teste de actions pela fronteira do contrato (experimental) |
+| `@softize/opus/dsl` | — | Expressões declarativas avaliadas em `load` e em consultas |
 | `@softize/opus/seed` | — | Declaração e binding de datasets verificáveis operados pela CLI |
+| `@softize/opus/vite` | — | Plugins Vite: runtime em modo design e auth de sessão fixa |
 
-Drivers via subpath ESM (estilo Drizzle): `@softize/opus/server/fastify`, `@softize/opus/data/kysely`.
+Os drivers são resolvidos por subpath ESM (no estilo do Drizzle): `@softize/opus/server/fastify`, `@softize/opus/data/kysely`.
 
 ## Quick start
 
@@ -80,10 +88,11 @@ await app.listen({ port: 3000 })
 
 ```
 src/
-  core/      schema/    server/    client/    ui/
-  data/      auth/      audit/     log/       queue/   events/   scheduler/   dsl/
+  core/      schema/    server/    client/    ui/      data/    auth/    audit/
+  log/       queue/     events/    scheduler/ storage/ cache/   ai/      mcp/
+  observability/        testing/   dsl/       seed/    vite/
 registry/    # scaffolds + skills Opus — geração e conhecimento do SDK, não runtime
-bin/         # CLI (opus setup/gen/copy/check/seed/introspect/mcp) + libs
+bin/         # CLI (opus create/setup/gen/copy/check/db/seed/pre-push/introspect/mcp) + libs
 docs/
   protocol.md   # contrato completo (16 seções)
   data-layer.md · seeds.md · releasing.md · code-style.md
@@ -108,7 +117,7 @@ O contrato não oferece reset/truncate, e `apply` precisa convergir quando repet
 
 ## Status
 
-- **v0**: 12 superfícies, 430 tests, 100% coverage.
+- **v0**: 21 superfícies, suíte vitest com cobertura medida por `pnpm test:cov`. O threshold de 100% em `vitest.config.ts` é aspiracional e não faz parte do gate de release (ver [docs/releasing.md](docs/releasing.md)).
 - **v1+**: drivers adicionais (Hono, Drizzle, ArkType, Vue, Inngest, Redis events), camada de entidades (`defineEntity`), Conversya migration plan.
 
 ## Desenvolvimento

package/bin/cli.mjs

@@ -1,31 +1,20 @@
 #!/usr/bin/env node
 /**
- * @softize/opus CLI — copia templates do registry pro consumer.
+ * @softize/opus CLI — `opus <comando>`.
  *
- * Uso:
- *   npx @softize/opus add <name>             # copia registry/<name>.tsx
- *   npx @softize/opus add <name> --force      # sobrescreve se existe
- *   npx @softize/opus list                    # lista templates disponíveis
- *   npx @softize/opus gen                     # gera manifest/openapi/docs/stubs
- *
- * Lê components.json do consumer pra resolver path destino (mesma config
- * do shadcn). Default: <cwd>/src/components/action/<name>.tsx.
+ * Cobre o ciclo de um projeto Opus: bootstrap (`create`, `setup`), projeções a partir
+ * das declarações (`gen`, `copy`, `introspect`), gates (`check`, `pre-push`, `db`,
+ * `seed`) e o server MCP para agentes (`mcp`). `opus --help` lista os comandos;
+ * `opus <comando> --help` detalha cada um.
  */
 
-import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import {
-  canonicalProjectDirectory,
-  ensureProjectDirectory,
-  readProjectFile,
-  safeProjectPath,
-  writeProjectFileAtomically,
-} from '@softize/base/project-path'
 
 import { cmdGen, helpGen } from './lib/gen.mjs'
 import { cmdDb } from './lib/db.mjs'
 import { scanDir, emptyScanVerdict } from './lib/check.mjs'
+import { log } from './lib/cli-shared.mjs'
 import { checkCopyInventory, writeCopyInventory } from './lib/copy.mjs'
 import { createMonorepo, createProject } from './lib/create.mjs'
 import { initProject, repoRootOf, setupUiFoundation } from './lib/init.mjs'
@@ -38,149 +27,10 @@ const __dirname = path.dirname(__filename)
 const PACKAGE_ROOT = path.resolve(__dirname, '..')
 const REGISTRY_DIR = path.join(PACKAGE_ROOT, 'registry')
 
-// =============================================================================
-// Helpers
-// =============================================================================
-
-function log(level, msg) {
-  const colors = {
-    info: '\x1b[36m',
-    success: '\x1b[32m',
-    error: '\x1b[31m',
-    warn: '\x1b[33m',
-  }
-  const reset = '\x1b[0m'
-  console.log(`${colors[level]}${msg}${reset}`)
-}
-
-async function fileExists(p) {
-  try {
-    await fs.access(p)
-    return true
-  } catch {
-    return false
-  }
-}
-
-async function loadComponentsJson(cwd) {
-  const candidate = readProjectFile(cwd, 'components.json', { allowMissing: true })
-  if (!candidate.exists) {
-    return null
-  }
-  try {
-    return JSON.parse(candidate.content)
-  } catch (err) {
-    log('warn', `components.json existe mas não é JSON válido: ${err.message}`)
-    return null
-  }
-}
-
-function resolveAlias(alias, fallback) {
-  if (typeof alias !== 'string') return fallback
-  // Pega só a parte após "@/" pq path é relativo a src/.
-  // Ex: "@/components" → "components".
-  if (alias.startsWith('@/')) {
-    return alias.slice(2)
-  }
-  return alias
-}
-
-async function resolveDestination(cwd, name) {
-  const components = await loadComponentsJson(cwd)
-  if (components === null) {
-    log(
-      'warn',
-      'Sem components.json. Usando default ./src/components/action/. Roda `npx shadcn init` se quiser configurar.',
-    )
-    return path.join('src/components/action', `${name}.tsx`)
-  }
-  const aliasComponents =
-    components.aliases?.components ?? '@/components'
-  const componentsRel = resolveAlias(aliasComponents, 'components')
-  return path.join('src', componentsRel, 'action', `${name}.tsx`)
-}
-
-async function listTemplates() {
-  if (!(await fileExists(REGISTRY_DIR))) {
-    log('error', `Registry não encontrado em ${REGISTRY_DIR}.`)
-    process.exit(1)
-  }
-  const files = await fs.readdir(REGISTRY_DIR)
-  return files
-    .filter((f) => f.endsWith('.tsx') || f.endsWith('.ts'))
-    .map((f) => f.replace(/\.(tsx|ts)$/, ''))
-    .sort()
-}
-
 // =============================================================================
 // Commands
 // =============================================================================
 
-async function cmdList() {
-  const templates = await listTemplates()
-  if (templates.length === 0) {
-    log(
-      'info',
-      '\nSem templates de cópia (os componentes de UI agora são LIB, não se copiam):\n' +
-        '  • importe de `@softize/opus/ui/react` (Button, ActionForm, DropdownMenu…)\n' +
-        '  • descubra o catálogo via `opus mcp` → tool `opus_list_components`\n',
-    )
-    return
-  }
-  log('info', `\n@softize/opus templates disponíveis:\n`)
-  for (const t of templates) {
-    console.log(`  ${t}`)
-  }
-  console.log('')
-  log('info', `Adicionar: npx @softize/opus add <nome>\n`)
-}
-
-async function cmdAdd(name, options) {
-  if (typeof name !== 'string' || name.length === 0) {
-    log('error', 'Uso: npx @softize/opus add <name>')
-    process.exit(1)
-  }
-
-  const templates = await listTemplates()
-  if (!templates.includes(name)) {
-    log('error', `Template "${name}" não existe.`)
-    console.log(`\nDisponíveis: ${templates.join(', ')}\n`)
-    process.exit(1)
-  }
-
-  const cwd = canonicalProjectDirectory(process.cwd())
-  const src = path.join(REGISTRY_DIR, `${name}.tsx`)
-  const dest = await resolveDestination(cwd, name)
-  safeProjectPath(cwd, dest)
-  const current = readProjectFile(cwd, dest, { allowMissing: true })
-
-  if (current.exists) {
-    if (options.force !== true) {
-      log(
-        'warn',
-        `Já existe em ${dest} — passa --force pra sobrescrever.`,
-      )
-      process.exit(1)
-    }
-    log('warn', `Sobrescrevendo ${dest}`)
-  }
-
-  const parents = []
-  let parent = path.dirname(dest)
-  while (parent !== '.') {
-    parents.unshift(parent)
-    parent = path.dirname(parent)
-  }
-  for (const directory of parents) ensureProjectDirectory(cwd, directory)
-  const content = await fs.readFile(src, 'utf-8')
-  writeProjectFileAtomically(cwd, dest, content, { exists: current.exists, content: current.content })
-
-  log('success', `✓ Criado ${dest}`)
-  console.log(
-    '\n  Edita à vontade — esse arquivo é seu agora. Próximas runs com --force\n  sobrescrevem suas mudanças.\n',
-  )
-}
-
 async function cmdCheck(dir) {
   const root = path.resolve(process.cwd(), dir ?? '.')
   const rel = path.relative(process.cwd(), root) || '.'
@@ -392,6 +242,7 @@ async function cmdIntrospect(dir, flags) {
 function parseArgs(argv) {
   const args = argv.slice(2)
   const positional = []
+  // `force` sobrevive só por compatibilidade: gen aceita e ignora.
   const flags = { force: false, help: false }
   // Flags com valor — pega o próximo arg.
   const VALUE_FLAGS = new Set(['--config', '--output', '--profile', '--scope'])
@@ -445,35 +296,49 @@ async function main() {
     console.log(`
 @softize/opus CLI
 
-Comandos:
-  create <dir>     Scaffolda um app opus-based canônico (vite+react+ui+domínio-exemplo);
-                   detecta workspace (app em monorepo); --monorepo cria a RAIZ do workspace
-  setup            Reconcilia opus.json e os artefatos Opus versionados para Claude/Codex
-  add <name>       Copia template do catálogo empacotado pro projeto
-  list             Lista templates disponíveis
-  gen              Gera manifest/openapi/docs/stubs a partir do opus.config.ts
-  copy [dir]       Gera o inventário semântico de copy dos contratos; --check só confere
-  check [dir]      Valida as convenções das actions (régua de padrão; exit ≠ 0 se violar)
-  pre-push         Gate Git: freshness dos artefatos + convenções das actions
-  db <verbo>       Comandos de banco. v1: db check (drift-check entidade ↔ banco)
-  seed <verbo>     Lista, valida, planeja, aplica e verifica seeds estruturados
-  introspect [dir] Modelo da estrutura (actions/reactions/schedules + wiring); --json
-  mcp              Server MCP (introspect/check/scaffold de action) — agentes via mcp_config
-  help             Mostra esta mensagem
-
-Flags:
-  --force, -f      Sobrescreve arquivo existente
-  --check          Não escreve; falha se o inventário de copy estiver ausente/desatualizado
-  --config <path>  (gen) Caminho do opus.config.ts
-  --output <path>  (gen) Pasta de saída
-  --profile <name> (seed) Perfil do dataset
-  --scope <name>   (seed) Escopo explícito dos dados
-
-Exemplos:
-  npx @softize/opus add action-form
-  npx @softize/opus add action-list --force
-  npx @softize/opus list
+Uso: opus <comando> [argumentos] [flags]
+     opus <comando> --help detalha cada comando.
+
+Bootstrap
+  create <dir>       Cria um app Opus canônico (vite + react + UI + domínio-exemplo).
+                     Dentro de um workspace cria só o app; --monorepo cria a raiz do workspace.
+  setup              Reconcilia opus.json e os artefatos Opus versionados (skills, hooks,
+                     instruções) sem sobrescrever o que é seu.
+
+Projeções a partir das declarações
+  gen                Gera manifest, openapi, docs e stubs a partir do opus.config.ts.
+  copy [dir]         Gera o inventário semântico de copy dos contratos; --check só confere.
+  introspect [dir]   Mostra o modelo da estrutura (actions/reactions/schedules + wiring); --json.
+
+Gates (exit ≠ 0 quando há violação)
+  check [dir]        Valida as convenções das actions e da UI (opus check --help lista as regras).
+  pre-push [dir]     Gate do hook Git: o mesmo check; \`pre-push materialization\` confere só
+                     se os artefatos materializados estão atualizados.
+  db <subcomando>    check (drift entidade ↔ banco), migrate (aplica o schema idempotente) e
+                     scaffold (rascunho a partir do diff).
+  seed <subcomando>  list, check, plan, apply e verify de seeds estruturados.
+
+Agentes
+  mcp                Sobe o server MCP (introspect, check e scaffold de action) via stdio.
+
+Flags
+  --help, -h         Ajuda do comando.
+  --check            (copy) Compara sem escrever; falha se o inventário estiver ausente ou
+                     desatualizado.
+  --json             (introspect, seed) Saída estruturada em JSON.
+  --monorepo         (create) Cria a raiz do workspace em vez de um app.
+  --config <path>    (gen, db, seed) Caminho do opus.config.ts. Default: ./opus.config.ts.
+  --output <path>    (gen) Pasta de saída. Default: a do config, ou ./.gen.
+  --profile <nome>   (seed) Perfil do dataset. Default: o defaultProfile do seed.
+  --scope <nome>     (seed) Escopo explícito dos dados. Alternativa: OPUS_SEED_SCOPE.
+  --force, -f        (gen) Aceita por compatibilidade; sem efeito, o gen sempre sobrescreve
+                     a saída.
+
+Exemplos
+  npx @softize/opus create apps/portal
   npx @softize/opus gen --config ./apps/api/opus.config.ts
+  npx @softize/opus check src
+  npx @softize/opus db migrate
 `)
     return
   }
@@ -522,29 +387,6 @@ o gate universal de copy está habilitado; Maestro continua opcional.
     return
   }
 
-  if (command === 'list') {
-    await cmdList()
-    return
-  }
-
-  if (command === 'add') {
-    if (flags.help) {
-      console.log(`
-@softize/opus add <name>
-
-Copia o template registry/<name>.tsx pra src/components/action/<name>.tsx
-(ou ao alias resolvido via components.json).
-
-Flags:
-  --force, -f      Sobrescreve existente
-`)
-      return
-    }
-    const [name] = rest
-    await cmdAdd(name, flags)
-    return
-  }
-
   if (command === 'gen') {
     if (flags.help) {
       helpGen()
@@ -559,18 +401,31 @@ Flags:
       console.log(`
 @softize/opus check [dir]
 
-Valida as convenções das actions (estático, TS compiler API). Enxerga
-\`defineAction\` e o split \`defineContract\`+\`bindAction\`:
-  action-name             — <resource>.<verb> (minúsculo, ponto)
-  kind                    — simple|form|list|view
+Valida as convenções do projeto lendo o source (TS compiler API), sem executar nada.
+Enxerga \`defineAction\` e o split \`defineContract\`+\`bindAction\`, e varre os
+arquivos de UI do projeto (fora de node_modules, builds, testes e fixtures).
+
+Regras das actions:
+  action-name             — name no formato <resource>.<verb> (minúsculo, ponto)
+  kind                    — kind ∈ simple|form|list|view
   field-order             — identidade→docs→input/output→authorize→handler→comportamento
   export                  — defineAction/defineContract/bindAction como \`export const\`
   requires-sem-authorize  — \`requires\` é declarativo (o runtime não o executa);
-                            action com requires precisa de authorize (no contrato
-                            ou no binding — o join contrato↔bind é cross-file)
-
-Exit ≠ 0 se houver violação OU se não achar action nenhuma (gate vazio não
-passa verde). Default dir: cwd.
+                            action com requires precisa de authorize no contrato ou no
+                            binding (o join contrato↔bind é cross-file)
+
+Regras da UI (@softize/opus/ui):
+  ui-structure            — anatomia pública das superfícies compostas (ADR 0005):
+                            filho permitido dentro do pai correto
+  ui-semantic-api         — API semântica: \`context\` + \`variant\`; reprova aliases de
+                            migração e \`tone\` em novos dicionários
+  removed-ui-token        — token público removido (ring-edge, shadow-card…) com a
+                            substituição indicada
+  unpaired-ui-surface     — superfície sem o foreground do par (bg-card sem
+                            text-card-foreground, bg-popover sem text-popover-foreground)
+
+Exit ≠ 0 se houver violação. Sem nenhuma action: projeto marcado (opus.json) passa
+vacuamente; sem marcador, falha — gate vazio não é aprovação. Default dir: cwd.
 `)
       return
     }
@@ -600,6 +455,22 @@ Flags:
   }
 
   if (command === 'pre-push') {
+    if (flags.help) {
+      console.log(`
+@softize/opus pre-push [dir | materialization]
+
+Gate que o hook Git instalado por \`opus setup\` executa antes de cada push, também
+utilizável à mão:
+  pre-push [dir]            O mesmo \`opus check [dir]\` (convenções das actions e da UI).
+                            Default dir: cwd.
+  pre-push materialization  Confere se os artefatos Opus materializados no repo (skills,
+                            hooks, instruções) estão atualizados para a versão adotada.
+
+O hook roda \`copy --check\`, depois \`pre-push materialization\` na raiz e \`check\` em cada
+app com opus.json; qualquer um com exit ≠ 0 bloqueia o push.
+`)
+      return
+    }
     if (rest[0] === 'materialization') await cmdMaterializationCheck()
     else await cmdCheck(rest[0] ?? '.')
     return