iron-edge 1.2.0 → 2.0.0

package/skills/clone-transplant/scripts/transplant.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * transplant.mjs — veste a estrutura de um site (clonado) com a marca do cliente.
+ *
+ * Lê o inventory.json da ORIGEM (cores por papel, medidas) e um brand.css de
+ * DESTINO (a marca do cliente). Mapeia cor por PAPEL (fundo→fundo, texto→texto),
+ * troca no HTML/CSS, e checa contraste no fim. Nunca inventa matiz: papel que
+ * falta no destino é derivado por luminosidade de uma cor que existe.
+ *
+ * Escreve numa pasta NOVA — nunca sobrescreve a origem.
+ *
+ * Uso:
+ *   node transplant.mjs <origem: arquivo.html|pasta> <inventory.json> <brand.css> --out <pasta>
+ *        [--nivel raso|fundo]  [--so paleta,tipografia]  [--roles fundo=--crema,texto=--tartufo,...]
+ */
+import { readFile, writeFile, mkdir, readdir, stat, copyFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const argv = process.argv.slice(2);
+const [srcPath, invPath, brandPath] = argv;
+if (!srcPath || !invPath || !brandPath) { console.error('uso: node transplant.mjs <origem> <inventory.json> <brand.css> --out <pasta> [--nivel fundo] [--so ...] [--roles ...]'); process.exit(2); }
+const val = (n, d) => { const i = argv.indexOf(n); return i !== -1 && argv[i + 1] && !argv[i + 1].startsWith('--') ? argv[i + 1] : d; };
+const OUT = val('--out', '');
+const NIVEL = val('--nivel', 'fundo');
+const SO = val('--so', '');
+const ROLES_OVERRIDE = val('--roles', '');
+const FORCE = argv.includes('--force');
+if (!OUT) { console.error('erro: --out <pasta> obrigatório (nunca sobrescreve a origem)'); process.exit(2); }
+const log = (...a) => console.error('[transplant]', ...a);
+
+// o que aplicar. raso = só primária+fonte. fundo = paleta+tipografia (cor + fonte).
+// raio/sombra NÃO entram: o transplante ainda não os troca; prometer na doc era
+// mentira (achado do gate). Cor e fonte é o que ele faz de verdade.
+const DIMS = SO ? SO.split(',').map(s => s.trim()) : (NIVEL === 'raso' ? ['primaria', 'tipografia'] : ['paleta', 'tipografia']);
+const wantPalette = DIMS.includes('paleta');
+const wantPrimariaOnly = DIMS.includes('primaria') && !wantPalette;
+const wantType = DIMS.includes('tipografia');
+
+// ---------------------------------------------------------------- cor utils
+function parseColor(str) {
+  if (!str) return null; const s = String(str).trim().toLowerCase();
+  let m = s.match(/^#([0-9a-f]{3,8})$/);
+  if (m) { let h = m[1]; if (h.length === 3) h = h.split('').map(c => c + c).join(''); if (h.length >= 6) return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16), a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1 }; }
+  m = s.match(/^rgba?\(([^)]+)\)/); if (m) { const p = m[1].split(/[,\/\s]+/).filter(Boolean); const r = +p[0], g = +p[1], b = +p[2]; const a = p[3] === undefined ? 1 : (p[3].endsWith('%') ? +p[3].slice(0, -1) / 100 : +p[3]); if (![r, g, b].some(Number.isNaN)) return { r, g, b, a }; }
+  m = s.match(/^hsla?\(([^)]+)\)/); if (m) { const p = m[1].split(/[,\/\s]+/).filter(Boolean); const h = parseFloat(p[0]), S = parseFloat(p[1]) / 100, L = parseFloat(p[2]) / 100; const a = (mx => mx * S / 100)(0), q = 0; const c2 = (1 - Math.abs(2 * L - 1)) * S; const x = c2 * (1 - Math.abs((h / 60) % 2 - 1)); const mm = L - c2 / 2; let rr = 0, gg = 0, bb = 0; const hh = h % 360; if (hh < 60) [rr, gg, bb] = [c2, x, 0]; else if (hh < 120) [rr, gg, bb] = [x, c2, 0]; else if (hh < 180) [rr, gg, bb] = [0, c2, x]; else if (hh < 240) [rr, gg, bb] = [0, x, c2]; else if (hh < 300) [rr, gg, bb] = [x, 0, c2]; else [rr, gg, bb] = [c2, 0, x]; return { r: Math.round((rr + mm) * 255), g: Math.round((gg + mm) * 255), b: Math.round((bb + mm) * 255), a: p[3] === undefined ? 1 : +p[3] }; }
+  return null;
+}
+const toHex = c => '#' + [c.r, c.g, c.b].map(x => Math.max(0, Math.min(255, Math.round(x))).toString(16).padStart(2, '0')).join('');
+const key = c => `${Math.round(c.r)},${Math.round(c.g)},${Math.round(c.b)}`;      // casa hex e rgb do mesmo valor
+function toHsl({ r, g, b }) { r /= 255; g /= 255; b /= 255; const mx = Math.max(r, g, b), mn = Math.min(r, g, b), d = mx - mn; let h = 0; const l = (mx + mn) / 2; const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1)); if (d) { if (mx === r) h = ((g - b) / d) % 6; else if (mx === g) h = (b - r) / d + 2; else h = (r - g) / d + 4; h *= 60; if (h < 0) h += 360; } return { h, s, l }; }
+const lum = c => { const f = v => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }; return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b); };
+const contrast = (a, b) => { const l1 = lum(a), l2 = lum(b); const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1]; return +((hi + 0.05) / (lo + 0.05)).toFixed(2); };
+function lighten(c, dl) { let { h, s, l } = toHsl(c); l = Math.min(0.94, l + dl); const a = s * Math.min(l, 1 - l); const f = n => { const k = (n + h / 30) % 12; return Math.round(255 * (l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1)))); }; return { r: f(0), g: f(8), b: f(4), a: 1 }; }
+
+// ---------------------------------------------------------------- brand.css → papéis
+const ROLE_WORDS = [
+  ['fundo', /fundo\s+(principal|dominante|geral)|background\s+principal/],
+  ['superficie', /cart(ã|a)o|cartões|bloco|superf|card|painel/],
+  ['primaria', /destaque|romântic|prim(á|a)ri|marca|bot(ã|a)o|call|cta/],
+  ['texto', /texto|tinta|corpo|leitura/],
+  ['acento', /acento|realce|detalhe|natural|brilho/],
+  ['borda', /borda|linha|r(é|e)gua|moldura|divis/],
+];
+function inferRole(comment) {
+  const c = (comment || '').toLowerCase();
+  for (const [role, re] of ROLE_WORDS) {
+    const m = re.exec(c); if (!m) continue;
+    // negação antes da palavra ("NUNCA texto", "não é fundo") → papel negado,
+    // tenta o próximo. Sem isso, "--oro: NUNCA texto" virava a cor de texto.
+    const pre = c.slice(Math.max(0, m.index - 12), m.index);
+    if (/nunca|jamais|n(ã|a)o\b|never|evitar/.test(pre)) continue;
+    return role;
+  }
+  return null;
+}
+
+function parseBrand(css) {
+  const vars = [];
+  // varre linha a linha pra pegar o comentário na MESMA linha OU na de cima
+  // (achado do gate: comentário acima da variável era ignorado).
+  let pending = '';
+  for (const line of css.split('\n')) {
+    const cm = line.match(/\/\*([^*]*)\*\//);
+    const vm = line.match(/--([a-z0-9-]+)\s*:\s*(#[0-9a-fA-F]{3,8}|rgba?\([^)]+\)|hsla?\([^)]+\))/);
+    if (vm) {
+      const c = parseColor(vm[2]);
+      if (c) { const comment = (cm ? cm[1] : pending).trim(); vars.push({ name: '--' + vm[1], hex: toHex(c), rgb: c, comment, role: inferRole(comment) }); }
+      pending = '';
+    } else if (cm) { pending = cm[1]; }
+    else if (line.trim()) pending = '';
+  }
+  // fontes: --f-... : 'Familia'
+  const fonts = {};
+  const fr = /--(f-[a-z0-9-]+|font-[a-z0-9-]+)\s*:\s*['"]?([^,'";]+)/g;
+  let fm; while ((fm = fr.exec(css))) { const name = fm[1], fam = fm[2].trim(); if (/tit|disp|head/.test(name)) fonts.display = fam; else if (/text|body|corpo/.test(name)) fonts.body = fam; }
+  return { vars, fonts };
+}
+
+// escolhe a cor destino de cada papel (comentário; senão luminância/croma)
+function buildDestRoles(brand) {
+  // coleta TODOS os candidatos por papel (não só o primeiro do arquivo)
+  const cands = {};
+  for (const v of brand.vars) if (v.role) (cands[v.role] || (cands[v.role] = [])).push(v);
+  const chroma = v => Math.max(v.rgb.r, v.rgb.g, v.rgb.b) - Math.min(v.rgb.r, v.rgb.g, v.rgb.b);
+  const neutras = brand.vars.filter(v => chroma(v) < 40);
+  const marcas = brand.vars.filter(v => chroma(v) >= 40);
+  const byLumAsc = a => a.slice().sort((x, y) => lum(x.rgb) - lum(y.rgb));
+  const byRole = {};
+  // fundo primeiro (o texto se decide em função dele)
+  byRole.fundo = (cands.fundo || [])[0] || byLumAsc(neutras.length ? neutras : brand.vars).slice(-1)[0];
+  // texto: entre os candidatos, o de MAIOR contraste sobre o fundo. Faz o
+  // --tartufo (12:1) vencer o --oro-texto (5:1) pro corpo — legibilidade real.
+  if (cands.texto) byRole.texto = cands.texto.slice().sort((a, b) => contrast(b.rgb, byRole.fundo.rgb) - contrast(a.rgb, byRole.fundo.rgb))[0];
+  else byRole.texto = byLumAsc(neutras.length ? neutras : brand.vars)[0];
+  byRole.superficie = (cands.superficie || [])[0] || (neutras.length ? byLumAsc(neutras).slice(-2)[0] : byRole.fundo);
+  byRole.primaria = (cands.primaria || [])[0] || byLumAsc(marcas)[0] || byRole.texto;
+  byRole.acento = (cands.acento || [])[0] || marcas.find(v => v !== byRole.primaria) || byRole.primaria;
+  byRole.borda = (cands.borda || [])[0] || byRole.superficie || byRole.acento;
+  return byRole;
+}
+
+// aplica overrides "fundo=--crema,texto=--tartufo"
+function applyRoleOverride(destRoles, brand, str) {
+  if (!str) return destRoles;
+  for (const pair of str.split(',')) { const [role, varname] = pair.split('='); const v = brand.vars.find(x => x.name === varname.trim()); if (v) destRoles[role.trim()] = v; }
+  return destRoles;
+}
+
+// ---------------------------------------------------------------- substituição
+function buildColorMap(inv, destRoles, deriveNote) {
+  const c = inv.cores || {};
+  const rolesWanted = wantPrimariaOnly ? ['primaria'] : ['fundo', 'texto', 'superficie', 'primaria', 'acento', 'borda'];
+  const map = new Map();   // "r,g,b" origem -> {toHex, role, fromHex}
+  const table = [];
+  const colisoes = [];
+  for (const role of rolesWanted) {
+    const from = c[role]?.hex; const destVar = destRoles[role];
+    if (!from || !destVar) continue;
+    const fc = parseColor(from); if (!fc) continue;
+    const k = key(fc);
+    // dois papéis com a MESMA cor de origem: o primeiro (ordem: fundo→texto→…)
+    // ganha, não sobrescreve. Sem isso o Map trocava silenciosamente o papel.
+    if (map.has(k)) { colisoes.push({ role, fromHex: from, jaMapeado: map.get(k).role }); continue; }
+    map.set(k, { toHex: destVar.hex, role, fromHex: from, destName: destVar.name });
+    table.push({ role, fromHex: from, toHex: destVar.hex, destName: destVar.name });
+  }
+  return { map, table, colisoes };
+}
+
+const HEX_RE = /#[0-9a-fA-F]{3,8}\b/g;
+const FUNC_RE = /rgba?\([^)]+\)|hsla?\([^)]+\)/g;
+function rewriteColors(text, map, counts, orphans, destSet) {
+  const swap = (raw) => {
+    const c = parseColor(raw); if (!c) return raw;
+    const hit = map.get(key(c));
+    if (!hit) {
+      // cor real que não tinha papel no inventário e não é do brand: fica órfã.
+      // Registra pra revisão (ex: um card tintado que o inventário não mapeou).
+      if (c.a > 0.05 && !destSet.has(key(c))) orphans.set(key(c), (orphans.get(key(c)) || 0) + 1);
+      return raw;
+    }
+    counts[hit.role] = (counts[hit.role] || 0) + 1;
+    return c.a < 1 ? `rgba(${parseColor(hit.toHex).r}, ${parseColor(hit.toHex).g}, ${parseColor(hit.toHex).b}, ${c.a})` : hit.toHex;
+  };
+  return text.replace(FUNC_RE, swap).replace(HEX_RE, swap);
+}
+
+// no HTML, troca cor SÓ onde cor mora: blocos <style> e atributos style="".
+// NUNCA em href/id/JS — um #hex ali é âncora/rota/dado, não cor. (Auditoria pegou
+// href="#e8eef5" e strings JS sendo corrompidos pela troca cega.)
+function rewriteHtmlColors(html, map, counts, orphans, destSet) {
+  html = html.replace(/(<style[^>]*>)([\s\S]*?)(<\/style>)/gi, (_m, o, css, cl) => o + rewriteColors(css, map, counts, orphans, destSet) + cl);
+  html = html.replace(/style="([^"]*)"/gi, (m, s) => s.includes('#') || /rgb|hsl/i.test(s) ? `style="${rewriteColors(s, map, counts, orphans, destSet)}"` : m);
+  html = html.replace(/style='([^']*)'/gi, (m, s) => s.includes('#') || /rgb|hsl/i.test(s) ? `style='${rewriteColors(s, map, counts, orphans, destSet)}'` : m);
+  return html;
+}
+
+const fnorm = s => String(s || '').toLowerCase().replace(/\s+(variable|var)$/, '').trim();
+function rewriteFonts(text, invFonts, destFonts, counts, note) {
+  let out = text;
+  const dispFrom = invFonts?.display?.familia, corpoFrom = invFonts?.corpo?.familia;
+  const pairs = [];
+  // origem usa 1 família só (display==corpo): fazer UMA troca, senão o 1º replace
+  // consome tudo e o 2º não acha nada — saía tudo com a fonte de título e o
+  // relatório mentia "trocas:1" (achado do gate). Aplica a de CORPO (texto manda).
+  if (dispFrom && corpoFrom && fnorm(dispFrom) === fnorm(corpoFrom)) {
+    if (destFonts.body || destFonts.display) { pairs.push([dispFrom, destFonts.body || destFonts.display]); if (note) note.single = `origem usa 1 fonte só ("${dispFrom}"); apliquei a de corpo do destino em tudo — títulos não foram diferenciados`; }
+  } else {
+    if (dispFrom && destFonts.display) pairs.push([dispFrom, destFonts.display]);
+    if (corpoFrom && destFonts.body) pairs.push([corpoFrom, destFonts.body]);
+  }
+  for (const [from, to] of pairs) {
+    const bare = from.replace(/\s+(Variable|Var)$/i, '').trim();
+    for (const name of new Set([from, bare])) {
+      const re = new RegExp(name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'gi');
+      const n = (out.match(re) || []).length;
+      if (n) { out = out.replace(re, to); counts.tipografia = (counts.tipografia || 0) + n; }
+    }
+  }
+  return out;
+}
+
+async function listFiles(p) {
+  const s = await stat(p);
+  if (s.isFile()) return [{ abs: p, rel: path.basename(p) }];
+  const out = [];
+  const rec = async (d, base) => { for (const e of await readdir(d, { withFileTypes: true })) { if (e.name.startsWith('.') || e.name === 'node_modules' || e.name === '_verify') continue; const abs = path.join(d, e.name), rel = path.join(base, e.name); if (e.isDirectory()) await rec(abs, rel); else out.push({ abs, rel }); } };
+  await rec(p, ''); return out;
+}
+
+// ---------------------------------------------------------------- main
+(async () => {
+  // NUNCA sobrescrever dado do usuário: se --out já tem conteúdo, aborta (a menos
+  // de --force). Sem isso, apontar --out pra pasta de origem comia o original —
+  // e o relatório ainda afirmava "origem não foi tocada" (achado do gate).
+  const outResolved = path.resolve(OUT), srcResolved = path.resolve(srcPath);
+  if (outResolved === srcResolved || outResolved === path.dirname(srcResolved)) {
+    console.error(`erro: --out não pode ser a origem nem a pasta dela (sobrescreveria o original). Use uma pasta nova.`); process.exit(2);
+  }
+  try { const existing = await readdir(OUT); if (existing.length && !FORCE) { console.error(`erro: --out "${OUT}" já tem ${existing.length} arquivo(s). Use uma pasta vazia/nova, ou --force pra escrever por cima.`); process.exit(2); } } catch { /* não existe ainda: ok */ }
+
+  const inv = JSON.parse(await readFile(invPath, 'utf8'));
+  const brand = parseBrand(await readFile(brandPath, 'utf8'));
+  let destRoles = buildDestRoles(brand);
+  destRoles = applyRoleOverride(destRoles, brand, ROLES_OVERRIDE);
+
+  // MAPA DE PAPÉIS — mostrado pro usuário confirmar (não aplica cego)
+  log('mapa de papéis do destino (' + path.basename(brandPath) + '):');
+  for (const role of ['fundo', 'texto', 'superficie', 'primaria', 'acento', 'borda']) { const v = destRoles[role]; if (v) log(`  ${role.padEnd(11)} → ${v.name.padEnd(14)} ${v.hex}  ${v.comment ? '(' + v.comment + ')' : ''}`); }
+
+  const { map, table, colisoes } = buildColorMap(inv, destRoles, []);
+  const counts = {};
+  const fontNote = {};
+  const orphans = new Map();
+  const destSet = new Set(brand.vars.map(v => key(v.rgb)));   // cores do brand não são órfãs
+  const files = await listFiles(srcPath);
+  await mkdir(OUT, { recursive: true });
+
+  // cor só entra onde cor mora: .css (tudo) e .html (só <style> e style=""). JS,
+  // JSON e SVG são copiados sem troca de cor — evita corromper href/rota/dado.
+  let nText = 0, nCopy = 0;
+  for (const f of files) {
+    const dest = path.join(OUT, f.rel);
+    await mkdir(path.dirname(dest), { recursive: true });
+    const isCss = /\.css$/i.test(f.rel), isHtml = /\.html?$/i.test(f.rel);
+    if (isCss || isHtml) {
+      let t = await readFile(f.abs, 'utf8');
+      if (wantPalette || wantPrimariaOnly) t = isCss ? rewriteColors(t, map, counts, orphans, destSet) : rewriteHtmlColors(t, map, counts, orphans, destSet);
+      if (wantType) t = rewriteFonts(t, inv.tipografia, brand.fonts, counts, fontNote);
+      await writeFile(dest, t); nText++;
+    } else { await copyFile(f.abs, dest); nCopy++; }
+  }
+
+  // CONTRASTE final (obrigatório): texto destino sobre fundo destino
+  const tCol = destRoles.texto?.rgb, bCol = destRoles.fundo?.rgb;
+  const cr = tCol && bCol ? contrast(tCol, bCol) : null;
+  const contrasteOk = cr == null ? null : { texto_sobre_fundo: cr, passa_AA_corpo: cr >= 4.5, passa_AA_titulo: cr >= 3 };
+
+  // relatório
+  const R = [];
+  R.push(`# Transplante — ${path.basename(brandPath)} sobre ${inv.fonte}`);
+  R.push(`> nível: ${NIVEL}  ·  dimensões: ${DIMS.join(', ')}  ·  saída: ${OUT}\n`);
+  R.push(`## Mapa de cores aplicado`);
+  R.push('| Papel | Origem | → | Destino | Var | Trocas |');
+  R.push('|---|---|---|---|---|---|');
+  for (const r of table) R.push(`| ${r.role} | ${r.fromHex} | → | ${r.toHex} | \`${r.destName}\` | ${counts[r.role] || 0} |`);
+  R.push(`\n## Tipografia`);
+  R.push(`- display: ${inv.tipografia?.display?.familia || '—'} → ${brand.fonts.display || '—'}`);
+  R.push(`- corpo: ${inv.tipografia?.corpo?.familia || '—'} → ${brand.fonts.body || '—'}  (trocas: ${counts.tipografia || 0})`);
+  if (fontNote.single) R.push(`- ⚠️ ${fontNote.single}`);
+  // borda que virou igual à superfície fica invisível (achado do gate)
+  if (destRoles.borda && destRoles.superficie && destRoles.borda.hex === destRoles.superficie.hex) {
+    R.push(`\n## ⚠️ Borda = superfície (pode ficar invisível)`);
+    R.push(`- o brand.css não tem cor com papel "borda" claro; caiu na mesma cor de superfície (${destRoles.borda.hex}). Se o site usa borda de card, ela some. Marque uma cor de borda no brand.css ou use \`--roles borda=--alguma\`.`);
+  }
+  R.push(`\n## ✅ Contraste do resultado (check obrigatório)`);
+  if (contrasteOk) { R.push(`- texto sobre fundo: **${contrasteOk.texto_sobre_fundo}:1** — AA corpo: ${contrasteOk.passa_AA_corpo ? '✓' : '✗ REPROVA'} · AA título: ${contrasteOk.passa_AA_titulo ? '✓' : '✗ REPROVA'}`); if (!contrasteOk.passa_AA_corpo) R.push(`  - ⚠️ **BLOQUEADOR:** o par texto/fundo da marca não passa AA. Ajuste o mapa (--roles) ou a cor de texto antes de entregar.`); }
+  else R.push(`- não pôde medir (faltou papel fundo ou texto no destino)`);
+  if (colisoes.length) {
+    R.push(`\n## ⚠️ Colisão de papel (mesma cor de origem em papéis diferentes)`);
+    colisoes.forEach(c => R.push(`- ${c.fromHex}: papel "${c.role}" ignorado, já mapeado como "${c.jaMapeado}". Se ambos importam, separe as cores no original.`));
+  }
+  if (orphans.size) {
+    R.push(`\n## ⚠️ Cores órfãs (apareceram no site, sem papel no inventário — revise)`);
+    const rgbHex = k => { const [r, g, b] = k.split(',').map(Number); return toHex({ r, g, b }); };
+    [...orphans.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10).forEach(([k, n]) => R.push(`- ${rgbHex(k)} (${n}x) — não trocada. Se for superfície/detalhe, adicione ao mapa ou rode o inventário de novo.`));
+  }
+  const totalTrocas = Object.entries(counts).filter(([k]) => k !== 'tipografia').reduce((s, [, n]) => s + n, 0);
+  if ((wantPalette || wantPrimariaOnly) && table.length && totalTrocas === 0) {
+    R.push(`\n## ⚠️ ZERO trocas de cor — provável incompatibilidade de formato`);
+    R.push(`- O mapa tinha ${table.length} cor(es) mas nenhuma casou no CSS. Causa provável: o site usa \`oklch()\`/\`color()\` (Tailwind v4) no CSS, que não casa por valor rgb. O inventário normaliza, o transplante ainda não. Trate como limitação conhecida deste caso.`);
+  }
+  R.push(`\n## Origem preservada`);
+  R.push(`- ${nText} arquivo(s) reescrito(s), ${nCopy} copiado(s). A origem NÃO foi tocada — resultado em pasta separada.`);
+  const rep = R.join('\n');
+  await writeFile(path.join(OUT, '_transplante.md'), rep);
+  process.stdout.write(rep + '\n');
+  log(`pronto: ${nText} reescritos, ${nCopy} copiados em ${OUT}`);
+})().catch(e => { console.error('[transplant] FALHA:', e.message); process.exit(1); });

package/skills/conectar-mcp/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: conectar-mcp
+description: Ensina a conectar um MCP (servidor de ferramentas externas) ao Claude Code, passo a passo e com segurança — Shopify, Supabase, Higgsfield, ElevenLabs, Meta Ads ou qualquer outro serviço. Use quando o usuário pedir pra conectar/instalar um MCP, quando um agente precisar de ferramentas mcp__* que não existem na sessão, ou quando o usuário perguntar o que é MCP e como ligar o Iron a um serviço externo.
+---
+
+# conectar-mcp — ligar o Iron a um serviço externo
+
+MCP é a ponte entre o Claude Code e um serviço de fora (a sua loja Shopify, o seu banco Supabase, um gerador de imagem). Conectar um MCP dá ao Iron ferramentas novas — e dá ao serviço acesso ao que o seu token permitir. Por isso o processo tem regras.
+
+## As 4 regras antes de qualquer comando
+
+1. **A conta é SEMPRE do usuário.** Conectar MCP é decisão dele, com conta dele, token dele. Nunca sugira usar credencial de outra pessoa, e nunca guarde token em arquivo de projeto.
+2. **Menor permissão possível.** Se o serviço oferecer token read-only ou escopado, comece por ele. Dá pra subir depois; vazamento não desfaz.
+3. **Medir antes de decidir.** Diga ao usuário o que o MCP vai poder fazer ANTES de conectar ("este MCP lê e escreve produtos da loja"). Se ele só precisa ler, procure o modo read-only.
+4. ⚠️ **O token fica gravado em texto puro** em `~/.claude/.credentials.json` (ou no config de MCP). Numa máquina compartilhada ou corporativa, o usuário precisa saber disso antes de dizer sim. Desinstalar o MCP não apaga o token gravado — mostre onde fica e como revogar no painel do serviço.
+
+## O passo a passo (vale pra qualquer MCP)
+
+1. **Descobrir o comando de conexão na documentação OFICIAL do serviço** — busque na web na hora ("<serviço> MCP Claude Code"). Nunca invente endpoint nem nome de pacote: comando errado falha em silêncio ou conecta no lugar errado. Os dois formatos comuns:
+   - servidor local via npm: `claude mcp add <nome> -- npx -y <pacote-oficial>`
+   - servidor remoto: `claude mcp add --transport http <nome> <url-oficial>`
+2. **Rodar o comando** e, se o serviço pedir login/token, conduzir o usuário pelo fluxo dele (criar conta se não tiver, gerar o token no painel, colar quando o comando pedir).
+3. **Conferir que gravou:** `claude mcp get <nome>` tem que listar o servidor. Se não listar, não gravou — não finja que conectou.
+4. **Sessão NOVA.** MCP conectado só monta as ferramentas em sessão nova: feche e abra o Claude Code. Este é o passo que todo mundo pula e que faz parecer que "não funcionou".
+5. **Provar com uso real, não com "conectado".** Na sessão nova, rode UMA operação de leitura inofensiva (listar produtos, listar tabelas, checar saldo) e mostre a saída. "Connected" não prova que as ferramentas carregaram; a operação prova.
+
+## Exemplos do ecossistema Iron
+
+- **iron-shopify** (nas edições que o incluem — confira no seu routing map) → precisa do MCP de desenvolvimento da Shopify (pacote npm oficial `@shopify/dev-mcp`): `claude mcp add shopify-dev-mcp -- npx -y @shopify/dev-mcp@latest`. A autenticação da LOJA em si é separada (Shopify CLI, o agente conduz).
+- **iron-spy** → não usa MCP: usa a API da Apify direto por script; o próprio agente conduz a criação da conta e da chave.
+- **Supabase, Higgsfield, ElevenLabs, Meta Ads** e outros → cada um publica seu comando oficial; siga o passo 1 (buscar a doc atual) em vez de confiar em comando decorado, porque endpoints mudam.
+
+## Se der errado
+
+- Comando rodou mas `claude mcp get` não lista → o add falhou; leia a mensagem de erro de verdade em vez de repetir o comando.
+- Listou mas as ferramentas `mcp__<nome>__*` não aparecem → quase sempre é sessão velha (passo 4). Feche e abra antes de qualquer outra hipótese.
+- Máquina corporativa com proxy/política: o bloqueio pode ser de rede, não do comando. Painel do serviço abrir no navegador não prova que a API passa pelo proxy — teste a operação real (passo 5) antes de concluir qualquer coisa.
+- Pra remover: `claude mcp remove <nome>` — e lembre o usuário de revogar o token no painel do serviço, porque remover o MCP não revoga nada.

package/skills/escada/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: escada
+description: Escada de Modelos do Iron Edge — a regra de qual modelo de IA usar em cada momento do trabalho, pra cota render mais. Use quando o usuário disser "escada", "escada de modelos", "configura a escada", perguntar qual modelo usar, reclamar de cota/limite estourando, ou perguntar por que a conta gasta tão rápido. Na primeira vez, MEDE a conta do usuário e grava a regra no CLAUDE.md dele pra valer em toda sessão.
+---
+
+# escada — a regra de custo dos modelos
+
+A lógica cabe numa frase: **custo = peso do modelo × volume de tokens da fase.**
+
+PLANEJAR e DAR VEREDITO são fases curtas de julgamento — modelo caro ali custa pouco e rende muito. EXECUTAR é a fase longa (dezenas de comandos, ler e escrever arquivo) — modelo caro ali é onde a cota morre. BRAÇAL (buscar, varrer, formatar) nem julgamento precisa. Então: **caro nas pontas, médio no meio, barato no braçal.**
+
+## Primeira vez: MEDIR a conta antes de qualquer regra
+
+Nunca assuma quais modelos a conta do usuário tem — contas diferem. Conduza, pausando entre os passos:
+
+1. **O padrão atual.** Descubra o SO e leia a linha `"model"` do `~/.claude/settings.json` (Mac/Linux: `grep '"model"' ~/.claude/settings.json`; Windows: `Get-Content "$HOME\.claude\settings.json" | Select-String '"model"'`). Três resultados válidos: a linha, nada, ou arquivo inexistente. Anote qual foi — é o modelo em que toda sessão nasce hoje.
+2. **Peça pro usuário digitar `/model`** e anotar as opções da lista SEM escolher nenhuma (Esc pra sair — a vacina abaixo explica por quê).
+3. **Peça `/usage`**: qual plano aparece, e SE existe uma barra separada só do sonnet ("Sonnet only"/"Apenas Sonnet"). Se existir, é dado de ouro: execução no sonnet gasta saldo próprio e preserva o saldo dos modelos caros.
+4. **Defina os degraus com o que foi medido, e mostre antes de gravar:**
+   - JULGADOR (planeja e dá veredito) = o modelo mais capaz da lista (fable se apareceu; senão opus; senão sonnet).
+   - EXECUTOR (implementa e corrige) = sonnet.
+   - BRAÇAL (busca, varre, formata) = haiku; sem haiku na lista, o braçal usa o EXECUTOR com esforço baixo.
+   - Conta só com sonnet e haiku: a escada vale com um degrau a menos — o julgamento fica no sonnet e o que muda entre fases é o esforço (alto pra julgar, médio pra executar). Registre e siga; nada abaixo quebra.
+
+## A regra nas três situações do dia
+
+**DIA A DIA** (feature, ajuste, bug): planejar no plan mode → executar no EXECUTOR → revisar no JULGADOR se a coisa for séria. Se `opusplan` apareceu na lista, `/model opusplan` automatiza exatamente isso — é o único caso em que `/model` é bem-vindo, porque aí mudar o padrão É a intenção.
+
+**DEMANDA ESTRUTURAL** (desenhar um sistema, arquitetura, decisão cara de errar) — o fluxo das TRÊS ABAS do terminal:
+- aba 1: JULGADOR planeja e **salva o plano num ARQUIVO**;
+- aba 2: EXECUTOR executa lendo o arquivo. Sobe um degrau em DOIS casos apenas: implementação pesada em si, ou o EXECUTOR travou 2 vezes no mesmo ponto. Regra de bolso: **sonnet até travar, degrau acima pra destravar** — e subir é FECHAR a aba e abrir outra com `claude --model "opus"`, nunca `/model` na aba aberta;
+- aba 3: JULGADOR dá o veredito comparando entrega × plano.
+- O canal entre as abas é sempre um arquivo, nunca copiar e colar conversa.
+
+**BRAÇAL** (achar arquivos, varrer pastas, renomear em massa): delega pro degrau BRAÇAL, ou pede na sessão com esforço baixo. Não se usa cérebro caro pra segurar lanterna.
+
+## ⛔ A vacina do /model
+
+Caso real: uma conta estourou a cota TRÊS vezes pela mesma causa invisível.
+
+- **`/model` dentro da sessão GRAVA A ESCOLHA COMO PADRÃO PERMANENTE.** Não é "só desta vez". É assim que uma conta amanhece presa no modelo mais caro sem avisar.
+- **Troca pontual é SEMPRE aba nova do terminal**, com o modelo no comando de abrir: `claude --model "opus"`. Vale só pra aquela aba e morre com ela.
+- `/model` só quando o usuário QUER mudar o padrão de propósito (como o opusplan) — e nesse caso, conferir depois com o comando do passo 1 que gravou o que ele queria.
+
+## Cada agente com o modelo do cargo
+
+Subagente sem modelo próprio herda o modelo da sessão que o chamou — o agente de busca mais simples roda no cérebro mais caro da conta, por acidente. Caso real: um único fluxo multi-agente consumiu o equivalente a um dia inteiro de uso.
+
+Os agentes do Iron Edge já vêm com `model:` por cargo (opus = estrategista, sonnet = executor, haiku = mecânico). **Agente que o usuário criar segue a mesma tabela**, sempre com apelido (opus/sonnet/haiku), NUNCA nome de versão — apelido acompanha os lançamentos sozinho, versão fixa vira fóssil. E degrau que a medição rebaixou vale aqui também: apelido que a conta não tem não entra em arquivo.
+
+## Gravar a regra pra valer (o Iron passa a sugerir sozinho)
+
+Depois da medição, grave no `~/.claude/CLAUDE.md` do usuário (backup antes se existir; se a seção `## ESCADA DE MODELOS` já existir, ATUALIZE inteira no lugar, nunca duplique) a seção com:
+- a regra de ouro;
+- os três degraus MEDIDOS desta conta;
+- o fluxo das 3 abas, com a instrução de salvar o plano em arquivo;
+- a vacina do /model;
+- e a ordem de SUGERIR SOZINHO: quando o usuário pedir pra desenhar sistema/arquitetura/decisão grande, avisar em 1 linha que é demanda estrutural e dar o comando da aba do JULGADOR pronto pra copiar; quando um planejamento desses terminar, salvar o plano em arquivo sem pedir e dizer o caminho; quando a execução terminar, lembrar do veredito.
+
+Mostre a seção pronta ANTES de salvar. Lembre o usuário: CLAUDE.md novo só vale em sessão nova (fechar e abrir).
+
+**Teste de que pegou** (sessão nova): o usuário pede algo estrutural sem citar modelo nenhum. Critério duplo: (a) o Iron reconheceu sozinho e sugeriu a escada; (b) a sugestão veio com o comando pronto pra copiar. Se respondeu direto sem sugerir, a seção não carregou — conferir arquivo e sessão nova antes de qualquer outra coisa.

package/skills/faxina/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: faxina
+description: Higiene dos arquivos efêmeros da sessão — PDFs e relatórios que o Iron gerou pra leitura, prints e capturas de tela. Dispara quando o usuário disser "faxina", "limpa os pdfs", "limpa os prints", "limpa a bagunça" — e SEMPRE como pergunta única antes do "salvar"/"encerrar". Lista o que acumulou, propõe destino (apagar / arquivar / virar nota leve) e só apaga com aprovação.
+---
+
+# faxina — o par do salvar
+
+O **salvar** registra o que fica; a **faxina** decide o que sai. Sem ela, o computador acumula prints e PDFs que já cumpriram o papel — dezenas por dia em quem trabalha com o Iron o dia inteiro.
+
+## Quando rodar
+
+1. **Sempre antes do "salvar"/"encerrar"**: UMA pergunta curta, com o resumo ("Faxina: 2 PDFs desta sessão e 31 prints (40 MB). Limpo?").
+2. Por gatilho: "faxina", "limpa os prints", "limpa os pdfs", "limpa a bagunça".
+
+## O que varrer
+
+- **Arquivos de leitura que o Iron gerou nesta sessão** (PDF, HTML de relatório) — o Iron sabe os caminhos do que criou. Documento gerado só pra LER é efêmero por padrão.
+- **Prints/capturas**: descubra o local real da máquina antes de varrer — no Mac, `defaults read com.apple.screencapture location` (vazio = Desktop); no Windows, `Pictures/Screenshots` e a Área de Trabalho. Padrões: `Captura de Tela*`, `Screenshot*`, `CleanShot*`, `Screen Shot*`.
+- Mostrar SEMPRE: quantidade, tamanho total e os 3 mais recentes.
+
+## Os três destinos (perguntar, nunca decidir sozinho)
+
+| destino | quando | como |
+|---|---|---|
+| **Apagar** | cumpriu o papel | mover pro Lixo do sistema, nunca deletar direto — arrependimento tem volta |
+| **Arquivar** | vale guardar como está | PDF → pasta do projeto; print → subpasta datada (`prints-arquivo/AAAA-MM/`) |
+| **Virar nota leve** | o CONTEÚDO importa, o formato não | o essencial vira nota .md no cofre; o arquivo pesado sai |
+
+## Regras
+
+- **Print com menos de 24h só sai com confirmação individual** ou "pode limpar tudo de hoje" explícito — pode estar em uso em outra aba.
+- Nunca tocar em arquivo que não seja print/captura ou documento gerado pelo Iron — a faxina não é limpeza geral de pastas.
+- Fechar em 1 linha: `Faxina: 12 prints e 2 PDFs pro Lixo, 1 arquivado. (liberou 18 MB)`
+- Recusou? Não insistir. Zero registro, segue pro salvar.