@softize/opus 8.8.2 → 8.9.1

package/CHANGELOG.md

@@ -11,6 +11,31 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 > tinha ficado sem registro nenhum, o que é exatamente o caso que este arquivo existe
 > pra cobrir.
 
+## 8.9.1 — 2026-08-04
+
+**A migração deixa de esconder o hook Opus no Git.** `opus setup` agora remove também a
+exclusão local legada e específica de `.claude/hooks/opus-check-on-stop.mjs`, preservando
+as preferências realmente locais. Isso fecha o caso em que o check passava na máquina que
+já tinha o hook, mas o arquivo não entrava no commit para um clone novo.
+
+## 8.9.0 — 2026-08-04
+
+**O Opus passa a materializar e versionar suas próprias skills e garantias.** `opus setup`
+agora projeta as cinco skills do SDK para Claude e Codex, instala o hook Stop, participa do
+pre-push composto, cria o gate `opus.yml` e mantém um bloco próprio em `AGENTS.md` e
+`CLAUDE.md`. Tudo viaja no Git e `opus check` recusa drift entre o pacote instalado,
+`base.json` e os arquivos comitados. O Maestro deixa de ser requisito operacional.
+
+O catálogo é `implement-opus-change`, `create-opus-action`, `test-opus-action`,
+`build-opus-ui` e `upgrade-opus`. `create-opus-action` gera o split atual
+`defineContract` + `bindAction`; a skill legada `create-action`, que ainda emitia handler
+inline, foi removida.
+
+**Migração:** depois do bump, rode `pnpm exec opus setup`, remova do índice local quaisquer
+exclusões mais amplas de `.claude/` ou `.agents/` que o setup reportar e comite `base.json`,
+as duas projeções de skills, hooks, instruções, pre-push e workflow. O marcador per-app
+`opus.json` passa de `base/baseVersion` para `package/version`.
+
 ## 8.6.6 — 2026-07-30
 
 **O pacote passa a ser publicado no npm PÚBLICO.** O registry próprio

package/README.md

@@ -81,7 +81,7 @@ await app.listen({ port: 3000 })
 src/
   core/      schema/    server/    client/    ui/
   data/      auth/      audit/     log/       queue/   events/   scheduler/   dsl/
-registry/    # scaffolds + skills (create-action) — geração, não runtime
+registry/    # scaffolds + skills Opus — geração e conhecimento do SDK, não runtime
 bin/         # CLI (opus setup/gen/check/introspect/mcp) + libs
 docs/
   protocol.md   # contrato completo (16 seções)

package/bin/cli.mjs

@@ -20,8 +20,9 @@ import { cmdGen, helpGen } from './lib/gen.mjs'
 import { cmdDb } from './lib/db.mjs'
 import { scanDir, emptyScanVerdict } from './lib/check.mjs'
 import { createMonorepo, createProject } from './lib/create.mjs'
-import { initProject, setupUiFoundation } from './lib/init.mjs'
+import { initProject, repoRootOf, setupUiFoundation } from './lib/init.mjs'
 import { introspect } from './lib/introspect.mjs'
+import { materializeOpus } from './lib/materialize.mjs'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -167,6 +168,12 @@ async function cmdAdd(name, options) {
 async function cmdCheck(dir) {
   const root = path.resolve(process.cwd(), dir ?? '.')
   const rel = path.relative(process.cwd(), root) || '.'
+  const repoRoot = (await repoRootOf(root)) ?? root
+  const materialization = materializeOpus(repoRoot, 'check')
+  if (!materialization.ok) {
+    for (const error of materialization.errors) log('error', `✗ opus check: ${error}`)
+    process.exit(1)
+  }
   const { files, actions, contracts, findings, hasMarker } = await scanDir(root)
 
   if (actions === 0) {
@@ -202,6 +209,16 @@ async function cmdCheck(dir) {
   process.exit(1)
 }
 
+async function cmdMaterializationCheck() {
+  const root = (await repoRootOf(process.cwd())) ?? process.cwd()
+  const result = materializeOpus(root, 'check')
+  if (!result.ok) {
+    for (const error of result.errors) log('error', `✗ opus check: ${error}`)
+    process.exit(1)
+  }
+  log('success', '✓ opus check: artefatos materializados estão atualizados.')
+}
+
 async function cmdCreate(dir, flags) {
   if (!dir) {
     log('error', 'Uso: opus create <dir> — o nome do diretório vira o nome do app (--monorepo: a raiz do workspace).')
@@ -224,6 +241,9 @@ async function cmdCreate(dir, flags) {
   }
 
   const r = await createProject(REGISTRY_DIR, target, name)
+  if (!r.setup.materialization.ok) {
+    throw new Error(`setup incompleto: ${r.setup.materialization.errors.join(' | ')}`)
+  }
   const modeLabel = r.mode === 'app' ? 'app no monorepo (workspace detectado)' : 'repo standalone'
   log('success', `✓ opus create: app "${name}" criado (base v${r.version}, ${modeLabel}).`)
   console.log(`\n  ${r.files.length} arquivos do esqueleto + setup (${r.setup.created.join(', ')}).`)
@@ -238,7 +258,7 @@ async function cmdCreate(dir, flags) {
     pnpm install
     pnpm --filter ${name} test && pnpm --filter ${name} manifest
 
-  Depois: cadastro do app no admin (root/run) → sessão no Maestro.
+  Opcional: cadastre o app em uma interface de desenvolvimento como o Maestro.
 `)
   } else {
     console.log(`
@@ -248,7 +268,7 @@ async function cmdCreate(dir, flags) {
     pnpm install
     pnpm test && pnpm exec opus check src && pnpm manifest
 
-  Depois: repo no GitHub + cadastro no admin (workspace/repo/app/agentes) → sessão no Maestro.
+  Opcional: cadastre o repo em uma interface de desenvolvimento como o Maestro.
 `)
   }
 }
@@ -256,6 +276,10 @@ async function cmdCreate(dir, flags) {
 async function cmdInit() {
   const cwd = process.cwd()
   const r = await initProject(REGISTRY_DIR, cwd)
+  if (!r.materialization.ok) {
+    for (const error of r.materialization.errors) log('error', `✗ opus setup: ${error}`)
+    process.exitCode = 1
+  }
   log('success', `✓ opus setup: app v${r.version} ${r.wasInitialized ? 'atualizado' : 'inicializado'}.`)
   if (r.created.length) {
     console.log('\n  criados (per-app):')
@@ -287,9 +311,8 @@ async function cmdInit() {
   }
 
   console.log(
-    '\n  Per-app: opus.json (pin) + CLAUDE.md. A spec vive nas declarações (description → manifest).\n' +
-      '  A camada-base (.claude agents+skills) é REPO-LEVEL — o Maestro a materializa.\n' +
-      '  Gate de build: opus check.\n',
+    '\n  Per-app: opus.json. No repo: base.json + skills/hooks/instruções comitados.\n' +
+      '  A spec vive nas declarações (description → manifest). Gate: opus check.\n',
   )
 }
 
@@ -378,14 +401,15 @@ async function main() {
 Comandos:
   create <dir>     Scaffolda um app opus-based canônico (vite+react+ui+domínio-exemplo);
                    detecta workspace (app em monorepo); --monorepo cria a RAIZ do workspace
-  setup            Bootstrap PER-APP: grava opus.json + CLAUDE.md (se faltam)
+  setup            Reconcilia opus.json e os artefatos Opus versionados para Claude/Codex
   add <name>       Copia template do registry pro consumer
   list             Lista templates disponíveis
   gen              Gera manifest/openapi/docs/stubs a partir do opus.config.ts
   check [dir]      Valida as convenções das actions (régua de padrão; exit ≠ 0 se violar)
+  pre-push         Gate Git: freshness dos artefatos + convenções das actions
   db <verbo>       Comandos de banco. v1: db check (drift-check entidade ↔ banco)
   introspect [dir] Modelo da estrutura (actions/reactions/schedules + wiring); --json
-  mcp              Server MCP (introspect/check/create-action) — agentes via mcp_config
+  mcp              Server MCP (introspect/check/scaffold de action) — agentes via mcp_config
   help             Mostra esta mensagem
 
 Flags:
@@ -411,8 +435,8 @@ Scaffolda um app opus-based CANÔNICO no diretório <dir> (recusa dir não-vazio
 O esqueleto versiona com a base — nasce com os pré-requisitos plugados:
   protocolo   opus.config.ts + domínio-exemplo + manifest/scripts (+ teste verde)
   UI          vite + react + tailwind v4 CSS-first (tema + @source do Opus)
-  Maestro     dev server na porta injetada (PORT) + allowedHosts do preview
-  dia zero    opus.json, CLAUDE.md (bloco), .claude/memory/, CI de fábrica
+  desenvolvimento dev server na porta injetada (PORT) + allowedHosts do preview
+  dia zero    opus.json + skills/hooks/instruções comitados no repo
 
 Depois: git init && pnpm install && pnpm test — e cadastre repo/app no admin.
 `)
@@ -427,16 +451,16 @@ Depois: git init && pnpm install && pnpm test — e cadastre repo/app no admin.
       console.log(`
 @softize/opus setup
 
-Bootstrap PER-APP de um projeto pra usar a base (idempotente):
-  opus.json        marcador com a versão da base pinada (fonte da verdade)
-  CLAUDE.md        pointer do protocolo — criado só se faltar (não sobrescreve)
+Setup idempotente de um projeto Opus:
+  opus.json        marcador per-app com a versão do SDK
+  base.json        versão aplicada e eventuais skills excluídas
+  agentes          skills Claude/Codex, hook, instruções, pre-push e CI comitados
 
 Fundação de UI (só apps web — preset Tailwind + tema + flags do Opus):
   tailwind.config  criado se faltar; senão avisa pra estender o preset
   tema/tsconfig/dep — avisa o que falta plugar (não edita seus arquivos: sem clobber)
 
-A camada-base (agents/skills) é REPO-LEVEL — materializada pelo MAESTRO (o regente),
-NÃO pelo setup. Roda manual ou via postinstall.
+O próprio pacote materializa somente seus artefatos. Base e Maestro são opcionais.
 `)
       return
     }
@@ -500,6 +524,12 @@ passa verde). Default dir: cwd.
     return
   }
 
+  if (command === 'pre-push') {
+    if (rest[0] === 'materialization') await cmdMaterializationCheck()
+    else await cmdCheck(rest[0] ?? '.')
+    return
+  }
+
   if (command === 'db') {
     await cmdDb(rest, flags)
     return

package/bin/lib/create.mjs

@@ -3,7 +3,7 @@
  * (`registry/templates/app`). O esqueleto versiona com a base: sai do mesmo tarball que
  * o SDK que ele configura, então nasce certo por construção — os pré-requisitos do
  * protocolo (opus.config/manifest/scripts), da UI (preset+tema v4 CSS-first) e do
- * Maestro (porta injetada, allowedHosts do preview) já vêm plugados.
+ * previews externos (porta injetada, allowedHosts configurável) já vêm plugados.
  *
  * DOIS MODOS, por detecção (sobe do destino procurando `pnpm-workspace.yaml`):
  *   • standalone — repo próprio: o template inteiro (raiz inclusa);
@@ -17,7 +17,7 @@
  *     o npm pack descarta dotfiles do tarball, então a fonte não pode tê-los;
  *   • tokens `{{APP_NAME}}` e `{{OPUS_VERSION}}` são substituídos em todo arquivo.
  *
- * Depois da cópia roda o `initProject` (setup): opus.json, CLAUDE.md (bloco),
+ * Depois da cópia roda o `initProject` (setup): opus.json e artefatos Opus rastreáveis,
  * `.claude/memory/` e o CI de fábrica (repo-level: acha a raiz pelo `.git`).
  */
 
@@ -201,8 +201,8 @@ export async function createProject(registryDir, targetDir, appName) {
 
   const warnings = mode === 'app' ? await workspaceWarnings(wsRoot, path.resolve(targetDir)) : []
 
-  // Setup por cima: opus.json (pin), CLAUDE.md (bloco), .claude/memory/, CI de fábrica
-  // (os repo-level acham a raiz pelo .git — no monorepo caem na raiz, só-se-faltar).
+  // Setup por cima: opus.json per-app e materialização repo-level. Em monorepo, a raiz
+  // é descoberta pelo Git e recebe skills, hooks, instruções e CI específicos do Opus.
   const setup = await initProject(registryDir, targetDir)
-  return { version, mode, files, warnings, setup: { created: setup.created, warnings: setup.warnings } }
+  return { version, mode, files, warnings, setup }
 }

package/bin/lib/init.mjs

@@ -1,18 +1,9 @@
-/**
- * opus setup — faz um projeto "leigo" passar a CONHECER a base. PER-APP, idempotente:
- *   • grava o marcador `opus.json` (versão da base pinada) — fonte da verdade
- *     que torna o projeto auto-anunciável (Maestro/CI/agente leem isso);
- *   • cria `CLAUDE.md` SE faltar; se existir, atualiza SÓ o bloco gerenciado
- *     (`<!-- opus:base -->…<!-- /opus:base -->`) — fora dele o arquivo é do projeto
- *     e nunca é tocado; arquivo antigo sem marcadores fica 100% intocado.
- *
- * NÃO materializa a camada-base (`.claude`) — isso é REPO-LEVEL, do MAESTRO (pull do
- * admin). Re-rodar atualiza pin + bloco. Roda manual (`opus setup`) ou via postinstall.
- */
+/** opus setup: aplica o marcador per-app e os artefatos Opus rastreáveis no repo. */
 
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { execFileSync } from "node:child_process";
+
+import { materializeOpus, PACKAGE_VERSION } from "./materialize.mjs";
 
 const MARKER = "opus.json";
 
@@ -34,7 +25,7 @@ async function readJson(p) {
 }
 
 /** Raiz do repo (sobe até achar `.git`); sem repo → null (o chamador decide o fallback). */
-async function repoRootOf(dir) {
+export async function repoRootOf(dir) {
   let cur = path.resolve(dir);
   for (;;) {
     if (await exists(path.join(cur, ".git"))) return cur;
@@ -44,86 +35,6 @@ async function repoRootOf(dir) {
   }
 }
 
-/** CI de fábrica do projeto (só se faltar — depois é seu): roda o que existir em cada
- *  package via --if-present, então cresce junto com o projeto sem editar o workflow. */
-function checkWorkflowTemplate() {
-  return `name: check
-
-# Gate de PR/push (gerado pelo \`opus setup\` — edite à vontade, é seu).
-# Roda o que existir em cada package: typecheck, test e manifest:check.
-on:
-  push:
-    branches: [main]
-  pull_request: {}
-  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
-      - name: Typecheck
-        run: pnpm -r --if-present run typecheck
-      - name: Testes
-        run: pnpm -r --if-present run test
-      - name: Formatação
-        run: pnpm -r --if-present run format:check
-      # Manifest commitado tem que estar fresco (spec defasada = diff que mente).
-      - name: Manifest fresco
-        run: pnpm -r --if-present run manifest:check
-`;
-}
-
-const BASE_OPEN = "<!-- opus:base -->";
-const BASE_CLOSE = "<!-- /opus:base -->";
-const BASE_BLOCK_RE = /<!-- opus:base -->[\s\S]*?<!-- \/opus:base -->/;
-
-/**
- * Bloco GERENCIADO do CLAUDE.md — o miolo que o setup mantém em dia quando o Opus
- * evolui (era only-if-missing: template melhorava e projeto antigo nunca via). Fora dos
- * marcadores o arquivo é do projeto e o setup nunca toca. Sem número de versão no texto
- * de propósito: a versão mora no `opus.json` (nada se duplica).
- */
-export function claudeMdBaseBlock() {
-  return `${BASE_OPEN}
-# Opus
-
-Este projeto usa o **Opus** (\`@softize/opus\`), um SDK/protocolo de actions; a versão
-fica pinada em \`opus.json\`.
-
-## Antes de mexer
-- **A camada \`.claude/\` é REPO-LEVEL, materializada — não editar à mão.** Skills, agents
-  e hooks vivem na raiz do repo, postos pelo **orquestrador da base** (o Opus semeia as
-  skills do framework; agents e método são o seu setup). Num monorepo o agente enxerga o
-  repo todo (libs compartilhadas inclusas).
-- **Seu, deste app (per-app):** \`opus.json\` (pin), este \`CLAUDE.md\` (fora do bloco) e o código.
-- **A spec vive nas DECLARAÇÕES:** cada action/entidade carrega o \`description\` (o doc
-  de negócio — a fonte); o \`opus gen\` projeta no manifest. Doc colado na declaração não
-  defasa (a \`domain.md\` à parte foi aposentada).
-- **Gate de build:** \`opus check\` (valida as convenções das actions — defineAction e
-  o split defineContract+bindAction; exit ≠ 0 se violar OU se não achar action nenhuma).
-  Rode antes de commitar/buildar.
-- **Atualizar o Opus:** depois do bump, leia \`node_modules/@softize/opus/CHANGELOG.md\`
-  (breaking = seção **Breaking**, com a migração) e rode os gates — eles apontam o
-  que a mudança cobra do código.
-- **Estado/contratos ao vivo:** \`opus mcp\` (introspect/check/create-action).
-- **Nada se duplica:** estado/contratos+negócio → declarações (\`description\`) → manifest ·
-  quem executa → agents · como se faz uma tarefa → skills. Regra duplicada em vez de
-  apontada é defeito — aponte.
-
-> Bloco gerenciado pelo \`opus setup\` — acompanha o Opus. O que você escrever fora
-> dele é seu; o setup nunca toca.
-${BASE_CLOSE}`;
-}
-
 // =============================================================================
 // Fundação de UI (apps web) — preset Tailwind + tema + flags
 // =============================================================================
@@ -395,152 +306,34 @@ export async function setupUiFoundation(projectDir) {
   return { applicable: true, created, warnings };
 }
 
-/**
- * Inicializa/atualiza um projeto pra usar a base.
- * @returns {Promise<{version:string, created:string[], synced:string[], warnings:string[], wasInitialized:boolean}>}
- */
-/**
- * Onde o `info/exclude` deste repo mora de verdade. `null` = não há onde escrever.
- *
- * Montar `<raiz>/.git/info/exclude` na mão parece óbvio e está errado em **worktree**,
- * que é como toda sessão do Maestro nasce: ali `.git` não é pasta, é um ARQUIVO com um
- * ponteiro (`gitdir: …`). Checar só existência passava, e o `mkdir` seguinte estourava
- * `ENOTDIR` — derrubando o postinstall, e com ele o `pnpm install` inteiro. O sintoma
- * chegava longe da causa: ambiente "subindo" pra sempre, sem erro na tela.
- *
- * Perguntar ao git responde certo nos dois layouts. O caminho montado à mão FICA como
- * rede: `opus setup` roda em postinstall, e num ambiente sem `git` no PATH trocar a
- * resposta por `null` faria a exclusão parar em silêncio — a base voltaria a sujar o
- * `git status` de todo mundo. Só se aplica quando `.git` é pasta; sendo arquivo, sem o
- * git não há como saber pra onde o ponteiro aponta, e chutar é o defeito original.
- */
-function excludePathOf(repoRoot) {
-  try {
-    const p = execFileSync("git", ["rev-parse", "--git-path", "info/exclude"], {
-      cwd: repoRoot,
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-    // `--git-path` devolve relativo ao cwd quando o repo é o próprio cwd.
-    if (p !== "") return path.isAbsolute(p) ? p : path.join(repoRoot, p);
-  } catch {
-    /* sem git no PATH, ou fora de repo — cai na rede abaixo. */
-  }
-  return null;
-}
-
-/** A rede: só vale com `.git` PASTA, que é o layout onde montar o caminho acerta. */
-async function excludePathFallback(repoRoot) {
-  const dotGit = path.join(repoRoot, ".git");
-  try {
-    if (!(await fs.stat(dotGit)).isDirectory()) return null;
-  } catch {
-    return null;
-  }
-  return path.join(dotGit, "info", "exclude");
-}
-
-/** Anexa padrões ao info/exclude do repo (exclusão local, fora do .gitignore). */
-async function gitExclude(repoRoot, patterns) {
-  const excludePath = excludePathOf(repoRoot) ?? (await excludePathFallback(repoRoot));
-  if (excludePath === null) return;
-  let cur = "";
-  try {
-    cur = await fs.readFile(excludePath, "utf-8");
-  } catch {
-    /* exclude novo. */
-  }
-  const have = new Set(cur.split("\n").map((l) => l.trim()));
-  const add = patterns.filter((p) => !have.has(p));
-  if (add.length === 0) return;
-  await fs.mkdir(path.dirname(excludePath), { recursive: true });
-  await fs.writeFile(
-    excludePath,
-    `${cur}${cur.endsWith("\n") || cur === "" ? "" : "\n"}${add.join("\n")}\n`,
-  );
-}
-
-/**
- * Semeia as skills DO PACOTE (registry/skills) em `.claude/skills/` do repo, sem
- * clobber (o Maestro é o reconciliador quando o projeto for regido). Untracked por
- * design: projeção da base, não código do projeto — vai pro info/exclude.
- */
-async function seedRegistrySkills(registryDir, repoRoot) {
-  const from = path.join(registryDir, "skills");
-  if (!(await exists(from))) return 0;
-  let seeded = 0;
-  for (const slug of await fs.readdir(from)) {
-    const src = path.join(from, slug);
-    if (!(await fs.stat(src)).isDirectory()) continue;
-    const dest = path.join(repoRoot, ".claude", "skills", slug);
-    if (await exists(dest)) continue;
-    await fs.cp(src, dest, { recursive: true });
-    seeded += 1;
-  }
-  if (seeded > 0) await gitExclude(repoRoot, [".claude/skills/"]);
-  return seeded;
-}
-
 export async function initProject(registryDir, projectDir) {
+  void registryDir;
   const created = [];
   const synced = [];
-  const pkg = await readJson(path.join(registryDir, "..", "package.json"));
-  const version = pkg?.version ?? "0.0.0";
+  const version = PACKAGE_VERSION;
 
-  // Marcador (sempre regravado — é da base; pina a versão).
   const markerPath = path.join(projectDir, MARKER);
   const prev = await readJson(markerPath);
-  await fs.writeFile(
-    markerPath,
-    JSON.stringify({ base: "@softize/opus", baseVersion: version }, null, 2) +
-      "\n",
-  );
+  const marker = `${JSON.stringify({ package: "@softize/opus", version }, null, 2)}\n`;
+  if (!(await exists(markerPath)) || (await fs.readFile(markerPath, "utf8")) !== marker) {
+    await fs.writeFile(markerPath, marker);
+    (prev === null ? created : synced).push(MARKER);
+  }
 
-  // CLAUDE.md — cria se faltar; se existir, atualiza SÓ o bloco gerenciado (o resto é
-  // do projeto). Arquivo antigo sem marcadores = 100% do projeto, intocado. A domain.md
-  // foi APOSENTADA (13/06/2026): a spec vive nas declarações (`description`).
+  // Remove somente o bloco legado que o próprio setup antigo declarava como gerenciado.
   const claudePath = path.join(projectDir, "CLAUDE.md");
-  const block = claudeMdBaseBlock();
-  if (!(await exists(claudePath))) {
-    await fs.writeFile(claudePath, `${block}\n`);
-    created.push("CLAUDE.md");
-  } else {
+  if (await exists(claudePath)) {
     const cur = await fs.readFile(claudePath, "utf-8");
-    if (BASE_BLOCK_RE.test(cur)) {
-      // Replacement por função: o bloco tem `$` em potencial (template) — literal, sem
-      // os padrões especiais do replace.
-      const next = cur.replace(BASE_BLOCK_RE, () => block);
-      if (next !== cur) {
-        await fs.writeFile(claudePath, next);
-        synced.push("CLAUDE.md");
-      }
+    const next = cur.replace(/<!-- opus:base -->[\s\S]*?<!-- \/opus:base -->\s*/g, "");
+    if (next !== cur) {
+      await fs.writeFile(claudePath, next);
+      synced.push("CLAUDE.md (bloco legado removido)");
     }
   }
 
-  // Dia zero REPO-level — mas só do que é DO PROJETO (tracked, viaja no git):
-  //   • semente da memória versionada (política da skill memory; sem o dir, o hook
-  //     link-memory-on-start no-opa e a sessão roda amnésica);
-  //   • CI de fábrica (check.yml) se faltar.
-  // A camada-base do ADMIN (agents + skills de metodologia) segue sendo do MAESTRO;
-  // as skills DO PACOTE (registry/skills) entram aqui: esqueleto standalone não pode
-  // nascer sem o que o próprio tarball carrega (projeção untracked, git-excluded —
-  // o Maestro re-materializa por cima quando reger o projeto).
   const repoRoot = (await repoRootOf(projectDir)) ?? projectDir;
-  const seededSkills = await seedRegistrySkills(registryDir, repoRoot);
-  if (seededSkills > 0)
-    created.push(`.claude/skills/ (${seededSkills} da base, untracked)`);
-  const memDir = path.join(repoRoot, ".claude", "memory");
-  if (!(await exists(memDir))) {
-    await fs.mkdir(memDir, { recursive: true });
-    await fs.writeFile(path.join(memDir, "MEMORY.md"), "");
-    created.push(".claude/memory/ (repo)");
-  }
-  const ciPath = path.join(repoRoot, ".github", "workflows", "check.yml");
-  if (!(await exists(ciPath))) {
-    await fs.mkdir(path.dirname(ciPath), { recursive: true });
-    await fs.writeFile(ciPath, checkWorkflowTemplate());
-    created.push(".github/workflows/check.yml (repo)");
-  }
+  const materialization = materializeOpus(repoRoot, "setup");
+  synced.push(...materialization.changes);
 
   // Avisos de dia zero (sem clobber — igual à fundação de UI): o que falta plugar à mão.
   const warnings = [];
@@ -551,6 +344,5 @@ export async function initProject(registryDir, projectDir) {
     );
   }
 
-  if (!prev) created.unshift(MARKER);
-  return { version, created, synced, warnings, wasInitialized: prev !== null };
+  return { version, created, synced, warnings, wasInitialized: prev !== null, materialization };
 }