@aksp/opencrew 1.4.2 → 1.6.0

package/CHANGELOG.md

@@ -3,6 +3,69 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.6.0] — 2026-10-02
+
+Trilha U2 "Crew que conhece o projeto" + U6 "Convivência" (`specs/fase-u2-crew-que-conhece-o-projeto.md`).
+
+### Added
+- **`fontes:` no `crew.yaml`** — arquivos/pastas do projeto (caminho relativo) que a crew lê em todo
+  run e trata como verdade; o discovery pergunta quais são.
+- **Conferência de fontes** (`_opencrew/core/scripts/conferir-fontes.mjs`) no início de cada run:
+  arquivo movido → acha o novo lugar e oferece corrigir (`--corrigir`, com `.bak`); nome diferente →
+  lista a pasta; caminho absoluto → alerta "não é portátil". No uso real (Projeto B) achou os 5
+  caminhos quebrados pela reorganização, cada um com o lugar exato.
+- **Correção gravada na hora** — o que o usuário corrige num checkpoint vai para a memória antes do
+  próximo passo; termo removido vira proibição entre aspas (trava do verificador); conflito com o
+  `company.md` gera a pergunta "Atualizo o perfil da empresa?".
+- **`_opencrew/best-practices.local/`** — best-practices do usuário (aprendidas/criadas), lidas antes
+  das do core e nunca tocadas pelo `update`; o verificador também lê os limites dali primeiro.
+
+### Changed
+- **`update` completo e seguro**: entrega pastas novas do framework (agentes-base, config, templates
+  de crew) sem sobrescrever; guarda em `.opencrew-backup/<data>/` o que o usuário editou antes de
+  substituir (manifesto `_opencrew/manifest.json`); recusa voltar para versão mais antiga; atualiza
+  as pontes **só das IDEs instaladas**; faz merge do Playwright no `.mcp.json` (saída em
+  `_opencrew/logs/playwright/`, outros servidores intactos); avisa sobre pontes antigas (`opensquad`).
+- **Convivência**: pontes e bloco do `AGENTS.md` só ativam o OpenCrew com `/opencrew` (ou pedido
+  sobre crews) e apontam direto para `_opencrew/core/system.md`; outras instruções do projeto têm
+  prioridade no resto.
+- Migração do formato de memória faz `memories.md.bak` e avisa (fim do reset silencioso); regra única
+  sobre o que vai para a memória (só feedback explícito).
+- `_build/discovery.yaml` agora em `crews/{code}/_build/`; build grava caminhos relativos à raiz.
+## [1.5.0] — 2026-10-02
+
+Trilha U1 "Revisor com dentes" — primeira melhoria vinda do uso real
+(`docs/jornada/2026-10-02-uso-real.md`, `specs/fase-u1-revisor-com-dentes.md`).
+
+### Added
+- **Verificador automático** (`_opencrew/core/scripts/verificar.mjs`, Node puro): mede o texto
+  ANTES do revisor usando os limites `constraints:` dos best-practices — título e meta description
+  do blog, legenda e hashtags do Instagram, slides do carrossel, post do LinkedIn, tweets, links
+  (alerta quando abaixo do mínimo). Bloqueia placeholders (`wa.me/55…9999…`, `[Empresa X]`,
+  `lorem ipsum`…), termos entre aspas em `## Proibições Explícitas` da memória da crew e
+  `[PREENCHER: …]`; alerta afirmações em 1ª pessoa com dado concreto (R$, %, ano passado,
+  "N clientes"). Relatório em PT-BR com valor medido × limite; última linha
+  `VERIFICACAO:OK | BLOQUEADA | AGUARDANDO_USUARIO`.
+- **Regras de veracidade** injetadas em todo passo de criação: nunca inventar casos, depoimentos,
+  números ou histórias em 1ª pessoa — usar `[PREENCHER: o que falta]`.
+
+### Changed
+- **Revisão com trava**: antes de todo passo com `on_reject`, o runner verifica **todas** as saídas
+  desde o redator (não só a entrada do revisor — no uso real as legendas nunca eram revisadas);
+  `VERIFICACAO:BLOQUEADA` força REJECT seja qual for a nota; no limite de ciclos o usuário escolhe
+  corrigir, aceitar (registrado) ou abortar; a aprovação final mostra o resumo e pede os
+  `[PREENCHER]`.
+- `review.md`: o revisor copia os números do relatório (nunca estima), não aprova com bloqueio e
+  tem nota máxima 7/10 com alerta não resolvido. `copywriting.md` e o build: regra de não inventar.
+- **Instagram em 4:5**: carrossel/feed agora 1080×1350 (a API do Instagram só publica de 4:5 a
+  1,91:1), no máximo 10 slides; presets do `image-creator`, `template-designer` (e modelos-base),
+  `image-fetcher` e best-practices atualizados. Limites com nomes canônicos (`hashtags_max`).
+
+### Internal
+- Docs de jornada (`docs/jornada/`: uso real, roteiro de teste U0, medições) e roadmap de trilhas U.
+- Regras de dev 12 (limite só vale se medido) e 13 (PT-BR para o usuário); alerta de tamanho e
+  lint cobrem os scripts do runtime.
+
 ## [1.4.2] — 2026-10-02
 
 Hotfix "parar de causar dano" (Fase 1 da auditoria — `specs/fase-1-hotfix.md`).

package/README.md

@@ -35,6 +35,15 @@ dentro da sua IDE.**
 - 🎛️ **Seleção inteligente de agentes** — o sistema analisa seu pedido e
   sugere quais agentes são necessários para aquela tarefa. Você confirma ou
   ajusta com um clique. Agentes pulados não gastam tokens naquele run.
+- 🔎 **Revisor com dentes** — antes da revisão, um verificador automático mede o texto
+  (tamanho de título, meta description, legenda, hashtags, slides), barra placeholders,
+  termos que você proibiu e `[PREENCHER]` pendentes, e aponta afirmações a confirmar.
+  Bloqueio não passa, seja qual for a nota do revisor. A crew não inventa casos nem números:
+  quando falta um dado real, ela pergunta na aprovação final.
+- 📂 **Crew que conhece o projeto** — liste em `fontes:` os arquivos e pastas do seu projeto
+  (decisões, calendário, manual de marca) e a crew os lê em todo run, tratando-os como verdade.
+  Reorganizou as pastas? No início do run ela confere os caminhos, acha para onde o arquivo foi
+  e oferece corrigir. Correções que você faz num checkpoint ficam gravadas na hora.
 
 ---
 
@@ -196,28 +205,31 @@ meu-projeto/
 ## Mantendo o OpenCrew atualizado
 
 ```bash
-npx @aksp/opencrew update
+npx @aksp/opencrew@latest update
 ```
 
-O `update` não toca nas suas crews nem na sua memória. Ele atualiza apenas:
+Um único comando traz **todas** as melhorias para quem já usa uma versão antiga — sem perder
+o que você fez:
 
 | O que é atualizado | O que NUNCA é tocado |
 |---|---|
-| `_opencrew/core/` (framework — sobrescrito por inteiro) | `crews/` (suas crews) |
-| Skills do catálogo (sobrescritas — edições locais se perdem) | `_opencrew/_memory/` (perfil, preferências) |
-| `_opencrew/core/system.md` | `.env` (suas chaves) |
-| Bloco `<!-- opencrew -->` no `AGENTS.md` | Pontes das IDEs (`CLAUDE.md`, `.cursor/`, `.agents/`…) |
+| `_opencrew/core/` (framework) e skills do catálogo | `crews/` (suas crews) |
+| Pastas novas do framework (agentes-base, config) — só o que falta | `_opencrew/_memory/` (perfil, preferências) |
+| Pontes das IDEs **que você já tem instaladas** (nunca cria de IDE nova) | `_opencrew/best-practices.local/` (suas best-practices) |
+| Bloco `<!-- opencrew -->` do `AGENTS.md`/`CLAUDE.md` (o resto do arquivo fica intacto) | `.env` (suas chaves) |
+| Servidor Playwright no `.mcp.json` (outros servidores intactos) | |
 
-As **pontes das IDEs não são atualizadas** pelo `update`. Para regravá-las com a versão
-atual, use:
+- **Editou um arquivo do framework ou um skill do catálogo?** Antes de substituir, o `update`
+  guarda a sua versão em `.opencrew-backup/<data>/` e lista o que copiou.
+- **Versão mais nova instalada?** O `update` não volta para uma versão mais antiga (cache do
+  `npx`): ele para e pede `npx @aksp/opencrew@latest update`.
+
+Para regravar as pontes de IDEs específicas (ou adicionar uma IDE nova):
 
 ```bash
 npx @aksp/opencrew init --repair-bridges --ide=claude-code
 ```
 
-(troque `claude-code` pelas IDEs que você usa, separadas por vírgula; sem `--ide`, o
-comando grava as pontes de **todas** as IDEs suportadas).
-
 Se você está migrando de uma versão anterior a v1.3, o `update` detecta
 AGENTS.md legados (sistema completo de 150 linhas) e os substitui pela ponte
 fina. Desde a v1.4.2 o arquivo original é copiado antes para `AGENTS.md.bak` (até a v1.4.1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "publishConfig": {
     "access": "public"
   },

package/src/commands/init.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { templatesDir, packageJsonPath } from '../lib/paths.js';
-import { copyDir, exists, writeFileSafe, readJson, writeBridgeFile } from '../lib/fsx.js';
+import { exists, writeFileSafe, readJson, writeBridgeFile } from '../lib/fsx.js';
+import { newDelivery, deliverTree, deliverFile, writeManifest, readManifest } from '../lib/manifest.js';
 import { ideById, allIdeIds, AGENTS_BRIDGE } from '../lib/ides.js';
 import { pickIdes as promptIdes } from '../lib/prompts.js';
 import { UsageError } from '../lib/errors.js';
@@ -26,7 +27,10 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
     const ids = await resolveIdes(opts, async () => allIdeIds());
     log(`\n${c.bold(c.cyan('opencrew'))} ${c.dim('v' + version)} — repairing IDE bridges`);
     log(c.dim(`Target: ${target}\n`));
-    await writeBridges(target, ids, { overwrite: true });
+    const previous = await readManifest(target);
+    const repairCtx = newDelivery(target, previous);
+    await writeBridges(target, ids, { overwrite: true, ctx: repairCtx });
+    await writeManifest(target, version, { ...(previous?.files ?? {}), ...repairCtx.files });
 
     log(`\n${c.green(c.bold('Done!'))} IDE bridges regenerated.\n`);
     log(`${c.bold('Next step:')} Restart your IDE, then type ${c.cyan('/opencrew')} to verify.\n`);
@@ -51,7 +55,8 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
 
   // 1. Copy the framework payload (never clobber user work).
   step('Installing framework files');
-  const copied = await installPayload(target);
+  const ctx = newDelivery(target, null);
+  const copied = await installPayload(target, ctx);
   ok(`Framework files ready (${copied} written, existing files preserved)`);
 
   // 2. System doc + root configs.
@@ -59,7 +64,7 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
 
   // Full system definition lives in _opencrew/core/ — never at project root.
   // The root AGENTS.md is just a thin bridge (like CLAUDE.md, GEMINI.md, etc.).
-  await writeFileSafe(path.join(target, '_opencrew', 'core', 'system.md'), await tpl('AGENTS.md'));
+  await deliverFile(ctx, path.join(target, '_opencrew', 'core', 'system.md'), await tpl('AGENTS.md'), { overwrite: true });
   ok('_opencrew/core/system.md (full system definition)');
 
   const agentsResult = await writeBridgeFile(path.join(target, 'AGENTS.md'), AGENTS_BRIDGE);
@@ -78,14 +83,16 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
 
   // 3. IDE bridge files.
   step('Configuring AI IDEs');
-  await writeBridges(target, ids, { overwrite: false });
+  await writeBridges(target, ids, { overwrite: false, ctx });
 
   if (ids.includes('claude-code')) {
     warn(`opencrew ships its own Playwright MCP server (.mcp.json) — disable Claude Code's`);
     warn(`native Playwright plugin/extension to avoid the two conflicting.`);
   }
 
-  // 4. Version stamp — written LAST: it is what marks the install as complete.
+  // 4. Manifest (what OpenCrew delivered — lets `update` spot the user's edits), then the
+  // version stamp LAST: it is what marks the install as complete.
+  await writeManifest(target, version, ctx.files);
   await fs.writeFile(path.join(target, STAMP), version + '\n');
 
   // 5. Done.
@@ -101,21 +108,18 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
  * Never copies the version stamp: only a finished init writes it.
  * @returns {Promise<number>} files written
  */
-export async function installPayload(target) {
-  let count = 0;
-  const onCopy = () => (count += 1);
-  await copyDir(path.join(templatesDir, '_opencrew'), path.join(target, '_opencrew'), {
+export async function installPayload(target, ctx = newDelivery(target, null)) {
+  await deliverTree(ctx, path.join(templatesDir, '_opencrew'), path.join(target, '_opencrew'), {
     overwrite: false,
     // Never ship stray logs, browser sessions or the template's own stamp.
     skip: (rel) =>
       (rel.startsWith('logs/') && rel !== 'logs/.gitkeep') ||
       rel.startsWith('_browser_profile/') ||
       rel === '.opencrew-version',
-    onCopy,
   });
-  await copyDir(path.join(templatesDir, 'skills'), path.join(target, 'skills'), { overwrite: false, onCopy });
-  await copyDir(path.join(templatesDir, 'crews'), path.join(target, 'crews'), { overwrite: false });
-  return count;
+  await deliverTree(ctx, path.join(templatesDir, 'skills'), path.join(target, 'skills'), { overwrite: false });
+  await deliverTree(ctx, path.join(templatesDir, 'crews'), path.join(target, 'crews'), { overwrite: false });
+  return ctx.written;
 }
 
 /** 'none' (no core) · 'partial' (core without stamp: interrupted install) · 'complete'. */
@@ -148,7 +152,7 @@ async function resolveIdes(opts, fallback) {
  * @param {string[]} ids — validated IDE ids to configure
  * @param {{ overwrite: boolean }} opts
  */
-async function writeBridges(target, ids, { overwrite }) {
+async function writeBridges(target, ids, { overwrite, ctx }) {
   const writtenPaths = new Set();
 
   for (const id of ids) {
@@ -162,7 +166,7 @@ async function writeBridges(target, ids, { overwrite }) {
       const fp = path.join(target, f.path);
       const hasFrontmatter = f.content.startsWith('---');
       if (hasFrontmatter) {
-        await writeFileSafe(fp, f.content, { overwrite });
+        await deliverFile(ctx, fp, f.content, { overwrite });
       } else {
         const result = await writeBridgeFile(fp, f.content);
         if (result.merged) info(`${f.path} (merged — existing content preserved)`);

package/src/commands/update.js

@@ -1,17 +1,19 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { templatesDir, packageJsonPath } from '../lib/paths.js';
-import { copyDir, exists, writeFileSafe, readJson, writeBridgeFile, readFile } from '../lib/fsx.js';
+import { exists, writeFileSafe, readJson, writeBridgeFile, readFile } from '../lib/fsx.js';
 import { AGENTS_BRIDGE, LEAKED_STATUS_SECTION, ideById } from '../lib/ides.js';
-import { c, log, info, ok, warn, step } from '../lib/ui.js';
-
-// Update refreshes ONLY the framework. It never touches:
-//   crews/, _opencrew/_memory/, _opencrew/_browser_profile/, .env, IDE bridges
-//   (one exception: the CLAUDE.md block leaked by 1.4.0/1.4.1 — see removeLeakedStatusSection).
-// Note: catalog skills (skills/<name>/ that ship with the package) ARE fully
-// overwritten below — user edits to a catalog skill's own files are not preserved.
-// Only skill directories that don't exist in the package's templates/skills/ at all
-// (i.e. custom/user-authored skills) are left untouched.
+import { readManifest, writeManifest, newDelivery, deliverTree, deliverFile } from '../lib/manifest.js';
+import { compareVersions, detectInstalledIdes, refreshBridges, mergeMcp, findLegacyBridges } from '../lib/migrations.js';
+import { c, log, info, ok, warn, err, step } from '../lib/ui.js';
+
+// `update` brings EVERY improvement to people who already use OpenCrew (AGENTS.md rule 14),
+// without losing what they made:
+//   - _opencrew/core and catalog skills are replaced — a file the user edited is copied to
+//     .opencrew-backup/<date>/ first (manifest of hashes; none = copy whatever differs);
+//   - new framework folders (agents, config, crew templates) arrive without overwriting;
+//   - bridges of the IDEs already installed are refreshed (never new IDEs);
+//   - crews/, _opencrew/_memory/, _opencrew/best-practices.local/ and .env are never touched.
 export async function update(opts = {}) {
   const target = process.cwd();
   const pkg = await readJson(packageJsonPath);
@@ -27,14 +29,15 @@ export async function update(opts = {}) {
   const current = (await exists(versionFile))
     ? (await fs.readFile(versionFile, 'utf8')).trim()
     : 'unknown';
+  const newer = current !== 'unknown' && compareVersions(current, version) > 0;
 
   log(`\n${c.bold(c.cyan('opencrew update'))}`);
   log(c.dim(`Installed: ${current}  →  Package: ${version}\n`));
 
   if (opts.check) {
-    if (current === version) {
-      ok(`Up to date (v${version}).`);
-    } else {
+    if (current === version) ok(`Up to date (v${version}).`);
+    else if (newer) info(`A versão instalada (v${current}) é mais nova que este pacote (v${version}).`);
+    else {
       info(`Update available: v${current} → v${version}.`);
       info(`Run ${c.cyan('npx @aksp/opencrew update')} to apply.`);
       process.exitCode = 1;
@@ -42,45 +45,58 @@ export async function update(opts = {}) {
     return;
   }
 
-  if (current === version) {
-    ok('Already up to date. Refreshing framework files anyway.');
+  if (newer) {
+    err(`Você tem a v${current} instalada e este pacote é a v${version} (mais antigo). Nada foi alterado.`);
+    info(`Use ${c.cyan('npx @aksp/opencrew@latest update')}.`);
+    process.exitCode = 1;
+    return;
   }
 
-  // Refresh core framework: _opencrew/core is fully overwritten (it is not user data).
+  const manifest = await readManifest(target);
+  const ctx = newDelivery(target, manifest);
+  const tpl = (...p) => path.join(templatesDir, ...p);
+  const dest = (...p) => path.join(target, ...p);
+
   step('Refreshing framework');
-  let n = 0;
-  await copyDir(path.join(templatesDir, '_opencrew', 'core'), path.join(target, '_opencrew', 'core'), {
-    overwrite: true,
-    onCopy: () => (n += 1),
-  });
-  ok(`_opencrew/core refreshed (${n} files)`);
-
-  // Refresh catalog skills: every skill shipped in templates/skills/ is fully
-  // overwritten (edits to a catalog skill's files do not survive an update).
-  // Skill directories that only exist in the user's project — i.e. not part of
-  // the catalog — are never touched, since copyDir only visits paths that exist
-  // in the source (templates/skills/).
-  step('Refreshing catalog skills');
-  warn('Catalog skills are fully overwritten — your edits to any built-in skill files will be lost.');
-  let s = 0;
-  await copyDir(path.join(templatesDir, 'skills'), path.join(target, 'skills'), {
-    overwrite: true,
-    onCopy: () => (s += 1),
-  });
-  ok(`Catalog skills refreshed (${s} files)`);
-
-  // System doc — full definition in _opencrew/core/, thin bridge at root.
-  const systemContent = await fs.readFile(path.join(templatesDir, 'AGENTS.md'), 'utf8');
-  await writeFileSafe(path.join(target, '_opencrew', 'core', 'system.md'), systemContent);
-  ok('_opencrew/core/system.md refreshed');
+  await deliverTree(ctx, tpl('_opencrew', 'core'), dest('_opencrew', 'core'), { overwrite: true });
+  await deliverFile(ctx, dest('_opencrew', 'core', 'system.md'), await fs.readFile(tpl('AGENTS.md')), { overwrite: true });
+  await deliverTree(ctx, tpl('skills'), dest('skills'), { overwrite: true });
+  // New framework folders (e.g. base agents since 1.3.2): only what is missing.
+  for (const dir of ['agents', 'config', '_investigations']) {
+    await deliverTree(ctx, tpl('_opencrew', dir), dest('_opencrew', dir), { overwrite: false });
+  }
+  await deliverTree(ctx, tpl('crews'), dest('crews'), { overwrite: false });
+  ok(`Framework and catalog skills refreshed (${ctx.written} files written)`);
 
+  step('Refreshing IDE bridges');
   await refreshAgentsBridge(target);
+  const ides = await detectInstalledIdes(target);
+  await refreshBridges(ctx, ides);
+  ok(ides.length ? `Bridges refreshed: ${ides.map((i) => i.label).join(', ')}` : 'No IDE bridges found to refresh');
   await removeLeakedStatusSection(target);
 
+  const mcp = await mergeMcp(target, tpl('.mcp.json'));
+  if (mcp === 'updated' || mcp === 'created') ok(`.mcp.json (Playwright: ${mcp === 'created' ? 'created' : 'saída em _opencrew/logs/playwright/'})`);
+  if (mcp === 'invalid') warn('.mcp.json não é um JSON válido — não alterado. Confira o arquivo.');
+
+  for (const legacy of await findLegacyBridges(target)) {
+    warn(`Ponte antiga encontrada: ${legacy} (aponta para _opensquad/, que não existe neste projeto). Pode apagar com segurança.`);
+  }
+
+  if (ctx.copied.length) {
+    const rel = path.relative(target, ctx.backupDir).split(path.sep).join('/');
+    const what = manifest ? 'que você tinha editado' : 'diferentes do pacote novo';
+    warn(`${ctx.copied.length} arquivo(s) ${what} foram copiados para ${rel}/ antes de serem substituídos:`);
+    for (const f of ctx.copied.slice(0, 15)) log(`    ${f}`);
+    if (ctx.copied.length > 15) log(`    … e mais ${ctx.copied.length - 15}`);
+    if (!manifest) info('Primeira atualização com proteção: sem registro anterior, guardamos tudo o que diferia. Daqui em diante, só o que você editar.');
+  }
+
+  await writeManifest(target, version, ctx.files);
   // Stamp last: a crash above leaves the old version, so the next update retries.
   await fs.writeFile(versionFile, version + '\n');
   log(`\n${c.green(c.bold('Updated to v' + version))}.`);
-  log(c.dim('Your crews, memory, IDE bridges and .env were left untouched.\n'));
+  log(c.dim('Your crews, memory, local best-practices and .env were left untouched.\n'));
 }
 
 // Root AGENTS.md: create it if missing; a legacy full-system doc (pre-v1.3) is backed up

package/src/lib/ides.js

@@ -1,12 +1,18 @@
-// Single source of truth = AGENTS.md (shipped at project root).
-// Every IDE gets only a THIN bridge file that points at AGENTS.md.
+// Single source of truth = _opencrew/core/system.md (from templates/AGENTS.md).
+// Every IDE gets only a THIN bridge file that points at it.
 // Adding support for a new IDE = one more entry in this list.
 
-const BRIDGE = `Read \`AGENTS.md\` at the project root and adopt the opencrew system role.
-Follow all initialization, command routing, and workflow instructions defined there.
+// Coexistence (U6): opencrew only takes over when called — other agent systems in the same
+// project keep priority for everything else.
+const ACTIVATION = `Use opencrew ONLY when the user types \`/opencrew\` or asks to create, run or manage
+AI agent crews. In that case, read \`_opencrew/core/system.md\` and follow its initialization,
+command routing and workflow instructions. For anything else, the other instructions of this
+project take precedence.`;
+
+const BRIDGE = `${ACTIVATION}
 
 If invoked with arguments (e.g. \`/opencrew create ...\`, \`/opencrew run ...\`),
-route to the matching action from the Command Routing table in AGENTS.md.
+route to the matching action from the Command Routing table in \`_opencrew/core/system.md\`.
 If invoked without arguments, show the Main Menu.`;
 
 // Claude Code needs one extra rule (checkpoints must use AskUserQuestion) and a
@@ -20,7 +26,7 @@ description: "opencrew — multi-agent orchestration. Use when the user types /o
 
 ${BRIDGE}
 
-## Claude Code specifics (override AGENTS.md where they conflict)
+## Claude Code specifics (override system.md where they conflict)
 
 - **Checkpoints MUST use \`AskUserQuestion\`** — never output a checkpoint question as plain text.
   Combine multiple questions into a single call (max 4 slots, each with 2–4 options).
@@ -32,7 +38,8 @@ ${BRIDGE}
 const CLAUDE_MD = `# opencrew — Project Instructions
 
 This project uses **opencrew**, a multi-agent orchestration framework.
-The full system definition lives in \`AGENTS.md\` — read it and adopt that role.
+
+${ACTIVATION}
 
 Type \`/opencrew\` to open the main menu.
 
@@ -44,11 +51,7 @@ Type \`/opencrew\` to open the main menu.
 `;
 
 // Root AGENTS.md: thin bridge to the full system definition (written by init and update).
-export const AGENTS_BRIDGE = '# opencrew\n\n'
-  + 'The opencrew system definition lives at `_opencrew/core/system.md`.\n'
-  + 'Read that file and adopt the opencrew system role — follow all initialization,\n'
-  + 'command routing, and workflow instructions defined there.\n\n'
-  + 'Type `/opencrew` to open the main menu.\n';
+export const AGENTS_BRIDGE = `# opencrew\n\n${ACTIVATION}\n\nType \`/opencrew\` to open the main menu.\n`;
 
 // Marker that identifies the maintainer STATUS.md section leaked into CLAUDE.md by 1.4.0/1.4.1.
 export const LEAKED_STATUS_SECTION = '## STATUS.md (gestão de sessão)';

package/src/lib/manifest.js

@@ -0,0 +1,89 @@
+// Manifest of the files OpenCrew delivered (path → sha256). It lets `update` tell a file the
+// user edited (copy it to .opencrew-backup/ before replacing) from one that is just older.
+// Workspaces without a manifest (≤ 1.5.0): any file that differs from the new package is copied.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { exists } from './fsx.js';
+
+export const MANIFEST = path.join('_opencrew', 'manifest.json');
+
+// Text files are hashed with LF line endings: an editor, git or a sync tool switching CRLF/LF
+// must not make a file look "edited by the user". Binary files (with NUL bytes) are hashed as is.
+const normalize = (buf) => {
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+  return b.includes(0) ? b : Buffer.from(b.toString('utf8').replace(/\r\n/g, '\n'));
+};
+const sha = (buf) => createHash('sha256').update(normalize(buf)).digest('hex');
+const rel = (target, abs) => path.relative(target, abs).split(path.sep).join('/');
+
+/** @returns {Promise<{files: Record<string,string>} | null>} null = no (or unreadable) manifest */
+export async function readManifest(target) {
+  try {
+    const data = JSON.parse(await fs.readFile(path.join(target, MANIFEST), 'utf8'));
+    return data && typeof data.files === 'object' ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeManifest(target, version, files) {
+  const sorted = Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
+  await fs.writeFile(path.join(target, MANIFEST), JSON.stringify({ version, files: sorted }, null, 2) + '\n');
+}
+
+/**
+ * Delivery context shared by one init/update run.
+ * @param {string} target project root
+ * @param {{files:Record<string,string>}|null} manifest previous manifest (null = none)
+ */
+export function newDelivery(target, manifest) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return { target, manifest, backupDir: path.join(target, '.opencrew-backup', stamp), files: {}, copied: [], written: 0 };
+}
+
+/**
+ * Put `content` at `dest`. Missing → write. Equal → nothing. Different → only if `overwrite`,
+ * copying the current file to the backup dir first when the user edited it.
+ */
+export async function deliverFile(ctx, dest, content, { overwrite }) {
+  const key = rel(ctx.target, dest);
+  const fresh = sha(content);
+  if (!(await exists(dest))) {
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.writeFile(dest, content);
+    ctx.files[key] = fresh;
+    ctx.written += 1;
+    return;
+  }
+  const current = sha(await fs.readFile(dest));
+  if (current === fresh) {
+    ctx.files[key] = fresh;
+    return;
+  }
+  if (!overwrite) return; // the user's version stays (and is not tracked)
+  const edited = ctx.manifest ? ctx.manifest.files[key] !== current : true;
+  if (edited) {
+    const copy = path.join(ctx.backupDir, key);
+    await fs.mkdir(path.dirname(copy), { recursive: true });
+    await fs.copyFile(dest, copy);
+    ctx.copied.push(key);
+  }
+  await fs.writeFile(dest, content);
+  ctx.files[key] = fresh;
+  ctx.written += 1;
+}
+
+/** deliverFile for every file under `src`, mirrored into `dest`. */
+export async function deliverTree(ctx, src, dest, { overwrite, skip = () => false }) {
+  async function walk(dir) {
+    for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+      const from = path.join(dir, entry.name);
+      const relPath = path.relative(src, from).split(path.sep).join('/');
+      if (skip(relPath)) continue;
+      if (entry.isDirectory()) await walk(from);
+      else await deliverFile(ctx, path.join(dest, relPath), await fs.readFile(from), { overwrite });
+    }
+  }
+  await walk(src);
+}

package/src/lib/migrations.js

@@ -0,0 +1,110 @@
+// What `update` does beyond refreshing _opencrew/core and the catalog skills, so that every
+// improvement reaches people who already use OpenCrew (AGENTS.md rule 14).
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { exists, writeBridgeFile } from './fsx.js';
+import { IDES } from './ides.js';
+import { deliverFile } from './manifest.js';
+
+/** Semver compare (no pre-release tags): >0 if a > b, <0 if a < b, 0 if equal. */
+export function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+const sharedPaths = (() => {
+  const count = new Map();
+  for (const ide of IDES) for (const f of ide.files) count.set(f.path, (count.get(f.path) ?? 0) + 1);
+  return new Set([...count].filter(([, n]) => n > 1).map(([p]) => p));
+})();
+
+async function hasOpencrew(file) {
+  return (await exists(file)) && /opencrew/i.test(await fs.readFile(file, 'utf8'));
+}
+
+/**
+ * IDEs installed in `target`, detected by their own bridge files (a path shared by several
+ * IDEs only counts for an IDE that has no file of its own — e.g. Codex).
+ */
+export async function detectInstalledIdes(target) {
+  const found = [];
+  for (const ide of IDES) {
+    const own = ide.files.filter((f) => !sharedPaths.has(f.path));
+    const probes = own.length ? own : ide.files;
+    for (const f of probes) {
+      if (await hasOpencrew(path.join(target, f.path))) {
+        found.push(ide);
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+/** Rewrite the bridges of the installed IDEs only (frontmatter files whole, others by block). */
+export async function refreshBridges(ctx, ides) {
+  const done = new Set();
+  for (const ide of ides) {
+    for (const f of ide.files) {
+      if (done.has(f.path)) continue;
+      done.add(f.path);
+      const file = path.join(ctx.target, f.path);
+      if (f.content.startsWith('---')) await deliverFile(ctx, file, f.content, { overwrite: true });
+      else await writeBridgeFile(file, f.content);
+    }
+  }
+}
+
+const OUTPUT_DIR = ['--output-dir', '_opencrew/logs/playwright'];
+
+/**
+ * Merge the Playwright server of the template into the project's .mcp.json without touching
+ * other servers. @returns 'created' | 'updated' | 'unchanged' | 'invalid'
+ */
+export async function mergeMcp(target, templateFile) {
+  const file = path.join(target, '.mcp.json');
+  const template = JSON.parse(await fs.readFile(templateFile, 'utf8'));
+  if (!(await exists(file))) {
+    await fs.writeFile(file, JSON.stringify(template, null, 2) + '\n');
+    return 'created';
+  }
+  let current;
+  try {
+    current = JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch {
+    return 'invalid';
+  }
+  current.mcpServers ??= {};
+  const pw = current.mcpServers.playwright;
+  if (!pw) current.mcpServers.playwright = template.mcpServers.playwright;
+  else if (Array.isArray(pw.args) && !pw.args.includes('--output-dir')) pw.args.push(...OUTPUT_DIR);
+  else return 'unchanged';
+  await fs.writeFile(file, JSON.stringify(current, null, 2) + '\n');
+  return 'updated';
+}
+
+const LEGACY_ROOTS = ['.gemini/skills', '.claude/skills', '.agents/skills', '.agent/workflows', '.agent/rules'];
+
+/** Old bridges that point to a system no longer installed (e.g. `_opensquad/`). Never deleted. */
+export async function findLegacyBridges(target) {
+  if (await exists(path.join(target, '_opensquad'))) return [];
+  const found = [];
+  async function walk(dir, depth) {
+    let entries;
+    try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory() && depth < 2) await walk(p, depth + 1);
+      else if (e.isFile() && e.name.endsWith('.md') && /_opensquad\//.test(await fs.readFile(p, 'utf8'))) {
+        found.push(path.relative(target, p).split(path.sep).join('/'));
+      }
+    }
+  }
+  for (const root of LEGACY_ROOTS) await walk(path.join(target, root), 0);
+  return found;
+}

package/templates/.mcp.json

@@ -3,7 +3,7 @@
   "mcpServers": {
     "playwright": {
       "command": "npx",
-      "args": ["@playwright/mcp@0.0.78", "--config", "_opencrew/config/playwright.config.json"]
+      "args": ["@playwright/mcp@0.0.78", "--config", "_opencrew/config/playwright.config.json", "--output-dir", "_opencrew/logs/playwright"]
     }
   }
 }