@softize/opus 8.8.2 → 8.9.0

package/bin/lib/materialize.mjs

@@ -0,0 +1,273 @@
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, extname, join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { validateSkill } from './validate-skill.mjs'
+
+export const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+export const PACKAGE_NAME = '@softize/opus'
+export const PACKAGE_VERSION = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8')).version
+
+const REGISTRY = join(PACKAGE_ROOT, 'registry')
+const BLOCK_SOURCE = 'registry/instructions/opus.md'
+const BLOCK_END = '<!-- softize-managed:end @softize/opus -->'
+const MANAGED_ROOTS = ['.agents/skills', '.claude/skills', '.claude/hooks', '.github/workflows', '.githooks/pre-push.d']
+
+const hash = (content) => createHash('sha256').update(content).digest('hex')
+const readJson = (path) => {
+  try { return JSON.parse(readFileSync(path, 'utf8')) } catch { return null }
+}
+
+function filesUnder(root, base = root) {
+  if (!existsSync(root)) return []
+  return readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
+    const path = join(root, entry.name)
+    return entry.isDirectory() ? filesUnder(path, base) : entry.isFile() ? [{ path, relative: relative(base, path) }] : []
+  })
+}
+
+function sourceSkills() {
+  return readdirSync(join(REGISTRY, 'skills'), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && existsSync(join(REGISTRY, 'skills', entry.name, 'SKILL.md')))
+    .map((entry) => entry.name).sort()
+}
+
+function marker(path, source, content) {
+  const value = `softize-managed: ${JSON.stringify({ package: PACKAGE_NAME, source, sha256: hash(content) })}`
+  if (extname(path) === '.md') return `<!-- ${value} -->`
+  if (['.js', '.mjs', '.cjs', '.ts', '.tsx'].includes(extname(path))) return `// ${value}`
+  return `# ${value}`
+}
+
+export function addMarker(path, source, content) {
+  const line = marker(path, source, content)
+  if (content.startsWith('#!')) {
+    const at = content.indexOf('\n') + 1
+    return `${content.slice(0, at)}${line}\n${content.slice(at)}`
+  }
+  if (extname(path) === '.md' && content.startsWith('---\n')) {
+    const close = content.indexOf('\n---\n', 4)
+    if (close !== -1) {
+      const at = close + 5
+      return `${content.slice(0, at)}${line}\n${content.slice(at)}`
+    }
+  }
+  return `${line}\n${content}`
+}
+
+function metadata(content) {
+  const match = /^(?:<!-- |\/\/ |# )softize-managed: (\{[^\n]+\})(?: -->)?$/m.exec(content)
+  if (match === null) return null
+  try { return JSON.parse(match[1]) } catch { return null }
+}
+
+function stripMarker(content) {
+  return content.replace(/^(?:<!-- |\/\/ |# )softize-managed: \{[^\n]+\}(?: -->)?\r?\n/m, '')
+}
+
+function config(root, mode, errors, changes) {
+  const path = join(root, 'base.json')
+  const original = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  const current = original === '' ? { schemaVersion: 1, packages: {} } : readJson(path)
+  if (current === null || current.schemaVersion !== 1 || typeof current.packages !== 'object') {
+    errors.push('base.json: formato inválido; esperado schemaVersion 1 e packages.')
+    return []
+  }
+  const previous = current.packages[PACKAGE_NAME] ?? {}
+  const exclude = Array.isArray(previous.exclude) ? previous.exclude : []
+  if (previous.exclude !== undefined && !Array.isArray(previous.exclude)) errors.push('base.json: exclude deve ser uma lista de slugs.')
+  const available = new Set(sourceSkills())
+  for (const slug of exclude) if (typeof slug !== 'string' || !available.has(slug)) errors.push(`base.json: skill excluída desconhecida: ${String(slug)}.`)
+  if (mode === 'setup') {
+    current.packages[PACKAGE_NAME] = { version: PACKAGE_VERSION, exclude }
+    const rendered = `${JSON.stringify(current, null, 2)}\n`
+    if (rendered !== original) {
+      writeFileSync(path, rendered)
+      changes.push(`${original === '' ? 'criado' : 'atualizado'} base.json`)
+    }
+  } else if (previous.version !== PACKAGE_VERSION) errors.push(`base.json: Opus aplicado ${previous.version ?? 'ausente'}, instalado ${PACKAGE_VERSION}.`)
+  return exclude.filter((slug) => available.has(slug))
+}
+
+function expectedFiles(exclude) {
+  const expected = new Map()
+  const addTree = (sourceRoot, destinationRoot) => {
+    for (const file of filesUnder(join(PACKAGE_ROOT, sourceRoot))) {
+      const source = `${sourceRoot}/${file.relative}`
+      const destination = `${destinationRoot}/${file.relative}`
+      const content = readFileSync(file.path, 'utf8')
+      expected.set(destination, { source, content, output: addMarker(destination, source, content) })
+    }
+  }
+  for (const slug of sourceSkills()) {
+    if (exclude.includes(slug)) continue
+    addTree(`registry/skills/${slug}`, `.agents/skills/${slug}`)
+    addTree(`registry/skills/${slug}`, `.claude/skills/${slug}`)
+  }
+  for (const [source, destination] of [
+    ['registry/hooks/opus-check-on-stop.mjs', '.claude/hooks/opus-check-on-stop.mjs'],
+    ['registry/git/pre-push.d/opus', '.githooks/pre-push.d/opus'],
+    ['registry/github/opus.yml', '.github/workflows/opus.yml'],
+  ]) {
+    const content = readFileSync(join(PACKAGE_ROOT, source), 'utf8')
+    expected.set(destination, { source, content, output: addMarker(destination, source, content) })
+  }
+  return expected
+}
+
+function reconcileFile(root, destination, item, mode, errors, changes) {
+  const path = join(root, destination)
+  if (!existsSync(path)) {
+    if (mode === 'check') errors.push(`${destination}: ausente.`)
+    else {
+      mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, item.output)
+      if (destination.startsWith('.githooks/')) chmodSync(path, 0o755)
+      changes.push(`criado ${destination}`)
+    }
+    return
+  }
+  const current = readFileSync(path, 'utf8')
+  if (current === item.output) return
+  const owner = metadata(current)
+  if (owner?.package !== PACKAGE_NAME) { errors.push(`${destination}: colisão com arquivo não gerenciado pelo Opus.`); return }
+  if (hash(stripMarker(current)) !== owner.sha256) { errors.push(`${destination}: arquivo gerenciado foi editado; preservado.`); return }
+  if (mode === 'check') errors.push(`${destination}: desatualizado.`)
+  else {
+    writeFileSync(path, item.output)
+    if (destination.startsWith('.githooks/')) chmodSync(path, 0o755)
+    changes.push(`atualizado ${destination}`)
+  }
+}
+
+function removeObsolete(root, expected, mode, errors, changes) {
+  for (const managedRoot of MANAGED_ROOTS) for (const file of filesUnder(join(root, managedRoot), root)) {
+    const content = readFileSync(file.path, 'utf8')
+    const owner = metadata(content)
+    if (owner?.package !== PACKAGE_NAME || expected.has(file.relative)) continue
+    if (hash(stripMarker(content)) !== owner.sha256) errors.push(`${file.relative}: obsoleto, mas editado; preservado.`)
+    else if (mode === 'check') errors.push(`${file.relative}: artefato obsoleto.`)
+    else { rmSync(file.path); changes.push(`removido ${file.relative}`) }
+  }
+}
+
+function detectLegacyArtifacts(root, errors) {
+  for (const destination of ['.agents/skills/create-action', '.claude/skills/create-action']) {
+    if (existsSync(join(root, destination))) {
+      errors.push(`${destination}: skill legada detectada; remova-a após revisar qualquer edição local. Use create-opus-action.`)
+    }
+  }
+}
+
+function expectedBlock() {
+  const body = readFileSync(join(PACKAGE_ROOT, BLOCK_SOURCE), 'utf8').trimEnd()
+  const open = `<!-- softize-managed:start ${JSON.stringify({ package: PACKAGE_NAME, source: BLOCK_SOURCE, sha256: hash(body) })} -->`
+  return { body, text: `${open}\n${body}\n${BLOCK_END}` }
+}
+
+function findBlock(content) {
+  const pattern = /<!-- softize-managed:start (\{[^\n]+\}) -->/g
+  for (const match of content.matchAll(pattern)) {
+    let owner = null
+    try { owner = JSON.parse(match[1]) } catch { /* outro marcador inválido */ }
+    if (owner?.package !== PACKAGE_NAME) continue
+    const start = match.index
+    const openEnd = start + match[0].length
+    const end = content.indexOf(BLOCK_END, openEnd)
+    if (end === -1) return { malformed: true }
+    const bodyStart = openEnd + 1
+    const bodyEnd = content[end - 1] === '\n' ? end - 1 : end
+    return { start, end: end + BLOCK_END.length, body: content.slice(bodyStart, bodyEnd), owner }
+  }
+  if (/<!-- softize-managed:start [^\n]*@softize\/opus/.test(content)) return { malformed: true }
+  return null
+}
+
+function reconcileInstructions(root, file, mode, errors, changes) {
+  const path = join(root, file)
+  const expected = expectedBlock()
+  const current = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  const block = findBlock(current)
+  if (block?.malformed) { errors.push(`${file}: bloco Opus malformado.`); return }
+  if (block === null) {
+    if (mode === 'check') errors.push(`${file}: bloco Opus ausente.`)
+    else { writeFileSync(path, `${current.trimEnd()}${current.trimEnd() === '' ? '' : '\n\n'}${expected.text}\n`); changes.push(`atualizado ${file}`) }
+    return
+  }
+  if (hash(block.body) !== block.owner.sha256) { errors.push(`${file}: bloco Opus foi editado; preservado.`); return }
+  const actual = current.slice(block.start, block.end)
+  if (actual === expected.text) return
+  if (mode === 'check') errors.push(`${file}: bloco Opus desatualizado.`)
+  else { writeFileSync(path, `${current.slice(0, block.start)}${expected.text}${current.slice(block.end)}`); changes.push(`atualizado ${file}`) }
+}
+
+function isOpusHook(hook) { return typeof hook?.command === 'string' && hook.command.includes('.claude/hooks/opus-check-on-stop.mjs') }
+function reconcileSettings(root, mode, errors, changes) {
+  const destination = '.claude/settings.json'
+  const path = join(root, destination)
+  const current = existsSync(path) ? readJson(path) : {}
+  if (current === null || typeof current !== 'object') { errors.push(`${destination}: JSON inválido; preservado.`); return }
+  const expected = structuredClone(current); expected.hooks ??= {}
+  for (const event of Object.keys(expected.hooks)) expected.hooks[event] = expected.hooks[event]
+    .map((group) => ({ ...group, hooks: (group.hooks ?? []).filter((hook) => !isOpusHook(hook)) }))
+    .filter((group) => group.hooks.length > 0)
+  expected.hooks.Stop = [...(expected.hooks.Stop ?? []), { hooks: [{ type: 'command', command: 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/opus-check-on-stop.mjs"', timeout: 120 }] }]
+  if (JSON.stringify(current) === JSON.stringify(expected)) return
+  if (mode === 'check') errors.push(`${destination}: hook Opus ausente ou desatualizado.`)
+  else { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(expected, null, 2)}\n`); changes.push(`atualizado ${destination}`) }
+}
+
+function reconcileSharedPrePush(root, mode, errors, changes) {
+  const destination = '.githooks/pre-push'
+  const path = join(root, destination)
+  const expected = readFileSync(join(REGISTRY, 'git/pre-push'), 'utf8')
+  if (!existsSync(path)) {
+    if (mode === 'check') errors.push(`${destination}: dispatcher compartilhado ausente.`)
+    else { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, expected); chmodSync(path, 0o755); changes.push(`criado ${destination}`) }
+  } else if (readFileSync(path, 'utf8') !== expected) errors.push(`${destination}: dispatcher compartilhado incompatível; preservado.`)
+  else if (mode === 'setup' && (statSync(path).mode & 0o111) === 0) { chmodSync(path, 0o755); changes.push(`corrigido modo executável de ${destination}`) }
+}
+
+function configureGit(root, mode, errors, changes) {
+  if (!existsSync(join(root, '.git'))) return
+  try {
+    try { execFileSync('git', ['rev-parse', '--git-dir'], { cwd: root, stdio: 'ignore' }) } catch { return }
+    let hooksPath = ''
+    try { hooksPath = execFileSync('git', ['config', '--local', '--get', 'core.hooksPath'], { cwd: root, encoding: 'utf8' }).trim() } catch { /* ausente */ }
+    if (mode === 'setup' && hooksPath === '') execFileSync('git', ['config', '--local', 'core.hooksPath', '.githooks'], { cwd: root })
+    else if (hooksPath !== '.githooks') errors.push(`git core.hooksPath ${hooksPath === '' ? 'não configurado' : `aponta para ${hooksPath}`}.`)
+
+    const excludePath = execFileSync('git', ['rev-parse', '--git-path', 'info/exclude'], { cwd: root, encoding: 'utf8' }).trim()
+    const absolute = resolve(root, excludePath)
+    if (existsSync(absolute)) {
+      const current = readFileSync(absolute, 'utf8')
+      const forbidden = new Set(['.claude/', '.claude/skills/', '.agents/', '.agents/skills/'])
+      const lines = current.split(/\r?\n/)
+      const blocked = lines.filter((line) => forbidden.has(line.trim()))
+      if (blocked.length > 0 && mode === 'check') errors.push(`git info/exclude oculta artefatos de agentes: ${blocked.join(', ')}.`)
+      else if (blocked.length > 0) {
+        const kept = lines.filter((line) => !forbidden.has(line.trim())).join('\n').replace(/\n+$/, '')
+        writeFileSync(absolute, kept === '' ? '' : `${kept}\n`)
+        changes.push('removidas exclusões locais de artefatos de agentes')
+      }
+    }
+  } catch (error) { errors.push(`git: ${String(error).slice(0, 140)}.`) }
+}
+
+export function materializeOpus(root, mode = 'setup') {
+  const target = resolve(root)
+  const errors = sourceSkills().flatMap((slug) => validateSkill(join(REGISTRY, 'skills', slug)).map((error) => `skills/${slug}: ${error}`))
+  const changes = []
+  const exclude = config(target, mode, errors, changes)
+  const expected = expectedFiles(exclude)
+  reconcileSharedPrePush(target, mode, errors, changes)
+  for (const [destination, item] of expected) reconcileFile(target, destination, item, mode, errors, changes)
+  removeObsolete(target, expected, mode, errors, changes)
+  detectLegacyArtifacts(target, errors)
+  reconcileInstructions(target, 'AGENTS.md', mode, errors, changes)
+  reconcileInstructions(target, 'CLAUDE.md', mode, errors, changes)
+  reconcileSettings(target, mode, errors, changes)
+  configureGit(target, mode, errors, changes)
+  return { ok: errors.length === 0, errors, changes, expected: [...expected.keys()] }
+}

package/bin/lib/mcp.mjs

@@ -1,6 +1,6 @@
 /**
  * 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
+ * a régua (opus check) + o gerador usado por `create-opus-action`. Os agentes apontam pra cá via
  * `mcp_config`. Embrulha os engines já testados (introspect/check/scaffold).
  *
  * Tools:
@@ -16,7 +16,7 @@ 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 { actionFiles } from '../../registry/skills/create-opus-action/scripts/scaffold.mjs'
 import { listComponents, getComponent } from './components.mjs'
 
 const asText = (data) => ({
@@ -56,7 +56,7 @@ export function buildServer() {
         kind: z.enum(['simple', 'form', 'list', 'view']).optional(),
       },
     },
-    async ({ resource, verb, kind }) => asText(actionTemplate({ resource, verb, kind })),
+    async ({ resource, verb, kind }) => asText(actionFiles({ resource, verb, kind })),
   )
 
   server.registerTool(

package/bin/lib/postinstall.mjs

@@ -1,8 +1,7 @@
 #!/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.
+ * postinstall do @softize/opus — tenta rodar o setup no consumidor. É conveniência
+ * best-effort; a garantia vem de `opus setup` explícito + `opus check` no CI.
  *
  * Blindagem (best-effort, NUNCA falha o install):
  *   • OPUS_SKIP_INIT=1            → pula
@@ -42,11 +41,15 @@ async function main() {
   if (!deps['@softize/opus']) return // Não é consumidor da base.
 
   const r = await initProject(REGISTRY_DIR, projectDir)
+  if (!r.materialization.ok) {
+    console.log(`\x1b[33m[opus]\x1b[0m setup incompleto: ${r.materialization.errors.join(' | ')}`)
+    return
+  }
   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.`,
+      `. Veja base.json / opus.json.`,
   )
 }
 

package/bin/lib/validate-skill.mjs

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const PROHIBITED = new Set(['README.md', 'CHANGELOG.md', 'INSTALLATION_GUIDE.md', 'QUICK_REFERENCE.md'])
+
+function frontmatter(content) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(content)
+  if (match === null) return null
+  const entries = match[1].split(/\r?\n/).filter(Boolean).map((line) => {
+    const at = line.indexOf(':')
+    return at === -1 ? [line, ''] : [line.slice(0, at).trim(), line.slice(at + 1).trim()]
+  })
+  return Object.fromEntries(entries)
+}
+
+export function validateSkill(root) {
+  const errors = []
+  const slug = basename(root)
+  const path = join(root, 'SKILL.md')
+  if (!existsSync(path)) return ['SKILL.md ausente.']
+  const content = readFileSync(path, 'utf8')
+  const metadata = frontmatter(content)
+  if (metadata === null) errors.push('frontmatter ausente ou inválido.')
+  else {
+    if (Object.keys(metadata).sort().join(',') !== 'description,name') errors.push('frontmatter deve conter somente name e description.')
+    if (metadata.name !== slug) errors.push(`name deve ser igual à pasta (${slug}).`)
+    if (!NAME.test(metadata.name ?? '') || slug.length > 64) errors.push('name deve usar lowercase kebab-case e no máximo 64 caracteres.')
+    if (!/(use|usar|quando)/i.test(metadata.description ?? '')) errors.push('description deve declarar quando usar a skill.')
+  }
+  if (content.split(/\r?\n/).length > 500) errors.push('SKILL.md excede 500 linhas.')
+  if (/\bTODO\b|\bTBD\b|\[placeholder\]/i.test(content)) errors.push('skill contém placeholder.')
+  for (const name of readdirSync(root)) if (PROHIBITED.has(name)) errors.push(`${name} não pertence a uma skill.`)
+  const links = [...content.matchAll(/\[[^\]]+\]\(([^)]+)\)/g)].map((match) => match[1]).filter((link) => !/^[a-z]+:|^#/.test(link))
+  for (const link of links) if (!existsSync(join(root, link))) errors.push(`recurso inexistente: ${link}.`)
+  const ui = join(root, 'agents/openai.yaml')
+  if (!existsSync(ui)) errors.push('agents/openai.yaml ausente.')
+  else if (!readFileSync(ui, 'utf8').includes(`$${slug}`)) errors.push(`default_prompt deve mencionar $${slug}.`)
+  return errors
+}

package/docs/code-style.md

@@ -5,12 +5,12 @@ 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.
+Este arquivo registra as convenções editoriais da documentação do Opus. Regras
+transversais de engenharia pertencem à `@softize/base`; o Opus mantém apenas o que é
+específico do SDK e seus gates.
 
 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.
+campos do spec, registro no runtime); o restante vem das instruções versionadas no repo.

package/docs/releasing.md

@@ -5,23 +5,23 @@ order: 6
 
 # Publicar o @softize/opus
 
-O Opus é publicado no **registry compartilhado da Softize** (`registry.softize.com.br`),
-**não** no npm público. Os clientes consomem de lá.
+O Opus é publicado no **npm público** (`registry.npmjs.org`). O registry próprio foi
+aposentado; clientes instalam sem configuração ou token de leitura.
 
-> O `publishConfig` do `package.json` já aponta pra lá — `pnpm publish` "só funciona",
+> O `publishConfig` do `package.json` já aponta para o npm — `pnpm publish` "só funciona",
 > sem `--registry`. Não precisa decorar a URL.
 
 ## Release pela estação (o caminho normal)
 
 ```bash
-pnpm release            # patch bump + publica no registry.softize.com.br
+pnpm release            # patch bump + publica no npm público
 pnpm release minor      # minor
 pnpm release major      # major
 pnpm release 2.9.0      # versão explícita
 pnpm release none       # publica sem bump
 ```
 
-Auth: o token do registry no `~/.npmrc` global (`//registry.softize.com.br/:_authToken=…`),
+Auth: o token do npm no `~/.npmrc` global (`//registry.npmjs.org/:_authToken=…`),
 NÃO commitado.
 
 ## Não existe caminho pela CI (29/jul)
@@ -32,7 +32,7 @@ o `release.yml` (publicava por tag `v*`), o `deploy.yml` (doc, já reserva) e o
 caminho só, na estação, com os gates junto. Não há gatilho de reserva.
 
 O secret **`OPUS_REGISTRY_TOKEN`** ficou órfão — nada mais o lê. Apague no GitHub. O que
-autentica hoje é o token do registry no seu `~/.npmrc` global.
+autentica hoje é o token do npm no seu `~/.npmrc` global.
 
 **O que o `release.sh` absorveu**, porque sem CI ficaria sem dono:
 
@@ -70,9 +70,7 @@ pra commitar.
 ## Verificar
 
 ```bash
-npm view @softize/opus version --registry https://registry.softize.com.br/
-# ou
-curl -s https://registry.softize.com.br/@softize%2fopus | node -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>console.log(JSON.parse(d)['dist-tags'].latest))"
+npm view @softize/opus version --registry https://registry.npmjs.org/
 ```
 
 ## Testar localmente (sem tocar no compartilhado)
@@ -95,16 +93,16 @@ pnpm add @softize/opus@8.7.0-rc.0 --registry http://127.0.0.1:6873/
 ```
 
 Valide o app normalmente. Ao encerrar a sessão, restaure o intervalo de versão do
-consumidor para o registry compartilhado e rode `pnpm install`; a prerelease local nunca
-é enviada para `registry.softize.com.br`. Para publicar outra tentativa, incremente o
-sucesso (`8.6.0-rc.1`, por exemplo) e repita o mesmo fluxo.
+consumidor para o npm e rode `pnpm install`; a prerelease local nunca é enviada ao npm.
+Para publicar outra tentativa, incremente o sucesso (`8.6.0-rc.1`, por exemplo) e repita
+o mesmo fluxo.
 
 ## Auth
 
-O publish no compartilhado exige o token no **`~/.npmrc` global** do dev:
+O publish exige o token no **`~/.npmrc` global** do dev:
 
 ```
-//registry.softize.com.br/:_authToken=<token>
+//registry.npmjs.org/:_authToken=<token>
 ```
 
 Não vai no repo. Leitura (install) é aberta — não precisa de token.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "8.8.2",
+  "version": "8.9.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,9 @@
     "./init": {
       "default": "./bin/lib/init.mjs"
     },
+    "./materialize": {
+      "default": "./bin/lib/materialize.mjs"
+    },
     "./docs-include": "./bin/lib/docs-include.mjs",
     "./core": {
       "types": "./src/core/index.ts",
@@ -185,16 +188,6 @@
   "bin": {
     "opus": "./bin/cli.mjs"
   },
-  "scripts": {
-    "postinstall": "node ./bin/lib/postinstall.mjs",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:cov": "vitest run --coverage",
-    "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",
-    "release": "bash ./scripts/release.sh",
-    "release:local": "bash ./scripts/release.sh --local"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@radix-ui/react-checkbox": "^1.1.3",
@@ -329,11 +322,20 @@
     "vitest": "^2.1.0",
     "zod": "^3.24.0"
   },
-  "packageManager": "pnpm@9.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/softize-dev/opus.git",
     "directory": "packages/opus"
   },
-  "homepage": "https://opus.softize.com.br"
-}
+  "homepage": "https://opus.softize.com.br",
+  "scripts": {
+    "postinstall": "node ./bin/lib/postinstall.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "registry:up": "npx -y verdaccio --config ~/.config/verdaccio/config.yaml",
+    "release": "bash ./scripts/release.sh",
+    "release:local": "bash ./scripts/release.sh --local"
+  }
+}

package/registry/git/pre-push

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+hook_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+for hook in "$hook_dir"/pre-push.d/*; do
+  [ -x "$hook" ] || continue
+  "$hook" "$@" || exit $?
+done

package/registry/git/pre-push.d/opus

@@ -0,0 +1,9 @@
+#!/bin/sh
+if [ -f node_modules/@softize/opus/bin/cli.mjs ]; then
+  node node_modules/@softize/opus/bin/cli.mjs pre-push
+elif [ -f packages/opus/bin/cli.mjs ]; then
+  node packages/opus/bin/cli.mjs pre-push materialization
+else
+  echo "opus pre-push: @softize/opus não está instalado." >&2
+  exit 1
+fi

package/registry/github/opus.yml

@@ -0,0 +1,22 @@
+name: opus
+
+on:
+  pull_request: {}
+  push:
+    branches: [main]
+  workflow_dispatch: {}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec opus check

package/registry/instructions/opus.md

@@ -0,0 +1,15 @@
+# Opus
+
+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`.
+
+## Regras permanentes
+
+- Tratar declarações como fonte de contratos e documentação de negócio; manifest, OpenAPI
+  e docs são projeções geradas.
+- 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.
+- Rodar `opus check` e os gates do projeto depois de alterar actions, bindings ou versão do SDK.
+- Consultar as skills Opus materializadas conforme o workflow; não atribuir ao SDK decisões
+  universais de domínio ou arquitetura.

package/registry/skills/build-opus-ui/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: build-opus-ui
+description: Constrói interface contract-driven com hooks, forms, listas, views e componentes de @softize/opus/ui. Use ao implementar ou alterar telas que consomem actions Opus.
+---
+
+# Construir UI Opus
+
+## Resultado
+
+Entregar uma interface que deriva dados, validação, mensagens e execução dos contratos
+existentes, mantendo navegação observável e componentes reutilizáveis sem layout oculto.
+
+## Procedimento
+
+1. Identificar o contrato e o kind da action; corrigir lacuna do contrato na fonte em vez
+   de compensá-la com tipo ou validação na UI.
+2. Usar os hooks e componentes do catálogo `@softize/opus/ui/react` adequados ao kind.
+3. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
+   o produto precisa de deep link, back/forward ou refresh.
+4. Manter margem e posicionamento no consumidor; componente reutilizável controla apenas
+   seu interior.
+5. Evoluir um pattern compartilhado apenas quando a recorrência e o contrato estiverem claros.
+6. Testar estados de loading, vazio, erro, sucesso, permissão e interação relevante.
+
+## Verificação
+
+Rodar testes focados, typecheck e build da superfície. Inspecionar visualmente a rota real
+e validar navegação por URL quando aplicável.
+
+## Limites
+
+- Não criar fetch, schema ou tipo paralelo ao contrato.
+- Não copiar componente da lib para customizar sem antes verificar extensão/composição.
+- Não forçar modal roteável quando o estado é efêmero e sem valor de navegação.
+
+## Recursos
+
+- Leia [patterns de UI](references/ui-patterns.md) para decisões de estado e composição.
+- Use [avaliações](references/evaluations.md) ao evoluir esta skill.

package/registry/skills/build-opus-ui/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Construir UI Opus"
+  short_description: "Constrói UI contract-driven com os componentes Opus"
+  default_prompt: "Use $build-opus-ui para construir esta interface Opus."

package/registry/skills/build-opus-ui/references/evaluations.md

@@ -0,0 +1,5 @@
+# Avaliações
+
+- Dispara: “Monte a tela de edição usando a form action do Opus.”
+- Não dispara: “Ajuste o CSS de um e-mail estático.”
+- Execução: implementar uma lista com modal roteável e provar loading, erro, vazio e back.

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -0,0 +1,8 @@
+# Patterns de UI Opus
+
+- O kind da action orienta a primitiva: form, list, view ou trigger simples.
+- Campos, labels, mensagens e invalidações pertencem ao contrato quando são parte da
+  operação, não a uma tela isolada.
+- URL representa estado que precisa sobreviver a refresh, deep link ou histórico.
+- Componentes compartilhados não impõem margem externa; páginas e shells compõem layout.
+- Catálogo e API efetivos vêm dos exports da versão instalada, não de memória ou exemplo antigo.