@aksp/opencrew 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -3,6 +3,108 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.7.0] — 2026-10-06
+
+Fase E1 "Escritório ao vivo — a equipe trabalhando, em 8 bits"
+(`specs/fase-e1-escritorio-ao-vivo.md`). Chega a quem já usa com um
+`npx @aksp/opencrew@latest update`.
+
+### Added
+- **Escritório ao vivo.** Uma página em pixel-art, aberta no navegador, mostra a crew
+  trabalhando: cada agente na sua mesa, digitando na vez dele, levando o papel ao colega na
+  passagem de bastão, de mão levantada quando espera a sua resposta, com ✓ quando termina e "!"
+  quando falha. Ao lado, o passo atual, a lista dos agentes com o status por extenso e o que cada
+  um fez, e a última passagem de bastão. O título da aba acompanha a execução.
+- **`/opencrew dashboard`** liga o Escritório, sobe a página e mostra o endereço
+  (`http://127.0.0.1:4747`, ou a porta livre seguinte); repetir o comando devolve o mesmo
+  endereço. **`/opencrew dashboard off`** desliga. Continua desligado por padrão.
+- Roda só no seu computador, sem internet e sem medição: o servidor
+  (`_opencrew/core/scripts/escritorio.mjs`) escuta só em `127.0.0.1`, só lê e não escreve em disco.
+- Sem execução nenhuma, a página roda uma demonstração e troca sozinha para a execução real
+  quando ela aparece (`?demo` no endereço força a demonstração). Com mais de uma crew, mostra a
+  de atualização mais recente e um seletor com as outras.
+- A página não mente sobre o que não sabe: execução há mais de 2 minutos sem novidade mostra há
+  quanto tempo foi a última atualização; há mais de 20, o agente sai da pose de digitar e aparece
+  "sem sinal". Servidor fora do ar: a página avisa e tenta de novo sozinha.
+
+### Changed
+- **Quem avisa o Escritório é um script, não a IA escrevendo JSON.** Com o Escritório ligado, o
+  runner roda um comando curto por passo (`_opencrew/core/scripts/estado.mjs`). Checkpoint, agente
+  pulado e execução que falha passam a aparecer; antes nunca eram gravados. Falha desse comando
+  não para a execução: o runner avisa uma vez e segue.
+- **Com o Escritório ligado, o estado final deixa de ser copiado para
+  `crews/<crew>/output/<run>/state.json`.** O estado da execução mora só em
+  `crews/<crew>/state.json`.
+- `state.json`: os agentes ganham os status `checkpoint` e `failed` e o campo `label`; a
+  execução ganha `checkpoint` e `failed`; `desk` e `delivering` deixam de ser gravados. Arquivo
+  gravado por versão anterior continua sendo lido pela página.
+- Os prompts de criar e de consertar crew não escrevem mais `state.json`.
+- README: a nota "o dashboard não é instalado" deu lugar à seção "Escritório ao vivo".
+
+### Removed
+- A pasta `dashboard/` do repositório (o desenho antigo, que nunca foi instalado pelo `init`). O
+  que servia migrou para `_opencrew/core/escritorio/`, sem os defeitos apontados na auditoria:
+  nome de agente entrava na página como HTML, o modo ao vivo lia o arquivo no lugar errado e a
+  página congelava se a primeira leitura falhasse.
+
+### Internal
+- `npm run verify`: o lint passa a cobrir `templates/_opencrew/core/escritorio/` (com os nomes
+  globais de navegador) e o alerta de tamanho mede os `.js` dessa pasta. Travas novas:
+  `tests/estado*.test.js`, `tests/escritorio*.test.js`, `tests/runtime-contracts-e1.test.js`,
+  `tests/docs-e1.test.js` e os cenários E1-07a, E1-07c e E1-upg nos testes de pacote, de
+  referências e de upgrade. A trava de conteúdo do mantenedor passa a ler também `.mjs` e `.css`.
+
+## [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`.

package/README.md

@@ -40,6 +40,9 @@ 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.
+- 🖥️ **Escritório ao vivo** — veja a equipe trabalhando numa sala em pixel-art, no navegador:
+  quem está digitando, quem passou o bastão, quem espera a sua resposta. Opcional, desligado por
+  padrão, só neste computador. Liga com `/opencrew dashboard`.
 - 📂 **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
@@ -69,7 +72,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**.
@@ -175,6 +178,8 @@ meu-projeto/
 │   │   ├── skills.engine.md      ← gerenciador de skills
 │   │   ├── architect.agent.yaml  ← definição do Arquiteto
 │   │   ├── best-practices/       ← 22 guias de melhores práticas + _catalog.yaml
+│   │   ├── scripts/              ← verificador, conferência de fontes e os scripts do Escritório
+│   │   ├── escritorio/           ← página do Escritório ao vivo (abre com /opencrew dashboard)
 │   │   └── prompts/              ← 13 prompts de fase (discovery, design, build, etc.)
 │   ├── agents/                   ← 5 agentes base compartilhados
 │   │   ├── researcher.agent.md
@@ -184,7 +189,7 @@ meu-projeto/
 │   │   └── strategist.agent.md
 │   ├── _memory/
 │   │   ├── company.md            ← perfil da sua empresa (onboarding)
-│   │   └── preferences.md        ← idioma, tier padrão, dashboard
+│   │   └── preferences.md        ← idioma, tier padrão, Escritório ligado ou desligado
 │   └── .opencrew-version
 │
 ├── crews/                        ← suas crews vivem aqui
@@ -202,9 +207,47 @@ 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 U3a — ver `IDEIAS.md` no repositório).
+---
+
+## Escritório ao vivo
+
+Quer ver a equipe trabalhando? O **Escritório** é uma página em pixel-art, aberta no navegador,
+em que cada agente tem a sua mesa: digita quando é a vez dele, leva o papel ao colega na passagem
+de bastão e levanta a mão quando espera uma resposta sua. Ao lado do desenho ficam o passo atual,
+a lista dos agentes (com o status por extenso e o que cada um fez) e a última passagem de bastão.
+
+**Como abrir:** no chat da sua IDE, digite `/opencrew dashboard`. O comando liga o Escritório,
+sobe a página e mostra o endereço — `http://127.0.0.1:4747`, ou a porta livre seguinte. A próxima
+execução de crew aparece ali; enquanto não há nenhuma, a página roda uma demonstração. Repetir o
+comando é seguro: ele devolve o mesmo endereço.
+
+Se a sua IDE não roda comando em segundo plano, ela mostra o comando para você rodar em outro
+terminal, na pasta do projeto:
+
+```bash
+node _opencrew/core/scripts/escritorio.mjs            # Ctrl+C para fechar
+node _opencrew/core/scripts/escritorio.mjs --porta 5000
+```
+
+Para desligar: `/opencrew dashboard off`.
+
+O que vale saber antes de ligar:
+
+- **Vem desligado.** Sem o `/opencrew dashboard`, nada muda nas suas execuções.
+- **Roda só neste computador, sem internet e sem medição.** A página é servida em `127.0.0.1`,
+  só lê o estado das suas crews (`crews/<crew>/state.json`), não carrega nada de fora e não envia
+  dado nenhum para lugar nenhum.
+- **Com ele ligado, cada passo custa um comando curto a mais.** É assim que a IA avisa o que está
+  fazendo: um comando de terminal por passo. Em IDE que pede aprovação a cada comando, libere o
+  `estado.mjs` uma vez.
+- **A tela mostra o que a IA avisa, e pode atrasar.** Se a IA pular um aviso, o desenho só se
+  acerta no passo seguinte. Depois de 2 minutos sem novidade a página diz há quanto tempo foi a
+  última atualização; depois de 20, o agente aparece "sem sinal" — o que não quer dizer que
+  travou: um passo longo é normal.
+- **O Escritório nunca para a execução.** Se o aviso falhar, a crew segue trabalhando.
+- **Até 12 mesas.** Numa crew maior, os agentes a mais aparecem só na lista ao lado.
+
+Quem já usa o OpenCrew recebe o Escritório com um `npx @aksp/opencrew@latest update`.
 
 ---
 
@@ -219,14 +262,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 +294,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.
 
@@ -272,7 +327,9 @@ npx @aksp/opencrew update --check
 | `/opencrew delete <nome>` | Remove uma crew |
 | `/opencrew skills` | Navega, instala ou remove skills |
 | `/opencrew install <skill>` | Instala uma skill do catálogo |
-| `/opencrew settings` | Altera preferências (idioma, tier, dashboard) |
+| `/opencrew settings` | Altera preferências (idioma, tier, Escritório) |
+| `/opencrew dashboard` | Liga e abre o Escritório ao vivo (a equipe trabalhando, no navegador) |
+| `/opencrew dashboard off` | Desliga o Escritório |
 | `/opencrew show-company` | Mostra o perfil da empresa |
 | `/opencrew edit-company` | Reconfigura o perfil da empresa |
 | `/opencrew help` | Mostra a lista de comandos |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "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(', ')}`);
   }