@aksp/opencrew 1.4.0 → 1.4.2

package/CHANGELOG.md

@@ -3,6 +3,82 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.4.2] — 2026-10-02
+
+Hotfix "parar de causar dano" (Fase 1 da auditoria — `specs/fase-1-hotfix.md`).
+
+### Fixed
+- **`CLAUDE.md` gerado não traz mais o fluxo STATUS.md do mantenedor** (vazado na 1.4.0/1.4.1);
+  o `update` remove a seção de instalações existentes, sem tocar no texto do usuário.
+  `STATUS.md` saiu do `.gitignore` do template.
+- **`--help` nunca executa comando**: `update --help` / `-h` e `init --help` só mostram a ajuda.
+  Parser estrito (`node:util.parseArgs`): opção desconhecida, `--ide` sem id válido ou
+  argumento solto (`init minha-pasta`) falham com exit 1 **antes** de escrever qualquer arquivo.
+  `--ide claude-code` (com espaço) e `-yv` funcionam. `update --dry-run` = `--check`.
+- **`update` sem `AGENTS.md`** cria a ponte em vez de quebrar com ENOENT.
+- **Migração do `AGENTS.md` legado faz backup** em `AGENTS.md.bak` (ou `.bak-<timestamp>`).
+- **`.env.example` e `.gitignore` do usuário não são mais sobrescritos/ignorados**: recebem um
+  bloco `# opencrew:start … # opencrew:end` no fim; as linhas do usuário ficam intactas.
+  O bloco do `.gitignore` agora cobre `.claude/settings.local.json`, `crews/*/state.json` e
+  `crews/*/_investigations/`.
+- **Ctrl+C no prompt de IDEs não deixa instalação pela metade**: as IDEs são escolhidas antes
+  da primeira escrita; cancelamento sai com 130 e "Cancelled — nothing was written.". Uma
+  instalação interrompida (core sem stamp de versão) é **retomada** pelo próximo `init`.
+- Erros inesperados mostram uma linha `✗ <mensagem>` (stack só com `OPENCREW_DEBUG=1`).
+- Marcadores de bloco: um `start` órfão (fim apagado à mão) não faz mais a regravação engolir
+  linhas do usuário.
+- Skills: caminho do `image-ai-generator` corrigido (`{skill_path}/scripts/generate.py`, nota
+  `py -3` no Windows); `instagram-publisher` lê as imagens da pasta do run atual; o
+  `image-creator` renderiza JPEG quando o destino é Instagram.
+- Runner: o toggle do dashboard reconhece o formato `- **Dashboard:** enabled` gravado no
+  onboarding.
+
+### Security
+- **Publicar/enviar é sempre o último trecho do pipeline**: `… → Review → Final Approval
+  checkpoint → [Publish/Send]` (design), com o novo Gate 2c BLOCKING no build. Passos com
+  `side_effects: irreversible` rodam inline e **nunca** têm retry automático nem auto-correção
+  de veto — o runner avisa que a ação pode já ter acontecido e pergunta.
+- **`instagram-publisher`**: legenda via `--caption-file` (nunca interpolada no shell); só
+  aceita `.jpg`/`.jpeg` dentro de `crews/*/output/`; upload no imgBB expira em 24h; token da
+  Graph API no corpo dos POST, não na URL; fluxo preview → `--dry-run` → confirmação explícita
+  ("publish"/"publicar") → publicação única.
+
+### Changed
+- Template `templates/AGENTS.md` (o `system.md` instalado) compactado (−24%) sem mudar o roteamento.
+
+### Internal
+- Testes por cenário da spec (F1-01a…F1-13a); trava nova: nenhum arquivo de `templates/`
+  carrega conteúdo do mantenedor. `KNOWN_BROKEN` de referências zerado.
+
+### Added (governança do repositório — Fase 0)
+- Auditoria geral da v1.4.1 com roadmap por fases: `docs/auditoria/2026-10-02-auditoria-geral.md`.
+- Regras de desenvolvimento em `AGENTS.md` (project-standards T3, tabela Regra → Trava);
+  `CLAUDE.md` da raiz vira apontador versionado.
+- Porta de verificação única `npm run verify` (`scripts/verify.js`): lint (agora inclui
+  `bin/`), testes (descobertos automaticamente em `tests/`), version-sync e alerta de
+  tamanho (`scripts/check-size.js`). CI e publish chamam a mesma porta.
+- Travas novas: `tests/package.test.js` (conteúdo do tarball × README),
+  `tests/template-refs.test.js` (caminhos citados nos prompts existem),
+  `tests/verify.test.js` e `tests/check-size.test.js` (provetas).
+- `GLOSSARIO.md`; `IDEIAS.md` reformatado com triagem e `Alocação: →`.
+
+### Changed (governança do repositório — Fase 0)
+- Dogfood do mantenedor sai da raiz e vai para `sandbox/` (fora do git).
+- `publish.yml` confere a tag contra a versão do `package.json` e roda `npm run verify`;
+  CI e publish usam só `npm ci` (sem fallback que esconde drift do lockfile).
+
+### Docs (Fase 0)
+- README: o dashboard não é instalado pelo `init`; `update` não atualiza as pontes de IDE
+  (use `init --repair-bridges`); migração do `AGENTS.md` legado perde instruções extras;
+  flags `upgrade`, `--ide`, `--all`/`-y`, `--repair-bridges` documentadas; contagens
+  corrigidas (22 guias, 13 prompts); Windsurf removido da lista; promessa "30-70% de
+  economia" sem base removida.
+
+## [1.4.1] — 2026-08-04
+
+### Fixed
+- **NPM publish**: v1.4.0 já existia no registro. Re-publicado como 1.4.1.
+
 ## [1.4.0] — 2026-08-04
 
 ### Added
@@ -20,6 +96,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
   - `AGENTS.md` — step 7b na seção Loading the Pipeline Runner.
   - 3 novos testes de contrato em `docs.test.js`.
 
+> Itens desta versão que ficaram de fora da entrada original (acrescentados na auditoria
+> de 2026-10-02):
+- **Pontes `.agents/`** para Antigravity, Gemini CLI e Qwen Code
+  (`.agents/skills/opencrew/SKILL.md`, `.agents/workflows/opencrew.md`).
+- **`init --repair-bridges`**: regrava as pontes de IDE num workspace existente.
+- **`update` migra `AGENTS.md` legado** (pré-1.3, sistema completo) para a ponte fina.
+- **Fix Antigravity**: frontmatter no workflow para registrar `/opencrew`.
+- ⚠️ **Regressão**: o `CLAUDE.md` gerado passou a conter a seção "STATUS.md (gestão de
+  sessão)" do fluxo pessoal do mantenedor, e `templates/gitignore` ganhou `STATUS.md`.
+  Correção prevista na 1.4.2 (F1-01).
+
 ## [1.3.3] — 2026-08-03
 
 ### Fixed

package/README.md

@@ -34,7 +34,7 @@ dentro da sua IDE.**
   sem abrir editor nenhum.
 - 🎛️ **Seleção inteligente de agentes** — o sistema analisa seu pedido e
   sugere quais agentes são necessários para aquela tarefa. Você confirma ou
-  ajusta com um clique. Economia de 30-70% de tokens quando agentes são pulados.
+  ajusta com um clique. Agentes pulados não gastam tokens naquele run.
 
 ---
 
@@ -126,12 +126,12 @@ enxuto — todos apontam para a mesma fonte.
 |---|---|
 | `AGENTS.md` (ponte) + `.claude/skills/opencrew/SKILL.md` + `CLAUDE.md` | Claude Code |
 | `AGENTS.md` (ponte) + `.agents/skills/opencrew/SKILL.md` | OpenAI Codex, Codex CLI |
-| `AGENTS.md` (ponte) + `.cursor/rules/opencrew.mdc` | Cursor, Windsurf |
+| `AGENTS.md` (ponte) + `.cursor/rules/opencrew.mdc` | Cursor |
 | `AGENTS.md` (ponte) + `.github/copilot-instructions.md` | VS Code + GitHub Copilot |
 | `AGENTS.md` (ponte) + `.opencode/commands/opencrew.md` | OpenCode |
 | `AGENTS.md` (ponte) + `.agent/rules/opencrew.md` + `.agent/workflows/opencrew.md` + `.agents/skills/opencrew/SKILL.md` + `.agents/workflows/opencrew.md` | Google Antigravity |
-| `GEMINI.md` (ponte) | Gemini CLI |
-| `QWEN.md` (ponte) | Qwen Code |
+| `GEMINI.md` (ponte) + `.agents/skills/opencrew/SKILL.md` | Gemini CLI |
+| `QWEN.md` (ponte) + `.agents/skills/opencrew/SKILL.md` | Qwen Code |
 | `AGENTS.md` (ponte) + `.trae/rules/opencrew.md` | Trae |
 
 > ⚠️ **Importante:** `CLAUDE.md`, `GEMINI.md` e os demais arquivos de IDE são
@@ -150,8 +150,8 @@ meu-projeto/
 ├── CLAUDE.md                     ← ponte fina + suas instruções (merge)
 ├── GEMINI.md                     ← ponte fina (Gemini CLI)
 ├── .mcp.json                     ← servidor Playwright do OpenCrew
-├── .gitignore
-├── .env.example
+├── .gitignore                    ← bloco `# opencrew` no fim; suas linhas são mantidas
+├── .env.example                  ← idem
 │
 ├── _opencrew/
 │   ├── core/
@@ -159,8 +159,8 @@ meu-projeto/
 │   │   ├── runner.pipeline.md    ← executor de pipeline
 │   │   ├── skills.engine.md      ← gerenciador de skills
 │   │   ├── architect.agent.yaml  ← definição do Arquiteto
-│   │   ├── best-practices/       ← 23 guias de melhores práticas
-│   │   └── prompts/              ← 12 prompts de fase (discovery, design, build, etc.)
+│   │   ├── best-practices/       ← 22 guias de melhores práticas + _catalog.yaml
+│   │   └── prompts/              ← 13 prompts de fase (discovery, design, build, etc.)
 │   ├── agents/                   ← 5 agentes base compartilhados
 │   │   ├── researcher.agent.md
 │   │   ├── copywriter.agent.md
@@ -185,11 +185,12 @@ meu-projeto/
 │   ├── instagram-publisher/      ← publicação no Instagram
 │   ├── resend/                   ← envio de emails
 │   └── ...
-│
-└── dashboard/
-    └── index.html                ← dashboard visual (opcional, offline)
 ```
 
+> 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/`).
+
 ---
 
 ## Mantendo o OpenCrew atualizado
@@ -198,18 +199,29 @@ meu-projeto/
 npx @aksp/opencrew update
 ```
 
-O `update` **nunca destrói seus dados**. Ele atualiza apenas:
+O `update` não toca nas suas crews nem na sua memória. Ele atualiza apenas:
 
 | O que é atualizado | O que NUNCA é tocado |
 |---|---|
-| `_opencrew/core/` (framework) | `crews/` (suas crews) |
-| Skills do catálogo | `_opencrew/_memory/` (perfil, preferências) |
+| `_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 -->` nos bridges | Arquivos de IDE (fora do bloco) |
+| Bloco `<!-- opencrew -->` no `AGENTS.md` | Pontes das IDEs (`CLAUDE.md`, `.cursor/`, `.agents/`…) |
+
+As **pontes das IDEs não são atualizadas** pelo `update`. Para regravá-las com a versão
+atual, use:
+
+```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 automaticamente, sem perder suas instruções.
+fina. Desde a v1.4.2 o arquivo original é copiado antes para `AGENTS.md.bak` (até a v1.4.1,
+instruções suas adicionadas a esse `AGENTS.md` legado eram perdidas).
 
 Para verificar se há atualização disponível sem aplicar:
 
@@ -245,7 +257,11 @@ npx @aksp/opencrew update --check
 |---|---|
 | `npx @aksp/opencrew init` | Instala o OpenCrew na pasta atual |
 | `npx @aksp/opencrew update` | Atualiza o framework |
-| `npx @aksp/opencrew update --check` | Verifica se há update disponível |
+| `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 version` | Mostra a versão instalada |
 | `npx @aksp/opencrew help` | Mostra ajuda dos comandos CLI |
 

package/bin/opencrew.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // opencrew — CLI entry point
-import { run } from '../src/cli.js';
+import { run, reportError } from '../src/cli.js';
 
-run(process.argv.slice(2)).catch((err) => {
-  console.error(err?.stack || String(err));
-  process.exit(1);
+// run() reports its own errors; this only catches a failure inside the reporter itself.
+run(process.argv.slice(2)).catch((e) => {
+  process.exitCode = reportError(e);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "publishConfig": {
     "access": "public"
   },
@@ -19,8 +19,9 @@
   ],
   "scripts": {
     "start": "node bin/opencrew.js",
-    "test": "node --test tests/cli.test.js tests/docs.test.js tests/fsx.test.js tests/ides.test.js tests/init.test.js tests/paths.test.js tests/ui.test.js tests/update.test.js",
-    "lint": "eslint src/ tests/ scripts/",
+    "test": "node scripts/verify.js test",
+    "lint": "node scripts/verify.js lint",
+    "verify": "node scripts/verify.js",
     "version": "node scripts/stamp-version.js && git add templates/_opencrew/.opencrew-version"
   },
   "keywords": [

package/src/cli.js

@@ -1,6 +1,8 @@
+import { parseArgs as nodeParseArgs } from 'node:util';
 import { readJson } from './lib/fsx.js';
 import { packageJsonPath } from './lib/paths.js';
 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 { c, log, err, warn, info } from './lib/ui.js';
@@ -31,27 +33,56 @@ function lt(a, b) {
   return false; // equal
 }
 
-function parseArgs(argv) {
-  const opts = { _: [] };
-  for (const a of argv) {
-    if (a.startsWith('--')) {
-      const eq = a.indexOf('=');
-      const k = eq > -1 ? a.slice(2, eq) : a.slice(2);
-      const v = eq > -1 ? a.slice(eq + 1) : true;
-      opts[k] = v;
-    } else if (a.startsWith('-') && a.length === 2) {
-      // Short flags: -y → yes, -v → version, -h → help
-      const short = a[1];
-      opts[short] = true;
-    } else {
-      opts._.push(a);
-    }
+const OPTION_SPEC = {
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean', short: 'v' },
+  ide: { type: 'string' },
+  all: { type: 'boolean' },
+  yes: { type: 'boolean', short: 'y' },
+  'repair-bridges': { type: 'boolean' },
+  check: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+};
+
+const GLOBAL_OPTIONS = ['help', 'version'];
+const COMMAND_OPTIONS = {
+  init: ['ide', 'all', 'yes', 'repair-bridges'],
+  update: ['check', 'dry-run'],
+  upgrade: ['check', 'dry-run'],
+};
+
+/**
+ * Strict argument parsing: unknown options, options of another command and stray
+ * positionals are UsageErrors — raised before any command can write a file.
+ */
+export function parseArgs(argv) {
+  let parsed;
+  try {
+    parsed = nodeParseArgs({ args: argv, options: OPTION_SPEC, allowPositionals: true, strict: true, tokens: true });
+  } catch (e) {
+    const unknown = e.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' && e.message.match(/'([^']+)'/);
+    const cmd = argv.find((a) => !a.startsWith('-')) ?? 'init';
+    throw new UsageError(unknown
+      ? `Unknown option '${unknown[1]}' for "${cmd}".`
+      : e.message.split('. ')[0].replace(/\.$/, '') + '.');
   }
-  // Normalize short flags to their long-form equivalents.
-  if (opts.y) opts.yes = true;
-  if (opts.v) opts.version = true;
-  if (opts.h) opts.help = true;
-  return opts;
+  const [cmd, ...extra] = parsed.positionals;
+  const { values } = parsed;
+  const command = cmd ?? (values.version ? 'version' : values.help ? 'help' : 'init');
+
+  const allowed = new Set([...GLOBAL_OPTIONS, ...(COMMAND_OPTIONS[command] ?? [])]);
+  const foreign = parsed.tokens.find((t) => t.kind === 'option' && !allowed.has(t.name));
+  if (foreign) throw new UsageError(`Unknown option '${foreign.rawName}' for "${command}".`);
+
+  if (extra.length) {
+    throw new UsageError(command === 'init'
+      ? 'init does not take a directory — cd into the project folder first.'
+      : `Unexpected argument "${extra[0]}" for "${command}".`);
+  }
+
+  const opts = { ...values, _: parsed.positionals };
+  if (opts['dry-run']) opts.check = true;
+  return { command, opts };
 }
 
 function help(version) {
@@ -65,8 +96,8 @@ ${c.bold('Commands')}
   init            Scaffold an opencrew workspace in the current folder
   update          Refresh the framework (keeps your crews, memory and .env)
   upgrade         Alias for update
-  help            Show this help
-  version         Print the version
+  help            Show this help (also: <command> --help, -h)
+  version         Print the version (also: --version, -v)
 
 ${c.bold('Options for init')}
   --ide=a,b       Preselect IDEs (skip the prompt). Valid: ${allIdeIds().join(', ')}
@@ -75,7 +106,8 @@ ${c.bold('Options for init')}
   --repair-bridges  Regenerate IDE bridge files in an existing workspace
 
 ${c.bold('Options for update')}
-  --check         Dry-run: report whether an update is available without making changes
+  --check         Report whether an update is available without making changes
+  --dry-run       Same as --check
 
 ${c.bold('Examples')}
   npx @aksp/opencrew init
@@ -87,8 +119,26 @@ ${c.bold('Examples')}
 `);
 }
 
-export async function run(argv) {
-  const opts = parseArgs(argv);
+/** Turn any error into one readable line and an exit code. Stack only with OPENCREW_DEBUG=1. */
+export function reportError(e) {
+  if (isPromptCancel(e)) {
+    warn('Cancelled — nothing was written.');
+    return 130;
+  }
+  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);
+  return 1;
+}
+
+export async function run(argv, { commands = { init, update } } = {}) {
+  let command, opts;
+  try {
+    ({ command, opts } = parseArgs(argv));
+  } catch (e) {
+    process.exitCode = reportError(e);
+    return;
+  }
 
   let version = 'unknown';
   let engines = {};
@@ -115,23 +165,23 @@ export async function run(argv) {
     }
   }
 
-  const cmd = opts._[0] || (opts.version ? 'version' : opts.help ? 'help' : 'init');
-
-  switch (cmd) {
-    case 'init':
-      return init(opts);
-    case 'update':
-    case 'upgrade':
-      return update(opts);
-    case 'version':
-    case '--version':
-      return log(version);
-    case 'help':
-    case '--help':
-      return help(version);
-    default:
-      err(`Unknown command: ${cmd}`);
-      help(version);
-      process.exitCode = 1;
+  // --version / --help never run a command (they may follow any command).
+  if (opts.version || command === 'version') return log(version);
+  if (opts.help || command === 'help') return help(version);
+
+  try {
+    switch (command) {
+      case 'init':
+        return await commands.init(opts);
+      case 'update':
+      case 'upgrade':
+        return await commands.update(opts);
+      default:
+        err(`Unknown command: ${command}`);
+        help(version);
+        process.exitCode = 1;
+    }
+  } catch (e) {
+    process.exitCode = reportError(e);
   }
 }

package/src/commands/init.js

@@ -2,26 +2,30 @@ 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 { ideById, allIdeIds } from '../lib/ides.js';
-import { pickIdes } from '../lib/prompts.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 { c, log, info, ok, warn, step } from '../lib/ui.js';
 
-export async function init(opts = {}) {
+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
+ * @param {{ pickIdes?: () => Promise<string[]> }} deps  injectable for tests
+ */
+export async function init(opts = {}, { pickIdes = promptIdes } = {}) {
   const target = process.cwd();
   const pkg = await readJson(packageJsonPath);
   const version = pkg.version;
-  const repairBridges = opts['repair-bridges'];
-
-  const alreadyInstalled = await exists(path.join(target, '_opencrew', 'core'));
+  const state = await workspaceState(target);
 
   // --repair-bridges mode: regenerate IDE bridge files in an existing workspace.
-  if (repairBridges && alreadyInstalled) {
+  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`));
-
-    let ids = normalizeIdes(opts.ide);
-    if (opts.all) ids = allIdeIds();
-    if (opts.yes || !ids) ids = allIdeIds();
     await writeBridges(target, ids, { overwrite: true });
 
     log(`\n${c.green(c.bold('Done!'))} IDE bridges regenerated.\n`);
@@ -29,7 +33,7 @@ export async function init(opts = {}) {
     return;
   }
 
-  if (alreadyInstalled) {
+  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')}`);
@@ -37,28 +41,18 @@ export async function init(opts = {}) {
     return;
   }
 
+  // Every choice is resolved BEFORE the first write: a bad --ide or Ctrl+C on the
+  // prompt leaves the folder exactly as it was.
+  const ids = await resolveIdes(opts, pickIdes);
+
   log(`\n${c.bold(c.cyan('opencrew'))} ${c.dim('v' + version)} — scaffolding a crew workspace`);
   log(c.dim(`Target: ${target}\n`));
+  if (state === 'partial') info('A previous install was interrupted — resuming (existing files are kept).');
 
   // 1. Copy the framework payload (never clobber user work).
   step('Installing framework files');
-  const copied = { count: 0 };
-  await copyDir(path.join(templatesDir, '_opencrew'), path.join(target, '_opencrew'), {
-    overwrite: false,
-    // Never ship stray logs or browser sessions; keep the empty dir via .gitkeep only.
-    skip: (rel) =>
-      (rel.startsWith('logs/') && rel !== 'logs/.gitkeep') ||
-      rel.startsWith('_browser_profile/'),
-    onCopy: () => (copied.count += 1),
-  });
-  await copyDir(path.join(templatesDir, 'skills'), path.join(target, 'skills'), {
-    overwrite: false,
-    onCopy: () => (copied.count += 1),
-  });
-  await copyDir(path.join(templatesDir, 'crews'), path.join(target, 'crews'), {
-    overwrite: false,
-  });
-  ok(`Framework files ready (${copied.count} written, existing files preserved)`);
+  const copied = await installPayload(target);
+  ok(`Framework files ready (${copied} written, existing files preserved)`);
 
   // 2. System doc + root configs.
   step('Writing configuration');
@@ -68,13 +62,7 @@ export async function init(opts = {}) {
   await writeFileSafe(path.join(target, '_opencrew', 'core', 'system.md'), await tpl('AGENTS.md'));
   ok('_opencrew/core/system.md (full system definition)');
 
-  const agentsBridge = '# 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';
-
-  const agentsResult = await writeBridgeFile(path.join(target, 'AGENTS.md'), agentsBridge);
+  const agentsResult = await writeBridgeFile(path.join(target, 'AGENTS.md'), AGENTS_BRIDGE);
   if (agentsResult.merged) info('AGENTS.md (merged — existing content preserved)');
   else ok('AGENTS.md (bridge to system.md)');
 
@@ -83,18 +71,13 @@ export async function init(opts = {}) {
   });
   info(mcpWritten ? '.mcp.json' : '.mcp.json (kept existing)');
 
-  await writeFileSafe(path.join(target, '.env.example'), await tpl('.env.example'));
-  const giWritten = await writeFileSafe(path.join(target, '.gitignore'), await tpl('gitignore'), {
-    overwrite: false,
-  });
-  info(giWritten ? '.gitignore' : '.gitignore (kept existing)');
+  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);
+  }
 
   // 3. IDE bridge files.
   step('Configuring AI IDEs');
-  let ids = normalizeIdes(opts.ide);
-  if (opts.all) ids = allIdeIds();
-  if (opts.yes) ids = allIdeIds();
-  if (!ids) ids = await pickIdes();
   await writeBridges(target, ids, { overwrite: false });
 
   if (ids.includes('claude-code')) {
@@ -102,8 +85,8 @@ export async function init(opts = {}) {
     warn(`native Playwright plugin/extension to avoid the two conflicting.`);
   }
 
-  // 4. Version stamp.
-  await fs.writeFile(path.join(target, '_opencrew', '.opencrew-version'), version + '\n');
+  // 4. Version stamp — written LAST: it is what marks the install as complete.
+  await fs.writeFile(path.join(target, STAMP), version + '\n');
 
   // 5. Done.
   log(`\n${c.green(c.bold('Done!'))} opencrew is installed.\n`);
@@ -113,10 +96,56 @@ export async function init(opts = {}) {
   log(`     No API keys needed up front — opencrew asks for them in chat only if a skill you use requires one.\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'), {
+    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;
+}
+
+/** 'none' (no core) · 'partial' (core without stamp: interrupted install) · 'complete'. */
+async function workspaceState(target) {
+  if (!(await exists(path.join(target, '_opencrew', 'core')))) return 'none';
+  return (await exists(path.join(target, STAMP))) ? 'complete' : 'partial';
+}
+
+/**
+ * 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.
+ */
+async function resolveIdes(opts, fallback) {
+  if (opts.all || opts.yes) return allIdeIds();
+  const ids = normalizeIdes(opts.ide);
+  if (!ids) return fallback();
+  const invalid = ids.filter((id) => !ideById(id));
+  const valid = ids.filter((id) => ideById(id));
+  if (!valid.length) {
+    throw new UsageError(`Unknown IDE "${invalid.join('", "')}". Valid: ${allIdeIds().join(', ')}`);
+  }
+  for (const id of invalid) warn(`Unknown IDE "${id}" — skipped. Valid: ${allIdeIds().join(', ')}`);
+  return valid;
+}
+
 /**
  * Write IDE bridge files to the target directory.
  * @param {string} target — project root
- * @param {string[]} ids — IDE ids to configure
+ * @param {string[]} ids — validated IDE ids to configure
  * @param {{ overwrite: boolean }} opts
  */
 async function writeBridges(target, ids, { overwrite }) {
@@ -124,10 +153,6 @@ async function writeBridges(target, ids, { overwrite }) {
 
   for (const id of ids) {
     const ide = ideById(id);
-    if (!ide) {
-      warn(`Unknown IDE "${id}" — skipped. Valid: ${allIdeIds().join(', ')}`);
-      continue;
-    }
     for (const f of ide.files) {
       if (writtenPaths.has(f.path)) {
         info(`${f.path} (shared path — written once)`);
@@ -155,5 +180,6 @@ async function tpl(name) {
 function normalizeIdes(val) {
   if (!val || val === true) return null;
   const list = Array.isArray(val) ? val : String(val).split(',');
-  return list.map((s) => s.trim()).filter(Boolean);
+  const ids = list.map((s) => s.trim()).filter(Boolean);
+  return ids.length ? ids : null;
 }