@aksp/opencrew 1.5.0 → 1.6.1

package/CHANGELOG.md

@@ -3,6 +3,96 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.6.1] — 2026-10-05
+
+Fase R1 "Reparos da 1.6.0: o verificador mede de verdade" (`specs/fase-r1-reparos-1-6-1.md`),
+vinda da revisão das specs (`docs/auditoria/2026-10-04-revisao-specs.md`). Chega a quem já usa com
+um `npx @aksp/opencrew@latest update`.
+
+### Fixed
+- **O verificador mede o texto escrito com rótulos**, do jeito que os próprios best-practices
+  ensinam (`=== CAPTION ===`, `=== HASHTAGS ===`, `=== SLIDES ===`, `=== HOOK ===`, `=== TWEET ===`,
+  `=== TITLE ===`). Antes respondia "Nada a apontar" sem medir.
+- **"Não medido" é dito**: com o formato informado e a peça principal não achada, o relatório
+  alerta em vez de aprovar em silêncio. O resumo passa a ser
+  `X bloqueios, Y alertas, Z não medidos`.
+- **Bloqueios falsos**: cor hexadecimal (`#666666`), número comum, CEP e "XXX Congresso" não são
+  mais "Placeholder"; `{{name}}` em e-mail e WhatsApp vira nota; termo proibido vale como palavra
+  inteira ("IA" não bloqueia "dia a dia"); o termo que o usuário mandou preferir não é proibido.
+- **Arquivo local sem limites não desliga o verificador**: os limites de
+  `_opencrew/best-practices.local/` somam aos do core, chave a chave.
+- **Erros que passavam por OK**: rodar fora da pasta do projeto ou com crew inexistente agora dá
+  erro (código 1), sem linha de status; um arquivo ausente na lista não derruba a verificação dos
+  outros; imagem e `.docx` não são lidos como texto; no HTML, só o texto visível e os links;
+  arquivo de texto fora do UTF-8 vira alerta "Não verificado" (UTF-16 com marca é lido).
+- **Relatório que não saía**: com o projeto aberto por junção ou link de pasta, os dois scripts
+  terminavam sem imprimir nada.
+- **Várias peças no mesmo arquivo** são medidas uma a uma (três posts não viram uma soma); a linha
+  `---` não encerra mais a seção; slides contados nas escritas comuns ("📌 Slide 2", "Slide #3").
+  Título e meta description em bloco YAML (`>-`, `|`) são medidos inteiros; `[PREENCHER: …]`
+  longo não escapa; imagem e link de âncora não contam como link.
+- **Conferência de fontes**: enxerga `caminho:` com comentário ou aspas e os arquivos de `agents/`
+  (agentes e tasks); recusa crew de fora do projeto; mensagens corrigidas ("Não há correção
+  automática…", aviso de busca parcial); caminho com marcador de modelo (`AAAA-MM-DD`) e comando
+  entre crases não são conferidos; o `--corrigir` troca só o caminho citado (antes trocava
+  qualquer trecho igual) e nunca aponta o destino de gravação de um agente para um arquivo que
+  já existe.
+- **`init --repair-bridges`** sem `--ide` regrava só as IDEs instaladas (antes criava as pontes
+  das 9); `--all` regrava todas; o resumo lista as cópias de segurança. Numa pasta sem workspace,
+  para com erro em vez de instalar; num workspace sem manifesto, não cria um.
+
+### Changed
+- **Runner**: passa o formato de cada arquivo ao verificador (`caminho=formato`); laço de revisão
+  com 3 ciclos por padrão (`max_review_cycles`) e saída também quando não há bloqueio; regras do
+  revisor injetadas em toda execução (valem para crews já criadas); avisa quando um script não
+  rodou; a conferência de fontes roda antes de carregar as fontes; a aprovação final mostra o que
+  ficou sem medir e as notas do relatório.
+- Crew nova recebe o limite de ciclos de revisão pelo tier: Express 1, Standard 2, Full 3.
+- Em blog, a seção com cabeçalho de outro canal ("Como postar no LinkedIn") não é medida como
+  post, e o relatório diz isso ("Não medido").
+- Hashtags sob um cabeçalho que cita o canal ("Hashtags LinkedIn") somam à peça desse canal.
+- "Aceitar assim mesmo" não promete mais registro: o registro chega com a entrega por canal.
+- Texto solto depois de uma linha `---` passa a contar na peça de cima. Telefone falso de 8 ou 9
+  dígitos, fora de link, deixa de ser pego.
+
+### Internal
+- Scripts do runtime em módulos (`verificar/`, `conferir-fontes/`, `comum.mjs`); leitor de peças
+  exportado para a próxima fase. Todos os cenários R1 com teste de mesmo ID; teste de upgrade
+  1.6.0 → 1.6.1.
+- Revisão do código antes da tag: sete leituras independentes e duas rodadas de conserto com
+  teste; o que ficou adiado tem destino na spec (§11 e §12).
+- Revisão das specs (265 achados) e faxina de documentos; specs R1, U3a e U3b.
+
+## [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.
 
 ---
 
@@ -139,6 +143,12 @@ enxuto — todos apontam para a mesma fonte.
 | `QWEN.md` (ponte) + `.agents/skills/opencrew/SKILL.md` | Qwen Code |
 | `AGENTS.md` (ponte) + `.trae/rules/opencrew.md` | Trae |
 
+> **Claude Cowork (modo alternativo):** o Cowork não reconhece o comando `/opencrew` (ele não lê
+> skills de dentro da pasta do projeto). Funciona assim: abra a pasta do projeto e peça, em texto:
+> *"Leia o arquivo `_opencrew/core/system.md` deste projeto e siga as instruções dele. Mostre o
+> menu principal."* Depois use frases como "rodar a crew blog-semanal" no lugar dos comandos com `/`.
+
+
 > ⚠️ **Importante:** `CLAUDE.md`, `GEMINI.md` e os demais arquivos de IDE são
 > pontes geradas automaticamente. Eles são finos (5-10 linhas) e usam blocos
 > marcados (`<!-- opencrew:start/end -->`) que permitem **merge não-destrutivo**
@@ -194,34 +204,45 @@ meu-projeto/
 
 > O dashboard visual (`dashboard/index.html`) **não é instalado** pelo `init` — ele vive
 > só no repositório do OpenCrew e ainda é experimental (decisão de publicar ou remover:
-> Fase 4 da auditoria em `docs/auditoria/`).
+> fase U3a — ver `IDEIAS.md` no repositório).
 
 ---
 
 ## 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) | |
+
+- **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`.
 
-As **pontes das IDEs não são atualizadas** pelo `update`. Para regravá-las com a versão
-atual, use:
+Para regravar as pontes de IDE num workspace que já existe:
 
 ```bash
-npx @aksp/opencrew init --repair-bridges --ide=claude-code
+npx @aksp/opencrew@latest init --repair-bridges                    # só as IDEs que você já tem instaladas
+npx @aksp/opencrew@latest init --repair-bridges --ide=claude-code  # só as indicadas (ou uma IDE nova)
+npx @aksp/opencrew@latest init --repair-bridges --all              # as 9 IDEs
 ```
 
-(troque `claude-code` pelas IDEs que você usa, separadas por vírgula; sem `--ide`, o
-comando grava as pontes de **todas** as IDEs suportadas).
+Sem `--ide` e sem `--all`, o `init --repair-bridges` usa a mesma detecção do `update` (aqui o
+`--yes` não escolhe IDE); se não encontra nenhuma ponte, para com erro e pede `--ide=<id>`.
+O reparo não instala: numa pasta sem workspace do OpenCrew ele para com erro e pede o `init`.
+Ponte de arquivo inteiro que você editou (ex.: `.claude/skills/opencrew/SKILL.md`) é copiada
+antes para `.opencrew-backup/<data>/`, e o resumo do `init --repair-bridges` lista cada cópia.
 
 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
@@ -261,12 +282,12 @@ npx @aksp/opencrew update --check
 | Comando | O que faz |
 |---|---|
 | `npx @aksp/opencrew init` | Instala o OpenCrew na pasta atual |
-| `npx @aksp/opencrew update` | Atualiza o framework |
+| `npx @aksp/opencrew@latest update` | Atualiza o framework |
 | `npx @aksp/opencrew update --check` (ou `--dry-run`) | Verifica se há update disponível, sem alterar nada |
 | `npx @aksp/opencrew upgrade` | Atalho para `update` |
 | `npx @aksp/opencrew init --ide=claude-code,cursor` | Instala só as pontes das IDEs indicadas |
 | `npx @aksp/opencrew init --all` (ou `-y`) | Instala as pontes de todas as IDEs |
-| `npx @aksp/opencrew init --repair-bridges` | Regrava as pontes de IDE num workspace existente |
+| `npx @aksp/opencrew@latest init --repair-bridges` | Regrava as pontes das IDEs já instaladas num workspace existente (`--ide=a,b`: só as indicadas; `--all`: as 9) |
 | `npx @aksp/opencrew version` | Mostra a versão instalada |
 | `npx @aksp/opencrew help` | Mostra ajuda dos comandos CLI |
 

package/package.json

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

package/src/cli.js

@@ -103,7 +103,8 @@ ${c.bold('Options for init')}
   --ide=a,b       Preselect IDEs (skip the prompt). Valid: ${allIdeIds().join(', ')}
   --all           Configure every supported IDE
   --yes, -y       Non-interactive; accept defaults
-  --repair-bridges  Regenerate IDE bridge files in an existing workspace
+  --repair-bridges  Rewrite the bridges of the IDEs already installed in an existing
+                    workspace (with --ide: only those; with --all: every IDE)
 
 ${c.bold('Options for update')}
   --check         Report whether an update is available without making changes

package/src/commands/init.js

@@ -1,10 +1,12 @@
 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';
+import { repairIdeIds, backupSummary, recordRepair, NO_BRIDGES_FOUND, NO_WORKSPACE } from '../lib/migrations.js';
 import { c, log, info, ok, warn, step } from '../lib/ui.js';
 
 const STAMP = path.join('_opencrew', '.opencrew-version');
@@ -21,22 +23,13 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
   const version = pkg.version;
   const state = await workspaceState(target);
 
-  // --repair-bridges mode: regenerate IDE bridge files in an existing workspace.
-  if (opts['repair-bridges'] && state !== 'none') {
-    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 });
-
-    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`);
-    return;
-  }
+  if (opts['repair-bridges'] && state === 'none') throw new UsageError(NO_WORKSPACE); // before any write
+  if (opts['repair-bridges']) return repairBridges(target, version, opts);
 
   if (state === 'complete') {
     warn('An opencrew workspace already exists here.');
-    info(`To update only the framework, use: ${c.cyan('npx @aksp/opencrew update')}`);
-    info(`To repair IDE bridges, use: ${c.cyan('npx @aksp/opencrew init --repair-bridges')}`);
+    info(`To update only the framework, use: ${c.cyan('npx @aksp/opencrew@latest update')}`);
+    info(`To repair IDE bridges, use: ${c.cyan('npx @aksp/opencrew@latest init --repair-bridges')}`);
     info(`To reinstall from scratch, delete _opencrew/ first, then run init again.`);
     return;
   }
@@ -51,7 +44,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 +53,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 +72,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.
@@ -96,26 +92,42 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
   log(`     No API keys needed up front — opencrew asks for them in chat only if a skill you use requires one.\n`);
 }
 
+/**
+ * --repair-bridges: rewrite IDE bridge files in an existing workspace. --ide wins (even next
+ * to --all); --all alone means every IDE; otherwise only the IDEs `update` would detect.
+ */
+async function repairBridges(target, version, opts) {
+  const ids = await resolveIdes({ ide: opts.ide }, () => repairIdeIds(target, opts));
+  if (!ids.length) throw new UsageError(NO_BRIDGES_FOUND); // before the first write
+  log(`\n${c.bold(c.cyan('opencrew'))} ${c.dim('v' + version)} — repairing IDE bridges`);
+  log(c.dim(`Target: ${target}\n`));
+  const ctx = newDelivery(target, await readManifest(target));
+  await writeBridges(target, ids, { overwrite: true, ctx });
+  await recordRepair(ctx, version); // only where a manifest already exists
+  const [copied, ...copies] = backupSummary(ctx);
+  if (copied) warn(copied);
+  for (const copy of copies) log(copy);
+  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`);
+}
+
 /**
  * Copy the framework payload into `target` without overwriting anything.
  * 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'. */
@@ -126,8 +138,8 @@ async function workspaceState(target) {
 
 /**
  * Decide which IDEs to configure. --all / --yes → every IDE; --ide → validated list;
- * nothing → `fallback()` (the interactive prompt). Throws UsageError if --ide names no
- * valid IDE.
+ * nothing → `fallback()` (the interactive prompt; in repair mode, the detection). Throws
+ * UsageError if --ide names no valid IDE.
  */
 async function resolveIdes(opts, fallback) {
   if (opts.all || opts.yes) return allIdeIds();
@@ -148,7 +160,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 +174,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)';