@aksp/opencrew 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 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

package/README.md

@@ -40,6 +40,10 @@ dentro da sua IDE.**
   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.
 
 ---
 
@@ -201,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.5.0",
+  "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"]
     }
   }
 }

package/templates/AGENTS.md

@@ -115,4 +115,5 @@ enabled, it writes `crews/{name}/state.json` before each step and at every hando
 - ALWAYS save outputs to the crew's output directory
 - When switching personas (inline execution), clearly indicate which agent is speaking
 - When using subagents, inform the user that background work is happening
-- After each pipeline run, update the crew's memories.md with key learnings
+- Crew memory (memories.md) records only the user's explicit feedback and corrections —
+  written at the checkpoint where they happen (see the Pipeline Runner), never invented learnings

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-1.5.0
+1.6.0

package/templates/_opencrew/core/prompts/build.prompt.md

@@ -90,6 +90,18 @@ Generate these files. Use the Write tool for all file creation — never use Bas
        - pipeline/data/anti-patterns.md
        - pipeline/data/tone-of-voice.md  # for content crews
       ```
+    - Include a `fontes:` section with the project sources from `discovery.yaml →
+      project_sources` (omit it only if that list is empty). The Pipeline Runner reads them at the
+      start of every run and checks they still exist:
+      ```yaml
+      fontes:
+        - caminho: Memoria/01_Decisoes.md      # relative to the project root
+          para_que: decisões de público e posicionamento
+      ```
+    - **Paths to the user's project files** — in `crew.yaml`, step files and tasks — are always
+      written as a caminho relativo à raiz do projeto (relative to the project root), between
+      backticks, e.g. `` `Ativos/Identidade Visual/logo.png` ``. NEVER write absolute paths
+      (`C:/…`, `J:/…`, `/Users/…`): they break as soon as the user moves or syncs the folder.
     - Include an `agent_dependencies:` section (OPTIONAL — enables runtime
       Pre-Execution Agent Selection):
       ```yaml

package/templates/_opencrew/core/prompts/discovery.prompt.md

@@ -117,6 +117,14 @@ Based on the detected domain, ask the most relevant contextual question first. W
 **If domain = `mixed`:**
 Ask the most pressing question from each relevant domain, starting with the primary one. Cap at 3 questions total in this step.
 
+**Always (any domain) — project sources (fontes):** ask ONE question:
+"Tem arquivos ou pastas deste projeto que a crew deve consultar sempre? (por exemplo: decisões,
+calendário de eventos, manual de marca, pasta de logos). Pode citar o caminho ou o nome."
+If the user names files/folders, confirm each one exists (search the project if only a name was
+given) and store them in `project_sources` with paths **relative to the project root** (never
+absolute — absolute paths break when the folder is moved or synced to another computer).
+If the user says no, store an empty list.
+
 ---
 
 ### Step 4 — Tools and Integrations (automatic)
@@ -234,12 +242,17 @@ Wait for confirmation before writing the output file.
 
 ---
 
-## Output: `_build/discovery.yaml`
+## Output: `crews/{code}/_build/discovery.yaml`
 
-After the user confirms in Step 7, write the following file:
+After the user confirms in Step 7, write the following file **inside the crew folder** —
+`crews/{code}/_build/discovery.yaml` (never at the project root; `{code}` = the unique
+`crew_code` below):
 
 ```yaml
 crew_code: "{slugified crew name from purpose}"
+project_sources:                     # relative to the project root; becomes `fontes:` in crew.yaml
+  - path: "{e.g. Memoria/01_Decisoes.md}"
+    purpose: "{what the crew uses it for}"
 purpose: "{user's description from Step 1}"
 domain: "{content | research | automation | analysis | mixed}"
 # When a template was used (Step 0), these fields are populated from discovery.template.yaml:

package/templates/_opencrew/core/runner.pipeline.md

@@ -52,8 +52,12 @@ Before starting execution:
    [ -f crews/{name}/_memory/memories.md ] && grep -q "## Estilo de Escrita" crews/{name}/_memory/memories.md && echo "NEW_FORMAT" || echo "OLD_FORMAT"
    ```
    - If `NEW_FORMAT` → proceed normally.
-   - If `OLD_FORMAT` (or file is empty / does not exist) → silently migrate before proceeding:
-     a. Write `crews/{name}/_memory/memories.md` with the new empty-sections format (do NOT attempt to salvage content from the old file — reset unconditionally):
+   - If `OLD_FORMAT` (or file is empty / does not exist) → migrate before proceeding:
+     a0. If the file exists and is not empty, FIRST copy it to `crews/{name}/_memory/memories.md.bak`
+        (never lose what the crew learned), then tell the user in one line:
+        "Atualizei o formato da memória da crew; a versão anterior está em `memories.md.bak`."
+        Move every rule you can recognize from the old file into the matching new section.
+     a. Write `crews/{name}/_memory/memories.md` with the new sections format:
         ```markdown
         # Crew Memory: {crew-name}
 
@@ -79,7 +83,31 @@ Before starting execution:
         | Data | Run ID | Tema | Output | Score | Resultado |
         |------|--------|------|--------|-------|-----------|
         ```
-   - Do NOT inform the user or pause execution for this migration — it is transparent.
+   - Do not pause execution for this migration (the one-line notice above is enough).
+
+1c. **Project sources (`fontes:`)** — if `crew.yaml` has a `fontes:` list (files or folders of
+    the user's project, paths relative to the project root), read them now: a file in full up to
+    ~300 lines, otherwise its headings plus the passages relevant to this run's task; a folder as
+    its file list. Treat them as the **truth of the project**: when they disagree with the
+    briefing, the research or your own assumptions, the sources take precedence over them
+    (as fontes valem sobre o briefing e a pesquisa) — and say so when it matters.
+
+1d. **Source check** — before the first step, run:
+    ```bash
+    node _opencrew/core/scripts/conferir-fontes.mjs --crew crews/{name}
+    ```
+    If the last line is `FONTES:PENDENTE` (a cited file was moved, renamed or deleted), show the
+    report and ask — never continue silently with a missing source:
+    ```
+    Alguns arquivos que a crew usa não estão mais onde ela espera:
+    {resumo do relatório}
+
+    1. Corrigir os caminhos sugeridos (troco nos arquivos da crew e guardo .bak)
+    2. Seguir assim mesmo
+    3. Parar
+    ```
+    On 1, run the same command with `--corrigir` and show the new result. Not-portable alerts
+    (absolute paths) are mentioned once, without stopping.
 
 2. Read `crews/{name}/pipeline/pipeline.yaml` for the pipeline definition
 3. **Resolve skills**: Read `crew.yaml` → `skills` section. For each non-native skill (anything other than web_search, web_fetch):
@@ -261,8 +289,10 @@ Before executing any step that references an agent:
       - The agent must follow the export process for the specified format — read the input file,
         transform the content, and write the output file in the target format.
       - Skip the best-practices lookup below for export formats.
-   b. **Content formats** — otherwise, read `_opencrew/core/best-practices/{format}.md` (e.g., `_opencrew/core/best-practices/instagram-feed.md`)
-      - If the file does not exist → **WARNING**: "Format '{format}' not found in _opencrew/core/best-practices/. Skipping format injection." Continue without format.
+   b. **Content formats** — otherwise, read `_opencrew/best-practices.local/{format}.md` (the user's
+      own version, never touched by `update`) if it exists, else `_opencrew/core/best-practices/{format}.md`
+      (e.g., `_opencrew/core/best-practices/instagram-feed.md`)
+      - If neither exists → **WARNING**: "Format '{format}' not found in _opencrew/best-practices.local/ or _opencrew/core/best-practices/. Skipping format injection." Continue without format.
    c. Parse the YAML frontmatter to extract the `name` field
    d. Extract the Markdown body (everything after the YAML frontmatter closing `---`)
    e. Append to the agent's context, before skill instructions:
@@ -530,6 +560,14 @@ Apply this transformation consistently for every write in this step.
 - **Always include the file path** of any generated content the user needs to review. Example: "Review the content at `crews/{name}/output/{run_id}/v1/content.md` and let me know if it looks good."
 - Wait for user input before proceeding
 - Save the user's choice/response for the next step
+- **Correction → memory, right away**: if the answer corrects something (tone, audience, a term,
+  a fact, a format), write it to `crews/{name}/_memory/memories.md` in the matching section
+  **before the next step** (antes do próximo passo) — not only at the end of the run, which may
+  never come. A term the user asked to remove goes to `## Proibições Explícitas` **between
+  quotes** (entre aspas: `- Nunca usar "termo"`), so the automatic checker blocks it next time.
+- **Correction vs. company profile**: if the correction contradicts `_opencrew/_memory/company.md`
+  (e.g. the organization's name, the main audience), ask: "Isso vale para todas as crews?
+  Atualizo o perfil da empresa?" — change `company.md` only after a yes.
 - **If the step frontmatter contains `outputFile`**: after collecting the user's full response,
   apply the Output Path Transformation **Step 1 only** (run_id injection — skip Step 2, version folder) to the `outputFile` path, then write the response to the transformed path using the Write tool before moving to the next step. Checkpoint files are user input captures, not versioned output — Step 2 does not apply here, regardless of the general "every write" rule in the Output Path Transformation section above.
   Use this format:
@@ -766,7 +804,7 @@ This archives the run state for the `runs` command while keeping crew history av
    - Run scores, review grades, output file paths, topics from past runs
 
    **Technical routing:** For any technical learning (bugs, workarounds, API behavior):
-   - If it affects any crew (Playwright bugs, OS rendering quirks, API limits) → write to the appropriate `_opencrew/core/best-practices/` file instead of `memories.md`
+   - If it affects any crew (Playwright bugs, OS rendering quirks, API limits) → write to `_opencrew/best-practices.local/{format}.md` instead of `memories.md` (copy the core file there first if the local one does not exist yet — the core folder is replaced by every `update`; the local one is never touched)
    - If it is specific to this crew's output type or toolchain → add to `## Técnico (específico do crew)` following the dedup rules above
 
    After applying all candidates, write the updated `memories.md`.

package/templates/_opencrew/core/scripts/conferir-fontes.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+// Conferência de fontes do OpenCrew — no início do run, confere se os arquivos que a crew cita
+// existem. Se foram movidos, sugere o novo caminho (relativo à raiz do projeto); se o nome mudou,
+// lista o que existe na pasta esperada. Nunca apaga nada; só corrige com --corrigir (e .bak).
+// Uso: node _opencrew/core/scripts/conferir-fontes.mjs --crew crews/<nome> [--corrigir]
+// Última linha da saída: FONTES:OK ou FONTES:PENDENTE (o runner lê esta linha).
+// Spec: specs/fase-u2-crew-que-conhece-o-projeto.md (repositório do OpenCrew).
+import { readFile, writeFile, readdir, copyFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const IGNORAR = new Set(['node_modules', 'output', '_opencrew', '_build']);
+const LIMITE_ENTRADAS = 20000;
+
+const barra = (p) => p.split(path.sep).join('/');
+const ehAbsoluto = (p) => /^[A-Za-z]:[\\/]/.test(p) || p.startsWith('/');
+
+function pareceCaminho(t) {
+  if (/[{}<>*$|]/.test(t) || /^https?:/i.test(t) || !/[\\/]/.test(t)) return false;
+  return /\.[A-Za-z0-9]{1,5}$/.test(t) || /[\\/]$/.test(t);
+}
+const saidaDeRun = (t) => /(^|[\\/])(output|_build)[\\/]/.test(t);
+
+/** Caminhos citados entre crases no crew.yaml e nos passos, mais as `fontes:` do crew.yaml. */
+async function coletar(raiz, crew) {
+  const refs = new Map();
+  const add = (ref, arquivo) => {
+    if (!refs.has(ref)) refs.set(ref, new Set());
+    refs.get(ref).add(arquivo);
+  };
+  const crewYaml = path.join(raiz, crew, 'crew.yaml');
+  const passos = path.join(raiz, crew, 'pipeline', 'steps');
+  const arquivos = existsSync(crewYaml) ? [crewYaml] : [];
+  if (existsSync(passos)) {
+    for (const f of await readdir(passos)) if (f.endsWith('.md')) arquivos.push(path.join(passos, f));
+  }
+  for (const arquivo of arquivos) {
+    const texto = await readFile(arquivo, 'utf8');
+    for (const m of texto.matchAll(/`([^`\n]+)`/g)) {
+      const t = m[1].trim();
+      if (pareceCaminho(t) && !saidaDeRun(t)) add(t, arquivo);
+    }
+    if (arquivo === crewYaml) {
+      for (const m of texto.matchAll(/^\s*-?\s*caminho:\s*["']?([^"'\n#]+?)["']?\s*$/gm)) add(m[1].trim(), arquivo);
+    }
+  }
+  return refs;
+}
+
+function resolver(raiz, crew, ref) {
+  if (ehAbsoluto(ref)) return existsSync(ref) ? path.resolve(ref) : null;
+  for (const base of [path.join(raiz, crew), raiz]) {
+    const p = path.resolve(base, ref);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/** Índice nome-do-arquivo → caminhos relativos, ignorando saídas, dependências e pastas ocultas. */
+async function indexar(raiz) {
+  const porNome = new Map();
+  let n = 0;
+  async function walk(dir) {
+    let entradas;
+    try { entradas = await readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entradas) {
+      if (++n > LIMITE_ENTRADAS) return;
+      if (e.name.startsWith('.') || (e.isDirectory() && IGNORAR.has(e.name))) continue;
+      const abs = path.join(dir, e.name);
+      const chave = e.name.toLowerCase();
+      if (!porNome.has(chave)) porNome.set(chave, []);
+      porNome.get(chave).push(barra(path.relative(raiz, abs)) + (e.isDirectory() ? '/' : ''));
+      if (e.isDirectory()) await walk(abs);
+    }
+  }
+  await walk(raiz);
+  return porNome;
+}
+
+export async function conferir({ raiz, crew }) {
+  const refs = await coletar(raiz, crew);
+  let indice = null;
+  const lista = [];
+  for (const [ref, citado] of refs) {
+    const item = { ref, citadoEm: [...citado], estado: 'ok', sugestao: null, candidatos: [], pasta: [] };
+    const achado = resolver(raiz, crew, ref);
+    if (achado) {
+      if (ehAbsoluto(ref)) {
+        item.estado = 'nao-portatil';
+        const rel = path.relative(raiz, achado);
+        if (!rel.startsWith('..') && !path.isAbsolute(rel)) item.sugestao = barra(rel) + (/[\\/]$/.test(ref) ? '/' : '');
+      }
+    } else {
+      item.estado = 'faltando';
+      indice ??= await indexar(raiz);
+      const nome = path.basename(ref.replace(/[\\/]+$/, '')).toLowerCase();
+      item.candidatos = (indice.get(nome) ?? []).filter((c) => /[\\/]$/.test(ref) === c.endsWith('/'));
+      if (item.candidatos.length === 1) item.sugestao = item.candidatos[0];
+      if (!item.candidatos.length) {
+        const pai = resolver(raiz, crew, path.dirname(ref.replace(/[\\/]+$/, '')));
+        if (pai) {
+          try { item.pasta = (await readdir(pai)).filter((f) => !f.startsWith('.')); } catch { /* não é pasta */ }
+        }
+      }
+    }
+    lista.push(item);
+  }
+  const status = lista.some((i) => i.estado === 'faltando') ? 'PENDENTE' : 'OK';
+  return { crew, raiz, refs: lista, status };
+}
+
+async function copiaDeSeguranca(arquivo) {
+  const bak = existsSync(`${arquivo}.bak`) ? `${arquivo}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}` : `${arquivo}.bak`;
+  await copyFile(arquivo, bak);
+}
+
+/** Troca, nos arquivos da crew, cada caminho com sugestão única. @returns quantos caminhos */
+export async function corrigir({ resultado }) {
+  const comSugestao = resultado.refs.filter((i) => i.sugestao && i.estado !== 'ok');
+  const tocados = new Set();
+  for (const item of comSugestao) {
+    for (const arquivo of item.citadoEm) {
+      const texto = await readFile(arquivo, 'utf8');
+      if (!tocados.has(arquivo)) {
+        await copiaDeSeguranca(arquivo);
+        tocados.add(arquivo);
+      }
+      await writeFile(arquivo, texto.split(item.ref).join(item.sugestao));
+    }
+  }
+  return comSugestao.length;
+}
+
+export function formatar(r) {
+  const rel = (a) => barra(path.relative(r.raiz, a));
+  const linhas = [`## Conferência de fontes — ${r.crew}`, ''];
+  for (const i of r.refs.filter((x) => x.estado !== 'ok')) {
+    const onde = `citado em ${i.citadoEm.map(rel).join(', ')}`;
+    if (i.estado === 'nao-portatil') {
+      linhas.push(`- ⚠️ \`${i.ref}\` é um caminho absoluto (não é portátil — quebra em outro computador).${i.sugestao ? ` Sugestão: \`${i.sugestao}\`` : ''} (${onde})`);
+    } else if (i.sugestao) {
+      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}). Novo caminho sugerido: \`${i.sugestao}\``);
+    } else if (i.candidatos.length) {
+      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}). Encontrei ${i.candidatos.length} candidatos: ${i.candidatos.map((c) => `\`${c}\``).join(', ')}`);
+    } else if (i.pasta.length) {
+      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}). Na pasta esperada existem: ${i.pasta.join(', ')}`);
+    } else {
+      linhas.push(`- ❌ Não encontrei \`${i.ref}\` (${onde}) nem nada com esse nome no projeto.`);
+    }
+  }
+  const ok = r.refs.filter((i) => i.estado === 'ok').length;
+  const pend = r.refs.filter((i) => i.estado === 'faltando').length;
+  const alertas = r.refs.filter((i) => i.estado === 'nao-portatil').length;
+  linhas.push('', `**Resumo: ${r.refs.length} fontes — ${ok} ok, ${pend} pendentes, ${alertas} alertas**`, '');
+  return linhas.join('\n');
+}
+
+/** @returns {Promise<number>} 0 = conferiu · 1 = erro de uso */
+export async function main(argv, { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = {}) {
+  const i = argv.indexOf('--crew');
+  const crew = i > -1 ? argv[i + 1] : null;
+  if (!crew) {
+    escrever('Uso: node _opencrew/core/scripts/conferir-fontes.mjs --crew crews/<nome> [--corrigir]');
+    return 1;
+  }
+  if (!existsSync(path.join(cwd, crew))) {
+    escrever(`Crew não encontrada: ${crew}`);
+    return 1;
+  }
+  let r = await conferir({ raiz: cwd, crew });
+  escrever(formatar(r));
+  if (argv.includes('--corrigir')) {
+    const n = await corrigir({ resultado: r });
+    if (!n) escrever('Nada a corrigir.');
+    else {
+      escrever(`${n} ${n === 1 ? 'caminho corrigido' : 'caminhos corrigidos'} (cópia .bak ao lado de cada arquivo alterado).\n`);
+      r = await conferir({ raiz: cwd, crew });
+      escrever(formatar(r));
+    }
+  }
+  escrever(`FONTES:${r.status}`);
+  return 0;
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+  main(process.argv.slice(2)).then((code) => { process.exitCode = code; });
+}

package/templates/_opencrew/core/scripts/verificar/leitura.mjs

@@ -37,11 +37,16 @@ export function semFrontmatter(texto) {
   return texto.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
 }
 
-/** Limites do formato: `constraints:` de `_opencrew/core/best-practices/<id>.md`. */
+/**
+ * Limites do formato: `constraints:` do best-practice — primeiro o do usuário
+ * (`_opencrew/best-practices.local/<id>.md`, nunca tocado pelo update), depois o do core.
+ */
 export async function lerLimites(raiz, formatoId) {
-  const arquivo = path.join(raiz, '_opencrew', 'core', 'best-practices', `${formatoId}.md`);
-  if (!existsSync(arquivo)) return null;
-  return lerFrontmatter(await readFile(arquivo, 'utf8'))?.constraints ?? {};
+  for (const pasta of [['best-practices.local'], ['core', 'best-practices']]) {
+    const arquivo = path.join(raiz, '_opencrew', ...pasta, `${formatoId}.md`);
+    if (existsSync(arquivo)) return lerFrontmatter(await readFile(arquivo, 'utf8'))?.constraints ?? {};
+  }
+  return null;
 }
 
 /**

package/templates/skills/opencrew-best-practice-creator/SKILL.md

@@ -15,7 +15,7 @@ version: "2.0.0"
 
 # Best-Practice Creator — Workflow
 
-Use this workflow when creating a new best-practice file for the `_opencrew/core/best-practices/` library.
+Use this workflow when creating a new best-practice file. New and customized best-practices live in `_opencrew/best-practices.local/` — the user's own library, read before `_opencrew/core/best-practices/` and never touched by `npx @aksp/opencrew update` (the core folder is replaced on every update).
 
 ## Pre-flight Checks
 
@@ -67,7 +67,7 @@ For each existing best-practice file whose scope overlaps with the new one:
 
 ### 2. Update `_catalog.yaml`
 
-Add a new entry to `_opencrew/core/best-practices/_catalog.yaml` with:
+Add a new entry to `_opencrew/best-practices.local/_catalog.yaml` (create it if missing) with:
 - `id`: matching the frontmatter `id`
 - `name`: matching the frontmatter `name`
 - `whenToUse`: single-line summary of the scope (positive only, no "NOT for")
@@ -77,7 +77,7 @@ Place it under the appropriate section comment (Discipline or Platform best prac
 
 ### 3. File placement
 
-Save to `_opencrew/core/best-practices/{id}.md`.
+Save to `_opencrew/best-practices.local/{id}.md`.
 
 ### 4. Validation
 
@@ -93,7 +93,7 @@ Re-read the created file and verify:
 
 # Best-Practice Updater — Workflow
 
-Use this workflow when updating best-practice files in the `_opencrew/core/best-practices/` library.
+Use this workflow when updating best-practice files. To change a core best-practice, first copy it from `_opencrew/core/best-practices/` to `_opencrew/best-practices.local/` and edit the copy there (the local copy overrides the core one and survives updates).
 
 ## Versioning Rules (Semver)