@softize/opus 13.0.0 → 14.0.0

package/bin/lib/gen-openapi.mjs

@@ -82,15 +82,15 @@ function buildResponses(action) {
   const successStatus = String(action.successStatus ?? 200)
   return {
     [successStatus]: {
-      description: 'Success',
+      description: 'Sucesso',
       content: {
         'application/json': {
           schema: wrapEnvelope(action.output, action.kind),
         },
       },
     },
-    '4XX': errorResponse('Client error', action.errors),
-    '5XX': errorResponse('Server error'),
+    '4XX': errorResponse('Erro do cliente', action.errors),
+    '5XX': errorResponse('Erro do servidor'),
   }
 }
 

package/bin/lib/gen-runner.mjs

@@ -75,7 +75,7 @@ const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
 async function main() {
   const configPath = process.argv[2]
   if (typeof configPath !== 'string' || configPath.length === 0) {
-    return emitError('Missing config path argv[2]')
+    return emitError('Caminho do config ausente (argv[2])')
   }
 
   const configAbs = path.resolve(configPath)

package/bin/lib/gen.mjs

@@ -16,17 +16,13 @@
  *   - config: ./opus.config.ts (no cwd)
  *   - output: o que o config disser, ou ./.gen
  *
- * Flag `--force`: sobrescreve arquivos existentes (default sobrescreve
- * silenciosamente — opus gen é idempotente e o output mora num dir
- * dedicado, então não há valor real em bloquear sem --force. Mantemos a
- * flag pra paridade com `add`).
+ * Flag `--force`: aceita por compatibilidade, sem efeito — o gen sempre
+ * sobrescreve (é idempotente e o output mora num dir dedicado, então não
+ * há valor real em bloquear a escrita).
  */
 
-import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { execFile } from 'node:child_process'
-import { promisify } from 'node:util'
 import {
   canonicalProjectDirectory,
   ensureProjectDirectory,
@@ -42,46 +38,25 @@ import { buildOpenAPI } from './gen-openapi.mjs'
 import { buildDocs } from './gen-docs.mjs'
 import { buildClientStubs } from './gen-stubs.mjs'
 import { buildDictStubs } from './gen-dicts.mjs'
-
-const execFileAsync = promisify(execFile)
+import { lastJsonLine, log, resolveConfig, spawnTsx } from './cli-shared.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
-const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
 const RUNNER_PATH = path.join(__dirname, 'gen-runner.mjs')
 
-const COLORS = {
-  info: '\x1b[36m',
-  success: '\x1b[32m',
-  error: '\x1b[31m',
-  warn: '\x1b[33m',
-  dim: '\x1b[2m',
-}
-const RESET = '\x1b[0m'
-
-function log(level, msg) {
-  console.log(`${COLORS[level] ?? ''}${msg}${RESET}`)
-}
-
 // =============================================================================
 // Comando
 // =============================================================================
 
 export async function cmdGen(flags) {
-  const cwd = canonicalProjectDirectory(process.cwd())
-  const configRel = flags.config ?? 'opus.config.ts'
-  const config = safeProjectPath(cwd, configRel)
-  const configPath = config.path
-
-  if (!config.exists) {
-    log('error', `opus.config.ts não encontrado em ${configPath}`)
-    log(
-      'dim',
-      '  Cria um arquivo na raiz do projeto exportando `{ domains: [...] }` como default,',
-    )
-    log('dim', '  ou passa o path via --config <path>.')
+  let resolved
+  try {
+    resolved = resolveConfig(flags)
+  } catch (error) {
+    log('error', error instanceof Error ? error.message : String(error))
     process.exit(1)
   }
+  const { cwd, configPath } = resolved
 
   log('info', `→ Carregando ${path.relative(cwd, configPath)}...`)
 
@@ -190,22 +165,12 @@ function auditDocs(manifest, cwd) {
 // =============================================================================
 
 async function loadConfig(configPath) {
-  // tsx mora em <package>/node_modules/.bin/tsx — usamos absoluto pra
-  // evitar depender de PATH do consumer.
-  const tsxBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', 'tsx')
-  const hasLocalTsx = await fileExists(tsxBin)
-
-  // Args do runner: <runner.mjs> <configPath>. tsx aceita .mjs também
-  // (passthrough) e nos permite resolver TS na cadeia de imports.
-  const args = [RUNNER_PATH, configPath]
-  const cmd = hasLocalTsx ? tsxBin : 'tsx'
-
+  // tsx aceita .mjs também (passthrough) e nos permite resolver TS na cadeia
+  // de imports do config.
   try {
     // Buffer grande pra acomodar manifests gordos.
-    const { stdout, stderr } = await execFileAsync(cmd, args, {
-      encoding: 'utf8',
+    const { stdout, stderr } = await spawnTsx(RUNNER_PATH, [configPath], {
       maxBuffer: 64 * 1024 * 1024,
-      env: { ...process.env },
     })
 
     // Runner emite a linha JSON na ÚLTIMA linha de stdout. Qualquer log do
@@ -236,30 +201,10 @@ async function loadConfig(configPath) {
   }
 }
 
-function lastJsonLine(stdout) {
-  const lines = stdout.split('\n').filter((l) => l.trim().length > 0)
-  for (let i = lines.length - 1; i >= 0; i--) {
-    const trimmed = lines[i].trim()
-    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
-      return trimmed
-    }
-  }
-  return null
-}
-
 // =============================================================================
 // FS helpers
 // =============================================================================
 
-async function fileExists(p) {
-  try {
-    await fs.access(p)
-    return true
-  } catch {
-    return false
-  }
-}
-
 function ensureProjectTree(root, requested) {
   let cursor = '.'
   for (const segment of requested.split(path.sep).filter((item) => item !== '' && item !== '.')) {
@@ -332,7 +277,7 @@ Lê opus.config.ts do consumer e gera:
 Flags:
   --config <path>   Caminho interno ao projeto para opus.config.ts. Default: ./opus.config.ts
   --output <path>   Pasta interna ao projeto. Default: do config (ou ./.gen)
-  --force, -f       Sobrescreve existente (atualmente sempre sobrescreve)
+  --force, -f       Aceita por compatibilidade; sem efeito, o gen sempre sobrescreve a saída
 
 Exemplos:
   npx @softize/opus gen

package/bin/lib/mcp.mjs

@@ -11,6 +11,7 @@
  *   opus_get_component   — detalhe de um componente pelo nome
  */
 
+import { createRequire } from 'node:module'
 import path from 'node:path'
 import { z } from 'zod'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -23,10 +24,11 @@ const asText = (data) => ({
   content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
 })
 const dirOf = (d) => path.resolve(process.cwd(), d ?? '.')
+const { version: OPUS_VERSION } = createRequire(import.meta.url)('../../package.json')
 
 /** Monta o McpServer com as tools da base. Exportado pra testar (transport in-memory). */
 export function buildServer() {
-  const server = new McpServer({ name: 'opus', version: '0.0.0' })
+  const server = new McpServer({ name: 'opus', version: OPUS_VERSION })
 
   server.registerTool(
     'opus_introspect',

package/bin/lib/seed.mjs

@@ -1,30 +1,13 @@
 /** Grupo `opus seed`: descoberta, gate e execução segura dos seeds do projeto. */
 
-import { execFile } from 'node:child_process'
-import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { promisify } from 'node:util'
 
-import { canonicalProjectDirectory, readProjectFile, safeProjectPath } from '@softize/base/project-path'
+import { readProjectFile } from '@softize/base/project-path'
 
-const execFileAsync = promisify(execFile)
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = path.dirname(__filename)
-const PACKAGE_ROOT = path.resolve(__dirname, '..', '..')
+import { log, resolveConfig, runJsonRunner } from './cli-shared.mjs'
 
-const COLORS = {
-  info: '\x1b[36m',
-  success: '\x1b[32m',
-  error: '\x1b[31m',
-  warn: '\x1b[33m',
-  dim: '\x1b[2m',
-}
-const RESET = '\x1b[0m'
-
-function log(level, message) {
-  console.log(`${COLORS[level] ?? ''}${message}${RESET}`)
-}
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 export function findAdHocSeedScripts(scripts = {}) {
   return Object.entries(scripts).flatMap(([name, command]) => {
@@ -116,14 +99,6 @@ function fail(flags, message) {
   process.exitCode = 1
 }
 
-function resolveConfig(flags) {
-  const cwd = canonicalProjectDirectory(process.cwd())
-  const configRel = flags.config ?? 'opus.config.ts'
-  const config = safeProjectPath(cwd, configRel)
-  if (!config.exists) throw new Error(`opus.config.ts não encontrado em ${config.path}`)
-  return { cwd, configPath: config.path }
-}
-
 function readSeedScriptFindings(cwd) {
   const packageFile = readProjectFile(cwd, 'package.json', { allowMissing: true })
   if (!packageFile.exists) return []
@@ -140,22 +115,8 @@ function readSeedScriptFindings(cwd) {
   }))
 }
 
-async function runRunner(configPath, extraArgs) {
-  const tsxBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', 'tsx')
-  const command = (await fileExists(tsxBin)) ? tsxBin : 'tsx'
-  const runnerPath = path.join(__dirname, 'seed-runner.mjs')
-  try {
-    const { stdout } = await execFileAsync(command, [runnerPath, configPath, ...extraArgs], {
-      encoding: 'utf8',
-      maxBuffer: 16 * 1024 * 1024,
-      env: { ...process.env },
-    })
-    const line = lastJsonLine(stdout)
-    return line === null ? { ok: false, error: 'runner não emitiu JSON' } : JSON.parse(line)
-  } catch (error) {
-    const detail = typeof error.stderr === 'string' && error.stderr.trim() ? error.stderr.trim() : error.message
-    return { ok: false, error: detail }
-  }
+function runRunner(configPath, extraArgs) {
+  return runJsonRunner(path.join(__dirname, 'seed-runner.mjs'), [configPath, ...extraArgs])
 }
 
 function printList(seeds) {
@@ -188,24 +149,6 @@ function printDiagnostics(diagnostics) {
   for (const diagnostic of diagnostics) log('warn', `[${diagnostic.code}] ${diagnostic.message}`)
 }
 
-function lastJsonLine(stdout) {
-  const lines = stdout.split('\n').filter((line) => line.trim())
-  for (let index = lines.length - 1; index >= 0; index--) {
-    const line = lines[index].trim()
-    if (line.startsWith('{') && line.endsWith('}')) return line
-  }
-  return null
-}
-
-async function fileExists(file) {
-  try {
-    await fs.access(file)
-    return true
-  } catch {
-    return false
-  }
-}
-
 export function helpSeed() {
   console.log(`
 @softize/opus seed — datasets estruturados do projeto

package/docs/code-style.md

@@ -86,13 +86,16 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 | `messages.success`, `messages.error`, `messages.confirmation` | `success`, `error`, `message` |
 | `confirm.message` | `dialog-body` |
 | `fields.*.label`, `filters.*.label` | `label` |
-| `placeholder`, `hint`, `help` | `placeholder`, `helper-text` |
+| `placeholder`, `help` | `placeholder`, `helper-text` |
 | opções estáticas | `menu-item` |
 | `columns[].label`, `periods[].label` | `heading`, `tab` |
 | `Select.emptyText`, `Select.searchPlaceholder` | `empty-state`, `placeholder` |
 | `Select.options[].hint/triggerLabel/group` | `label`, `label`, `heading` |
 | `ActionTrigger.confirm.*` | papel correspondente do diálogo |
 | `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário | `label`, `description` |
+| `DataState`/`PageState`/`ActionList`/`ActionListDialog` — `emptyMessage`, `errorMessage`, `retryLabel`; `PageState`/`ActionListDialog` — `title`, `description`; `ActionView.emptyMessage` | `empty-state`, `error`, `button`, `title`, `description` |
+| `dialog.alert/confirm/prompt/choose()` — `title`, `description`, `body`, `action`, `cancel`, `placeholder`, `actions[].label` | papel correspondente do diálogo |
+| `TooltipContent` (children), `LabelHelp.help` | `label`, `helper-text` |
 
 ## Cobertura e significado do gate verde
 

package/docs/ownership-vs-shadcn-lock.md

@@ -73,9 +73,8 @@ upstream com quem se tem que ficar idêntico atrita com ter opinião.
 3. **Re-sync por diff sob demanda, com IA.** Em vez de "re-porta e o hash diz o que
    mudou", o fluxo é um **merge de 3 vias**: base (o `upstreamHash` gravado) → shadcn
    atual → nosso customizado. O Claude lê os dois diffs e reconcilia preservando o delta
-   da casa. Vale uma skill/comando (`opus resync <componente>`) pra ser um gesto de uma
-   linha, com teste + revisão como rede de segurança (o hash determinístico sai, o
-   julgamento entra).
+   da casa. Hoje é um fluxo conduzido com IA, com teste + revisão como rede de segurança
+   (o hash determinístico sai, o julgamento entra); não existe comando `opus resync`.
 
 ## Tradeoffs honestos
 

package/docs/protocol.md

@@ -424,21 +424,21 @@ handler: async (ctx, input) => {
   if (!deal) throw error({
     code: 'deal.archive.notFound',
     category: 'not_found',
-    message: `Deal ${input.dealId} not found`,
+    message: `Negócio ${input.dealId} não encontrado`,
     i18nKey: 'deal.error.notFound',
     i18nParams: { id: input.dealId },
   })
   if (deal.archivedAt) throw error({
     code: 'deal.archive.alreadyArchived',
     category: 'conflict',
-    message: 'Deal already archived',
+    message: 'Negócio já arquivado',
     retriable: false,
   })
   // ...
 }
 ```
 
-Erros não-categorizados (ex: `throw new Error(...)` cru, ou exceção do driver do DB) são **normalizados** pelo runtime para `{ category: 'internal', code: 'internal.unhandled', severity: 'error', retriable: false, cause: <original> }`.
+Erros não-categorizados (ex: `throw new Error(...)` cru, ou exceção do driver do DB) são **normalizados** pelo runtime para `{ category: 'internal', code: 'internal.unhandled', severity: 'error', retriable: false, message: 'Não foi possível concluir a operação. Tente novamente.', cause: <original> }`. A `message` é fixa: o texto da exceção original nunca chega à pessoa — fica no logger do runtime e em `cause` (só a mensagem; stack não vaza).
 
 ### Validation: caso especial
 
@@ -448,12 +448,12 @@ Erros de schema (input que não satisfaz Zod/ArkType) são **automaticamente** t
 {
   code:     'validation.invalid_input',
   category: 'validation',
-  message:  'Input validation failed',
+  message:  'Dados de entrada inválidos',
   severity: 'warning',
   retriable: false,
   issues: [
-    { path: 'dealId',   code: 'required',  message: 'dealId is required' },
-    { path: 'priority', code: 'out_of_range', message: 'priority must be 1..5' },
+    { path: 'dealId',   code: 'required',  message: 'dealId é obrigatório' },
+    { path: 'priority', code: 'out_of_range', message: 'priority precisa estar entre 1 e 5' },
   ],
 }
 ```
@@ -540,7 +540,7 @@ authorize: async (ctx, input, loaded) => {
   if (loaded.deal.locked) return error({                   // específico
     code: 'deal.archive.locked',
     category: 'authorization',
-    message: 'Locked deals cannot be archived',
+    message: 'Negócios bloqueados não podem ser arquivados',
   })
   return ctx.can('deal:archive', loaded.deal)              // delega
 }

package/docs/releasing.md

@@ -53,17 +53,21 @@ pra testar publicação seria a guarda atrapalhando quem está experimentando.
 
 **Gate de qualidade**: depois do bump e da materialização, mas antes de publicar, roda
 `pnpm typecheck` + `pnpm test` + `pnpm copy:check` + `base copy check` e **aborta a release
-se qualquer um falhar**. O Opus declara `@softize/base ^2.1.0` em `dependencies`, pois usa
+se qualquer um falhar**. O Opus declara `@softize/base ^2.2.1` em `dependencies`, pois usa
 suas APIs públicas de filesystem em runtime, e materializa os artefatos Base no próprio repo;
 a release não baixa uma política ad hoc. Como o
 Opus **ship source** (`.ts`, sem build), essa é a última barreira antes do tarball — sem ela,
 um `tsc` vermelho, inventário desatualizado ou violação da política vaza pro cliente. Emergência (evite):
 `pnpm release --skip-checks`.
 
+O gate roda `pnpm test`, não `pnpm test:cov`: o threshold de 100% de cobertura em
+`vitest.config.ts` é uma meta aspiracional e **não** faz parte do gate de release. Uma release
+não é bloqueada por cobertura abaixo de 100%; a cobertura é acompanhada com `pnpm test:cov`.
+
 **Smoke do esqueleto**: depois do bump e antes do publish, o `release.sh` gera um app com
 `opus create`, instala o **tarball exato** que vai ser publicado e roda os gates dele
 (typecheck · test · `opus check` · `opus copy --check` · `base copy check` · manifest ·
-build). O template exige `@softize/base ^2.1.0`; publique a Base compatível antes do Opus.
+build). O template exige `@softize/base ^2.2.1`; publique a Base compatível antes do Opus.
 O `minimumReleaseAgeExclude` do template inclui os dois pacotes, e o smoke executa os
 fragmentos de pre-push para provar que o layout pnpm instalado resolve ambos os CLIs.
 É o que pega o que typecheck+test não
@@ -93,6 +97,8 @@ sem `link:`/`file:`, que podem mascarar exports e peers.
 ```bash
 # terminal 1 — uma vez por máquina/sessão
 pnpm registry:up                              # Verdaccio em 127.0.0.1:6873
+# `registry:up` lê `~/.config/verdaccio/config.yaml`, que não é versionado: cada estação
+# mantém o seu, com `listen: 127.0.0.1:6873` (a porta que `release.sh --local` espera).
 
 # terminal 2 — no Opus
 pnpm version 8.7.0-rc.0 --no-git-tag-version # escolha uma versão ainda não publicada

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -202,6 +202,7 @@
     "docs",
     "README.md",
     "CHANGELOG.md",
+    "PROMOTED.md",
     "LICENSE"
   ],
   "publishConfig": {
@@ -259,7 +260,8 @@
     "node-cron": "^3.0.0",
     "pg": "^8.0.0",
     "pino": "^9.0.0",
-    "react": "^18.0.0 || ^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "react-hook-form": "^7.0.0",
     "vite": "^5.0.0 || ^6.0.0",
     "zod": "^3.24.0"
@@ -301,6 +303,9 @@
     "react": {
       "optional": true
     },
+    "react-dom": {
+      "optional": true
+    },
     "vite": {
       "optional": true
     },
@@ -328,7 +333,6 @@
     "@tanstack/react-query": "^5.62.0",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
-    "@types/better-sqlite3": "^7.6.0",
     "@types/jsonwebtoken": "^9.0.0",
     "@types/node": "^22.0.0",
     "@types/node-cron": "^3.0.0",

package/registry/instructions/opus.md

@@ -17,9 +17,9 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
 - Não duplicar schemas, tipos de transporte, validação ou fetch que o contrato já fornece.
 - Em UI semântica, declarar primeiro `context` (`neutral`, `primary`, `info`, `success`, `warning`
   ou `danger`) e usar `variant` somente para o tratamento visual (`solid`, `subtle`, `outline`,
-  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` e variantes
-  semânticas antigas são apenas compatibilidade de migração. `destructive` permanece uma
-  propriedade comportamental de actions e se projeta visualmente como `danger`.
+  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` é apenas
+  compatibilidade de migração e as variantes semânticas antigas não existem mais. `destructive`
+  permanece uma propriedade comportamental de actions e se projeta visualmente como `danger`.
 - Declarar datasets persistentes com `defineSeed` + `bindSeed`, registrá-los em `opus.config.ts`
   e operá-los por `opus seed`; não criar comandos de seed paralelos nem reset implícito.
 - Regenerar o inventário com `opus copy` quando mudar copy em contrato ou componente Opus

package/registry/templates/app/package.json

@@ -30,7 +30,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@softize/base": "^2.1.0",
+    "@softize/base": "^2.2.1",
     "@tailwindcss/vite": "^4.1.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",

package/registry/templates/app/src/App.tsx

@@ -1,5 +1,5 @@
 import type { z } from 'zod'
-import { Badge, Card, useListAction } from '@softize/opus/ui/react'
+import { Badge, Card, DataState, useListAction } from '@softize/opus/ui/react'
 import { Task, taskList } from './domains/tasks/actions/list.ts'
 
 type TaskItem = z.infer<typeof Task>
@@ -10,7 +10,7 @@ export function App(): React.ReactElement {
   // O front consome o CONTRATO via /api — o plugin opusDesign (vite.config.ts)
   // serve o backend no próprio dev server: dev normal executa o handler real;
   // `pnpm dev:design` responde com o mockHandler, isolado de qualquer backend.
-  const { items, isLoading } = useListAction<TaskItem>(taskList)
+  const { items, isLoading, error, refetch } = useListAction<TaskItem>(taskList)
 
   return (
     <main className="flex min-h-full items-center justify-center bg-background p-6">
@@ -19,9 +19,14 @@ export function App(): React.ReactElement {
         <p className="mb-4 text-sm text-muted-foreground">
           Esqueleto criado pelo opus create. A spec vive nas declarações do domínio.
         </p>
-        {isLoading ? (
-          <p className="text-sm text-muted-foreground">Carregando…</p>
-        ) : (
+        {/* Carregando, erro e vazio saem do DataState; a lista só cuida dos itens. */}
+        <DataState
+          loading={isLoading}
+          error={error ?? null}
+          empty={items.length === 0}
+          emptyMessage="Nenhuma tarefa ainda."
+          onRetry={() => refetch()}
+        >
           <ul className="space-y-2">
             {items.map((t) => (
               <li key={t.id} className="flex items-center justify-between gap-2 text-sm">
@@ -30,7 +35,7 @@ export function App(): React.ReactElement {
               </li>
             ))}
           </ul>
-        )}
+        </DataState>
       </Card>
     </main>
   )

package/registry/templates/app/src/main.tsx

@@ -1,13 +1,13 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { TbdlibProvider, TooltipProvider } from '@softize/opus/ui/react'
+import { OpusProvider, TooltipProvider } from '@softize/opus/ui/react'
 import { fetchClient } from '@softize/opus/client/fetch'
 import { App } from './App.tsx'
 import './index.css'
 
 // O trio de providers do padrão da casa — os hooks (useTriggerAction/useFormAction…)
-// exigem QueryClient + Tbdlib, e qualquer Tooltip da base exige o TooltipProvider.
+// exigem QueryClient + OpusProvider, e qualquer Tooltip da base exige o TooltipProvider.
 const queryClient = new QueryClient()
 // Same-origin (/api). Quando o app ganhar server próprio, aponte o baseUrl pra ele.
 const client = fetchClient({ baseUrl: '' })
@@ -15,11 +15,11 @@ const client = fetchClient({ baseUrl: '' })
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
     <QueryClientProvider client={queryClient}>
-      <TbdlibProvider client={client}>
+      <OpusProvider client={client}>
         <TooltipProvider>
           <App />
         </TooltipProvider>
-      </TbdlibProvider>
+      </OpusProvider>
     </QueryClientProvider>
   </StrictMode>,
 )

package/src/audit/drivers/console.ts

@@ -40,6 +40,7 @@ export interface ConsoleAuditOptions {
   redact?: (value: unknown) => unknown
 }
 
+/** Sink de auditoria que imprime cada registro no console, com redação opcional de campos sensíveis. */
 export function consoleAudit(options: ConsoleAuditOptions = {}): AuditSink {
   const {
     format = defaultFormat(),

package/src/auth/drivers/better-auth.ts

@@ -40,6 +40,7 @@ export interface BetterAuthDriverOptions {
 
 const denyAll: CanFn = () => false
 
+/** AuthAdapter que valida a sessão no IdP better-auth (`/api/auth/get-session`) com o cookie da request. */
 export function betterAuthSession(options: BetterAuthDriverOptions): AuthAdapter {
   const { baseURL, mapUser, mapTenant, can, timeoutMs = 5000, name = 'better-auth' } = options
   const base = baseURL.replace(/\/+$/, '')

package/src/auth/drivers/jwt.ts

@@ -79,6 +79,7 @@ export interface JwtAuthOptions<P extends JwtPayload = JwtPayload> {
 // Adapter factory
 // =============================================================================
 
+/** AuthAdapter que verifica um JWT (Bearer) e projeta o payload em `User` + `can`. */
 export function jwtAuth<P extends JwtPayload = JwtPayload>(
   options: JwtAuthOptions<P>,
 ): AuthAdapter {

package/src/cache/drivers/memory.ts

@@ -31,6 +31,7 @@ export interface MemoryCache extends CacheAdapter {
   size(): number
 }
 
+/** CacheAdapter em memória do processo, com TTL por entrada e limite opcional de itens; adequado a dev e testes. */
 export function memoryCache(options: MemoryCacheOptions = {}): MemoryCache {
   const entries = new Map<string, Entry>()
   const maxEntries = options.maxEntries ?? 10_000

package/src/client/drivers/fetch.ts

@@ -50,6 +50,7 @@ export interface FetchClientOptions {
 // Adapter factory
 // =============================================================================
 
+/** ClientAdapter que chama actions via HTTP `fetch`, classificando falhas de transporte como `dependency`. */
 export function fetchClient(options: FetchClientOptions): ClientAdapter {
   const {
     baseUrl,
@@ -92,7 +93,7 @@ export function fetchClient(options: FetchClientOptions): ClientAdapter {
           error({
             code: 'client.network',
             category: 'dependency',
-            message: 'Network request failed',
+            message: `Falha de rede ao chamar ${action.name}`,
             cause: String(cause),
           }),
         )

package/src/core/actions.ts

@@ -1,9 +1,14 @@
 /**
- * tbdlib — `defineAction` factory + type guards
+ * Opus — `defineAction` factory + type guards
  *
  * `defineAction` é identity function tipada que aceita qualquer variante
  * de `ActionDef` e preserva o subtipo exato pra type narrowing posterior.
  *
+ * Quando cliente e servidor consomem a mesma action, o caminho canônico é
+ * `defineContract` (parte compartilhável) + `bindAction` (handler, loads e o
+ * resto server-only) — ver `contracts.ts`. `defineAction` continua válido e
+ * suportado para action server-only, em que não há contrato a compartilhar.
+ *
  * Validação estrutural acontece no `Runtime.register()`, não aqui. Esta função
  * é puramente sobre **declaração**.
  *

package/src/core/audit.ts

@@ -1,5 +1,5 @@
 /**
- * tbdlib — AuditEmitter
+ * Opus — AuditEmitter
  *
  * Classe que coordena a emissão de `AuditRecord` pros `AuditSink` registrados.
  * Aplica config da action (redact, fields, severity, sink filter) antes de
@@ -71,11 +71,17 @@ export class AuditEmitter {
     if (failures.length === 0) return
 
     if (this.mode === 'strict') {
+      this.log.error('audit sinks failed (strict mode)', {
+        failures: failures.length,
+        total: targetSinks.length,
+        reasons: failures.map((f) => String(f.reason)),
+      })
       throw error({
         code: 'audit.sink.failed',
         category: 'internal',
-        message: `${failures.length}/${targetSinks.length} audit sinks failed`,
-        meta: { failures: failures.map((f) => String(f.reason)) },
+        message: `${failures.length} de ${targetSinks.length} sinks de auditoria falharam`,
+        // Só o número vai à wire; o motivo cru de cada sink fica no log do servidor.
+        meta: { failures: failures.length },
       })
     }