@aksp/opencrew 1.6.1 → 1.6.3

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.6.3] — 2026-10-06
+
+**O Node mínimo subiu para o 20.17, numa versão de correção.** O pacote dizia 20.0, mas a lista
+de IDEs do `init` só abria a partir do 20.12 e as dependências só garantem o 20.17. Quem está no
+Node 20.0 a 20.16 precisa atualizar o Node antes de rodar `init` ou `update` (saída de emergência:
+`npx @aksp/opencrew@1.6.2 update`).
+
+Fase R2 "update e envio seguros" (`specs/fase-r2-update-e-envio-seguros.md`): só defeitos já
+achados em revisão. Chega a quem já usa com um `npx @aksp/opencrew@latest update`.
+
+### Changed
+- **`blotato` e `resend` pedem confirmação antes de agir.** Mostram a prévia (contas ou
+  destinatários, texto, quando) e só publicam, enviam, agendam ou apagam depois da palavra
+  `publicar`, `enviar` ou `apagar`. Crew que hoje envia sem perguntar vai parar e pedir. Em falha,
+  não repetem sozinhas.
+- **`.mcp.json`: o servidor Playwright é entregue uma última vez.** Depois, se você o remover ou
+  apagar o arquivo, o `update` não repõe. A versão fixada não é trocada, e o arquivo é copiado
+  antes de qualquer regravação, mantendo a indentação.
+- **Primeiro `update` para esta versão copia o `.gitignore`** para `.opencrew-backup/`, mesmo sem
+  edição sua: o bloco do OpenCrew mudou (passa a ignorar `.opencrew-backup/`) e as versões
+  anteriores não registravam o bloco.
+- **O reparo de pontes só roda com o pacote na mesma versão do projeto.** Com outra versão, para
+  sem alterar nada e pede o `update`.
+- As frases do resumo do `update` saem em português e só afirmam o que foi feito.
+
+### Fixed
+- **Ponte de IDE que você não instalou**: um `CLAUDE.md`, `GEMINI.md`, `QWEN.md` ou
+  `copilot-instructions.md` seu que só citava "opencrew" fazia o `update` criar a ponte e pôr um
+  bloco no seu arquivo. A IDE agora se prova pelo arquivo de ponte. O resumo não cita mais o
+  Codex sem ele estar instalado.
+- **Bloco do OpenCrew editado por dentro** (em `AGENTS.md`, `CLAUDE.md`, `.gitignore`…) era
+  regravado sem cópia. Agora o arquivo inteiro é copiado antes, e o fim de linha é mantido.
+- **Texto antigo das pontes** (instalações até a 1.2.2), que mandava adotar o papel do OpenCrew
+  sempre, é retirado, com cópia, quando está idêntico ao gerado; se foi editado, só aviso.
+- **Manifesto ilegível** vira aviso e a atualização segue; `.mcp.json` fora do formato não derruba
+  mais o `update` no meio.
+- **A dica de reinstalar** não manda mais apagar `_opencrew/`, que guarda a sua memória.
+- **Restos do OpenSquad**: o aviso não promete mais "apagar com segurança" para arquivo que pode
+  ser seu, e cobre mais sete caminhos. Nada é apagado.
+- **Texto do usuário em linha de comando**: o prompt de imagem vai por arquivo (`--prompt-file`),
+  nome de arquivo com caractere inseguro não entra em comando, e caminhos e URLs vão entre aspas.
+- **Conferência de fontes**: o `--corrigir` não grava mais fora da crew por um link; caminho de
+  rede e endereço de site citados viram alerta "não conferido", sem tocar a rede e sem parar a
+  execução; erro de leitura sai com mensagem.
+- **Publicação**: a tag só publica depois do CI verde (Ubuntu e Windows, Node 20.17 e 22) e da
+  auditoria de segurança. Três das cinco últimas versões saíram com o CI vermelho.
+
+### Internal
+- CLI em módulos novos (`blocos`, `deteccao`, `legado`, `mcp`, `resumo`, `node-version`); 47
+  cenários R2 com teste de mesmo ID; teste de upgrade 1.6.2 → 1.6.3.
+
+## [1.6.2] — 2026-10-05
+
+Correção da 1.6.1. Chega a quem já usa com um `npx @aksp/opencrew@latest update`.
+
+### Fixed
+- **Node 20: o verificador não esgota mais a memória com texto grande.** Um post, tweet ou
+  legenda de dezenas de milhares de caracteres numa peça só derrubava o verificador no Node 20,
+  sem relatório (o runner avisava que a verificação não rodou). A contagem de caracteres passou a
+  ser feita em janelas, com o mesmo resultado. O defeito vinha da 1.5.0; Node 22 e 24 não o
+  tinham.
+
+### Internal
+- Release: a tag só sai depois do CI verde nas quatro células (Ubuntu e Windows, Node 20 e 22).
+  A 1.6.1 foi publicada com o CI do Node 20 vermelho, porque a publicação roda só no Node 22.
+
 ## [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`),

package/README.md

@@ -69,7 +69,7 @@ dentro da sua IDE.**
 
 ### Pré-requisitos
 
-- **Node.js 20+** ([baixar](https://nodejs.org/))
+- **Node.js 20.17 ou mais novo** ([baixar](https://nodejs.org/))
 - Uma IDE de IA com acesso a arquivos locais: **Claude Code**, **Cursor**,
   **Codex (OpenAI)**, **Gemini CLI**, **Google Antigravity**, **OpenCode**,
   **VS Code + Copilot**, **Qwen Code** ou **Trae**.
@@ -219,14 +219,24 @@ o que você fez:
 
 | O que é atualizado | O que NUNCA é tocado |
 |---|---|
-| `_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) |
+| `_opencrew/core/` (framework) e skills do catálogo | As crews que você criou em `crews/` |
+| Pastas novas do framework (agentes-base, config) e modelos de crew — 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.
+| Bloco do OpenCrew em `AGENTS.md`, `CLAUDE.md` e `.gitignore` (o resto do arquivo fica intacto) | `.env` (suas chaves) |
+| Servidor Playwright no `.mcp.json`, entregue uma vez (outros servidores intactos) | |
+
+- **Editou um arquivo do framework, um skill do catálogo ou o bloco do OpenCrew?** Antes de
+  substituir, o `update` guarda o arquivo inteiro em `.opencrew-backup/<data>/` e lista o que
+  copiou. Essa pasta fica fora do git (entra no bloco do `.gitignore`). No primeiro `update` para
+  a 1.6.3 há cópia do `.gitignore` mesmo sem edição sua: as versões anteriores não registravam o
+  bloco.
+- **Apagou um modelo de crew ou um skill do catálogo?** Ele volta no `update`, e a saída diz o
+  que foi entregue de novo.
+- **Removeu o servidor Playwright do `.mcp.json`?** O `update` o entrega uma única vez; se você
+  remover de novo, não volta. A versão fixada no arquivo não é trocada.
+- **Uma IDE só conta como instalada pelo arquivo de ponte dela**, não por um arquivo seu que cite
+  o OpenCrew. Texto antigo das pontes (instalações até a 1.2.2) é retirado, com cópia, quando
+  está idêntico ao que o OpenCrew gravou.
 - **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`.
 
@@ -241,6 +251,8 @@ npx @aksp/opencrew@latest init --repair-bridges --all              # as 9 IDEs
 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`.
+Ele também só roda com o pacote na mesma versão do projeto: com outra versão, para sem alterar
+nada e pede o `update`.
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "publishConfig": {
     "access": "public"
   },
@@ -50,7 +50,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.17.0"
   },
   "dependencies": {
     "@inquirer/checkbox": "^5.1.0",

package/src/cli.js

@@ -5,34 +5,9 @@ import { allIdeIds } from './lib/ides.js';
 import { UsageError, isPromptCancel } from './lib/errors.js';
 import { init } from './commands/init.js';
 import { update } from './commands/update.js';
+import { nodeBelowFloor } from './lib/node-version.js';
 import { c, log, err, warn, info } from './lib/ui.js';
 
-// Extract the minimum required Node version from an engines.node range string.
-// Handles: ">=20.0.0", "^20.5", ">=18.0.0 || >=20.0.0", plain "20.0.0".
-function minNodeVersion(range) {
-  // Split on || and take the lowest version (user is expected to meet at least one).
-  const parts = range.split(/\s*\|\|\s*/);
-  let lowest = null;
-  for (const part of parts) {
-    const v = part.replace(/[^0-9.]/g, '');
-    if (!v) continue;
-    if (!lowest || lt(v, lowest)) lowest = v;
-  }
-  return lowest;
-}
-
-// Simple semver comparison (no prerelease tags). Returns true if a < b.
-function lt(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
-  for (let i = 0; i < 3; i++) {
-    const na = pa[i] || 0;
-    const nb = pb[i] || 0;
-    if (na !== nb) return na < nb;
-  }
-  return false; // equal
-}
-
 const OPTION_SPEC = {
   help: { type: 'boolean', short: 'h' },
   version: { type: 'boolean', short: 'v' },
@@ -128,11 +103,15 @@ export function reportError(e) {
   }
   err(e?.message ?? String(e));
   if (e instanceof UsageError) info(`Run ${c.cyan('npx @aksp/opencrew help')} for usage.`);
-  else if (process.env.OPENCREW_DEBUG) console.error(e?.stack);
+  else if (process.env.OPENCREW_DEBUG) console.error(e?.cause ? e : e?.stack); // with a cause: both stacks
   return 1;
 }
 
-export async function run(argv, { commands = { init, update } } = {}) {
+/**
+ * @param {string[]} argv
+ * @param {{ commands?: object, nodeVersion?: string }} deps  injectable for tests
+ */
+export async function run(argv, { commands = { init, update }, nodeVersion = process.versions.node } = {}) {
   let command, opts;
   try {
     ({ command, opts } = parseArgs(argv));
@@ -154,16 +133,14 @@ export async function run(argv, { commands = { init, update } } = {}) {
     return;
   }
 
-  // Validate Node version against engines.node requirement.
-  if (engines.node) {
-    const required = minNodeVersion(engines.node);
-    const current = process.versions.node;
-    if (required && lt(current, required)) {
-      warn(`opencrew requires Node.js ${engines.node}. You have v${current}.`);
-      info(`Upgrade Node or use a compatible version.`);
-      process.exitCode = 1;
-      return;
-    }
+  // Below the floor of engines.node every command stops here — --version and help too —
+  // before anything is written (spec R2, rule 27).
+  const tooOld = nodeBelowFloor(engines.node, nodeVersion);
+  if (tooOld) {
+    err(tooOld[0]);
+    info(tooOld[1]);
+    process.exitCode = 1;
+    return;
   }
 
   // --version / --help never run a command (they may follow any command).

package/src/commands/init.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 { exists, writeFileSafe, readJson, writeBridgeFile } from '../lib/fsx.js';
-import { newDelivery, deliverTree, deliverFile, writeManifest, readManifest } from '../lib/manifest.js';
+import { exists, readJson } from '../lib/fsx.js';
+import { newDelivery, deliverTree, deliverFile, writeManifest, readManifest, manifestUnreadable, UNREADABLE } from '../lib/manifest.js';
+import { deliverBlock, deliverBridges } from '../lib/blocos.js';
+import { createMcp } from '../lib/mcp.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 { withoutLegacy, legacyLines } from '../lib/legado.js';
+import { repairIdeIds, repairVersionGuard, backupSummary, recordRepair, NO_BRIDGES_FOUND, NO_WORKSPACE } from '../lib/migrations.js';
+import { ALREADY_INSTALLED } from '../lib/resumo.js';
 import { c, log, info, ok, warn, step } from '../lib/ui.js';
 
 const STAMP = path.join('_opencrew', '.opencrew-version');
-// .gitignore / .env.example belong to the user: opencrew only owns a marked block at the end.
-const SHARED_BLOCK = { comment: 'hash', position: 'append' };
 
 /**
  * @param {object} opts  parsed CLI options
@@ -28,9 +30,8 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
 
   if (state === 'complete') {
     warn('An opencrew workspace already exists here.');
-    info(`To update only the framework, use: ${c.cyan('npx @aksp/opencrew@latest update')}`);
+    info(ALREADY_INSTALLED); // R2 rule 15: never tells the user to delete _opencrew/
     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;
   }
 
@@ -56,23 +57,22 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
   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);
-  if (agentsResult.merged) info('AGENTS.md (merged — existing content preserved)');
+  const agents = await deliverBlock(ctx, 'AGENTS.md', AGENTS_BRIDGE);
+  if (agents.action === 'added') info('AGENTS.md (merged — existing content preserved)');
   else ok('AGENTS.md (bridge to system.md)');
 
-  const mcpWritten = await writeFileSafe(path.join(target, '.mcp.json'), await tpl('.mcp.json'), {
-    overwrite: false,
-  });
-  info(mcpWritten ? '.mcp.json' : '.mcp.json (kept existing)');
+  // Created here → recorded in the manifest as delivered; the user's own file is kept as it is.
+  info((await createMcp(ctx, await tpl('.mcp.json'))) ? '.mcp.json' : '.mcp.json (kept existing)');
 
+  // .gitignore / .env.example belong to the user: opencrew only owns a marked block at the end.
   for (const [file, template] of [['.env.example', '.env.example'], ['.gitignore', 'gitignore']]) {
-    const res = await writeBridgeFile(path.join(target, file), await tpl(template), SHARED_BLOCK);
-    info(res.merged ? `${file} (opencrew block added at the end — your lines kept)` : file);
+    const res = await deliverBlock(ctx, file, await tpl(template));
+    info(res.action === 'added' ? `${file} (opencrew block added at the end — your lines kept)` : file);
   }
 
   // 3. IDE bridge files.
   step('Configuring AI IDEs');
-  await writeBridges(target, ids, { overwrite: false, ctx });
+  await writeBridges(ctx, ids, false);
 
   if (ids.includes('claude-code')) {
     warn(`opencrew ships its own Playwright MCP server (.mcp.json) — disable Claude Code's`);
@@ -83,6 +83,7 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
   // 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');
+  reportBackups(ctx); // a reinstall over blocks the user edited copies those files first
 
   // 5. Done.
   log(`\n${c.green(c.bold('Done!'))} opencrew is installed.\n`);
@@ -95,20 +96,30 @@ export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
 /**
  * --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.
+ * Only with the package at the version of the workspace (R2 rule 6), whatever the options.
  */
 async function repairBridges(target, version, opts) {
+  const otherVersion = await repairVersionGuard(target, version);
+  if (otherVersion) throw new Error(otherVersion); // before any write; exit 1, no usage hint
   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
+  await withoutLegacy(ctx, ids.map(ideById), () => writeBridges(ctx, ids, true)); // R2 rule 3
+  for (const line of legacyLines(ctx)) warn(line);
+  if (await manifestUnreadable(target)) warn(UNREADABLE.repair); // R2 rule 12: copied as with none
+  await recordRepair(ctx, version); // only where a manifest already exists (and can be read)
+  reportBackups(ctx);
+  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`);
+}
+
+/** Say where the backup copies of this run are (nothing when none was made). */
+function reportBackups(ctx) {
   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`);
 }
 
 /**
@@ -155,31 +166,17 @@ async function resolveIdes(opts, fallback) {
 }
 
 /**
- * Write IDE bridge files to the target directory.
- * @param {string} target — project root
- * @param {string[]} ids — validated IDE ids to configure
- * @param {{ overwrite: boolean }} opts
+ * Write the bridge files of the IDEs `ids` (validated) and say what happened to each.
+ * `overwrite`: replace a whole-file bridge that differs (repair) or keep it (init).
  */
-async function writeBridges(target, ids, { overwrite, ctx }) {
-  const writtenPaths = new Set();
-
-  for (const id of ids) {
-    const ide = ideById(id);
-    for (const f of ide.files) {
-      if (writtenPaths.has(f.path)) {
-        info(`${f.path} (shared path — written once)`);
-        continue;
-      }
-      writtenPaths.add(f.path);
-      const fp = path.join(target, f.path);
-      const hasFrontmatter = f.content.startsWith('---');
-      if (hasFrontmatter) {
-        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)`);
-        else if (result.written && overwrite) info(`${f.path} (regenerated)`);
-      }
+async function writeBridges(ctx, ids, overwrite) {
+  const ides = ids.map(ideById);
+  const written = await deliverBridges(ctx, ides, { overwrite });
+  for (const ide of ides) {
+    for (const f of written.filter((w) => w.ide === ide)) {
+      if (f.shared) info(`${f.file} (shared path — written once)`);
+      else if (f.action === 'added') info(`${f.file} (merged — existing content preserved)`);
+      else if (f.block && f.action !== 'kept' && overwrite) info(`${f.file} (regenerated)`);
     }
     ok(`${ide.label} → ${ide.files.map((f) => f.path).join(', ')}`);
   }

package/src/commands/update.js

@@ -1,23 +1,37 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { templatesDir, packageJsonPath } from '../lib/paths.js';
-import { exists, writeFileSafe, readJson, writeBridgeFile, readFile } from '../lib/fsx.js';
-import { AGENTS_BRIDGE, LEAKED_STATUS_SECTION, ideById } from '../lib/ides.js';
-import { readManifest, writeManifest, newDelivery, deliverTree, deliverFile } from '../lib/manifest.js';
-import { compareVersions, detectInstalledIdes, refreshBridges, mergeMcp, findLegacyBridges } from '../lib/migrations.js';
+import { exists, writeFileSafe, readJson, readFile } from '../lib/fsx.js';
+import { AGENTS_BRIDGE, LEAKED_STATUS_SECTION } from '../lib/ides.js';
+import { readManifest, manifestUnreadable, UNREADABLE, writeManifest, newDelivery, deliverTree, deliverFile } from '../lib/manifest.js';
+import { deliverBlock, deliverBridges, blockHas } from '../lib/blocos.js';
+import { detectInstalledIdes } from '../lib/deteccao.js';
+import { withoutLegacy } from '../lib/legado.js';
+import { updateMcp } from '../lib/mcp.js';
+import { compareVersions, installedVersion, findLeftovers } from '../lib/migrations.js';
+import { say, recreatedLines, updateSummary, UNTOUCHED } from '../lib/resumo.js';
 import { c, log, info, ok, warn, err, step } from '../lib/ui.js';
 
+const tpl = (...p) => path.join(templatesDir, ...p);
+
 // `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.
+//   - new framework folders (agents, config, crew templates) arrive without overwriting — a
+//     crew template the user deleted comes back, and the output lists it;
+//   - bridges of the IDEs already installed are refreshed (never new IDEs — an IDE is proved by
+//     a file, src/lib/deteccao.js), and so are the opencrew blocks of AGENTS.md and .gitignore
+//     — a block the user edited is copied first; the text bridges had up to 1.2.2 leaves the
+//     outside of the block, with a copy, only when it is still exactly what was generated;
+//   - the Playwright server of .mcp.json is delivered once (the manifest records it) and never
+//     put back; the file is copied before any rewrite (src/lib/mcp.js);
+//   - the crews the user created, _opencrew/_memory/, _opencrew/best-practices.local/ and .env
+//     are never touched.
+// Every step returns what it did, and the summary only says that (src/lib/resumo.js).
 export async function update(opts = {}) {
   const target = process.cwd();
-  const pkg = await readJson(packageJsonPath);
-  const version = pkg.version;
+  const { version } = await readJson(packageJsonPath);
 
   if (!(await exists(path.join(target, '_opencrew', 'core')))) {
     warn('No opencrew workspace found here.');
@@ -25,15 +39,15 @@ export async function update(opts = {}) {
     return;
   }
 
-  const versionFile = path.join(target, '_opencrew', '.opencrew-version');
-  const current = (await exists(versionFile))
-    ? (await fs.readFile(versionFile, 'utf8')).trim()
-    : 'unknown';
-  const newer = current !== 'unknown' && compareVersions(current, version) > 0;
-
+  const current = (await installedVersion(target)) ?? 'unknown';
   log(`\n${c.bold(c.cyan('opencrew update'))}`);
   log(c.dim(`Installed: ${current}  →  Package: ${version}\n`));
+  if (canApply(opts, current, version)) await apply(target, version);
+}
 
+/** `--check` only reports, and a package older than the workspace stops: false = write nothing. */
+function canApply(opts, current, version) {
+  const newer = current !== 'unknown' && compareVersions(current, version) > 0;
   if (opts.check) {
     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}).`);
@@ -42,82 +56,82 @@ export async function update(opts = {}) {
       info(`Run ${c.cyan('npx @aksp/opencrew update')} to apply.`);
       process.exitCode = 1;
     }
-    return;
+    return false;
   }
-
   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;
   }
+  return !newer;
+}
 
+async function apply(target, version) {
+  // A manifest that exists but cannot be used is said so, then treated as none (R2 rule 12).
   const manifest = await readManifest(target);
+  const unreadable = !manifest && (await manifestUnreadable(target));
+  if (unreadable) warn(UNREADABLE.update);
   const ctx = newDelivery(target, manifest);
-  const tpl = (...p) => path.join(templatesDir, ...p);
-  const dest = (...p) => path.join(target, ...p);
 
   step('Refreshing framework');
-  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 });
+  const crews = await refreshFramework(ctx);
   ok(`Framework and catalog skills refreshed (${ctx.written} files written)`);
+  say(recreatedLines(crews));
 
   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.');
-  }
+  const done = { unreadable, ...(await refreshBridges(ctx)) };
+  done.mcp = await updateMcp(ctx, await readFile(tpl('.mcp.json')));
+  done.leftovers = await findLeftovers(target);
+  say(updateSummary(ctx, done));
 
   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');
+  await fs.writeFile(path.join(target, '_opencrew', '.opencrew-version'), version + '\n');
   log(`\n${c.green(c.bold('Updated to v' + version))}.`);
-  log(c.dim('Your crews, memory, local best-practices and .env were left untouched.\n'));
+  log(c.dim(`${UNTOUCHED}\n`));
 }
 
-// Root AGENTS.md: create it if missing; a legacy full-system doc (pre-v1.3) is backed up
-// byte for byte and replaced by the thin bridge; otherwise only the marked block changes.
-async function refreshAgentsBridge(target) {
-  const agentsPath = path.join(target, 'AGENTS.md');
-  if (!(await exists(agentsPath))) {
-    await writeBridgeFile(agentsPath, AGENTS_BRIDGE);
-    ok('AGENTS.md (bridge created)');
-    return;
+/** @returns what `deliverTree` did to each crew template (only the missing ones are written). */
+async function refreshFramework(ctx) {
+  const dest = (...p) => path.join(ctx.target, ...p);
+  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 });
   }
-  const existing = await readFile(agentsPath);
+  return deliverTree(ctx, tpl('crews'), dest('crews'), { overwrite: false });
+}
+
+/** AGENTS.md, .gitignore and the bridges of the IDEs installed: what happened to each. */
+async function refreshBridges(ctx) {
+  const agents = await refreshAgentsBridge(ctx);
+  // The copies in .opencrew-backup/ stay out of the user's git (R2 rule 7).
+  const gitignore = await deliverBlock(ctx, '.gitignore', await readFile(tpl('gitignore')));
+  const ides = await detectInstalledIdes(ctx.target);
+  // 1.4.0/1.4.1 shipped the maintainer's STATUS.md workflow inside CLAUDE.md's opencrew block.
+  // It leaves with the block; the same title outside the block is the user's and stays.
+  const leaked = () => blockHas(ctx.target, 'CLAUDE.md', LEAKED_STATUS_SECTION);
+  const hadLeak = await leaked();
+  const bridges = await withoutLegacy(ctx, ides, () => deliverBridges(ctx, ides)); // R2 rule 3 (src/lib/legado.js)
+  return { agents, gitignore, ides, bridges, leak: hadLeak && !(await leaked()) };
+}
+
+// Root AGENTS.md: a legacy full-system doc (pre-v1.3) is backed up byte for byte and replaced by
+// the thin bridge (said here; returns null); otherwise only the marked block is delivered (a
+// block the user edited is copied first — src/lib/blocos.js) and its result goes to the summary.
+async function refreshAgentsBridge(ctx) {
+  const agentsPath = path.join(ctx.target, 'AGENTS.md');
+  const existing = (await exists(agentsPath)) ? await readFile(agentsPath) : '';
   if (existing.includes('# opencrew Instructions') && !existing.includes('<!-- opencrew:start -->')) {
     const backup = await freeBackupPath(agentsPath);
     await fs.copyFile(agentsPath, backup);
     await writeFileSafe(agentsPath, AGENTS_BRIDGE);
     ok(`AGENTS.md (migrated from legacy full-system to thin bridge — backed up to ${path.basename(backup)})`);
-    return;
+    return null;
   }
-  await writeBridgeFile(agentsPath, AGENTS_BRIDGE);
-  ok('AGENTS.md refreshed');
+  return deliverBlock(ctx, 'AGENTS.md', AGENTS_BRIDGE);
 }
 
 async function freeBackupPath(file) {
@@ -125,14 +139,3 @@ async function freeBackupPath(file) {
   if (!(await exists(bak))) return bak;
   return `${file}.bak-${new Date().toISOString().replace(/[:.]/g, '-')}`;
 }
-
-// 1.4.0/1.4.1 shipped the maintainer's STATUS.md workflow inside CLAUDE.md's opencrew
-// block. Rewrite that block (only that block, only if the leak is there).
-async function removeLeakedStatusSection(target) {
-  const claudePath = path.join(target, 'CLAUDE.md');
-  if (!(await exists(claudePath))) return;
-  if (!(await readFile(claudePath)).includes(LEAKED_STATUS_SECTION)) return;
-  const bridge = ideById('claude-code').files.find((f) => f.path === 'CLAUDE.md');
-  await writeBridgeFile(claudePath, bridge.content);
-  ok('CLAUDE.md (removed the STATUS.md section shipped by mistake in 1.4.0/1.4.1)');
-}