@aksp/opencrew 1.6.1 → 1.6.3

package/templates/_opencrew/core/scripts/conferir-fontes.mjs

@@ -6,27 +6,32 @@
 // Rode a partir da pasta do projeto (a que tem `_opencrew/`); a crew fica dentro dela.
 // Última linha da saída: FONTES:OK ou FONTES:PENDENTE (o runner lê esta linha).
 // Código de saída: 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso (opção faltando, pasta sem
-// `_opencrew/`, crew fora do projeto ou inexistente), sem linha FONTES: e sem escrever nada.
-// Specs: specs/fase-u2-crew-que-conhece-o-projeto.md e specs/fase-r1-reparos-1-6-1.md
-// (repositório do OpenCrew). Módulos em conferir-fontes/: coleta, busca e relatório.
+// `_opencrew/`, crew fora do projeto ou inexistente) ou arquivo da crew que não dá para ler
+// ("Não consegui conferir: …"); com código 1 não há linha FONTES:.
+// Caminho de rede e endereço de site citados não são testados (alerta "não conferi"); o script
+// nunca acessa a rede, e o --corrigir nunca grava fora da pasta real da crew.
+// Specs: specs/fase-u2-crew-que-conhece-o-projeto.md, specs/fase-r1-reparos-1-6-1.md e
+// specs/fase-r2-update-e-envio-seguros.md, regras 23 a 26 (repositório do OpenCrew).
+// Módulos em conferir-fontes/: coleta, busca e relatório.
 import { readFile, writeFile, copyFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { erroDeUso, dentroDoProjeto, ehPrincipal } from './comum.mjs';
+import { erroDeUso, dentroDoProjeto, relativoAoProjeto, realDentroDe, ehPrincipal } from './comum.mjs';
 import { coletar, trocarCitacao } from './conferir-fontes/coleta.mjs';
 import {
-  LIMITE_DA_BUSCA, barra, ehAbsoluto, temBarraFinal, resolver, indexar, candidatosPorNome, nomesDaPastaEsperada,
+  LIMITE_DA_BUSCA, ehAbsoluto, ehRedeOuSite, pareceSite, temBarraFinal, resolver, indexar, candidatosPorNome, nomesDaPastaEsperada,
 } from './conferir-fontes/busca.mjs';
 import { formatar, MSG } from './conferir-fontes/relatorio.mjs';
 
 export { formatar };
 
 /**
- * Caminho absoluto que existe dentro do projeto: o mesmo caminho, relativo à raiz. A própria raiz
- * não tem caminho relativo a sugerir.
+ * Caminho absoluto que existe dentro do projeto: o mesmo caminho, relativo à raiz — pelo lugar
+ * real, quando foi escrito por um link que leva ao projeto. A própria raiz não tem caminho
+ * relativo a sugerir.
  */
 function sugestaoRelativa(raiz, ref, achado) {
-  const relativo = dentroDoProjeto(raiz, achado) ? barra(path.relative(raiz, achado)) : '';
+  const relativo = dentroDoProjeto(raiz, achado) ? relativoAoProjeto(raiz, achado) : '';
   return relativo ? relativo + (temBarraFinal(ref) ? '/' : '') : null;
 }
 
@@ -43,27 +48,43 @@ async function procurar(item, { raiz, crew, indice, destino }) {
   if (!item.candidatos.length) item.pasta = await nomesDaPastaEsperada(raiz, crew, item.ref);
 }
 
+/**
+ * Estado de uma citação. Caminho de rede ou endereço de site não é testado: vira o alerta
+ * "não conferido" (regra 25). O resto é procurado no disco: o que falta é pendência, e o caminho
+ * absoluto que existe, o alerta de não portátil. `ctx.indice` é montado só na primeira falta.
+ */
+async function classificar(item, destino, ctx) {
+  const { raiz, crew } = ctx;
+  if (ehRedeOuSite(item.ref)) {
+    item.estado = 'nao-conferido';
+    return;
+  }
+  const achado = resolver(raiz, crew, item.ref, item.citadoEm);
+  if (!achado) {
+    ctx.indice ??= await indexar(raiz, ctx.limite);
+    if (pareceSite(ctx, item) && !candidatosPorNome(ctx.indice, item.ref).length) item.estado = 'nao-conferido';
+    else await procurar(item, { raiz, crew, indice: ctx.indice, destino });
+  } else if (ehAbsoluto(item.ref)) {
+    item.estado = 'nao-portatil';
+    item.sugestao = sugestaoRelativa(raiz, item.ref, achado);
+  }
+}
+
 /**
  * Confere os caminhos que a crew cita. `limite` é o máximo de itens do projeto vistos na busca
- * por nome; quando a busca para nele, `buscaParcial` é true.
+ * por nome; quando a busca para nele, `buscaParcial` é true. Estados: ok · faltando (pendência) ·
+ * nao-portatil e nao-conferido (alertas; não mudam o status).
  */
 export async function conferir({ raiz, crew, limite = LIMITE_DA_BUSCA }) {
-  let indice = null;
+  const ctx = { raiz, crew, limite, indice: null };
   const refs = [];
   for (const [ref, { arquivos, destino }] of await coletar(raiz, crew)) {
     const item = { ref, citadoEm: [...arquivos], estado: 'ok', sugestao: null, candidatos: [], pasta: [] };
-    const achado = resolver(raiz, crew, ref, item.citadoEm);
-    if (!achado) {
-      indice ??= await indexar(raiz, limite);
-      await procurar(item, { raiz, crew, indice, destino });
-    } else if (ehAbsoluto(ref)) {
-      item.estado = 'nao-portatil';
-      item.sugestao = sugestaoRelativa(raiz, ref, achado);
-    }
+    await classificar(item, destino, ctx);
     refs.push(item);
   }
   const status = refs.some((i) => i.estado === 'faltando') ? 'PENDENTE' : 'OK';
-  return { crew, raiz, refs, status, buscaParcial: Boolean(indice?.parcial), limite };
+  return { crew, raiz, refs, status, buscaParcial: Boolean(ctx.indice?.parcial), limite };
 }
 
 async function copiaDeSeguranca(arquivo) {
@@ -71,38 +92,69 @@ async function copiaDeSeguranca(arquivo) {
   await copyFile(arquivo, bak);
 }
 
+/** Regrava a citação num arquivo; a cópia .bak é feita uma vez por arquivo. */
+async function regravar(arquivo, item, tocados) {
+  const texto = await readFile(arquivo, 'utf8');
+  if (!tocados.has(arquivo)) {
+    await copiaDeSeguranca(arquivo);
+    tocados.add(arquivo);
+  }
+  await writeFile(arquivo, trocarCitacao(texto, item, path.basename(arquivo) === 'crew.yaml'));
+}
+
+/**
+ * Guarda de escrita do --corrigir (regra 24): só se grava em arquivo cujo lugar real fica dentro
+ * da pasta real da crew, e só se ela fica dentro do projeto. A pasta do arquivo passa pela mesma
+ * prova: é nela que a cópia .bak é gravada. Link físico não é reconhecido.
+ * @returns {((arquivo: string) => boolean)|null} null: a crew inteira é um link para fora do projeto
+ */
+function guardaDeEscrita(raiz, crew) {
+  const pasta = path.resolve(raiz, crew);
+  if (!realDentroDe(raiz, pasta)) return null;
+  return (arquivo) => [arquivo, path.dirname(arquivo)].every((lugar) => realDentroDe(pasta, lugar));
+}
+
 /**
  * Troca, nos arquivos da crew, cada caminho com sugestão única — só a citação que a coleta leu,
- * nunca um pedaço de outro texto. @returns quantos caminhos
+ * nunca um pedaço de outro texto. O que a guarda de escrita barra não muda: `avisar` recebe uma
+ * linha por arquivo pulado, ou uma só quando a crew inteira é um link para fora do projeto.
+ * @returns quantos caminhos foram gravados, em ao menos um arquivo
  */
-export async function corrigir({ resultado }) {
+export async function corrigir({ resultado, avisar = () => {} }) {
+  const { raiz, crew } = resultado;
   const comSugestao = resultado.refs.filter((i) => i.sugestao && i.estado !== 'ok');
+  const podeGravar = comSugestao.length ? guardaDeEscrita(raiz, crew) : null;
+  if (!podeGravar) {
+    if (comSugestao.length) avisar(MSG.crewLigadaParaFora(crew));
+    return 0;
+  }
   const tocados = new Set();
+  const pulados = new Set();
+  let gravados = 0;
   for (const item of comSugestao) {
-    for (const arquivo of item.citadoEm) {
-      const texto = await readFile(arquivo, 'utf8');
-      if (!tocados.has(arquivo)) {
-        await copiaDeSeguranca(arquivo);
-        tocados.add(arquivo);
-      }
-      await writeFile(arquivo, trocarCitacao(texto, item, path.basename(arquivo) === 'crew.yaml'));
-    }
+    const dentro = item.citadoEm.filter((arquivo) => podeGravar(arquivo));
+    for (const arquivo of item.citadoEm) if (!dentro.includes(arquivo)) pulados.add(arquivo);
+    for (const arquivo of dentro) await regravar(arquivo, item, tocados);
+    if (dentro.length) gravados += 1;
   }
-  return comSugestao.length;
+  for (const arquivo of pulados) avisar(MSG.linkParaFora(relativoAoProjeto(raiz, arquivo)));
+  return gravados;
 }
 
-/** --corrigir: troca o que tem sugestão única e diz quantas pendências ficam sem correção. */
+/** --corrigir: troca o que tem sugestão única, diz o que pulou e quantas pendências ficam sem correção. */
 async function corrigirEAvisar(r, escrever) {
-  const n = await corrigir({ resultado: r });
+  const pulados = [];
+  const n = await corrigir({ resultado: r, avisar: (linha) => pulados.push(linha) });
   let atual = r;
   if (n) {
     escrever(MSG.corrigidos(n));
     atual = await conferir({ raiz: r.raiz, crew: r.crew });
     escrever(formatar(atual));
   }
+  for (const linha of pulados) escrever(linha);
   const semSugestao = atual.refs.filter((i) => i.estado === 'faltando' && !i.sugestao).length;
   if (semSugestao) escrever(MSG.semCorrecaoAutomatica(semSugestao));
-  else if (!n) escrever(MSG.nadaACorrigir);
+  else if (!n && !pulados.length) escrever(MSG.nadaACorrigir);
   return atual;
 }
 
@@ -114,7 +166,7 @@ function lerCrew(argv) {
   return valor && !valor.startsWith('--') ? valor : null;
 }
 
-/** @returns {Promise<number>} 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso */
+/** @returns {Promise<number>} 0 = conferiu (OK ou PENDENTE) · 1 = erro de uso, ou arquivo da crew que não dá para ler */
 export async function main(argv, { cwd = process.cwd(), escrever = (s) => process.stdout.write(`${s}\n`) } = {}) {
   const crew = lerCrew(argv);
   const erro = erroDeUso({ raiz: cwd, faltando: crew ? [] : ['--crew'], crew });
@@ -123,11 +175,17 @@ export async function main(argv, { cwd = process.cwd(), escrever = (s) => proces
     if (!crew) escrever(USO);
     return 1;
   }
-  let r = await conferir({ raiz: cwd, crew });
-  escrever(formatar(r));
-  if (argv.includes('--corrigir')) r = await corrigirEAvisar(r, escrever);
-  escrever(`FONTES:${r.status}`);
-  return 0;
+  try {
+    let r = await conferir({ raiz: cwd, crew });
+    escrever(formatar(r));
+    if (argv.includes('--corrigir')) r = await corrigirEAvisar(r, escrever);
+    escrever(`FONTES:${r.status}`);
+    return 0;
+  } catch (erroDeLeitura) {
+    // Link quebrado, pasta com nome de arquivo, arquivo sem permissão: uma linha, sem linha FONTES:.
+    escrever(MSG.naoConferi(erroDeLeitura.message));
+    return 1;
+  }
 }
 
 if (ehPrincipal(import.meta.url)) {

package/templates/_opencrew/core/scripts/verificar/regras.mjs

@@ -13,10 +13,41 @@ export const FALTA_INFO = 'Falta informação sua';
 export const NAO_MEDIDO = 'Não medido';
 export const NAO_VERIFICADO = 'Não verificado';
 
+const JANELA = 1024;
+
+/**
+ * Quantos grafemas o texto tem, contados em janelas e sem guardar os segmentos. No Node 20 cada
+ * segmento carrega uma cópia da entrada: com o texto inteiro de uma vez a memória cresce ao
+ * quadrado, e 200 mil caracteres derrubavam o processo. O último grafema de uma janela pode
+ * continuar na seguinte, por isso fica para ela; a janela nunca corta um par substituto.
+ */
+export function grafemas(texto, janela = JANELA) {
+  let total = 0;
+  let tamanho = janela;
+  for (let inicio = 0; inicio < texto.length;) {
+    let fim = Math.min(inicio + tamanho, texto.length);
+    if (fim < texto.length && texto.codePointAt(fim - 1) > 0xffff) fim++;
+    let quantos = 0;
+    let ultimo = 0;
+    for (const { index } of segmentador.segment(texto.slice(inicio, fim))) {
+      quantos++;
+      ultimo = index;
+    }
+    const acabou = fim === texto.length;
+    if (!acabou && quantos === 1) tamanho *= 2; // um grafema maior que a janela: tenta de novo
+    else {
+      total += acabou ? quantos : quantos - 1;
+      inicio = acabou ? fim : inicio + ultimo;
+      tamanho = janela;
+    }
+  }
+  return total;
+}
+
 /** Caracteres visíveis: sem marcadores de negrito/itálico; emoji conta 1; quebra de linha conta. */
 export function contar(texto) {
   const limpo = String(texto).replace(/\*\*|__/g, '').replace(/\*([^*\n]+)\*/g, '$1').trim();
-  return [...segmentador.segment(limpo)].length;
+  return grafemas(limpo);
 }
 
 export const item = (nome, medido, limite, nivel, detalhe = '') => ({ item: nome, medido, limite, nivel, detalhe });

package/templates/_opencrew/core/scripts/verificar.mjs

@@ -11,10 +11,11 @@
 // obrigatória faltando, pasta sem `_opencrew/`, crew inexistente, crew ou caminho fora do
 // projeto, nenhum caminho da lista existe) ou erro que impediu a verificação inteira; com
 // código 1 não há linha VERIFICACAO:.
-// Specs: fase-u1-revisor-com-dentes.md e fase-r1-reparos-1-6-1.md (repositório do OpenCrew).
+// Specs: fase-u1-revisor-com-dentes.md, fase-r1-reparos-1-6-1.md e fase-r2-update-e-envio-seguros.md
+// (regra 23: "dentro do projeto" pelo texto ou pelo lugar real), no repositório do OpenCrew.
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { erroDeUso, ehPrincipal } from './comum.mjs';
+import { erroDeUso, ehPrincipal, relativoAoProjeto } from './comum.mjs';
 import { USO, lerArgs, lerItemDaLista } from './verificar/argumentos.mjs';
 import { lerItem } from './verificar/arquivos.mjs';
 import { lerLimites, lerDominioDoSite, semFrontmatter } from './verificar/leitura.mjs';
@@ -102,9 +103,11 @@ function semRepetidas(raiz, entradas) {
   });
 }
 
-/** Caminho absoluto de dentro do projeto aparece no relatório como o relativo. */
+/** No relatório, o absoluto de dentro do projeto (também por link, junção ou nome curto) sai como o relativo. */
 function nomeNoRelatorio(raiz, arquivo) {
-  return path.isAbsolute(arquivo) ? path.relative(raiz, arquivo).split(path.sep).join('/') : arquivo;
+  const relativo = relativoAoProjeto(raiz, arquivo);
+  const comoEscrito = !path.isAbsolute(arquivo) && path.resolve(raiz, relativo) === path.resolve(raiz, arquivo);
+  return comoEscrito ? arquivo : relativo;
 }
 
 function resumir(arquivos, naoTexto, notas) {

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

@@ -54,6 +54,7 @@ Frontmatter fields:
   - `dependencies`: Array of npm/pip packages to install
 - `env` (array): List of required environment variable names
 - `categories` (array): Classification tags (e.g., scraping, design, analytics)
+- `side_effects` (string, optional): `irreversible` for a skill that publishes or sends — read by Operation 6
 
 Body: Markdown instructions injected into agent context at runtime.
 
@@ -382,7 +383,7 @@ For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
 1. **Skip native skills**: `web_search` and `web_fetch` do not need instruction injection —
    they are handled natively.
 
-2. **Read each skill's SKILL.md** frontmatter only: Extract `name`, `description`, and `type` fields.
+2. **Read each skill's SKILL.md** frontmatter only: Extract `name`, `description`, `type` and `side_effects` fields.
 
 3. **Build the Tier 1 index** and append after all agent instructions:
    ```
@@ -394,8 +395,9 @@ For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
    you are invoking and the system will load its full instructions.
 
    - {skill-id}: {description from frontmatter} (type: {type})
-   - {skill-id}: {description from frontmatter} (type: {type})
+   - {skill-id}: {description from frontmatter} (type: {type}) — irreversível: carregue as instruções desta skill e peça a confirmação antes de usar
    ```
+   The second form is for every skill with `side_effects: irreversible`.
 
 4. **Tier 2 loading** — When the step's instructions explicitly reference a skill
    (e.g., the step file says "use image-creator to render the slides"), OR when the
@@ -412,7 +414,9 @@ For each skill declared in an agent's `.agent.md` frontmatter `skills:` field:
 5. **Step-level skill hints**: If the step's frontmatter contains a `skills_needed:` field
    (e.g., `skills_needed: [image-creator]`), load Tier 2 for those skills immediately
    without waiting for the agent to request them. This allows the Architect to pre-declare
-   which skills a step will need.
+   which skills a step will need. A skill with `side_effects: irreversible` always gets Tier 2
+   before its first use, even when no step names it: an MCP tool can be called without the body,
+   and the confirmation rules live there.
 
 6. **Missing skill handling**: If a skill listed in an agent's frontmatter was not resolved
    during Operation 5, skip it silently — the user was already warned during resolution.

package/templates/gitignore

@@ -8,4 +8,5 @@ _opencrew/_memory/company.md
 _opencrew/_memory/preferences.md
 _opencrew/_browser_profile/
 _opencrew/logs/
+.opencrew-backup/
 .claude/settings.local.json

package/templates/skills/blotato/SKILL.md

@@ -20,6 +20,7 @@ mcp:
   url: "https://mcp.blotato.com/mcp"
   headers:
     blotato-api-key: BLOTATO_API_KEY
+side_effects: irreversible
 env:
   - BLOTATO_API_KEY
 categories: [social-media, automation, publishing, scheduling]
@@ -35,19 +36,47 @@ Use Blotato when you need to publish or schedule social media posts across multi
 
 You have access to Blotato for social media publishing.
 
-### Key workflow
+### Workflow
 
-1. Use `blotato_list_accounts` to get account IDs and platforms
-2. If post includes images or videos, upload them with `blotato_upload_media` first and use the returned media IDs in `blotato_create_post`
-3. Use `blotato_create_post` to publish or schedule
-4. Use `blotato_get_post_status` to confirm success
+Publishing is **irreversible**: a post cannot be taken back once it is live. The rule below is
+about the **action**, whatever the tool is called on the server: before ANY call that publishes,
+schedules or deletes, follow this order. The messages to the user are in PT-BR, as written here.
+
+1. List the connected accounts (`blotato_list_accounts`, read-only) to get the account IDs and
+   platforms. Send nothing to Blotato yet, not even media.
+2. **Preview (prévia)** — show the user exactly this, filled in:
+   ```
+   Vou publicar isto:
+   Contas: {conta} ({rede}), …
+   Quando: agora, ou agendado para {data e hora}
+   Texto ({N} caracteres): {texto}
+   Mídia: {arquivos}, ou nenhuma
+   Para publicar, responda com a palavra publicar. Qualquer outra resposta cancela.
+   ```
+   (`Quando`: write `agora` or `agendado para …`. `Mídia`: the file names, or `nenhuma`.)
+3. Wait for the word **publicar**. Any other answer — including silence, "ok" or "sim" — cancels:
+   say "Nada foi publicado." and stop.
+4. Only after the word: upload the media, if any (`blotato_upload_media`), then make **one single
+   call** that publishes or schedules (`blotato_create_post`; if the server takes one account per
+   call, once per account of the preview and never twice for the same account).
+5. On success: check the result (`blotato_get_post_status`) and save the post URL and ID to the
+   step output file immediately.
+6. On failure, timeout or missing answer: do NOT repeat the call again, in this step or in a retry.
+   Tell the user: "⚠️ Não recebi a confirmação do Blotato. A publicação pode já ter saído. Confira
+   no painel antes de tentar de novo. Não vou repetir sozinho."
+7. One confirmation is worth one publication. If this step runs again in the same run (a retry, or
+   back from a rejected review), show the preview again, after this line: "Este passo já tentou
+   publicar nesta execução. Confira se saiu antes de confirmar de novo." — and wait for the word.
+8. A call that **deletes** (a post, a scheduled post, media) follows the same order with its own
+   word: "Vou apagar isto: {o que será apagado}. Para apagar, responda com a palavra apagar.
+   Qualquer outra resposta cancela." Any other answer: "Nada foi apagado."
 
 ### Best practices
 
-- Always call `blotato_list_accounts` first to get valid account IDs
 - For scheduled posts, use ISO 8601 format for datetime
-- After posting, poll `blotato_get_post_status` until status is "published" or "scheduled"
-- If status is "failed", report the error details to the user
+- After the publishing call, read `blotato_get_post_status` until status is "published" or
+  "scheduled" — reading the status is safe; calling `blotato_create_post` again is not
+- If status is "failed", report the error details to the user and let them decide
 
 ### Requirements
 
@@ -57,7 +86,7 @@ You have access to Blotato for social media publishing.
 ## Available operations
 
 - **List Accounts** -- Retrieve connected social media accounts and their platform types
-- **Upload Media** -- Upload images and videos for use in posts
-- **Create Post** -- Publish or schedule a post to one or more platforms
+- **Upload Media** -- Upload images and videos for use in posts (only after the word)
+- **Create Post** -- Publish or schedule a post to one or more platforms (only after the word)
 - **Get Post Status** -- Monitor publishing status (published, scheduled, failed)
 - **Multi-platform Publishing** -- Post the same content across Instagram, LinkedIn, Twitter/X, TikTok, YouTube simultaneously

package/templates/skills/image-ai-generator/SKILL.md

@@ -15,7 +15,7 @@ version: "1.0.0"
 script:
   path: scripts/generate.py
   runtime: python
-  invoke: "python3 {skill_path}/scripts/generate.py --prompt \"{prompt}\" --output \"{output}\" --mode \"{mode}\""
+  invoke: "python3 {skill_path}/scripts/generate.py --prompt-file \"{prompt_file}\" --output \"{output}\" --mode \"{mode}\""
 env:
   - OPENROUTER_API_KEY
 categories: [assets, images, ai, generation]
@@ -56,11 +56,22 @@ Use the Image Generator when you need to create visual assets from text prompts.
 `python3` (macOS/Linux). **On Windows** use `py -3` instead (or `python` if the `py` launcher is
 not installed).
 
+**The prompt goes in a file.** Write it with your file-writing tool, in UTF-8, next to the image
+(`crews/{crew}/output/{run_id}/assets/image-name.prompt.txt`). Never put the prompt inside a shell
+command: write it to a file and pass `--prompt-file`. The shell rewrites `$`, quotes and backticks
+in a typed text (a price like "R$50" reaches the model wrong, and the image is still charged). The
+old `--prompt` option is still accepted, for crews created before; do not use it.
+
+**File names.** Every path in the command (`--prompt-file`, `--output`, `--reference`, `--batch`)
+follows the safe-name rule (nome seguro) of `_opencrew/core/runner.pipeline.md` — letters, digits,
+space and `. _ - / \ : ( )`, between double quotes. With any other character do not run the
+command: ask the user to rename the file.
+
 ### Single image generation
 
 ```bash
 python3 {skill_path}/scripts/generate.py \
-  --prompt "A detailed description of the image to generate" \
+  --prompt-file "crews/{crew}/output/{run_id}/assets/image-name.prompt.txt" \
   --output "crews/{crew}/output/{run_id}/assets/image-name.jpg" \
   --mode test
 ```
@@ -71,7 +82,7 @@ Use `--reference` to send a local image to the model as visual context. The mode
 
 ```bash
 python3 {skill_path}/scripts/generate.py \
-  --prompt "A social media banner featuring the company logo prominently in the center" \
+  --prompt-file "crews/{crew}/output/{run_id}/assets/banner.prompt.txt" \
   --output "crews/{crew}/output/{run_id}/assets/banner.jpg" \
   --reference "crews/{crew}/assets/logo.png" \
   --mode production
@@ -87,7 +98,8 @@ python3 {skill_path}/scripts/generate.py \
   --mode production
 ```
 
-The batch JSON file should contain:
+Write the batch JSON file with your file-writing tool, in UTF-8 (the prompts inside it never go
+through the shell). It should contain:
 ```json
 [
   {"prompt": "Description of image 1", "output": "path/to/image1.jpg"},
@@ -115,13 +127,14 @@ Each item can optionally include a `"reference": "path/to/ref.png"` field.
 
 ## Available operations
 
-- **Single generation** — Generate one image from a text prompt
+- **Single generation** — Generate one image from a text prompt saved in a file
 - **Batch generation** — Generate multiple images from a JSON batch file
 - **Mode selection** — Choose between test (cheap) and production (high-quality) models
 - **Reference image** — Send a logo/mascot/brand asset as visual context for the generation
 
 ## Error handling
 
+- If the prompt file is missing or empty, or the batch file cannot be read (not UTF-8, invalid JSON), the script says so in one line and exits with code 1. Show the message to the user; nothing was generated or charged.
 - If `OPENROUTER_API_KEY` is not set, the script exits with an error message. Set it in your `.env` file or environment.
 - If the API returns an error, the script prints the error code and body, then exits with code 1.
 - If no image is found in the API response, the script reports which model was used and exits with code 1.

package/templates/skills/image-ai-generator/scripts/generate.py

@@ -4,14 +4,16 @@ Image Generator — opencrew Skill
 Generates images via Openrouter API using AI image models.
 
 Usage:
-  # Single image
-  python3 generate.py --prompt "description" --output "path/to/image.jpg" --mode test
+  # Single image (the prompt is read from a UTF-8 text file, never typed in the command)
+  python3 generate.py --prompt-file "path/to/prompt.txt" --output "path/to/image.jpg" --mode test
 
   # Single image with reference (logo/mascot)
-  python3 generate.py --prompt "description" --output "path/to/image.jpg" --reference "path/to/logo.png" --mode production
+  python3 generate.py --prompt-file "path/to/prompt.txt" --output "path/to/image.jpg" --reference "path/to/logo.png" --mode production
 
-  # Batch (JSON file with list of {prompt, output} objects)
+  # Batch (UTF-8 JSON file with list of {prompt, output} objects)
   python3 generate.py --batch "path/to/batch.json" --mode production
+
+--prompt "text" is still accepted (legacy): the shell may rewrite $, quotes and backticks in it.
 """
 
 import argparse
@@ -32,6 +34,42 @@ MODELS = {
 API_URL = "https://openrouter.ai/api/v1/chat/completions"
 
 
+def fail(message):
+    """Tell the user what went wrong and exit with code 1, without a traceback."""
+    print(message, file=sys.stderr)
+    sys.exit(1)
+
+
+def read_prompt_file(path):
+    """Read the prompt from a UTF-8 text file (BOM accepted); it never goes through the shell."""
+    if not os.path.isfile(path):
+        fail(f"Arquivo de prompt não encontrado: {path}")
+    try:
+        with open(path, "r", encoding="utf-8-sig") as f:
+            prompt = f.read().strip()
+    except (OSError, ValueError) as e:
+        fail(f"Não consegui ler o arquivo de prompt {path}: {e}. Grave o arquivo em UTF-8.")
+    if not prompt:
+        fail(f"O arquivo de prompt está vazio: {path}")
+    return prompt
+
+
+def read_batch(path):
+    """Read the batch list from a UTF-8 JSON file (BOM accepted)."""
+    try:
+        with open(path, "r", encoding="utf-8-sig") as f:
+            batch = json.load(f)
+    except (OSError, ValueError) as e:
+        fail(f"Não consegui ler o lote {path}: {e}. Grave o arquivo em UTF-8.")
+    ok = isinstance(batch, list) and all(
+        isinstance(i, dict) and all(isinstance(i.get(k), str) and i[k].strip() for k in ("prompt", "output"))
+        for i in batch
+    )
+    if not ok:
+        fail(f'O lote {path} tem de ser uma lista de itens com "prompt" e "output". Nada foi gerado.')
+    return batch
+
+
 def load_api_key():
     """Load OPENROUTER_API_KEY from environment."""
     key = os.environ.get("OPENROUTER_API_KEY")
@@ -130,7 +168,8 @@ def generate_image(prompt, output_path, mode, api_key, reference_image=None):
 
 def main():
     parser = argparse.ArgumentParser(description="Generate images via Openrouter API")
-    parser.add_argument("--prompt", help="Text prompt for single image generation")
+    parser.add_argument("--prompt-file", help="UTF-8 text file with the prompt for single image generation")
+    parser.add_argument("--prompt", help="Legacy: prompt typed in the command (use --prompt-file)")
     parser.add_argument("--output", help="Output file path for single image")
     parser.add_argument("--batch", help="Path to JSON batch file")
     parser.add_argument("--mode", choices=["test", "production"], default="test",
@@ -138,8 +177,13 @@ def main():
     parser.add_argument("--reference", help="Path to reference image to include in the prompt")
     args = parser.parse_args()
 
-    if not args.prompt and not args.batch:
-        parser.error("Either --prompt or --batch is required")
+    if args.prompt_file and args.batch:
+        fail("Use só um: --prompt-file ou --batch.")
+    if not (args.prompt_file or args.prompt or args.batch):
+        parser.error("Either --prompt-file or --batch is required")
+    # The input files are read first: a bad file stops here, before the key and any API call.
+    items = read_batch(args.batch) if args.batch else None
+    prompt = read_prompt_file(args.prompt_file) if args.prompt_file else args.prompt
 
     api_key = load_api_key()
     model = MODELS[args.mode]
@@ -147,8 +191,6 @@ def main():
 
     if args.batch:
         # Batch mode
-        with open(args.batch, "r") as f:
-            items = json.load(f)
         print(f"Generating {len(items)} images...\n")
         success = 0
         for i, item in enumerate(items, 1):
@@ -167,7 +209,7 @@ def main():
         if not args.output:
             parser.error("--output is required for single image generation")
         print(f"Generating: {os.path.basename(args.output)}...")
-        ok = generate_image(args.prompt, args.output, args.mode, api_key, reference_image=args.reference)
+        ok = generate_image(prompt, args.output, args.mode, api_key, reference_image=args.reference)
         sys.exit(0 if ok else 1)
 
 

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

@@ -74,6 +74,10 @@ and is **never** retried automatically.
 
 - Images: JPEG only (`.jpg`/`.jpeg`), 2-10 per carousel, inside `crews/*/output/` — the
   script refuses anything else before uploading
+- File names: the image paths and the caption file follow the safe-name rule (nome seguro) of
+  `_opencrew/core/runner.pipeline.md` — letters, digits, space and `. _ - / \ : ( )`. With any
+  other character (a comma included: it splits the `--images` list) do not run the command: ask
+  the user to rename the file
 - Images are hosted on imgBB for 24h only (enough for Instagram to fetch them)
 - Caption: max 2200 characters
 - Requires Instagram Business account (not Personal or Creator)

package/templates/skills/opencrew-skill-creator/references/skill-format.md

@@ -14,6 +14,7 @@ Every opencrew skill consists of a `SKILL.md` file with YAML frontmatter and a M
 | `version` | Yes | Semver version string (e.g., `1.0.0`) |
 | `categories` | No | Classification tags array (e.g., `["social-media", "content"]`) |
 | `env` | No | Required environment variable names array |
+| `side_effects` | No | `irreversible` for a skill that publishes or sends (a post, an e-mail). Its body must then show a preview, wait for a confirmation word and make one single call, never repeated after a failure. A skill that only costs money does not use it |
 
 ### Type: mcp