@softize/opus 8.6.6

package/bin/lib/mcp.mjs

@@ -0,0 +1,85 @@
+/**
+ * opus mcp — server MCP que expõe a base ao agente: introspecção (fonte única) +
+ * a régua (opus check) + o gerador (create-action). Os agentes apontam pra cá via
+ * `mcp_config`. Embrulha os engines já testados (introspect/check/scaffold).
+ *
+ * Tools:
+ *   opus_introspect      — modelo da estrutura + wiring (o que existe, ao vivo)
+ *   opus_check           — valida convenções (findings)
+ *   opus_create_action   — gera o esqueleto canônico de uma action
+ *   opus_list_components — catálogo da UI (o que existe, quando usar, o que importar)
+ *   opus_get_component   — detalhe de um componente pelo nome
+ */
+
+import path from 'node:path'
+import { z } from 'zod'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { introspect } from './introspect.mjs'
+import { scanDir } from './check.mjs'
+import { actionTemplate } from '../../registry/skills/create-action/scaffold.mjs'
+import { listComponents, getComponent } from './components.mjs'
+
+const asText = (data) => ({
+  content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
+})
+const dirOf = (d) => path.resolve(process.cwd(), d ?? '.')
+
+/** 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' })
+
+  server.registerTool(
+    'opus_introspect',
+    {
+      description: 'Modelo da estrutura do projeto Opus: actions/reactions/schedules + wiring (causalidade).',
+      inputSchema: { dir: z.string().optional() },
+    },
+    async ({ dir }) => asText(await introspect(dirOf(dir))),
+  )
+
+  server.registerTool(
+    'opus_check',
+    {
+      description: 'Valida as convenções das actions (régua) — defineAction e o split defineContract+bindAction: naming, kind, ordem dos campos, export, requires-sem-authorize. Retorna findings.',
+      inputSchema: { dir: z.string().optional() },
+    },
+    async ({ dir }) => asText(await scanDir(dirOf(dir))),
+  )
+
+  server.registerTool(
+    'opus_create_action',
+    {
+      description: 'Gera o esqueleto canônico de uma opus action (passa no opus check por construção).',
+      inputSchema: {
+        resource: z.string(),
+        verb: z.string(),
+        kind: z.enum(['simple', 'form', 'list', 'view']).optional(),
+      },
+    },
+    async ({ resource, verb, kind }) => asText(actionTemplate({ resource, verb, kind })),
+  )
+
+  server.registerTool(
+    'opus_list_components',
+    {
+      description:
+        'Catálogo da UI do Opus: cada componente com altitude, quando-usar, o que importar e as variantes (cva: variant/size + defaults). Use antes de criar UI na mão (evita reinventar primitivo que já existe ou chutar variante).',
+      inputSchema: {},
+    },
+    async () => asText(await listComponents()),
+  )
+
+  server.registerTool(
+    'opus_get_component',
+    {
+      description: 'Detalhe de um componente da UI pelo nome canônico (ex.: button, dropdown-menu).',
+      inputSchema: { name: z.string() },
+    },
+    async ({ name }) => {
+      const c = await getComponent(name)
+      return asText(c ?? `Componente "${name}" não existe. Use opus_list_components pra ver o catálogo.`)
+    },
+  )
+
+  return server
+}

package/bin/lib/postinstall.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * postinstall do @softize/opus — auto-bootstrap: roda `opus setup` no projeto
+ * consumidor assim que a base é instalada. Assim a DEPENDÊNCIA é o sinal: quem
+ * adiciona @softize/opus já nasce conhecendo a base, sem precisar saber do init.
+ *
+ * Blindagem (best-effort, NUNCA falha o install):
+ *   • OPUS_SKIP_INIT=1            → pula
+ *   • projeto = INIT_CWD (onde o install rodou); fallback cwd
+ *   • pula o próprio repo do Opus (dev do pacote)
+ *   • só roda se o consumidor tem @softize/opus nas deps (evita repo aleatório)
+ *
+ * Nota pnpm: por segurança o pnpm NÃO roda build scripts de dependência por
+ * padrão — o consumidor precisa allowlistar (`pnpm.onlyBuiltDependencies:
+ * ["@softize/opus"]`) ou aprovar. Sob npm roda direto.
+ */
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { initProject } from './init.mjs'
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const REGISTRY_DIR = path.join(PACKAGE_ROOT, 'registry')
+
+async function main() {
+  if (process.env.OPUS_SKIP_INIT) return
+
+  const projectDir = process.env.INIT_CWD || process.cwd()
+  // Não inicializa o próprio Opus.
+  if (projectDir === PACKAGE_ROOT || projectDir.startsWith(PACKAGE_ROOT + path.sep)) return
+
+  let pkg
+  try {
+    pkg = JSON.parse(await fs.readFile(path.join(projectDir, 'package.json'), 'utf-8'))
+  } catch {
+    return // Sem package.json → não é projeto.
+  }
+  if (pkg.name === '@softize/opus') return
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) }
+  if (!deps['@softize/opus']) return // Não é consumidor da base.
+
+  const r = await initProject(REGISTRY_DIR, projectDir)
+  const n = r.created.length + r.synced.length
+  console.log(
+    `\x1b[36m[opus]\x1b[0m base v${r.version} — ${r.wasInitialized ? 'sincronizada' : 'inicializada'}` +
+      (n ? ` (${n} arquivo(s))` : '') +
+      `. Veja CLAUDE.md / opus.json.`,
+  )
+}
+
+main().catch((e) => {
+  // O postinstall jamais derruba o install.
+  console.log(`\x1b[33m[opus]\x1b[0m init pulado: ${e?.message ?? e}`)
+})

package/docs/chat-event-protocol.md

@@ -0,0 +1,85 @@
+# Proposta: protocolo de eventos de conversa (streaming no `<Chat>` e na camada ai)
+
+> **Status: APROVADO pelo João e IMPLEMENTADO (2.22.0).** Desenho da issue
+> [softize-dev/opus#5](https://github.com/softize-dev/opus/issues/5). Implementação:
+> `ChatEvent` no core, `runStream` no driver anthropic e no `BoundAi`, `<Chat>` consumindo
+> os dois modos (docs vivas ai/chat atualizadas; 3 testes novos).
+
+## O problema
+
+A casa tem três chats artesanais com o mesmo contrato implícito e três implementações:
+
+| Consumidor | Transporte | O que precisa expressar |
+|---|---|---|
+| ChatRail do Maestro | SSE (replay idempotente, heartbeat) | texto incremental · tool em uso · fim de turno |
+| Vetra BI (bi-poc) | SSE (fetch stream) | texto incremental · tool em uso · **artefato** (card de relatório) · fim de turno |
+| Copilot / `<Chat>` atual | request/response | resposta inteira |
+
+O `<Chat>` (2.17) só fala o terceiro caso (`send(messages) => Promise<string>`), então os
+outros dois reimplementam bolha, indicador e transporte por fora — o mesmo filme do
+AppShell antes do 2.21.0. A doc do ai layer já previa: *"streaming entra quando um caso
+real cobrar"*. Cobrou duas vezes.
+
+## O contrato proposto
+
+O evento de conversa — o mínimo que os dois casos reais exigiram, nada além:
+
+```ts
+export type ChatEvent =
+  /** Texto incremental do agente (acumula na mensagem corrente). */
+  | { type: 'text'; delta: string }
+  /** Tool em uso — dado cru; a apresentação (humanizar, agrupar) é do componente. */
+  | { type: 'tool'; name: string; detail?: string }
+  /** Artefato produzido na conversa (relatório, arquivo, url) — render é do app. */
+  | { type: 'artifact'; kind: string; ref: string; title?: string }
+  /** Fim do turno. */
+  | { type: 'done'; ok: boolean; error?: string }
+```
+
+E o `send` do `<Chat>` vira uma união — **o contrato atual é o caso degenerado**:
+
+```ts
+type SendResult = Promise<string> | AsyncIterable<ChatEvent>
+// Promise<string> ≡ [{ type: 'text', delta: s }, { type: 'done', ok: true }]
+```
+
+## Decisões de desenho (e porquês)
+
+1. **`tool` cru, humanização no componente.** Maestro e Vetra BI humanizam o nome
+   ("Lendo o projeto…"); é apresentação, não dado. O `<Chat>` traz o `humanizeTool`
+   default (pt-BR, o do ChatRail) e aceita override por prop. O protocolo não opina.
+2. **Tool NÃO entra no transcript.** Convenção provada nos dois consumidores: eventos
+   `tool` alimentam o indicador vivo (pontinhos + rótulo), não viram mensagem. O
+   transcript é o que foi dito; a atividade é estado transiente.
+3. **`artifact` é aberto e o render é do app.** O componente não conhece "relatório
+   Evidence" — recebe `renderArtifact?: (a) => ReactNode` e um fallback (link). O card
+   com iframe da Vetra BI é um `renderArtifact` do app.
+4. **Transporte fora do contrato.** SSE, fetch stream, WebSocket: problema do app —
+   o `send` devolve o iterável e pronto. Em particular, **replay/reconexão continua do
+   transporte** (a lição do ChatRail — replay idempotente, buffer até `synced` — vive na
+   camada SSE do app; o `<Chat>` recebe `history` pronto + eventos do turno vivo).
+   Sobe pro componente só se um segundo caso real cobrar.
+5. **A camada ai ganha a variante streaming, aditiva.** `run()` permanece;
+   `runStream(input, opts): AsyncIterable<ChatEvent>` mapeia o loop agêntico no
+   protocolo (tool call → `tool`; texto → `text`; confirmação destrutiva segue o
+   contrato atual). O `chatRoute` canônico da doc passa a poder streamar (SSE) e o
+   `<Chat>` consumi-lo — o Copilot migra quando quiser, sem quebrar.
+6. **Nada quebra.** `send` atual compila e funciona igual (união). O `<Chat>` novo é o
+   mesmo componente com mais um modo, não um componente novo.
+
+## Não-objetivos (por ora)
+
+Memória longa/resumo de conversa, multi-agente na mesma sala, persistência de
+transcript no componente, replay no componente — sem caso real maduro; entram pela
+régua quando cobrarem.
+
+## Mapa de migração (depois do contrato pronto)
+
+| De | Para |
+|---|---|
+| `bi-poc/app/components/chat-rail.tsx` | `<Chat send={streamTurn} renderArtifact={ReportCard} …/>` |
+| ChatRail do Maestro (App.tsx ~1376) | idem, mantendo a camada SSE/replay do app como transporte |
+| Copilot | inalterado; opcionalmente `runStream` no backend quando quiser streaming |
+
+Doadores de implementação: indicador/humanização e disciplina de replay do ChatRail;
+`renderArtifact` e o mapeamento de eventos da Vetra BI.

package/docs/code-style.md

@@ -0,0 +1,16 @@
+---
+title: Code style
+order: 5
+---
+
+# Code style — padrão softize
+
+> **A fonte desta regra migrou pro admin** (metodologia 12/06/2026): skill `code-style`,
+> vinculada a todos os papéis e materializada em `.claude/skills/code-style/SKILL.md`
+> via `maestro pull`. Edite LÁ (aba Skills do admin) — este arquivo é só o ponteiro.
+
+Resumo de uma linha: **código em inglês; o que humano lê (UI, comentário, doc) em pt-BR;
+frases com maiúscula e ponto; labels curtos sem ponto.**
+
+O que dá, é regra executável no `opus check` (naming `<resource>.<verb>`, ordem dos
+campos do spec, registro no runtime); o resto vive na skill.

package/docs/data-layer.md

@@ -0,0 +1,246 @@
+---
+title: Camada de dados
+order: 2
+---
+
+# Camada de dados — decisão e contrato
+
+> Decisão (jun/2026). Fecha uma deliberação longa sobre engine de DB, fonte do
+> schema e migrations. Doc em pt-BR. Complementa a §15 (Entidades) do
+> `protocol.md`.
+
+## Decisão
+
+| Eixo | Escolha |
+|---|---|
+| **Engine de query** | **Kysely** (multi-banco, MSSQL incluso, já em prod no `admin/api`) |
+| **Fonte do schema** | **`defineEntity`** (única; ver §15) |
+| **Rodar migration** | **`Migrator` nativo do Kysely** |
+| **Escrever migration** | **`up/down` à mão** (scaffold de rascunho opcional) |
+| **Garantir sync** | **drift-check** — comparador read-only sobre a introspecção do Kysely |
+| **Auto-gen de migration** | **opt-in futuro** (drizzle-kit ou Atlas), mesmo `entityColumns` |
+
+**Stack = Kysely + a camada opus. Zero tooling estrangeiro, uma dep só (`kysely`).**
+
+## Por que não…
+
+- **Drizzle como engine** — ele quer **ser** o schema (a `pgTable`); isso cede a
+  fonte única (perde o tipo lógico que dirige UI/validação/OpenAPI/DB de uma só
+  declaração) e o swap de engine. O `defineEntity` fica por cima como declaração;
+  Drizzle no máximo seria um *materializador* opt-in.
+- **Differ próprio** (introspecção → ALTERs) — é **possuir um engine de migration**
+  (contra o §9). A gente possui só um **comparador** read-only, que é trivial e
+  seguro perto de gerar ALTERs corretos.
+- **drizzle-kit / Atlas como base** — drizzle-kit arrasta uma 2ª representação de
+  schema (a `pgTable`, mesmo gerada) + dep `drizzle-orm`; Atlas é binário Go no
+  toolchain. Viram **aceleradores opt-in** (mesmo `entityColumns` de entrada),
+  não a base.
+
+## O contrato
+
+```
+defineEntity ──► entityColumns(entity)         # colunas resolvidas (id auto, timestamps, deletedAt)
+                   │
+                   ├─► desiredColumns(entity)   # shape normalizado pro diff
+                   │
+   db (Kysely) ──► db.introspection.getTables() # shape real do banco
+                   │
+                   └─► diffColumns(table, desired, actual) ─► DriftFinding[]
+                            ▲
+              kyselyDriftCheck(db, entities)    # cola tudo; roda no `opus check`
+```
+
+- **`entityColumns(entity)`** (já existe) — colunas resolvidas + injetadas.
+- **`desiredColumns(entity)`** — `{ name, nullable }[]` derivado de `entityColumns`.
+- **`diffColumns(table, desired, actual)`** — **puro**, sem Kysely. Retorna
+  `DriftFinding[]` (`missing_table`, `missing_column`, `extra_column`,
+  `nullable_mismatch`). É o núcleo testável.
+- **`kyselyDriftCheck(db, entities)`** — bind fino: introspecta via Kysely e roda
+  o differ puro por tabela.
+
+## CLI: grupo `db` (separado do `opus check`)
+
+O `opus check` é **estático puro** (source-only, sem banco). O drift-check precisa
+de conexão + entidades carregadas — natureza diferente. Então vive num **grupo
+próprio**, `opus db <verbo>` (não estufa o `check`):
+
+```
+opus db check         # drift-check (entidade ↔ banco) — read-only, exit ≠ 0 se divergir
+opus db migrate       # aplica o SCHEMA IDEMPOTENTE + drift-check na sequência
+opus db scaffold      # gera rascunho a partir do diff (referência pro schema)
+```
+
+**Schema idempotente evolutivo** (o padrão da casa, não migration versionada): UM
+script SQL (`config.schema`, ex. `src/db/schema.sql`) re-rodável — `CREATE IF NOT
+EXISTS` + guards `DO $$ IF EXISTS` cobrem nascer do zero E upgrade de prod no mesmo
+artefato. Não existe `migrate down`: rollback = editar o script e re-rodar
+(catástrofe = snapshot pré-deploy). Upgrades já absorvidos por todos os ambientes
+podem ser podados do script. Depois de aplicar, o `migrate` roda o drift-check na
+mesma conexão — migrou mas diverge das entidades é estado quebrado que o deploy
+precisa ver na hora (exit ≠ 0). (A era Kysely Migrator foi aposentada: DDL `.ts`
+gerava identificadores camelCase errados e o formato nunca pegou.)
+
+O `db scaffold` roda o drift-check e emite `migrations/<ts>_scaffold.ts`: gera os
+casos **limpos** (tabela/coluna nova) e sinaliza como `// TODO` os **arriscados**
+(nullable/drop, dialect-específicos). É **referência** pra escrever o SQL no
+schema — a verdade é o script; revise à mão.
+
+Os comandos `db` carregam o `opus.config.ts` via `tsx` num runner isolado (mesma
+infra do `gen`, não a do `check`). Contrato do config **pros comandos `db`**:
+
+```ts
+export default {
+  domains: [...],                       // entidades coletadas de domain.models
+  entities: [Deal, Company],            // ou explícitas (opcional)
+  schema: './src/db/schema.sql',        // o script idempotente (default: ./db/schema.sql)
+  database: () => new Kysely({ ... }),  // factory LAZY do banco
+}
+```
+
+`database` é **factory, não instância**, de propósito: o `gen` importa o mesmo
+config e **nunca chama** `database()`, então não abre conexão. Só os comandos `db`
+chamam. CI compõe: `opus check && opus db check`.
+
+## Fluxo do dev
+
+1. Escreve/edita a entidade (`defineEntity`).
+2. Evolui o **schema idempotente** (SQL, com guards) — o scaffold rascunha o diff
+   como referência quando ajuda.
+3. `opus db migrate` aplica e já cobra o **drift-check**: se o banco divergir do
+   `defineEntity`, **falha** — o script e a entidade nunca silenciam um drift.
+
+## Uso ponta a ponta
+
+### 1. Entidade
+```ts
+// src/domains/deals/deal.entity.ts
+import { defineEntity, belongsTo } from '@softize/opus/schema'
+import { t } from '@softize/opus/schema/zod'
+
+export const Deal = defineEntity({
+  name: 'deal',
+  fields: {
+    title:   t.string(),
+    amount:  t.money(),
+    status:  t.enum(['open', 'won', 'lost']).default('open'),
+    ownerId: t.uuid(),
+    notes:   t.text().nullable(),
+  },
+  relations: { owner: belongsTo('user', { from: 'ownerId' }) },
+  timestamps: true,
+  softDelete: true,
+})
+```
+
+### 2. Config (uma vez)
+```ts
+// opus.config.ts
+import { Kysely, PostgresDialect, CamelCasePlugin } from 'kysely'
+import { Deal } from './src/domains/deals/deal.entity.ts'
+
+export default {
+  entities: [Deal],          // ou domains: [...] (entidades via domain.models)
+  naming: 'snake',           // colunas snake no banco
+  migrations: './migrations',
+  database: () => new Kysely({
+    dialect: new PostgresDialect({ pool }),
+    plugins: [new CamelCasePlugin()],   // backend camel ↔ banco snake
+  }),
+}
+```
+
+### 3. Schema
+```bash
+opus db scaffold     # rascunha o diff (referência pro SQL — revise!)
+opus db migrate      # aplica o schema idempotente + drift-check
+opus db check        # gate read-only: banco == entidade
+```
+
+### 4. CRUD instantâneo
+```ts
+import { crudActions } from '@softize/opus/data/kysely'
+
+// gera deal.view/create/update/delete/search (só as ops com authorize)
+export const dealActions = crudActions(Deal, {
+  view:   (ctx) => ctx.can('deal:read'),
+  create: (ctx) => ctx.can('deal:create'),
+  update: (ctx) => ctx.can('deal:update'),
+  delete: (ctx) => ctx.can('deal:delete'),
+  search: (ctx) => ctx.can('deal:read'),
+})
+// runtime.register(Object.values(dealActions))
+```
+
+### 5. Handler com lógica própria
+```ts
+import { defineAction } from '@softize/opus'
+import { kyselyRepo } from '@softize/opus/data/kysely'
+
+defineAction({
+  name: 'deal.win', kind: 'simple',
+  input: z.object({ id: t.uuid().zod() }),
+  output: entityRowSchema(Deal),
+  authorize: (ctx) => ctx.can('deal:update'),
+  handler: (ctx, input) => kyselyRepo(ctx.db, Deal).update(input.id, { status: 'won' }),
+})
+```
+
+## Naming (camel ↔ snake)
+
+O backend é **100% camelCase** (TS idiomático); o snake_case mora só no banco. Quem
+faz a ponte é o **`CamelCasePlugin` do Kysely** — ele reescreve query e DDL
+(`ownerId` → `owner_id`) na ida e os resultados na volta. Repo/scaffold/crud do Opus
+escrevem camel e **não tocam no assunto**.
+
+A exceção é a **introspecção** (`db.introspection.getTables()`): ela volta os nomes
+**crus** (snake), fora do plugin. Por isso o **drift-check** é o único ponto que o
+opus mapeia — ele aplica a `naming` no schema desejado antes de comparar.
+
+```ts
+// opus.config.ts
+export default {
+  naming: 'snake',                                   // default; 'identity' | fn custom
+  database: () => new Kysely({
+    dialect,
+    plugins: [new CamelCasePlugin()],                // OBRIGATÓRIO p/ naming: 'snake'
+  }),
+}
+```
+
+> **Footgun auto-denunciado:** se esquecer o `CamelCasePlugin`, o repo cria colunas
+> camelCase; o drift-check (snake) não bate → `db check` **falha** e mostra o erro.
+> A consistência é garantida pelo gate, não pela disciplina.
+
+## Limitações conhecidas (refinar depois)
+
+- **Nível-coluna:** o drift-check compara **presença + nullable**. Tipos, defaults,
+  índices, FKs e check constraints ficam pra um passo 2 (queries `pg_catalog` via
+  `sql` do Kysely — ainda tudo-JS).
+- **Drift de índices/FK** ainda fora (só colunas).
+
+## Sequência de construção
+
+1. ✅ `entityColumns` (§15).
+2. ✅ `diffColumns` (puro) + `desiredColumns` + `kyselyDriftCheck`.
+3. ✅ Grupo CLI `db` + `opus db check` (carrega config via tsx, factory `database()`).
+4. ✅ `kyselyRepo(db, entity)` — CRUD tipado (insert/findById/update/remove/list),
+   gera id (pk auto), preenche timestamps, respeita soft-delete. Falta o açúcar
+   `ctx.repo(Entity)` (wiring na ActionContext).
+5. ✅ `opus db migrate` — schema idempotente evolutivo (SQL, config `schema`) + drift-check
+   embutido. (A 1ª versão era Kysely Migrator; aposentada — o formato nunca pegou.)
+6. ✅ `opus db scaffold` (rascunho `up/down` do diff; casos limpos gerados, riscos viram `// TODO`).
+7. ✅ Composição (Opção D — sem tocar o core): schema builders
+   (`entityRowSchema`/`entityInsertSchema`/`entityUpdateSchema`) + `crudActions(entity,
+   {authorize})` no driver Kysely. Decisão: `entity:` no `defineAction` e `ctx.repo`
+   no `ActionContext` puxariam tipos de entidade pro core (ciclo schema↔core) — então
+   a composição vive onde core+schema convivem; usa-se `crudActions` / `kyselyRepo(ctx.db, E)`.
+8. ✅ `crudActions` + `kyselyRepo` para `search` (paginação offset + filtros de igualdade →
+   `Paginated`). CRUD completo: view/create/update/delete/search.
+9. ✅ `NamingStrategy` (camel↔snake) — **decisão: `CamelCasePlugin` do Kysely é dono do
+   mapeamento de query/DDL** (backend 100% camel; snake só no banco). O Opus snakeia
+   **só o drift-check** (a introspecção volta crua, fora do plugin). Default `snake`;
+   config em `opus.config.ts` (`naming`). Repo/scaffold/crud ficam camel, intocados.
+   Esquecer o plugin → o `db check` falha e expõe (footgun auto-denunciado).
+10. Aprofundar o drift (índices/FK/tipos/defaults).
+11. Cursor pagination + `FilterSpec` ricos no search (hoje offset + igualdade).
+12. (Opt-in) drivers de auto-gen: drizzle-kit / Atlas.

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

@@ -0,0 +1,102 @@
+# Ownership dos componentes: "it's ours" POR CONTATO (decidido)
+
+> **Status: DECIDIDO (João, jul/2026).** O modelo é o "afrouxar" da seção final, com uma
+> regra simples de transição: **tocar = assumir**.
+
+## A decisão
+
+1. **Tocar um componente quebra o vínculo — e tudo bem.** Qualquer opinião da casa num
+   componente `locked` o ejeta sem cerimônia nem culpa: vira `ejected` (nosso), com o
+   delta documentado no lock. É o caminho abençoado, não a exceção.
+2. **A referência ao original FICA.** `source` + `upstreamHash` permanecem no lock como
+   memória de origem — pra IA garimpar o shadcn quando valer (merge de 3 vias sob
+   demanda: base gravada → shadcn atual → nosso). Referência, não contrato.
+3. **Componente nunca tocado segue "isn't ours" por ora.** `locked` + hash-gate ativos
+   até o primeiro toque — o QA de graça do shadcn continua valendo onde a casa ainda não
+   tem opinião.
+4. Com o tempo, a biblioteca inteira converge pra "ours" naturalmente, pelo uso — sem
+   big-bang, sem cerimônia de virada.
+
+## Princípio irmão: sobrescrita sancionada
+
+Sobrescrever um default do Tailwind/shadcn é legítimo quando **declarado** num dos dois
+registros — o header de DIVERGÊNCIAS do `theme.css` (valores de token) ou o delta do
+`registry.lock.json` (componentes ejetados). Nunca sobrescrever a **mecânica** (utilitário
+mantém o significado documentado; preferir namespace próprio, como a elevação
+`shadow-card/popover/dialog`). O que não está declarado é drift.
+
+---
+
+*O histórico abaixo é o contexto que levou à decisão.*
+
+## O que está em jogo
+
+Hoje o `opus/ui` é **shadcn-native**: cada primitivo é byte-fiel ao registry do shadcn,
+com hash no `registry.lock.json` e um gate (`tests/ui/lock.test.ts`) que reprova se
+alguém editar um `locked` à mão. Customização da casa vai **por fora** (theme/cva/
+wrapper) ou o componente é **ejected** (assumido, delta documentado, fora do hash-check).
+
+A proposta é **inverter o default**: os componentes passam a ser **nossos** por padrão;
+o shadcn vira a **origem documentada** e uma **referência** de onde puxar melhorias quando
+valer — não um contrato de identidade byte-a-byte.
+
+## O gatilho (por que isto veio à tona)
+
+Ao deixar os controles "flat" (sem `shadow-xs`), a primeira tentativa foi neutralizar o
+token no tema: `--shadow-xs: 0 0 #0000`. Isso **mente sobre o que a variável contém** —
+um token de escala redefinido pra "nada" — só pra **não editar 16 componentes locked**.
+O lock empurrou a solução pra uma desonestidade. Corrigido na 2.20.1 (a sombra saiu de
+dentro dos componentes; os 14 byte-fiéis viraram `ejected`).
+
+A lição, do João: **honestidade da abstração > conveniência de sync.** Mentir num token
+é pior do que desvincular componentes. O sync é conveniência de menor prioridade.
+
+## O que o lock compra e custa
+
+**Compra:** QA de graça (a11y/teclado/Radix do shadcn), disciplina anti-drift, proveniência
+("nossos primitivos SÃO o shadcn"), re-sync barato por hash-diff.
+
+**Custa:** imposto interpretativo em toda opinião da casa ("posso tocar isso? theme? cva?
+ejetar?") — e, como o episódio da sombra mostrou, empurra pra contorções desonestas pra
+respeitar o lock. Um design system existe pelas suas opiniões; alugar os primitivos de um
+upstream com quem se tem que ficar idêntico atrita com ter opinião.
+
+## A proposta
+
+1. **Dropar o contrato de hash.** O `lock.test` deixa de reprovar edição; no máximo vira
+   advisory. Componentes são editados livremente, com honestidade (a intenção mora no
+   componente, não num token esvaziado).
+2. **O `registry.lock.json` vira ledger de proveniência.** Mantém `upstreamHash` /
+   `source` (qual versão do shadcn cada um forkou = o **merge-base**). Deixa de ser gate,
+   vira memória de origem.
+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).
+
+## Tradeoffs honestos
+
+**A favor:** honestidade (sem mentira-de-token, sem contorção); liberdade de opinião sem
+pedir licença; o `opus/ui` deixa de ser "shadcn com theme" e vira design system próprio de
+verdade. E o re-sync não morre — o merge-de-IA cobre a lacuna que o hash cobria.
+
+**Contra:** a casa passa a **owar a superfície de manutenção** de ~44 componentes (a11y,
+segurança, bumps de Radix) — o shadcn fazia esse trabalho chato de graça. O re-sync vira
+julgamento (merge de IA), não determinismo (hash) → depende de **teste + revisão** pegarem
+um merge torto, e de **alguém iniciar** o pull (não vem passivo pelo CI).
+
+## A pergunta que travava a decisão
+
+**O time (João + agentes) tem banda pra manter os primitivos?** A resposta escolhida foi o
+meio honesto: **afrouxar** em vez de matar — ejeção trivial e abençoada pra qualquer
+opinião (matando a tentação da mentira-de-token), hash mantido só nos que ninguém
+customizou. É exatamente a decisão do topo.
+
+## O que já mudou (2.20.1)
+
+Os 14 controles que usavam `shadow-xs` foram ejetados (flat mora dentro deles agora);
+`ejected` foi de 7 pra 21, `locked` de 44 pra 30. **Isto é a primeira instância concreta
+do "it's ours"** — mas foi escopada só aos controles com `shadow-xs`. A decisão desta
+proposta é se a gente estende isso pra biblioteca inteira e formaliza o modelo acima.