@softize/opus 12.6.3 → 12.7.0

package/docs/adr/0002-structured-seeds-are-declared-and-bound.md

@@ -0,0 +1,130 @@
+# ADR 0002 — Seeds estruturados separam declaração, execução e operação
+
+- Status: aceita
+- Data: 2026-08-25
+
+## Contexto e forças
+
+Projetos consumidores criam dados de desenvolvimento por comandos, scripts e convenções locais.
+O mesmo nome “seed” termina cobrindo usuários de desenvolvimento, demonstrações, datasets e
+fixtures de teste, sem uma forma comum de descobrir dependências, perfis, proteção de ambiente ou
+resultado esperado. Skills conseguem melhorar a experiência humana, mas não substituem uma
+operação determinística que CI e automações possam executar sem um agente.
+
+O contrato precisa:
+
+- manter dados, regras de negócio, conexão e drivers sob responsabilidade do consumidor;
+- oferecer descoberta e execução reproduzível pela CLI;
+- separar metadata compartilhável de implementação server-only;
+- bloquear produção e exigir um escopo de dados explícito antes de qualquer escrita;
+- tornar dependências, perfis e resultados verificáveis;
+- exigir aplicação convergente, sem transformar `apply` em reset implícito;
+- materializar orientação para autoria e operação sem guardar SQL dentro de uma skill;
+- preservar o Opus como protocolo e SDK, sem fazê-lo administrar o ciclo de vida do banco.
+
+## Alternativas consideradas
+
+### Manter scripts e comandos por projeto
+
+É a opção mais barata no SDK, mas conserva descoberta, segurança, nomenclatura e verificação como
+responsabilidades repetidas. O crescimento de cada projeto volta a produzir comandos paralelos e
+contratos implícitos. Rejeitada.
+
+### Executar seeds somente por skills
+
+Entrega uma interface conversacional conveniente, porém torna o comportamento dependente da
+interpretação do agente e dificulta CI, depuração e automação sem agente. Uma skill também não é o
+lugar adequado para persistir SQL ou regras de geração. Rejeitada como mecanismo de execução;
+skills permanecem como clientes da CLI.
+
+### Tratar seed como action do runtime
+
+Reutilizaria parte do pipeline de actions, mas misturaria dados de desenvolvimento com endpoints,
+autorização de pessoas, manifest de produto e ciclo de vida do servidor. Seeds são operações de
+projeto executadas pela CLI, não capacidades expostas pela aplicação. Rejeitada.
+
+### Declarar e vincular seeds em uma superfície própria
+
+Uma declaração pura descreve identidade, versão, perfis, dependências e escopos permitidos. Um
+binding server-only implementa planejamento, aplicação e verificação. O `opus.config.ts` registra
+os bindings, e a CLI os carrega em subprocesso TypeScript. Skills operam essa CLI. Aceita.
+
+## Decisão
+
+O pacote ganha a superfície `@softize/opus/seed` com dois construtores:
+
+- `defineSeed` valida e preserva a declaração compartilhável;
+- `bindSeed` anexa `plan`, `apply` e `verify`, produzindo o registrável server-only.
+
+Uma declaração possui nome estável em lowercase com segmentos separados por ponto, versão inteira
+positiva, descrição, um ou mais perfis, dependências opcionais e `safety.scopes`. Cada perfil pode
+declarar descrição e métricas numéricas esperadas. O binding recebe o perfil escolhido, o escopo
+explícito e a conexão produzida por `config.database()`, quando configurada. Planejamento e
+verificação são obrigatórios; o Opus não considera uma função de escrita isolada um seed completo.
+
+O `opus.config.ts` registra `seeds: SeedRegistryItem[]` no nível do projeto. Seeds não entram em
+`DomainConfig`, no runtime de actions, em OpenAPI nem em endpoints. A CLI oferece:
+
+- `opus seed list` para descoberta sem abrir o banco;
+- `opus seed check` para validar registro, bindings, dependências, ciclos e comandos locais
+  paralelos;
+- `opus seed plan <nome>` para descrever a aplicação sem escrever;
+- `opus seed apply <nome>` para aplicar o perfil convergente;
+- `opus seed verify <nome>` para conferir o estado atual sem escrever.
+
+`plan`, `apply` e `verify` exigem `--scope` ou `OPUS_SEED_SCOPE`. O escopo precisa constar na
+declaração e só pode ser `local`, `test` ou `isolated-preview`. Somente `NODE_ENV=development` e
+`NODE_ENV=test` permitem operações que possam abrir o banco; valor ausente, desconhecido ou
+`production` falha fechado, inclusive em `verify`. `list` e `check` continuam disponíveis porque
+não abrem conexão.
+
+Depois que `database()` abre a conexão, `assertSeedTarget({ database, scope })` precisa atestar o
+destino real antes de qualquer binding. A verificação é obrigatória e server-only porque somente o
+projeto conhece a identidade confiável do próprio banco. Repetir o rótulo informado na CLI ou
+inferir apenas pela URL não constitui atestação. O retorno positivo `true` é parte do protocolo;
+qualquer outro resultado falha fechado.
+
+`apply` é convergente por contrato: repeti-lo com o mesmo perfil deve preservar o mesmo estado
+observável. Reset, truncamento e remoção não fazem parte deste MVP. Um projeto que precise destruir
+dados deverá manter uma operação separada, com autorização explícita, até que recorrência e
+garantias suficientes justifiquem uma primitiva própria.
+
+Dependências são executáveis, não apenas documentais. `plan`, `apply` e `verify` percorrem primeiro
+a clausura de dependências em ordem topológica, com o perfil padrão de cada dependência e o mesmo
+escopo explícito do alvo.
+
+O gate detecta nomes e versões inválidos, perfis vazios, binding incompleto, seed duplicado,
+dependência ausente, ciclo e scripts `seed*` ou `db:seed*` que não deleguem para `opus seed`. Testes
+de integração do consumidor continuam responsáveis por provar idempotência contra seu banco; o
+SDK não provisiona infraestrutura nem tenta inferir equivalência de estado a partir de um driver
+genérico.
+
+O registry distribui duas skills:
+
+- `create-opus-seed`, para criar declaração, binding, registro e testes;
+- `apply-opus-seed`, para descobrir, planejar, aplicar e verificar pela CLI.
+
+As skills não contêm regra de negócio, credencial nem SQL. O resultado estruturado da CLI é a fonte
+que elas usam para relatar métricas.
+
+## Consequências
+
+Consumidores ganham uma porta única e testável sem entregar ao Opus o domínio dos dados. A
+separação adiciona um novo registrável ao `opus.config.ts`, um subprocesso de CLI e um gate
+específico. Projetos precisam migrar comandos existentes e tornar seu escopo de dados explícito.
+
+Como o MVP não possui ledger, `status` significa verificar cada seed, não consultar histórico. Ele
+também não prova idempotência universal: o binding e o teste persistente do consumidor continuam
+responsáveis por essa garantia. Ledger, reset genérico, paralelismo entre seeds e uma interface
+gráfica ficam fora desta decisão até existir uso real suficiente.
+
+## Verificação
+
+- testes unitários de `defineSeed`, `bindSeed` e validação do grafo;
+- testes do runner para listagem sem banco, proteção de escopo e bloqueio de produção;
+- testes da CLI para `list`, `check`, `plan`, `apply` e `verify`;
+- teste do gate contra scripts paralelos e dependências circulares;
+- validação das skills com casos positivo, negativo e de execução;
+- typecheck, suíte do pacote, `opus check` e gates de materialização verdes;
+- adoção posterior em um consumidor real com aplicação repetida e teste persistente de
+  idempotência.

package/docs/protocol.md

@@ -165,7 +165,7 @@ type FieldSpec = {
   order?:       number
   
   // UI override
-  widget?:      string                  // 'text' | 'select' | 'date' | 'rich' | custom
+  widget?:      FieldWidget             // 'textarea' | 'code' | 'lines' | 'refItems' | 'icon' | 'toggle-group'
   
   // Options (select/radio/lookup)
   options?:     OptionsSpec
@@ -174,6 +174,15 @@ type FieldSpec = {
   aiDescription?: string
 }
 
+type FieldWidget =
+  | 'textarea'
+  | 'code'
+  | 'lines'
+  | 'refItems'
+  | 'icon'
+  | 'toggle-group'
+  | string                       // identificador próprio de outro renderer
+
 type OptionsSpec =
   | { kind: 'static',     items: { value: string, label: I18nRef }[] }
   | { kind: 'dictionary', ref: string }                            // catálogo nomeado

package/docs/seeds.md

@@ -0,0 +1,132 @@
+# Seeds estruturados
+
+Seed é um dataset intencional e verificável para desenvolvimento, teste ou demonstração. No
+Opus, ele não é uma action da aplicação nem um script livre: a declaração descreve o que existe e
+o binding server-only sabe planejar, aplicar e verificar esse estado.
+
+Essa separação mantém credenciais, banco e regras de geração no projeto consumidor. A CLI oferece
+uma porta única para pessoas, CI e skills sem transformar o SDK em gerenciador do banco.
+
+## Contrato
+
+```ts
+// src/seeds/customers-scenarios.definition.ts
+import { defineSeed } from '@softize/opus/seed'
+
+export const customersScenariosDefinition = defineSeed({
+  name: 'customers.scenarios',
+  version: 1,
+  description: 'Clientes representativos, incluindo conflitos de identidade.',
+  profiles: {
+    smoke: {
+      description: 'Conjunto mínimo para desenvolvimento diário.',
+      expected: { people: 8, openConflicts: 3 },
+    },
+    volume: {
+      description: 'Volume suficiente para paginação e busca.',
+      expected: { people: 500, openConflicts: 25 },
+    },
+  },
+  defaultProfile: 'smoke',
+  dependsOn: ['foundation.users'],
+  safety: { scopes: ['local', 'isolated-preview'] },
+})
+```
+
+O nome e a versão identificam o dataset. Perfis variam quantidade ou composição sem criar
+comandos paralelos. `expected` declara métricas que `verify` precisa encontrar. Dependências
+precisam estar registradas e não podem formar ciclos. Ao operar um seed, a CLI percorre primeiro
+suas dependências na ordem topológica, usando o perfil padrão de cada uma e o mesmo escopo.
+
+## Binding e registro
+
+```ts
+// src/server/seeds/customers-scenarios.seed.ts
+import type { Kysely } from 'kysely'
+import { bindSeed } from '@softize/opus/seed'
+import { customersScenariosDefinition } from '../../seeds/customers-scenarios.definition.ts'
+import type { Database } from '../database.ts'
+
+export const customersScenariosSeed = bindSeed<Kysely<Database>>(customersScenariosDefinition, {
+  plan: ({ profile }) => ({
+    summary: `Preparar o perfil ${profile}.`,
+    operations: ['Convergir clientes conhecidos', 'Recalcular a projeção de conflitos'],
+  }),
+  apply: async ({ database, profile }) => {
+    const metrics = await convergeCustomerScenarios(database, profile)
+    return { summary: 'Cenários aplicados.', metrics }
+  },
+  verify: async ({ database, profile }) => {
+    const metrics = await inspectCustomerScenarios(database, profile)
+    return { summary: 'Cenários conferidos.', metrics }
+  },
+})
+```
+
+```ts
+// opus.config.ts
+import type { Kysely } from 'kysely'
+import type { SeedTargetAssertion } from '@softize/opus/seed'
+import type { Database } from './src/server/database.ts'
+
+const assertSeedTarget: SeedTargetAssertion<Kysely<Database>> = async ({ database, scope }) => {
+  if (database === null) {
+    throw new Error('A conexão de seed não foi aberta')
+  }
+  const target = await inspectSeedTarget(database)
+  if (target.scope !== scope || target.production) {
+    throw new Error('A conexão não corresponde ao escopo de seed solicitado')
+  }
+  return true
+}
+
+export default {
+  domains,
+  database: createDatabase,
+  assertSeedTarget,
+  seeds: [foundationUsersSeed, customersScenariosSeed],
+}
+```
+
+`apply` deve convergir: duas execuções com o mesmo perfil produzem o mesmo estado observável.
+Use chaves estáveis e upsert/merge explícito no consumidor. Ausência de um registro no perfil não
+autoriza removê-lo; reset, truncate e limpeza genérica não fazem parte deste contrato.
+
+`database()` é lazy. `seed list` e `seed check` não a chamam. Os demais comandos abrem a conexão,
+executam `assertSeedTarget` antes de qualquer binding e sempre tentam encerrá-la com `destroy()`.
+A atestação pertence ao consumidor porque só ele conhece o destino real: consulte metadados do
+banco ou outra identidade confiável da conexão; não compare apenas a URL ou repita o rótulo vindo
+da CLI. A função precisa retornar `true` explicitamente depois da conferência; `false`, `undefined`
+ou ausência de retorno fazem `plan`, `apply` e `verify` falharem fechado. `seed check` não abre a
+conexão nem executa a atestação: ele reprova a ausência da função no contrato de configuração.
+
+## Operação
+
+```bash
+pnpm exec opus seed list
+pnpm exec opus seed check
+pnpm exec opus seed plan customers.scenarios --profile smoke --scope local
+pnpm exec opus seed apply customers.scenarios --profile smoke --scope local
+pnpm exec opus seed verify customers.scenarios --profile smoke --scope local
+```
+
+O escopo também pode vir de `OPUS_SEED_SCOPE`, útil em uma execução isolada de CI. Ele precisa
+constar em `safety.scopes` e só pode ser `local`, `test` ou `isolated-preview`. O escopo não é um nome de
+ambiente inferido pela CLI. `plan`, `apply` e `verify` só abrem conexão quando `NODE_ENV` é
+explicitamente `development` ou `test`.
+
+`--json` entrega o mesmo resultado em formato estruturado. Isso permite que uma skill explique o
+plano e as métricas sem interpretar logs livres.
+
+## Gate
+
+`opus seed check` falha diante de binding incompleto, duplicidade, dependência ausente, ciclo ou
+script `seed*`/`db:seed*` que não delegue para `opus seed`. O gate valida estrutura e segurança;
+o teste persistente do consumidor continua responsável por provar que a aplicação repetida é
+idempotente no banco real.
+
+O manifest inclui somente as declarações. Funções, conexão e implementação do binding nunca são
+serializadas.
+
+Veja a decisão e os limites em
+[ADR 0002](adr/0002-structured-seeds-are-declared-and-bound.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "12.6.3",
+  "version": "12.7.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -149,6 +149,10 @@
       "types": "./src/schema/openapi.ts",
       "default": "./src/schema/openapi.ts"
     },
+    "./seed": {
+      "types": "./src/seed/index.ts",
+      "default": "./src/seed/index.ts"
+    },
     "./server": {
       "types": "./src/server/index.ts",
       "default": "./src/server/index.ts"

package/registry/instructions/opus.md

@@ -2,6 +2,8 @@
 
 <!-- softize-skill-route: $implement-opus-change -->
 <!-- softize-skill-route: $upgrade-opus -->
+<!-- softize-skill-route: $create-opus-seed -->
+<!-- softize-skill-route: $apply-opus-seed -->
 
 Este repo usa `@softize/opus`, um SDK e protocolo de actions. A versão aplicada aos
 artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `opus.json`.
@@ -13,6 +15,8 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
 - Manter contrato compartilhável separado de banco, segredo e driver server-only; usar
   `defineContract` com `bindAction` quando cliente e servidor consomem a mesma action.
 - Não duplicar schemas, tipos de transporte, validação ou fetch que o contrato já fornece.
+- 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
   mapeado; o Opus classifica os papéis semânticos e a política universal de `@softize/base`
   valida o conteúdo.

package/registry/skills/apply-opus-seed/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: apply-opus-seed
+description: Opera seeds Opus estruturados com descoberta, gate, plano, aplicação e verificação em escopo isolado. Use quando a pessoa pedir para popular ou atualizar dados de desenvolvimento, demonstração ou teste já registrados no opus.config.ts.
+---
+
+# Aplicar seed Opus
+
+## Resultado
+
+Aplicar o perfil solicitado no escopo autorizado e relatar o plano e as métricas verificadas pela
+CLI, sem executar scripts paralelos nem acessar produção.
+
+## Entradas
+
+- projeto e `opus.config.ts` corretos;
+- nome do seed e perfil desejado;
+- escopo isolado explícito entre os declarados pelo seed.
+
+## Procedimento
+
+1. Rodar `opus seed list --json` e localizar o nome, perfil, versão, dependências e escopos.
+2. Rodar `opus seed check --json`; parar se houver binding incompleto, ciclo, dependência ausente ou
+   comando local paralelo.
+3. Se seed, perfil ou escopo não estiverem explícitos e não puderem ser inferidos sem risco, pedir
+   a decisão. Nunca escolher produção nem ampliar `safety.scopes` para fazer a execução passar.
+4. Rodar `opus seed plan <nome> --profile <perfil> --scope <escopo> --json` e comunicar operações.
+5. Se a pessoa autorizou aplicar dados, rodar `opus seed apply` com os mesmos argumentos.
+6. Rodar `opus seed verify` e relatar as métricas estruturadas. Se falhar, preservar o erro e
+   diagnosticar o binding; não compensar com limpeza ou SQL improvisado.
+
+## Verificação
+
+O término exige `apply.ok=true`, `verify.ok=true` e métricas compatíveis com o perfil. Em CI ou
+preview, `OPUS_SEED_SCOPE` pode fornecer o mesmo escopo explícito.
+
+## Limites
+
+- Não executar `plan`, `apply` ou `verify` fora de `NODE_ENV=development` ou `NODE_ENV=test`.
+- Não chamar scripts de seed legados quando `opus seed check` os reprovar.
+- Não usar reset, truncate ou remoção para forçar métricas esperadas.
+- `list` e `check` são leitura; `apply` exige autorização para alterar o escopo informado.
+
+## Recursos
+
+- Use [avaliações](references/evaluations.md) ao evoluir esta skill.

package/registry/skills/apply-opus-seed/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Aplicar seed Opus"
+  short_description: "Planeja, aplica e verifica um dataset estruturado"
+  default_prompt: "Use $apply-opus-seed para aplicar este dataset no escopo isolado."

package/registry/skills/apply-opus-seed/references/evaluations.md

@@ -0,0 +1,8 @@
+# Avaliações
+
+- Positiva: “Suba o seed `customers.scenarios` no preview isolado e confira o resultado.” Deve
+  disparar, executar list/check/plan antes de apply e terminar com verify.
+- Negativa: “Rode as migrations de produção.” Não deve disparar; seed não administra schema nem
+  produção.
+- Execução: com dois perfis e dois escopos declarados, aplicar exatamente o perfil/escopo pedidos,
+  relatar as métricas JSON e recusar um escopo ausente ou não permitido.

package/registry/skills/create-opus-seed/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: create-opus-seed
+description: Cria ou migra um seed Opus estruturado com declaração, binding, registro, perfis, métricas e teste persistente de idempotência. Use ao adicionar datasets de desenvolvimento, demonstração ou teste em projeto baseado no Opus.
+---
+
+# Criar seed Opus
+
+## Resultado
+
+Entregar um seed descoberto por `opus seed list`, aprovado por `opus seed check` e cuja aplicação
+repetida converge para o mesmo estado observável no banco do consumidor.
+
+## Entradas
+
+- situação que o dataset precisa representar e pessoas que o usarão;
+- nome estável `<dominio>.<dataset>`, perfis e métricas verificáveis;
+- escopos isolados permitidos e dependências de outros seeds;
+- acesso real do projeto a repositório, serviço e banco.
+
+## Procedimento
+
+1. Inventariar scripts, fixtures e comandos existentes; preservar cenários válidos e identificar
+   reset, truncate ou limpeza implícita antes da migração.
+2. Rodar `node scripts/scaffold.mjs <nome>` a partir desta skill e usar a saída para criar a
+   declaração compartilhável e o binding server-only nos caminhos reais do projeto.
+3. Definir perfis por intenção, não por pessoa ou comando. Declarar em `expected` somente métricas
+   que `verify` consegue medir no estado persistido.
+4. Implementar `plan` sem escrita, `apply` convergente e `verify` sem escrita. Usar chaves estáveis;
+   não transformar ausência no perfil em autorização para excluir dados.
+5. Registrar o binding em `seeds` no `opus.config.ts`. Manter conexão, segredo, SQL e regras de
+   geração fora da declaração e da skill. Implementar `assertSeedTarget` com uma consulta à
+   identidade real do destino antes que qualquer binding seja executado e retornar `true` somente
+   depois da atestação bem-sucedida.
+6. Remover scripts `seed*`/`db:seed*` paralelos ou fazê-los delegar explicitamente para `opus seed`.
+7. Seguir o fluxo de testes do projeto e provar no banco de teste: primeira aplicação, segunda
+   aplicação com o mesmo resultado, verificação das métricas e falha segura em escopo proibido.
+
+## Verificação
+
+Rodar `opus seed check`, `opus seed list`, `plan`, duas aplicações e `verify` no escopo isolado.
+Depois executar typecheck, testes afetados e geração/check do manifest do projeto.
+
+## Limites
+
+- Não executar contra produção; `safety.scopes` aceita somente `local`, `test` e `isolated-preview`, e a
+  CLI exige `NODE_ENV=development` ou `NODE_ENV=test` antes de abrir conexão.
+- Não implementar reset, truncate ou remoção genérica como efeito de `apply`.
+- Não guardar SQL, credencial, dados pessoais reais ou regras de negócio dentro desta skill.
+- Não declarar idempotência apenas porque o comando terminou; comparar o estado após duas runs.
+
+## Recursos
+
+- Leia [contrato e exemplo](references/contract.md) ao definir os arquivos.
+- Use [avaliações](references/evaluations.md) ao evoluir esta skill.
+- Execute [scaffold.mjs](scripts/scaffold.mjs) para criar a estrutura inicial.

package/registry/skills/create-opus-seed/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Criar seed Opus"
+  short_description: "Estrutura um dataset seguro, verificável e convergente"
+  default_prompt: "Use $create-opus-seed para criar ou migrar este seed Opus."

package/registry/skills/create-opus-seed/references/contract.md

@@ -0,0 +1,16 @@
+# Contrato de autoria
+
+A declaração usa `defineSeed` e pode ser importada por ferramentas sem abrir banco. Ela contém
+nome, versão, descrição, perfis, dependências e escopos. O binding usa `bindSeed` no lado servidor
+e implementa três funções obrigatórias:
+
+- `plan`: descreve operações e não escreve;
+- `apply`: converge o estado e retorna métricas;
+- `verify`: lê o estado e retorna métricas comparáveis a `profiles[profile].expected`.
+
+O `opus.config.ts` registra bindings em `seeds`, mantém `database()` lazy e implementa
+`assertSeedTarget({ database, scope })` consultando a identidade real do alvo antes de qualquer
+binding e retornando `true` somente após a conferência. Qualquer outro retorno falha fechado.
+Repetir o rótulo da CLI ou confiar apenas na URL não atesta o banco. Nomeie
+perfis pela intenção (`smoke`, `conflicts`, `volume`) e use identificadores determinísticos nos
+registros. Se a regra exigir apagar o banco, isso é outra operação e não um seed Opus.

package/registry/skills/create-opus-seed/references/evaluations.md

@@ -0,0 +1,8 @@
+# Avaliações
+
+- Positiva: “Crie um seed com cenários de conflito de clientes e perfis smoke e volume.” Deve
+  disparar, separar declaração/binding, registrar no config e exigir teste de duas aplicações.
+- Negativa: “Crie fixtures unitárias em memória para este parser.” Não deve disparar quando não há
+  dataset persistente nem operação `opus seed`.
+- Execução: migrar um `db:seed` existente, obter zero violações em `opus seed check`, aplicar duas
+  vezes em escopo isolado e observar as mesmas métricas no `verify`.

package/registry/skills/create-opus-seed/scripts/scaffold.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+export function seedFiles(name) {
+  validateName(name)
+  const stem = name.replaceAll('.', '-')
+  const definitionName = `${camel(name)}Definition`
+  const bindingName = `${camel(name)}Seed`
+  return {
+    definition: `import { defineSeed } from '@softize/opus/seed'
+
+export const ${definitionName} = defineSeed({
+  name: '${name}',
+  version: 1,
+  description: 'Descreva a situação representada por este dataset.',
+  profiles: {
+    smoke: {
+      description: 'Menor conjunto útil para desenvolvimento.',
+      expected: { records: 0 },
+    },
+  },
+  defaultProfile: 'smoke',
+  safety: { scopes: ['local'] },
+})
+`,
+    binding: `import { bindSeed } from '@softize/opus/seed'
+
+import { ${definitionName} } from './${stem}.definition.ts'
+
+export const ${bindingName} = bindSeed(${definitionName}, {
+  plan: ({ profile }) => ({
+    summary: \`Preparar o perfil \${profile}.\`,
+    operations: ['Descreva as operações convergentes'],
+  }),
+  apply: async ({ database, profile }) => {
+    void database
+    void profile
+    throw new Error('Implemente a aplicação convergente antes de registrar este seed')
+  },
+  verify: async ({ database, profile }) => {
+    void database
+    void profile
+    throw new Error('Implemente a verificação das métricas antes de registrar este seed')
+  },
+})
+`,
+  }
+}
+
+export function seedFileNames(name) {
+  validateName(name)
+  const stem = name.replaceAll('.', '-')
+  return { definition: `${stem}.definition.ts`, binding: `${stem}.seed.ts` }
+}
+
+const isMain = process.argv[1] !== undefined && import.meta.url === new URL(`file://${process.argv[1]}`).href
+if (isMain) {
+  const [name] = process.argv.slice(2)
+  try {
+    const generated = seedFiles(name)
+    const names = seedFileNames(name)
+    process.stdout.write(
+      `// ${names.definition}\n${generated.definition}\n// ${names.binding}\n${generated.binding}`,
+    )
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exit(1)
+  }
+}
+
+function camel(value) {
+  return value.replace(/\.([a-z0-9])/g, (_, character) => character.toUpperCase())
+}
+
+function validateName(name) {
+  if (!/^[a-z][a-z0-9]*(?:\.[a-z][a-z0-9]*)+$/.test(name ?? '')) {
+    throw new Error('name deve usar segmentos lowercase, como customers.scenarios')
+  }
+}

package/registry/skills/implement-opus-change/SKILL.md

@@ -5,6 +5,7 @@ description: Implementa uma mudança em projeto baseado no Opus preservando cont
 <!-- softize-skill-route: $create-opus-action -->
 <!-- softize-skill-route: $test-opus-action -->
 <!-- softize-skill-route: $build-opus-ui -->
+<!-- softize-skill-route: $create-opus-seed -->
 
 # Implementar mudança Opus
 
@@ -25,7 +26,8 @@ dependências server-only, bindings registrados, testes e gates verdes.
 2. Modelar primeiro o contrato observável: nome, descrição, input, output, erros e metadata.
 3. Manter código compartilhável fora de banco, segredo, filesystem e drivers server-only.
 4. Implementar o binding e registrar o `ActionDef` no domínio/runtime conforme a topologia local.
-5. Carregar e seguir `$create-opus-action`, `$test-opus-action` ou `$build-opus-ui` antes
+5. Carregar e seguir `$create-opus-action`, `$test-opus-action`, `$build-opus-ui` ou
+   `$create-opus-seed` antes
    do passo correspondente quando a mudança entrar nesses workflows especializados.
 6. Atualizar manifest, docs geradas e exemplos somente pelos comandos do repo.
 

package/src/core/index.ts

@@ -54,6 +54,8 @@ export type {
   Example,
   ActionMessages,
   OptionsSpec,
+  BuiltInFieldWidget,
+  FieldWidget,
   FieldSpec,
   FilterOp,
   FilterSpec,

package/src/core/types.ts

@@ -529,6 +529,21 @@ export type OptionsSpec =
   | { kind: 'dictionary'; ref: string }
   | { kind: 'lookup'; source: string; depends?: string[] }
 
+/** Overrides declarativos nativos reconhecidos pelo ActionForm. */
+export type BuiltInFieldWidget =
+  | 'textarea'
+  | 'code'
+  | 'lines'
+  | 'refItems'
+  | 'icon'
+  | 'toggle-group'
+
+/**
+ * Widget nativo ou identificador próprio de outro renderer.
+ * A interseção preserva autocomplete dos nativos sem quebrar widgets customizados existentes.
+ */
+export type FieldWidget = BuiltInFieldWidget | (string & { readonly __opusCustomWidget?: never })
+
 /**
  * Descrição de campo em `FormAction.fields`. Drive UI rendering + AI tool
  * description per-field.
@@ -551,7 +566,7 @@ export interface FieldSpec {
   group?: string
   order?: number
 
-  widget?: string
+  widget?: FieldWidget
   options?: OptionsSpec
 
   aiDescription?: string