@aksp/opencrew 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -3,6 +3,44 @@
 All notable changes to opencrew are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [1.1.0] — 2026-08-01
+
+### Fixed
+- **Skill catalog URLs**: `/opencrew install` now fetches skills from the correct fork
+  (`alberthpalhares/opencrew/templates/skills/`) instead of the upstream OpenSquad repo.
+- **Publish workflow**: restored `push: tags` as the sole trigger — the actual release
+  flow is `npm version` + `git push --tags`, not GitHub Releases. Documented in
+  `CONTRIBUTING.md`.
+- **Cross-platform test script**: replaced shell glob (`tests/*.test.js`) with an
+  explicit file list so `npm test` works on Windows PowerShell + Node 20.
+- **CI matrix**: test suite now runs on Ubuntu and Windows on every push/PR.
+
+### Added
+- **Test suite**: 30 tests (`node:test`) covering `fsx.js`, init, update, IDE bridge
+  validation, and documentation contracts.
+- **CI version-sync check**: `scripts/check-version-sync.js` fails the build if
+  `.opencrew-version` drifts from `package.json`.
+- **Playwright plugin warning**: `init` now warns Claude Code users to disable the
+  native Playwright extension (opencrew ships its own via `.mcp.json`).
+
+### Changed
+- **Dashboard opt-in**: Pipeline Runner `state.json` writes are now gated on
+  `Dashboard: enabled` in `preferences.md` (default: disabled). Removed the
+  unconditional 10-second sleep at the end of every pipeline run.
+- **Smaller fixes**: removed `AskUserQuestion` references from IDE-neutral files,
+  corrected `update.js` comment about overwrite behavior, pinned `@playwright/mcp`
+  version, removed stale root `skills/` directory (drifted duplicate of
+  `templates/skills/`).
+
+## [1.0.1] — 2026-08-01
+
+### Changed
+- API keys for optional skills are now requested conversationally in chat (during crew
+  creation or skill install) instead of requiring the user to manually copy/edit `.env`
+  beforehand. Values are collected and written to `.env` automatically.
+- `init` no longer tells users to configure `.env` as a next step — no setup is required
+  to start using opencrew.
+
 ## [1.0.0] — 2026-08-01
 
 ### Added

package/README.md

@@ -1,61 +1,79 @@
 # opencrew
 
-**Create AI agent crews that work together — right from your IDE.**
+[![CI](https://github.com/alberthpalhares/opencrew/actions/workflows/ci.yml/badge.svg)](https://github.com/alberthpalhares/opencrew/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40aksp%2Fopencrew)](https://www.npmjs.com/package/@aksp/opencrew)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-opencrew is a multi-agent orchestration framework. Describe what you need in plain
-language and it assembles a team of specialized agents that run as an automated pipeline
-with human approval checkpoints. It works across Claude Code, Cursor, Codex, Gemini CLI,
-OpenCode, Antigravity and more.
+**Crie equipes de agentes de IA que trabalham juntos — direto na sua IDE.**
 
-> **This is not an original framework — it's my personal build of OpenSquad.**
-> [OpenSquad](https://github.com/renatoasse/opensquad) was created by
+> 🇧🇷 This README is in Brazilian Portuguese (PT-BR), the project's primary audience. If
+> you don't read Portuguese, use your browser's translator (e.g. Google Translate) or ask
+> an AI assistant to translate this page.
+
+opencrew é um framework de orquestração multi-agente. Descreva o que você precisa em
+linguagem natural e ele monta um time de agentes especializados que rodam como um pipeline
+automatizado, com pontos de aprovação humana. Funciona no Claude Code, Cursor, Codex,
+Gemini CLI, OpenCode, Antigravity e mais.
+
+> **Este não é um framework original — é a minha versão pessoal do OpenSquad.**
+> O [OpenSquad](https://github.com/renatoasse/opensquad) foi criado por
 > [Renato Asse](https://github.com/renatoasse) ([Comunidade Sem Codar](https://semcodar.com.br)).
-> I ([aksp](https://www.npmjs.com/~aksp)) use OpenSquad daily and wanted to improve a few
-> things for my own workflow — so `opencrew` is that reworked version, shared in case it
-> helps others too. All credit for the original idea and framework goes to Renato Asse.
-> See [Origin & credits](#origin--credits) below. MIT licensed, same as the original.
+> Eu ([aksp](https://www.npmjs.com/~aksp)) uso o OpenSquad no dia a dia e quis melhorar
+> algumas coisas para o meu próprio fluxo de trabalho — o `opencrew` é essa versão
+> reformulada, compartilhada caso ajude outras pessoas também. Todo o crédito pela ideia e
+> pelo framework original é do Renato Asse. Veja [Origem e créditos](#origem-e-créditos)
+> abaixo. Licenciado sob MIT, assim como o original.
 
 ---
 
-## Installation
+## Instalação
 
-**Prerequisite:** Node.js 20+
+**Pré-requisito:** Node.js 20+
 
 ```bash
 npx @aksp/opencrew init
 ```
 
-`init` scaffolds the workspace in the current folder and asks which AI IDEs you use, then
-generates the right integration files for each. Then:
+O `init` monta o workspace na pasta atual e pergunta quais IDEs de IA você usa, gerando os
+arquivos de integração certos para cada uma. Depois:
+
+1. Abra a pasta na sua IDE de IA.
+2. Digite `/opencrew` para começar — a primeira execução configura o perfil da sua empresa.
+
+Isso já é suficiente para criar e rodar crews: nenhuma configuração prévia, instalação
+extra ou chave de API é necessária para começar.
 
-1. Open the folder in your AI IDE.
-2. Copy `.env.example` to `.env` and fill in keys for the skills you plan to use.
-3. Type `/opencrew` to start — the first run sets up your company profile.
+Algumas **skills opcionais** dependem de serviços externos — por exemplo, publicar no
+Instagram, gerar imagens com IA, fazer web scraping (Apify) ou enviar e-mails (Resend). Você
+não precisa se preocupar com isso antes de começar: se, ao montar uma crew, o opencrew
+identificar que ela precisa de uma dessas skills, ele pede a chave direto na conversa
+(explicando o que é e onde consegui-la) e salva tudo por conta própria. Não é preciso abrir
+nem editar nenhum arquivo manualmente.
 
-Preselect IDEs (skip the prompt) or configure all of them:
+Você pode pré-selecionar as IDEs (pula a pergunta) ou configurar todas de uma vez:
 
 ```bash
 npx @aksp/opencrew init --ide=claude-code,codex
 npx @aksp/opencrew init --all
 ```
 
-## Updating
+## Atualizando
 
-Refresh the framework without losing your work:
+Atualize o framework sem perder o seu trabalho:
 
 ```bash
 npx @aksp/opencrew update
 ```
 
-`update` refreshes only `_opencrew/core`, the catalog skills and `AGENTS.md`.
-Your `crews/`, memory, IDE bridges and `.env` are left untouched.
+O `update` atualiza apenas `_opencrew/core`, as skills do catálogo e o `AGENTS.md`. Suas
+`crews/`, memória, integrações de IDE e `.env` continuam intactos.
 
-## Supported IDEs
+## IDEs suportadas
 
-| IDE | Bridge file(s) generated |
+| IDE | Arquivo(s) de integração gerado(s) |
 |-----|--------------------------|
 | Claude Code | `.claude/skills/opencrew/SKILL.md`, `CLAUDE.md` |
-| Codex (OpenAI) | `AGENTS.md` (native) + `.agents/skills/opencrew/SKILL.md` |
+| Codex (OpenAI) | `AGENTS.md` (nativo) + `.agents/skills/opencrew/SKILL.md` |
 | Cursor | `.cursor/rules/opencrew.mdc` |
 | VS Code + Copilot | `.github/copilot-instructions.md` |
 | OpenCode | `.opencode/commands/opencrew.md` |
@@ -64,55 +82,69 @@ Your `crews/`, memory, IDE bridges and `.env` are left untouched.
 | Qwen Code | `QWEN.md` |
 | Trae | `.trae/rules/opencrew.md` |
 
-Every bridge is a thin pointer to the single source of truth, **`AGENTS.md`**.
+Cada integração é só um ponteiro enxuto para a fonte única de verdade, o **`AGENTS.md`**.
+
+## Como funciona
+
+- **Architect** projeta uma crew a partir da sua descrição (agentes, pipeline, skills).
+- **Sherlock** (opcional) analisa perfis de referência para extrair padrões reais de conteúdo.
+- **Pipeline Runner** executa a crew, pausando nos checkpoints para sua aprovação.
+- **Skills Engine** carrega integrações (scraping, design, publicação, e-mail…) sob demanda,
+  usando um esquema em duas camadas para manter o consumo de tokens baixo.
+
+## Dashboard (opcional)
 
-## How it works
+O opencrew inclui um dashboard visual auto-contido — `dashboard/index.html`, um arquivo
+HTML único sem dependências que mostra a execução de uma crew como um escritório virtual
+animado (com agentes trabalhando em suas mesas, handoffs entre etapas, e indicador de
+progresso). 
 
-- **Architect** designs a crew from your description (agents, pipeline, skills).
-- **Sherlock** (optional) analyzes reference profiles to extract real content patterns.
-- **Pipeline Runner** executes the crew, pausing at checkpoints for your approval.
-- **Skills Engine** loads integrations (scraping, design, publishing, email…) on demand,
-  using a two-tier scheme to keep token usage low.
+Ele é **desligado por padrão** — o Pipeline Runner não escreve `state.json` a menos que
+você ligue o recurso (`Dashboard: enabled` em `_opencrew/_memory/preferences.md`, via
+`/opencrew settings`). Inclui modo demo embutido para visualização sem precisar rodar uma
+crew real.
 
-## Commands (inside your IDE)
+## Comandos (dentro da sua IDE)
 
-| Command | What it does |
+| Comando | O que faz |
 |---------|--------------|
-| `/opencrew` | Open the main menu |
-| `/opencrew create <description>` | Create a new crew |
-| `/opencrew run <name>` | Run a crew |
-| `/opencrew list` | List your crews |
-| `/opencrew edit <name>` | Modify a crew |
-| `/opencrew skills` | Browse / install / remove skills |
-
-## For maintainers
-
-See [CONTRIBUTING.md](CONTRIBUTING.md). The golden rule: `AGENTS.md` is the only place
-system instructions live; per-IDE files are generated from `src/lib/ides.js`.
-
-## Origin & credits
-
-`opencrew` is a **reworked distribution of [OpenSquad](https://github.com/renatoasse/opensquad)**,
-the multi-agent orchestration framework created and maintained by
-**[Renato Asse](https://github.com/renatoasse)**, founder of
-[Comunidade Sem Codar](https://semcodar.com.br). The original project, its concept, agent
-model, pipeline design and skill system are his work — please star and follow the
-[upstream repository](https://github.com/renatoasse/opensquad) and watch the
-[launch video](https://www.youtube.com/watch?v=CL1ppI4qHeU).
-
-I use OpenSquad in my day-to-day and made a few changes that fit how I work, which I believe
-can help other people as well. What this build changes relative to upstream:
-
-- **npm installer under my scope** — `npx @aksp/opencrew init` / `update`, with a
-  non-destructive update path that preserves your crews, memory and `.env`.
-- **Single source of truth for multi-IDE** — one canonical `AGENTS.md`; every IDE gets a
-  thin generated bridge file instead of a hand-maintained document per tool.
-- **Token-economy and skill-invocation improvements** to the framework core.
-
-This is an independent, community fork — it is **not** affiliated with or endorsed by
-Renato Asse or Comunidade Sem Codar. If you want the official project, use
+| `/opencrew` | Abre o menu principal |
+| `/opencrew create <descrição>` | Cria uma nova crew |
+| `/opencrew run <nome>` | Executa uma crew |
+| `/opencrew list` | Lista suas crews |
+| `/opencrew edit <nome>` | Modifica uma crew |
+| `/opencrew skills` | Navega / instala / remove skills |
+
+## Para mantenedores
+
+Veja [CONTRIBUTING.md](CONTRIBUTING.md). Regra de ouro: `AGENTS.md` é o único lugar onde
+vivem as instruções do sistema; os arquivos por IDE são gerados a partir de `src/lib/ides.js`.
+
+## Origem e créditos
+
+`opencrew` é uma **distribuição reformulada do [OpenSquad](https://github.com/renatoasse/opensquad)**,
+o framework de orquestração multi-agente criado e mantido por
+**[Renato Asse](https://github.com/renatoasse)**, fundador da
+[Comunidade Sem Codar](https://semcodar.com.br). O projeto original, seu conceito, o modelo
+de agentes, o design do pipeline e o sistema de skills são trabalho dele — dê uma estrela e
+siga o [repositório original](https://github.com/renatoasse/opensquad) e assista ao
+[vídeo de lançamento](https://www.youtube.com/watch?v=CL1ppI4qHeU).
+
+Eu uso o OpenSquad no meu dia a dia e fiz algumas mudanças que se encaixam no meu jeito de
+trabalhar, que acredito que também podem ajudar outras pessoas. O que esta versão muda em
+relação ao original:
+
+- **Instalador npm no meu escopo** — `npx @aksp/opencrew init` / `update`, com um caminho
+  de atualização não destrutivo que preserva suas crews, memória e `.env`.
+- **Fonte única de verdade para multi-IDE** — um `AGENTS.md` canônico; cada IDE recebe um
+  arquivo de integração gerado e enxuto, em vez de um documento mantido manualmente para
+  cada ferramenta.
+- **Melhorias de economia de tokens e de invocação de skills** no núcleo do framework.
+
+Este é um fork independente, feito pela comunidade — **não** é afiliado nem endossado pelo
+Renato Asse ou pela Comunidade Sem Codar. Se você quiser o projeto oficial, use
 [`npx opensquad init`](https://github.com/renatoasse/opensquad).
 
-## License
+## Licença
 
-MIT — see [LICENSE](LICENSE). Original OpenSquad framework © Renato Asse, also MIT.
+MIT — veja [LICENSE](LICENSE). Framework OpenSquad original © Renato Asse, também MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aksp/opencrew",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +19,7 @@
   ],
   "scripts": {
     "start": "node bin/opencrew.js",
-    "test": "node --test tests/*.test.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/update.test.js",
     "version": "node -e \"require('fs').writeFileSync('templates/_opencrew/.opencrew-version', require('./package.json').version + '\\n')\""
   },
   "keywords": [

package/src/cli.js

@@ -3,7 +3,7 @@ import { packageJsonPath } from './lib/paths.js';
 import { allIdeIds } from './lib/ides.js';
 import { init } from './commands/init.js';
 import { update } from './commands/update.js';
-import { c, log, err } from './lib/ui.js';
+import { c, log, err, warn, info } from './lib/ui.js';
 
 function parseArgs(argv) {
   const opts = { _: [] };
@@ -36,18 +36,49 @@ ${c.bold('Options for init')}
   --all           Configure every supported IDE
   --yes           Non-interactive; accept defaults
 
+${c.bold('Options for update')}
+  --check         Dry-run: report whether an update is available without making changes
+
 ${c.bold('Examples')}
   npx @aksp/opencrew init
   npx @aksp/opencrew init --ide=claude-code,codex
   npx @aksp/opencrew init --all
   npx @aksp/opencrew update
+  npx @aksp/opencrew update --check
 `);
 }
 
 export async function run(argv) {
   const opts = parseArgs(argv);
-  const pkg = await readJson(packageJsonPath);
-  const version = pkg.version;
+
+  let version = 'unknown';
+  let engines = {};
+  try {
+    const pkg = await readJson(packageJsonPath);
+    version = pkg.version;
+    engines = pkg.engines || {};
+  } catch {
+    err('Could not read package.json. The installation may be corrupted.');
+    info('Try reinstalling: npm install @aksp/opencrew');
+    process.exitCode = 1;
+    return;
+  }
+
+  // Validate Node version against engines.node requirement.
+  if (engines.node) {
+    const min = engines.node.replace(/[^0-9.]/g, '');
+    if (min) {
+      const major = Number(min.split('.')[0]);
+      const current = Number(process.versions.node.split('.')[0]);
+      if (current < major) {
+        warn(`opencrew requires Node.js ${engines.node}. You have v${process.versions.node}.`);
+        info(`Upgrade Node or use a compatible version.`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+
   const cmd = opts._[0] || (opts.help ? 'help' : 'init');
 
   switch (cmd) {

package/src/commands/init.js

@@ -75,6 +75,11 @@ export async function init(opts = {}) {
     ok(`${ide.label} → ${ide.files.map((f) => f.path).join(', ')}`);
   }
 
+  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.
   await fs.writeFile(path.join(target, '_opencrew', '.opencrew-version'), version + '\n');
 
@@ -82,8 +87,8 @@ export async function init(opts = {}) {
   log(`\n${c.green(c.bold('Done!'))} opencrew is installed.\n`);
   log(`${c.bold('Next steps:')}`);
   log(`  1. Open this folder in your AI IDE.`);
-  log(`  2. Copy ${c.cyan('.env.example')} to ${c.cyan('.env')} and fill in keys for the skills you use.`);
-  log(`  3. Type ${c.cyan('/opencrew')} to start (first run sets up your company profile).\n`);
+  log(`  2. Type ${c.cyan('/opencrew')} to start (first run sets up your company profile).`);
+  log(`     No API keys needed up front — opencrew asks for them in chat only if a skill you use requires one.\n`);
 }
 
 async function tpl(name) {

package/src/commands/update.js

@@ -6,7 +6,11 @@ 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.
-export async function update() {
+// 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.
+export async function update(opts = {}) {
   const target = process.cwd();
   const pkg = await readJson(packageJsonPath);
   const version = pkg.version;
@@ -25,6 +29,17 @@ export async function update() {
   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 {
+      info(`Update available: v${current} → v${version}.`);
+      info(`Run ${c.cyan('npx @aksp/opencrew update')} to apply.`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (current === version) {
     ok('Already up to date. Refreshing framework files anyway.');
   }
@@ -38,8 +53,11 @@ export async function update() {
   });
   ok(`_opencrew/core refreshed (${n} files)`);
 
-  // Refresh catalog skills but preserve any user-modified/added ones:
-  // only overwrite skills that ship with the package; leave others untouched.
+  // 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');
   let s = 0;
   await copyDir(path.join(templatesDir, 'skills'), path.join(target, 'skills'), {

package/src/lib/fsx.js

@@ -50,6 +50,21 @@ export async function writeFileSafe(p, content, { overwrite = true } = {}) {
   return true;
 }
 
+/**
+ * Remove a directory and all its contents.
+ * Does nothing silently if the path does not exist.
+ * @param {string} p  Directory path to remove.
+ * @returns {Promise<boolean>} true if something was deleted, false if it didn't exist.
+ */
+export async function deleteDir(p) {
+  try {
+    await fs.rm(p, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function readJson(p) {
   return JSON.parse(await fs.readFile(p, 'utf8'));
 }

package/templates/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "playwright": {
       "command": "npx",
-      "args": ["@playwright/mcp@latest", "--config", "_opencrew/config/playwright.config.json"]
+      "args": ["@playwright/mcp@0.0.78", "--config", "_opencrew/config/playwright.config.json"]
     }
   }
 }

package/templates/AGENTS.md

@@ -31,7 +31,7 @@ If `company.md` is empty or contains `<!-- NOT CONFIGURED -->`:
 
 ## Main Menu
 
-When the user types `/opencrew` or asks for the menu, present an interactive selector using AskUserQuestion with these options (max 4 per question):
+When the user types `/opencrew` or asks for the menu, present an interactive selector with these options (max 4 per question). Use your IDE's native interactive-choice mechanism if it has one (e.g. Claude Code's `AskUserQuestion`); otherwise present the options as a numbered list and ask the user to reply with a number:
 
 **Primary menu (first question):**
 - **Create a new crew** — Describe what you need and I'll build a crew for you
@@ -39,7 +39,7 @@ When the user types `/opencrew` or asks for the menu, present an interactive sel
 - **My crews** — View, edit, or delete your crews
 - **More options** — Skills, company profile, settings, and help
 
-If the user selects "More options", present a second AskUserQuestion:
+If the user selects "More options", present a second selector the same way:
 - **Skills** — Browse, install, create, and manage skills for your crews
 - **Company profile** — View or update your company information
 - **Settings & Help** — Language, preferences, configuration, and help
@@ -84,8 +84,28 @@ When running a crew:
 3. For each agent in the party CSV, also read their full `.agent.md` file from agents/ directory
 4. Load company context from `_opencrew/_memory/company.md`
 5. Load crew memory from `crews/{name}/_memory/memories.md`
-6. Read the pipeline runner instructions from `_opencrew/core/runner.pipeline.md`
-7. Execute the pipeline step by step following runner instructions
+6. Load user preferences from `_opencrew/_memory/preferences.md` (used to check the Dashboard toggle — see below)
+7. Read the pipeline runner instructions from `_opencrew/core/runner.pipeline.md`
+8. Execute the pipeline step by step following runner instructions
+
+## Dashboard (Optional)
+
+opencrew ships an optional visual dashboard — a self-contained HTML file
+(`dashboard/index.html`) that shows a crew run in progress as an animated
+virtual office. It is **disabled by default** and most installs never use it,
+so the Pipeline Runner does not write `state.json` unless the user has turned
+it on.
+
+- To use: open `dashboard/index.html` in a browser and point it at the
+  `crews/{name}/state.json` written during a run.
+- Toggle: `Dashboard: enabled` (or `disabled`) in `_opencrew/_memory/preferences.md`,
+  editable via `/opencrew settings`.
+- When disabled (default): the runner never creates, writes, or deletes `state.json`.
+- When enabled: the runner writes `crews/{name}/state.json` before each step and at
+  every handoff, exactly as described in `_opencrew/core/runner.pipeline.md`.
+- The dashboard auto-polls `state.json` every 1.5 seconds when in live mode;
+  it also includes a built-in demo mode so you can see what it looks like
+  without running a real crew.
 
 ## Language Handling
 
@@ -93,6 +113,13 @@ When running a crew:
 - All user-facing output should be in the user's preferred language
 - Internal file names and code remain in English
 - Agent personas communicate in the user's language
+- **Exception — crew memory scaffolding stays in PT-BR regardless of Output Language.**
+  The section headers in `crews/{name}/_memory/memories.md` (e.g. `## Estilo de Escrita`)
+  and the table columns in `crews/{name}/_memory/runs.md` (e.g. `Data | Run ID | Tema`) are
+  fixed structural labels, not generated prose — see `_opencrew/core/runner.pipeline.md`.
+  opencrew's primary supported audience is PT-BR (see README), so these are intentionally
+  not localized per-user. Only the *content* written into those sections follows the
+  user's Output Language.
 
 ## Critical Rules
 

package/templates/_opencrew/.opencrew-version

@@ -1 +1 @@
-0.1.15
+1.0.1

package/templates/_opencrew/_memory/preferences.md

@@ -7,3 +7,4 @@
 - **Output Language:**
 - **IDEs:**
 - **Date Format:** YYYY-MM-DD
+- **Dashboard:** disabled

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

@@ -14,6 +14,21 @@ Before starting execution:
    - The crew's `crew-party.csv` (all agent personas)
    - Company context from `_opencrew/_memory/company.md`
    - Crew memory from `crews/{name}/_memory/memories.md`
+   - User preferences from `_opencrew/_memory/preferences.md`
+
+1a. **Check the Dashboard toggle** — the visual dashboard (`state.json` writes) is an
+    optional, opt-in feature that most installs never use (it requires running the
+    separate dashboard app from source — see README). Scan the already-loaded
+    `preferences.md` for a `Dashboard:` field:
+    - If it reads `Dashboard: enabled` → set `dashboard_enabled = true` for this run.
+    - Otherwise (`disabled`, missing, or preferences.md not configured yet) →
+      set `dashboard_enabled = false`. This is the default.
+    Store `dashboard_enabled` in working memory for the rest of this run. Every
+    `state.json` read/write instruction in this document is conditional on it —
+    when `false`, skip ALL of them; never create, update, or delete
+    `crews/{name}/state.json`.
+
+> **Note on language**: the section headers below (`## Estilo de Escrita`, `## Design Visual`, etc.) and the `runs.md` table columns (`Data | Run ID | Tema | ...`) are fixed PT-BR structural labels, not translated per Output Language — opencrew's primary supported audience is PT-BR (see AGENTS.md → Language Handling). Only the *content* written under these headers follows the user's preferred language.
 
 1b. **Memory format migration** — After loading `memories.md`, check whether it uses the new format by scanning for the `## Estilo de Escrita` section header:
    ```bash
@@ -76,8 +91,8 @@ Before starting execution:
      - If it does (sub-second collision), append `-2`, `-3`, etc. until the folder does not exist
    - Create the folder using Bash: `mkdir -p crews/{name}/output/{run_id}`
    - Store `run_id` in working memory for this run — it will be used for ALL output paths
-6. **Initialize state.json**: Create `crews/{name}/state.json` from scratch (see below). State writes are always mandatory.
-   - **IMPORTANT**: You MUST write to `crews/{name}/state.json` before every step and after every handoff. This is non-negotiable. Never skip these writes.
+6. **Initialize state.json** (only if `dashboard_enabled` — see step 1a; otherwise skip this entire step, including all sub-steps below):
+   - **IMPORTANT**: When enabled, write to `crews/{name}/state.json` before every step and after every handoff, as described throughout this document. When `dashboard_enabled` is false, never create, write, or delete this file.
    - Create `state.json` from scratch:
      a. Read `crews/{name}/crew-party.csv` — for each agent row (skip header), extract:
         - `id`: take the `path` column, strip `./agents/` prefix and `.agent.md` suffix
@@ -270,7 +285,7 @@ Apply this transformation consistently for every write in this step.
 
 ### For each pipeline step:
 
-0. **Update dashboard** — MANDATORY. Write `crews/{name}/state.json` using the Write tool. Always write — it is never wrong to update the dashboard. Use this content:
+0. **Update dashboard** (only if `dashboard_enabled`; otherwise skip to step 1). Write `crews/{name}/state.json` using the Write tool. Use this content:
    ```json
    {
      "crew": "{crew code from crew.yaml}",
@@ -458,7 +473,8 @@ When a step has `on_reject: {step-id}`:
 
 ### Dashboard Handoff (between steps)
 
-After a step completes output and there IS a next step (MANDATORY):
+Only if `dashboard_enabled` (otherwise skip this entire section). After a step
+completes output and there IS a next step:
 
 1. **Write delivering state** — Write `crews/{name}/state.json` with:
    - Current step's agent: `"status": "delivering"`
@@ -489,13 +505,13 @@ After a step completes output and there IS a next step (MANDATORY):
 For reference, the complete execution order for each pipeline step is:
 
 ```
-0. Dashboard update (state.json)
+0. Dashboard update (state.json) — only if dashboard_enabled
 1. Pre-Step Input Validation (bash gate)
 2. Read step file
 3. Check execution mode and execute (subagent / inline / checkpoint)
 4. Post-Step Output Validation (bash gate)
 5. Veto Condition Enforcement
-6. Dashboard Handoff (to next step)
+6. Dashboard Handoff (to next step) — only if dashboard_enabled
 ```
 
 Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT advance — the user is consulted.
@@ -504,7 +520,7 @@ Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT adva
 
 1. Save final output to `crews/{name}/output/{run_id}/{filename}.md`
    (The run folder was created during initialization — no separate date subfolder needed)
-1b. **Update dashboard** — MANDATORY. Write `crews/{name}/state.json` with:
+1b. **Update dashboard** (only if `dashboard_enabled`; otherwise skip to step 2 below). Write `crews/{name}/state.json` with:
     - `"status": "completed"`
     - All agents: `"status": "done"`
     - `"updatedAt"`: now
@@ -512,7 +528,7 @@ Steps 1 and 4 are binary bash gates. If either fails, the pipeline does NOT adva
     - `"startedAt"`: preserve from existing `state.json`
     - Keep existing `"handoff"` object
 
-### Post-Completion Cleanup
+### Post-Completion Cleanup (only if `dashboard_enabled`)
 
 After writing the final "completed" state to `crews/{name}/state.json`:
 
@@ -521,13 +537,12 @@ After writing the final "completed" state to `crews/{name}/state.json`:
    ```bash
    cp crews/{name}/state.json crews/{name}/output/{run_id}/state.json
    ```
-3. Wait 10 seconds (so the dashboard can display the completed state)
-4. Delete the working copy:
-   ```bash
-   rm crews/{name}/state.json
-   ```
+3. Leave the working copy of `crews/{name}/state.json` in place — do not delete it and
+   do not add an artificial delay. A dashboard watching the file already sees the
+   "completed" status the moment it's written; the next run's initialization (step 6)
+   overwrites this file from scratch. There is nothing to clean up.
 
-This archives the run state for the `runs` command while keeping the crew root clean.
+This archives the run state for the `runs` command while keeping crew history available.
 
 2. **Update crew memory** — write to BOTH files (runs after Post-Completion Cleanup above):
 

package/templates/_opencrew/core/skills.engine.md

@@ -12,9 +12,19 @@ You are the Skills Engine. Your job is to manage skill integrations for opencrew
 ## File Locations
 
 - **Installed skills**: `skills/` — each skill in its own subdirectory with SKILL.md
-- **Skill catalog**: `https://github.com/renatoasse/opensquad/tree/main/skills`
+- **Skill catalog index**: `skills/catalog.json` (local) — structured skill metadata.
+  If missing, fall back to the catalog README:
+  `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md`
 - **Skill format reference**: `skills/opencrew-skill-creator/references/skill-format.md`
 
+### Catalog URL Resolution
+
+When fetching skill files from the catalog, resolve the base URL in this order:
+1. Read `skills/catalog.json` (installed locally during init/update) → use its `baseUrl` field
+2. If not available, default to:
+   `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills`
+3. Append `/<name>/SKILL.md` (or other file paths) to the base URL
+
 ## How Skills Are Detected
 
 A skill is installed if and only if `skills/<name>/SKILL.md` exists.
@@ -96,9 +106,18 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
 1. User provides a skill name (or selects from the catalog).
 
-2. **Fetch SKILL.md from GitHub**:
+2. **Resolve the catalog base URL** (see Catalog URL Resolution above).
+
+3. **Validate minimum version** (if catalog.json available):
+   - Check `catalog.json` → `skills.<name>.minVersion`
+   - Compare against the installed opencrew version (from `_opencrew/.opencrew-version`)
+   - If installed version < minVersion → **ERROR**: "Skill '{name}' requires opencrew
+     v{minVersion} or newer. You have v{installed}. Run `npx @aksp/opencrew update`
+     to upgrade."
+
+4. **Fetch SKILL.md from catalog**:
    ```
-   https://raw.githubusercontent.com/renatoasse/opensquad/main/skills/<name>/SKILL.md
+   {baseUrl}/<name>/SKILL.md
    ```
    - If fetch fails (404 or network error) → **ERROR**: "Skill '<name>' not found in the skills catalog."
    - Do NOT proceed if the SKILL.md cannot be fetched.
@@ -112,7 +131,7 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
 5. **Fetch additional files** (if the skill requires them):
    - If the SKILL.md frontmatter has `script.path` → fetch the script file from:
-     `https://raw.githubusercontent.com/renatoasse/opensquad/main/skills/<name>/{script.path}`
+     `{baseUrl}/<name>/{script.path}`
      Create subdirectories (e.g., `scripts/`) as needed.
    - If the skill has a `references/` directory mentioned → fetch those files too.
    - If the skill has an `assets/` directory mentioned → fetch those files too.
@@ -121,10 +140,25 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
    #### a. Environment Variables (if `env:` is present)
 
-   For each variable listed in the `env` array, check if it exists in the project `.env` file.
-   - For each missing variable, inform the user:
-     "⚠️ Environment variable `{VAR_NAME}` is required by {skill name}. Add it to your `.env` file."
-   - Do NOT block installation — warn only. The skill is installed even without env vars configured.
+   This is a conversational step — never ask the user to open or edit `.env` manually.
+   The audience is non-technical (managers, analysts), so all secrets are collected in
+   chat and written to disk automatically.
+
+   For each variable listed in the `env` array:
+   1. Check if it already exists (non-empty) in the project `.env` file → if so, reuse it
+      silently, skip to the next variable.
+   2. If missing, ask the user directly in chat:
+      "This skill needs an API key to work: **{VAR_NAME}** ({one-line purpose, e.g. 'your
+      Instagram access token'}). Paste it here, or press Enter to skip and set it up later."
+   3. If the user provides a value → write it to the project `.env` file (create the file
+      from `.env.example` if it doesn't exist yet). Confirm briefly: "✅ Saved."
+   4. If the user skips → inform them:
+      "⚠️ {skill name} won't fully work until `{VAR_NAME}` is set. You can add it anytime —
+      just ask me to configure {skill name} again."
+   - Do NOT block installation either way — the skill is installed regardless of whether
+     env vars were provided.
+   - Values collected here are reused in steps b/c below — do not ask for the same
+     variable twice.
 
    #### b. MCP Setup — stdio transport (if `type: mcp` or `type: hybrid` with `mcp.transport: stdio` or no transport specified)
 
@@ -135,9 +169,8 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
         1. Yes, overwrite
         2. No, keep existing
         If "No" → skip MCP configuration but still complete installation
-   3. For each env var listed in the skill's `env` array:
-      - Check `.env` for an existing value
-      - If missing, ask the user to type the value directly
+   3. Use the values already collected in step 6.a for each env var in the skill's `env`
+      array (do not ask again).
    4. Add to `mcpServers`:
       ```json
       "{server_name}": {
@@ -154,9 +187,8 @@ For the full SKILL.md specification, see `skills/opencrew-skill-creator/referenc
 
    1. Read `.claude/settings.local.json` (create with `{"mcpServers": {}}` if it doesn't exist)
    2. Check for `server_name` conflict (same as stdio above)
-   3. For each env var listed in the skill's `env` array:
-      - Check `.env` for an existing value
-      - If missing, ask the user to type the value directly
+   3. Use the values already collected in step 6.a for each env var in the skill's `env`
+      array (do not ask again).
    4. Build the mcpServers entry:
       - Start with `{ "type": "http", "url": "{url}" }`
       - If the skill has a `headers` field in `mcp`, add a `"headers"` object by resolving
@@ -267,8 +299,11 @@ before the pipeline begins (fail fast).
 
    d. **Verify env vars** (if `env:` is present):
       - Check each variable in `.env`
-      - If any are missing → warn the user but do NOT block pipeline execution.
-        "⚠️ Skill '{skill}' is missing environment variable(s): {list}. It may not work correctly."
+      - If any are missing → ask the user conversationally, right here in chat, the same
+        way as Operation 2, step 6.a (never point them to the `.env` file to edit it
+        themselves). If they provide a value, write it to `.env` and continue. If they
+        skip, warn: "⚠️ Skill '{skill}' is missing environment variable(s): {list}. It may
+        not work correctly." — but do NOT block pipeline execution either way.
 
 4. **Return resolved skill list**: Return all resolved skills with their parsed frontmatter
    and SKILL.md body content. This list is used by Operation 6 to inject instructions.
@@ -329,11 +364,16 @@ When the Architect reaches Phase 3.5 during crew creation:
    to get name, description, type, and categories.
 
 2. **Fetch the catalog index**:
-   Fetch the catalog README from GitHub to see all available skills:
-   ```
-   https://raw.githubusercontent.com/renatoasse/opensquad/main/skills/README.md
-   ```
-   - If fetch fails → proceed with only installed skills (do not block crew creation).
+   a. First, try to read `skills/catalog.json` (installed locally). If it exists:
+      - Parse the JSON and extract the `skills` map and `baseUrl`
+      - Use this for discovery (skip the network fetch below)
+   b. If `skills/catalog.json` does NOT exist (pre-v1.1 install), fall back to fetching
+      the catalog README from GitHub:
+      ```
+      https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/README.md
+      ```
+      Parse the markdown table to extract skill names, types, and descriptions.
+   c. If both fail → proceed with only installed skills (do not block crew creation).
 
 3. **Analyze crew requirements**:
    From the discovery phase answers (Phase 1), identify what the crew needs:

package/templates/skills/README.md

@@ -0,0 +1,22 @@
+# Catálogo de Skills — opencrew
+
+Este é o índice de skills disponíveis no catálogo oficial do opencrew. O Skills Engine
+(`_opencrew/core/skills.engine.md`) lê este arquivo durante a descoberta de skills (Operação 7)
+e busca `SKILL.md` de cada uma via `https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills/<name>/SKILL.md`
+para instalação (Operação 2).
+
+| Skill | Tipo | Descrição |
+|-------|------|-----------|
+| `apify` | mcp | Plataforma de web scraping e automação. Extrai dados de qualquer site usando Actors prontos da Apify Store. |
+| `blotato` | mcp | Publicação e agendamento em redes sociais (Instagram, LinkedIn, Twitter/X, TikTok, YouTube). |
+| `canva` | mcp | Cria, busca, preenche e exporta designs do Canva (autenticação via OAuth). |
+| `image-ai-generator` | script | Gera imagens via API do OpenRouter (modo teste barato + modo produção de alta qualidade). |
+| `image-creator` | mcp | Renderiza HTML/CSS em imagens pixel-perfect via Playwright. Motor genérico para qualquer formato visual. |
+| `image-fetcher` | hybrid | Obtém assets visuais de múltiplas fontes: busca na web, screenshots via Playwright, arquivos do usuário. |
+| `instagram-publisher` | script | Publica carrosséis do Instagram a partir de imagens locais via imgBB + Graph API. |
+| `opencrew-best-practice-creator` | prompt | Guia a criação e manutenção de arquivos de best-practice na biblioteca do opencrew. |
+| `opencrew-skill-creator` | prompt | Cria, edita e avalia (evals/benchmark) skills do opencrew de qualquer tipo. |
+| `resend` | mcp | Envio de emails pelo servidor MCP oficial da Resend (individual, lote, anexos, agendamento). |
+| `template-designer` | prompt | Seleção de template visual para agentes de design — gera variações, renderiza e salva a identidade aprovada. |
+
+Para instalar qualquer uma delas dentro da sua IDE: `/opencrew install <nome>`.

package/templates/skills/catalog.json

@@ -0,0 +1,61 @@
+{
+  "version": "1",
+  "baseUrl": "https://raw.githubusercontent.com/alberthpalhares/opencrew/main/templates/skills",
+  "skills": {
+    "apify": {
+      "type": "mcp",
+      "description": "Plataforma de web scraping e automação. Extrai dados de qualquer site usando Actors prontos da Apify Store.",
+      "minVersion": "1.0.0"
+    },
+    "blotato": {
+      "type": "mcp",
+      "description": "Publicação e agendamento em redes sociais (Instagram, LinkedIn, Twitter/X, TikTok, YouTube).",
+      "minVersion": "1.0.0"
+    },
+    "canva": {
+      "type": "mcp",
+      "description": "Cria, busca, preenche e exporta designs do Canva (autenticação via OAuth).",
+      "minVersion": "1.0.0"
+    },
+    "image-ai-generator": {
+      "type": "script",
+      "description": "Gera imagens via API do OpenRouter (modo teste barato + modo produção de alta qualidade).",
+      "minVersion": "1.0.0"
+    },
+    "image-creator": {
+      "type": "mcp",
+      "description": "Renderiza HTML/CSS em imagens pixel-perfect via Playwright. Motor genérico para qualquer formato visual.",
+      "minVersion": "1.0.0"
+    },
+    "image-fetcher": {
+      "type": "hybrid",
+      "description": "Obtém assets visuais de múltiplas fontes: busca na web, screenshots via Playwright, arquivos do usuário.",
+      "minVersion": "1.0.0"
+    },
+    "instagram-publisher": {
+      "type": "script",
+      "description": "Publica carrosséis do Instagram a partir de imagens locais via imgBB + Graph API.",
+      "minVersion": "1.0.0"
+    },
+    "opencrew-best-practice-creator": {
+      "type": "prompt",
+      "description": "Guia a criação e manutenção de arquivos de best-practice na biblioteca do opencrew.",
+      "minVersion": "1.0.0"
+    },
+    "opencrew-skill-creator": {
+      "type": "prompt",
+      "description": "Cria, edita e avalia (evals/benchmark) skills do opencrew de qualquer tipo.",
+      "minVersion": "1.0.0"
+    },
+    "resend": {
+      "type": "mcp",
+      "description": "Envio de emails pelo servidor MCP oficial da Resend (individual, lote, anexos, agendamento).",
+      "minVersion": "1.0.0"
+    },
+    "template-designer": {
+      "type": "prompt",
+      "description": "Seleção de template visual para agentes de design — gera variações, renderiza e salva a identidade aprovada.",
+      "minVersion": "1.0.0"
+    }
+  }
+}

package/templates/skills/instagram-publisher/SKILL.md

@@ -41,7 +41,7 @@ Use the Instagram Publisher when you need to publish carousel posts directly to
 
 1. List JPEG files in `crews/{crew}/output/images/` sorted by name.
    If no files found: stop and ask the user to add images before continuing.
-2. Present the image list to the user with AskUserQuestion to confirm order.
+2. Present the image list to the user to confirm order (use your IDE's native interactive-choice mechanism if it has one; otherwise a numbered list).
 3. Extract the caption from the content draft:
    - Use the hook slide text + CTA slide text
    - Max 2200 characters (Instagram limit)