sabia 1.1.3 → 2.0.0-alpha.1

package/compilar.mjs

@@ -0,0 +1,373 @@
+// Compilador as-built do Sabiá: fluxo/ + padrao/ + skills/ (a fonte, no framework) → skills comuns (SKILL.md +
+// references/) numa pasta de staging, uma por alvo. Seção 11 do plano da 2.0.
+import fs from "node:fs";
+import path from "node:path";
+
+const FM = /^---\n([\s\S]*?)\n---\n/;
+const ID = /`(sa-[a-z]+(?:\.[a-z][a-z-]*){1,2})`/g;
+const LINK = /\]\(([^)\s]+)\)/g;
+
+const ler = (f) => fs.readFileSync(f, "utf8");
+const json = (f) => JSON.parse(ler(f));
+const skillsDe = (fw) => fs.readdirSync(path.join(fw, "skills")).filter((d) => d === "sabia" || d.startsWith("sa-")).sort();
+const mds = (dir) => (fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith(".md")).sort() : []);
+
+/** Front-matter JSON (fluxo/, padrao/) e o corpo, com as linhas do front-matter preservadas para o número de linha. */
+export function partes(texto) {
+  const m = texto.match(FM);
+  return m ? { dados: JSON.parse(m[1]), corpo: texto.slice(m[0].length), pulo: m[0].split("\n").length - 1 } : { dados: null, corpo: texto, pulo: 0 };
+}
+
+/** Slug de âncora no estilo do GitHub: minúsculas, letras e números Unicode mantidos, espaço vira "-". */
+export const slug = (titulo) => titulo.trim().toLowerCase().replace(/`/g, "").replace(/[^\p{L}\p{N} _-]/gu, "").replace(/ /g, "-");
+const ancoras = (texto) => new Set([...texto.matchAll(/^#+ (.+)$/gm)].map((m) => slug(m[1])));
+
+/** Lê a fonte inteira: fluxos, passos, regras, padrões, travas e papéis. */
+export function carregar(fw) {
+  const m = { fw, fluxos: {}, regras: {}, padroes: {}, travas: {}, subag: {}, skillsAgente: {} };
+  const dirFluxo = path.join(fw, "fluxo");
+  if (fs.existsSync(path.join(dirFluxo, "travas.json"))) m.travas = json(path.join(dirFluxo, "travas.json")).travas;
+  const papeis = path.join(fw, "skills/sa-setup/assets/agents/papeis.json");
+  if (fs.existsSync(papeis))
+    for (const [k, v] of Object.entries(json(papeis).papeis)) {
+      m.subag[`sa-${k}`] = new Set(v.subagentes || []);
+      m.skillsAgente[`sa-${k}`] = new Set(v.skills || []);
+    }
+  for (const s of fs.existsSync(dirFluxo) ? fs.readdirSync(dirFluxo).sort() : []) {
+    const ds = path.join(dirFluxo, s);
+    if (!fs.statSync(ds).isDirectory()) continue;
+    if (fs.existsSync(path.join(ds, "regras.md"))) m.regras[s] = { arq: path.join(ds, "regras.md"), ...partes(ler(path.join(ds, "regras.md"))) };
+    for (const f of fs.readdirSync(ds).sort()) {
+      const mestre = path.join(ds, f, `${f}.md`);
+      if (!fs.existsSync(mestre)) continue;
+      const p = partes(ler(mestre));
+      const passos = (p.dados?.passos || []).map((x) => {
+        const arq = path.join(ds, f, "passos", `${x.id}.md`);
+        return { ...x, arq, ...(fs.existsSync(arq) ? partes(ler(arq)) : { dados: null, corpo: "", pulo: 0 }) };
+      });
+      m.fluxos[`${s}.${f}`] = { skill: s, fluxo: f, arq: mestre, d: p.dados || {}, corpo: p.corpo, pulo: p.pulo, passos };
+    }
+  }
+  const dirPadrao = path.join(fw, "padrao");
+  for (const s of fs.existsSync(dirPadrao) ? fs.readdirSync(dirPadrao).sort() : [])
+    m.padroes[s] = mds(path.join(dirPadrao, s)).map((n) => ({ nome: n, arq: path.join(dirPadrao, s, n), ...partes(ler(path.join(dirPadrao, s, n))) }));
+  return m;
+}
+
+const fluxosDa = (m, s) => Object.values(m.fluxos).filter((f) => f.skill === s);
+
+/** "sa-x.f" ou "sa-x.f.p" existe? Devolve o fluxo e o passo (ou null). */
+function resolverId(m, q) {
+  const [s, f, p] = q.split(".");
+  const fl = m.fluxos[`${s}.${f}`];
+  if (!fl) return null;
+  if (p === undefined) return { fl, passo: null };
+  const passo = fl.passos.find((x) => x.id === p);
+  return passo ? { fl, passo } : null;
+}
+
+/** Como o agente roda um fluxo chamado: "em linha" (mesmo dono ou skill do agente), "subagente", ou null (não pode). */
+function modoChamada(m, dono, alvo) {
+  if (alvo.d.dono === dono || m.skillsAgente[dono]?.has(alvo.skill)) return "em linha";
+  if (m.subag[dono]?.has(alvo.d.dono)) return "subagente";
+  return null;
+}
+
+// ---------------------------------------------------------------- validação
+
+/** Erros "arquivo:linha: mensagem" da fonte (as regras do conferidor da F2.0). Lista vazia = pronta para compilar. */
+export function validar(m) {
+  const erros = [];
+  const rel = (f) => path.relative(m.fw, f);
+  const e = (f, n, msg) => erros.push(`${rel(f)}:${n}: ${msg}`);
+  const porSkill = {};
+  for (const fl of Object.values(m.fluxos)) (porSkill[fl.skill] ||= []).push(fl);
+
+  for (const [q, fl] of Object.entries(m.fluxos)) {
+    const { d } = fl;
+    if (!d.passos?.length || d.fluxo !== fl.fluxo || !d.dono) e(fl.arq, 2, "mestre sem fluxo/dono/passos (ou fluxo ≠ nome da pasta)");
+    if (porSkill[fl.skill].length > 1 && !(Array.isArray(d.quando) ? d.quando.length : String(d.quando || "").trim()))
+      e(fl.arq, 2, `falta "quando" (a skill ${fl.skill} tem ${porSkill[fl.skill].length} fluxos)`);
+    const ids = fl.passos.map((x) => x.id);
+    const orfaos = fs.existsSync(path.join(path.dirname(fl.arq), "passos"))
+      ? mds(path.join(path.dirname(fl.arq), "passos")).map((f) => f.slice(0, -3)).filter((x) => !ids.includes(x)) : [];
+    for (const o of orfaos) e(fl.arq, 2, `passo ${o} órfão (tem arquivo, não está no mestre)`);
+    for (const t of d.travas_gerais || []) if (!m.travas[t]) e(fl.arq, 2, `trava ${t} fora do catálogo`);
+    for (const x of fl.passos) {
+      if (!x.dados) { e(x.arq, 1, `passo ${x.id} sem arquivo ou sem front-matter`); continue; }
+      if (!x.dados.resumo) e(x.arq, 2, "passo sem resumo");
+      for (const sec of ["## Entrada", "## Faça", "## Saída", "## Pare se"]) if (!x.corpo.includes(sec)) e(x.arq, 1, `falta ${sec}`);
+      for (const t of x.travas || []) if (!m.travas[t]) e(fl.arq, 2, `passo ${x.id}: trava ${t} fora do catálogo`);
+      for (const c of [].concat(x.chama || [])) {
+        const r = resolverId(m, c);
+        if (!r) e(fl.arq, 2, `passo ${x.id}: chama ${c} inexistente`);
+        else if (!modoChamada(m, d.dono, r.fl)) e(fl.arq, 2, `passo ${x.id}: chama ${c} (dono ${r.fl.d.dono}), mas ${d.dono} não tem a skill nem esse subagente → use passagem (→)`);
+      }
+      for (const [cond, dest] of Object.entries(x.saidas || {})) {
+        if (dest === "fim" || ids.includes(dest) || (dest.startsWith("→ ") && resolverId(m, dest.slice(2).trim()))) continue;
+        e(fl.arq, 2, `passo ${x.id}: saída "${cond}" → "${dest}" (use id do fluxo, fim ou "→ skill.fluxo[.passo]" existente)`);
+      }
+    }
+  }
+
+  const textos = [];
+  for (const fl of Object.values(m.fluxos)) {
+    textos.push({ arq: fl.arq, corpo: fl.corpo, pulo: fl.pulo, skill: fl.skill, fl });
+    for (const x of fl.passos) textos.push({ arq: x.arq, corpo: x.corpo, pulo: x.pulo, skill: fl.skill, fl });
+  }
+  for (const [s, r] of Object.entries(m.regras)) textos.push({ arq: r.arq, corpo: r.corpo, pulo: r.pulo, skill: s });
+  for (const [s, ps] of Object.entries(m.padroes)) for (const p of ps) textos.push({ arq: p.arq, corpo: p.corpo, pulo: p.pulo, skill: s });
+  for (const s of skillsDe(m.fw)) {
+    const dir = path.join(m.fw, "skills", s);
+    for (const f of [path.join(dir, "SKILL.md"), ...mds(path.join(dir, "references")).map((n) => path.join(dir, "references", n))]) {
+      if (!fs.existsSync(f)) continue;
+      const t = ler(f);
+      const fmYaml = t.match(FM);
+      const corpo = fmYaml ? t.slice(fmYaml[0].length) : t;
+      const pulo = fmYaml ? fmYaml[0].split("\n").length - 1 : 0;
+      if (path.basename(f) === "SKILL.md" && porSkill[s]) {
+        const resto = corpo.split("\n").filter((l) => l.trim() && !l.startsWith("# "));
+        if (resto.length) e(f, pulo + 1, `skill de fluxo com corpo além do H1 (${resto.length} linhas): vai para "quando" ou regras.md`);
+      }
+      textos.push({ arq: f, corpo, pulo, skill: s });
+    }
+  }
+
+  const passoRx = /\bpassos? ((?:`[a-z][a-z-]*`(?:, | e | ou )?)+)/g;
+  const fluxoRx = /\bfluxos? ((?:`[a-z][a-z-]*`(?:, | e | ou )?)+)/g;
+  const legado = [/`?\bsa-[a-z]+`?\*{0,2},? \(?(?:fluxo|passo)s? `/, /\b(?:fluxo|passo)s? `[a-z-]+`(?: \([^)]*\))? d[ao] \*{0,2}`?sa-[a-z]+/];
+  for (const t of textos) {
+    let cerca = false;
+    t.corpo.split("\n").forEach((linha, i) => {
+      const n = t.pulo + i + 1;
+      if (linha.trimStart().startsWith("```")) { cerca = !cerca; return; }
+      if (/~\/\.sabia\/(fluxo|padrao)\//.test(linha)) e(t.arq, n, "prefixo ~/.sabia/fluxo|padrao/ → ~/.sabia/framework/fluxo|padrao/");
+      if (cerca) return;
+      for (const [, q] of linha.matchAll(ID)) if (!/\.(md|json|sh|py)$/.test(q) && !resolverId(m, q)) e(t.arq, n, `id inexistente \`${q}\``);
+      const semId = linha.replace(ID, "ID");
+      for (const rx of legado) if (rx.test(semId)) e(t.arq, n, `referência em prosa → use o id: …${semId.match(rx)[0]}…`);
+      for (const [, grupo] of semId.matchAll(passoRx))
+        for (const [, x] of grupo.matchAll(/`([a-z][a-z-]*)`/g)) {
+          if (t.fl) { if (!t.fl.passos.some((p) => p.id === x)) e(t.arq, n, `passo \`${x}\` não é do fluxo ${t.skill}.${t.fl.fluxo} → use o id`); }
+          else if (porSkill[t.skill]) { if (porSkill[t.skill].filter((f) => f.passos.some((p) => p.id === x)).length !== 1) e(t.arq, n, `passo \`${x}\` sem fluxo → use o id`); }
+          else e(t.arq, n, `passo \`${x}\` fora de fluxo → use o id`);
+        }
+      for (const [, grupo] of semId.matchAll(fluxoRx))
+        for (const [, x] of grupo.matchAll(/`([a-z][a-z-]*)`/g)) if (!m.fluxos[`${t.skill}.${x}`]) e(t.arq, n, `fluxo \`${x}\` não é da skill ${t.skill} → use o id`);
+      for (const mi of semId.matchAll(/\bitens? \d+/g))
+        if (/^[^.;]*?(\bd[ao] `?sa-|ID|\bd[ao] passo `)/.test(semId.slice(mi.index + mi[0].length, mi.index + mi[0].length + 70)))
+          e(t.arq, n, `"${mi[0]}" de outro arquivo → use id ou âncora`);
+      for (const f of ["em `fluxo/`", "abra-os pelo caminho", "abra pelo caminho", "ficam fora do projeto"]) if (linha.includes(f)) e(t.arq, n, `frase de localização "${f}"`);
+      if (/`sa-[a-z]+\/[a-z-]+\/passos\/|`sa-[a-z]+\/regras\.md`/.test(linha)) e(t.arq, n, "caminho de fluxo/ em code-span → id do passo");
+    });
+  }
+  return erros;
+}
+
+// ---------------------------------------------------------------- reescrita
+
+/** Caminho na fonte (absoluto) → caminho relativo à pasta skills/ da saída, ou null se não for do framework. */
+export function mapear(fw, src) {
+  const r = path.relative(fw, src).split(path.sep);
+  if (r[0] === "skills" && r.length >= 2) return r.slice(1).join("/");
+  if (r[0] === "padrao" && r.length === 3) return `${r[1]}/references/padrao/${r[2]}`;
+  if (r[0] === "fluxo" && r.length === 3 && r[2] === "regras.md") return `${r[1]}/SKILL.md`;
+  if (r[0] === "fluxo" && r.length === 4 && r[3] === `${r[2]}.md`) return `${r[1]}/SKILL.md`;
+  if (r[0] === "fluxo" && r.length === 5 && r[3] === "passos") return `${r[1]}/references/${r[2]}/${r[4]}`;
+  return null;
+}
+
+/** Reescreve links e caminhos do framework para o caminho absoluto do alvo (`base`) e liga ids e padrões. */
+export function reescrever(texto, origem, { fw, base, m }) {
+  const destino = (alvo) => {
+    const [cam, anc = ""] = alvo.split("#");
+    let src;
+    if (cam.startsWith("~/.sabia/framework/")) src = path.join(fw, cam.slice("~/.sabia/framework/".length));
+    else if (!cam) src = origem;
+    else if (cam.startsWith("../") || cam.startsWith("references/") || cam.endsWith("SKILL.md")) src = path.resolve(path.dirname(origem), cam);
+    else return null;
+    const r = mapear(fw, src);
+    return r ? `${base}/${r}${anc ? "#" + anc : ""}` : null;
+  };
+  let cerca = false;
+  return texto.split("\n").map((linha) => {
+    if (linha.trimStart().startsWith("```")) { cerca = !cerca; return linha; }
+    linha = linha.replace(LINK, (todo, alvo) => {
+      if (/^(https?:|mailto:)/.test(alvo) || alvo.includes("<") || alvo.includes("…")) return todo;
+      const d = destino(alvo);
+      return d ? `](${d})` : todo;
+    });
+    linha = linha.replace(/~\/\.sabia\/framework\/[^\s)`'"]+/g, (cam) => destino(cam) || cam);
+    if (cerca || !m) return linha;
+    linha = linha.replace(/(\[)?`(sa-[a-z]+(?:\.[a-z][a-z-]*){1,2})`(\]\()?/g, (todo, abre, q, fecha) => {
+      if (abre || fecha || /\.(md|json|sh|py)$/.test(q)) return todo;
+      const r = resolverId(m, q);
+      if (!r) return todo;
+      const alvo = destinoId(base, r);
+      return `[\`${q}\`](${alvo})`;
+    });
+    return linha.replace(/o padrão `([a-z-]+)\/([a-z0-9.-]+\.md)`(?!\])/g, (todo, s, n) =>
+      m.padroes[s]?.some((p) => p.nome === n) ? `o padrão [\`${s}/${n}\`](${base}/${s}/references/padrao/${n})` : todo);
+  }).join("\n");
+}
+
+/** Desce os títulos `n` níveis (fora das cercas de código). */
+function rebaixar(texto, n) {
+  let cerca = false;
+  return texto.split("\n").map((l) => {
+    if (l.trimStart().startsWith("```")) cerca = !cerca;
+    return !cerca && /^#{1,5} /.test(l) ? "#".repeat(n) + l : l;
+  }).join("\n");
+}
+
+/** Tira o H1 do corpo; devolve o título e o resto. */
+function semH1(corpo) {
+  const m = corpo.match(/^\s*# (.+)\n/);
+  return m ? { titulo: m[1].trim(), resto: corpo.slice(m[0].length).replace(/^\n+/, "") } : { titulo: "", resto: corpo.replace(/^\n+/, "") };
+}
+
+/** Link de um id: o arquivo do passo, ou a seção do fluxo no SKILL.md. */
+const destinoId = (base, r) => (r.passo ? `${base}/${r.fl.skill}/references/${r.fl.fluxo}/${r.passo.id}.md` : `${base}/${r.fl.skill}/SKILL.md#${slug(`Fluxo ${r.fl.fluxo}`)}`);
+
+const cel = (t) => String(t).replace(/\|/g, "\\|").replace(/\n/g, " ");
+const italico = (resumo) => (resumo ? `_${resumo}_\n\n` : "");
+
+const NO_PROJETO = `## No projeto
+
+Antes de ler o arquivo de um passo (\`…/skills/<skill>/references/<fluxo>/<passo>.md\`, de qualquer skill), tente abrir
+direto \`.sabia/fluxo/<skill>/<fluxo>/passos/<passo>.md\` na raiz do projeto: se existir, vale ele; senão, o da skill.
+O mesmo para um padrão: \`.sabia/padrao/<skill>/<nome>.md\` no lugar de \`…/references/padrao/<nome>.md\`. Abra pelo
+caminho; não liste a pasta (a busca não vê pastas ocultas). Com agente do Sabiá, o prompt lista também os passos inseridos
+e removidos nos fluxos de que ele é dono.
+`;
+
+/** O SKILL.md compilado de uma skill de fluxo. */
+function skillMd(m, s, fmYaml, h1, ctx) {
+  const { base } = ctx;
+  const fls = fluxosDa(m, s);
+  const out = [fmYaml.trimEnd(), "", h1, ""];
+  if (m.regras[s]) out.push("## Regras", "", rebaixar(reescrever(semH1(m.regras[s].corpo).resto, m.regras[s].arq, ctx), 1).trimEnd(), "");
+  if (fls.length > 1) {
+    out.push("## Fluxos", "", "| Fluxo | Quando |", "|---|---|");
+    for (const fl of fls) out.push(`| [${fl.fluxo}](#${slug(`Fluxo ${fl.fluxo}`)}) | ${cel([].concat(fl.d.quando || []).join("; "))} |`);
+    out.push("");
+  }
+  const usadas = new Set();
+  for (const fl of fls) {
+    const { titulo, resto } = semH1(fl.corpo);
+    out.push(`## Fluxo ${fl.fluxo}`, "");
+    if (titulo) out.push(`**${titulo}**`, "");
+    out.push(`Agente: \`${fl.d.dono}\`. Sem ele, sugira à pessoa usá-lo; seguindo aqui, os passos inseridos pelo projeto e os`,
+      "desvios de toolkit (⇢) não entram.", "");
+    if (resto.trim()) out.push(rebaixar(reescrever(resto, fl.arq, ctx), 1).trimEnd(), "");
+    out.push("| # | Passo | Arquivo | Chama | Travas | Saídas |", "|---|---|---|---|---|---|");
+    (fl.d.travas_gerais || []).forEach((t) => usadas.add(t));
+    fl.passos.forEach((x, i) => {
+      (x.travas || []).forEach((t) => usadas.add(t));
+      const arq = `${base}/${s}/references/${fl.fluxo}/${x.id}.md`;
+      const chama = [].concat(x.chama || []).map((c) => {
+        const r = resolverId(m, c);
+        const modo = modoChamada(m, fl.d.dono, r.fl);
+        const alvo = destinoId(base, r);
+        return `[\`${c}\`](${alvo}) (${modo === "subagente" ? `${r.fl.d.dono}, subagente` : "em linha"})`;
+      }).join("<br>") || "—";
+      const saidas = Object.entries(x.saidas || {}).map(([cond, dest]) => {
+        if (dest === "fim") return `${cond} → fim`;
+        if (!dest.startsWith("→ ")) return `${cond} → \`${dest}\``;
+        const q = dest.slice(2).trim();
+        const r = resolverId(m, q);
+        const alvo = destinoId(base, r);
+        return `${cond} → passa a [\`${q}\`](${alvo})`;
+      }).join("<br>") || "—";
+      out.push(`| ${i + 1} | \`${x.id}\`${x.desvio ? " ⇢" : ""} | [${x.id}.md](${arq}) | ${cel(chama)} | ${cel((x.travas || []).join(", ") || "—")} | ${cel(saidas)} |`);
+    });
+    out.push("", "Ao começar um passo, leia o arquivo dele (não os dos outros passos) e o que ele mandar ler. Sem Saídas, segue para o",
+      `próximo da lista. Travas do fluxo: ${(fl.d.travas_gerais || []).map((t) => `\`${t}\``).join(", ") || "—"}.`, "");
+  }
+  const ordem = Object.keys(m.travas).filter((t) => usadas.has(t));
+  if (ordem.length) out.push("## Travas", "", "Valem sobre o corpo de qualquer passo.", "", ...ordem.map((t) => `- **${t}** — ${m.travas[t].texto}`), "");
+  const padroes = m.padroes[s] || [];
+  const refs = mds(path.join(m.fw, "skills", s, "references"));
+  if (padroes.length || refs.length) {
+    out.push("## Arquivos", "");
+    for (const p of padroes) out.push(`- padrão [\`${s}/${p.nome}\`](${base}/${s}/references/padrao/${p.nome})${p.dados?.resumo ? ` — ${p.dados.resumo}` : ""}`);
+    for (const r of refs) out.push(`- [\`references/${r}\`](${base}/${s}/references/${r})`);
+    out.push("");
+  }
+  out.push(NO_PROJETO);
+  return out.join("\n");
+}
+
+const comVersao = (fmYaml, versao) => (versao ? fmYaml.replace(/^(\s+version:\s*)"[^"]*"/m, `$1"${versao}"`) : fmYaml);
+
+function copiarArvore(origem, destino, transformar) {
+  fs.mkdirSync(destino, { recursive: true });
+  for (const n of fs.readdirSync(origem)) {
+    if (n === "__pycache__" || n === ".DS_Store") continue;
+    const o = path.join(origem, n), d = path.join(destino, n);
+    if (fs.statSync(o).isDirectory()) copiarArvore(o, d, transformar);
+    else if (n.endsWith(".md")) fs.writeFileSync(d, transformar(ler(o), o));
+    else fs.copyFileSync(o, d);
+  }
+}
+
+/** Confere a saída: todo link para `base` resolve num arquivo do staging (e a âncora existe); nada do layout da fonte sobra. */
+function conferirSaida(staging, base) {
+  const erros = [];
+  const raiz = path.join(staging, "skills");
+  const cache = {};
+  const andar = (dir) => fs.readdirSync(dir).flatMap((n) => (fs.statSync(path.join(dir, n)).isDirectory() ? andar(path.join(dir, n)) : n.endsWith(".md") ? [path.join(dir, n)] : []));
+  for (const f of andar(raiz)) {
+    const t = ler(f);
+    const rel = path.relative(staging, f);
+    t.split("\n").forEach((l, i) => {
+      if (/~\/\.sabia\/(framework\/(skills|fluxo|padrao)|fluxo|padrao)\//.test(l)) erros.push(`${rel}:${i + 1}: caminho da fonte na saída`);
+      for (const [, alvo] of l.matchAll(LINK)) {
+        if (!alvo.startsWith(base + "/")) continue;
+        const [cam, anc] = alvo.slice(base.length + 1).split("#");
+        const arq = path.join(raiz, cam);
+        if (!fs.existsSync(arq)) { erros.push(`${rel}:${i + 1}: link para ${cam} inexistente`); continue; }
+        if (anc && !(cache[arq] ||= ancoras(ler(arq))).has(anc)) erros.push(`${rel}:${i + 1}: âncora #${anc} não existe em ${cam}`);
+      }
+    });
+  }
+  return erros;
+}
+
+/**
+ * Compila o framework `fw` no `staging` (recriado do zero): staging/skills/<s>/… e, com `raiz`, plugin.json, mcp.json,
+ * README.md e LICENSE (o power do Kiro). `base` é o caminho absoluto com ~ onde as skills ficam no alvo.
+ */
+export function compilar(fw, staging, { base, raiz = false, versao = null } = {}) {
+  const m = carregar(fw);
+  const erros = validar(m);
+  if (erros.length) throw new Error(`a fonte do Sabiá tem ${erros.length} erro(s):\n${erros.slice(0, 40).join("\n")}`);
+  fs.rmSync(staging, { recursive: true, force: true });
+  const ctx = { fw, base, m };
+  const comFluxo = new Set(Object.values(m.fluxos).map((f) => f.skill));
+  for (const s of skillsDe(fw)) {
+    const dir = path.join(fw, "skills", s), out = path.join(staging, "skills", s);
+    copiarArvore(dir, out, (t, o) => reescrever(t, o, ctx));
+    const fonte = ler(path.join(dir, "SKILL.md"));
+    const fmYaml = (fonte.match(FM) || [""])[0];
+    if (comFluxo.has(s)) {
+      const h1 = (fonte.slice(fmYaml.length).match(/^# .+$/m) || [`# ${s}`])[0];
+      fs.writeFileSync(path.join(out, "SKILL.md"), skillMd(m, s, comVersao(fmYaml, versao), h1, ctx));
+      for (const fl of fluxosDa(m, s))
+        for (const x of fl.passos) {
+          fs.mkdirSync(path.join(out, "references", fl.fluxo), { recursive: true });
+          fs.writeFileSync(path.join(out, "references", fl.fluxo, `${x.id}.md`), italico(x.dados.resumo) + reescrever(x.corpo, x.arq, ctx).replace(/^\n+/, ""));
+        }
+    } else if (fmYaml) {
+      fs.writeFileSync(path.join(out, "SKILL.md"), comVersao(fmYaml, versao) + reescrever(fonte.slice(fmYaml.length), path.join(dir, "SKILL.md"), ctx));
+    }
+    for (const p of m.padroes[s] || []) {
+      fs.mkdirSync(path.join(out, "references", "padrao"), { recursive: true });
+      fs.writeFileSync(path.join(out, "references", "padrao", p.nome), italico(p.dados?.resumo) + reescrever(p.corpo, p.arq, ctx).replace(/^\n+/, ""));
+    }
+  }
+  if (raiz) for (const f of ["plugin.json", "mcp.json", "README.md", "LICENSE"]) if (fs.existsSync(path.join(fw, f))) fs.copyFileSync(path.join(fw, f), path.join(staging, f));
+  const ruins = conferirSaida(staging, base);
+  if (ruins.length) throw new Error(`a skill compilada tem ${ruins.length} erro(s):\n${ruins.slice(0, 40).join("\n")}`);
+  return staging;
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "sabia",
-  "version": "1.1.3",
-  "description": "Instala, atualiza e desinstala o Sabiá e os toolkits dele no Kiro, no Claude Code e no opencode, com um inventário em ~/.sabia/.",
+  "version": "2.0.0-alpha.1",
+  "description": "Instala, atualiza e desinstala o Sabiá e os toolkits dele no Kiro e no opencode, com um inventário em ~/.sabia/, e explica a rota dos fluxos (sabia rota).",
   "type": "module",
   "bin": {
     "sabia": "sabia.mjs"
   },
   "files": [
-    "sabia.mjs"
+    "sabia.mjs",
+    "compilar.mjs"
   ],
   "engines": {
     "node": ">=18"
@@ -25,7 +26,6 @@
   "keywords": [
     "sabia",
     "kiro",
-    "claude-code",
     "opencode",
     "skills",
     "agentes"

package/sabia.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Sabiá CLI — instala, atualiza e desinstala o Sabiá e os toolkits no Kiro, no Claude Code e no opencode.
+// Sabiá CLI — instala, atualiza e desinstala o Sabiá e os toolkits no Kiro e no opencode, e explica a rota (`sabia rota`).
 // ~/.sabia/ é a fonte (framework/ e toolkits/), cada ferramenta recebe uma cópia no padrão dela, e o
 // ~/.sabia/inventario.json registra cada cópia (com o hash de cada arquivo) e cada MCP: atualizar e desinstalar
 // mexem só no que está lá. Só a biblioteca padrão do Node 18+.
@@ -10,11 +10,12 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { carregar, compilar, partes } from "./compilar.mjs";
 
 const VERSAO = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
 const REPO = "https://github.com/dxaraujo/sabia.git";
 const INDICE = "https://github.com/dxaraujo/sabia-toolkits.git";
-const ALVOS = ["kiro", "claude", "opencode"];
+const ALVOS = ["kiro", "opencode"];
 const NOME = [
   "                               ▄▄▀",
   "███████╗ █████╗ ██████╗ ██╗ █████╗",
@@ -105,7 +106,6 @@ export const curto = (p) => (p.startsWith(home() + path.sep) ? "~/" + path.relat
 export const longo = (p) => (p.startsWith("~/") ? path.join(home(), ...p.slice(2).split("/")) : p);
 
 export const PASTA_SKILLS = {
-  claude: () => path.join(home(), ".claude", "skills"),
   opencode: () => path.join(home(), ".config", "opencode", "skills"),
 };
 
@@ -228,7 +228,7 @@ function temComando(cmd) {
 }
 
 export function detectarAlvos() {
-  return ALVOS.filter((a) => temComando({ kiro: "kiro-cli", claude: "claude", opencode: "opencode" }[a]));
+  return ALVOS.filter((a) => temComando({ kiro: "kiro-cli", opencode: "opencode" }[a]));
 }
 
 async function escolherAlvos(opcoes) {
@@ -276,28 +276,29 @@ function tirarMcpDoOpencode(nome) {
   }
 }
 
-async function registrarMcps(alvo, fw, reg) {
+/** Os MCPs do framework no opencode (no Kiro, vão no mcp.json do power). */
+async function registrarMcps(fw, reg) {
   reg.mcp ||= [];
-  const ja = alvo === "opencode" ? mcpsDoOpencode() : [];
+  const ja = mcpsDoOpencode();
   for (const [nome, s] of Object.entries(servidoresMcp(fw))) {
+    if (ja.includes(nome)) { ctx.log(`MCP ${nome} já existe no opencode — mantido`); continue; }
     const env = Object.entries(s.env || {}).map(([k, v]) => `${k}=${v}`);
-    let r;
-    if (alvo === "claude") {
-      if (ctx.exec("claude", ["mcp", "get", nome]).status === 0) { ctx.log(`MCP ${nome} já existe no Claude Code — mantido`); continue; }
-      // o nome vem antes do -e, que aceita vários valores e engoliria o nome
-      r = ctx.exec("claude", ["mcp", "add", "--scope", "user", nome, ...env.flatMap((e) => ["-e", e]), "--", s.command, ...s.args]);
-    } else {
-      if (ja.includes(nome)) { ctx.log(`MCP ${nome} já existe no opencode — mantido`); continue; }
-      r = ctx.exec("opencode", ["mcp", "add", "--global", ...env.flatMap((e) => ["--env", e]), nome, "--", s.command, ...s.args]);
-    }
-    if (r.status !== 0) throw new Error(`MCP ${nome} no ${alvo}: ${(r.stderr || r.error?.message || "").trim()}`);
+    const r = ctx.exec("opencode", ["mcp", "add", "--global", ...env.flatMap((e) => ["--env", e]), nome, "--", s.command, ...s.args]);
+    if (r.status !== 0) throw new Error(`MCP ${nome} no opencode: ${(r.stderr || r.error?.message || "").trim()}`);
     if (!reg.mcp.includes(nome)) reg.mcp.push(nome);
-    ctx.log(`MCP ${nome} registrado no ${alvo}`);
+    ctx.log(`MCP ${nome} registrado no opencode`);
   }
 }
 
+/** Compila o framework para o alvo em ~/.sabia/compilado/<alvo>/ (seção 11 do plano da 2.0). */
+function compilarPara(alvo, fw) {
+  const versao = JSON.parse(fs.readFileSync(path.join(fw, "plugin.json"), "utf8")).version;
+  const base = alvo === "kiro" ? "~/.kiro/powers/installed/sabia/skills" : curto(PASTA_SKILLS[alvo]());
+  return compilar(fw, sabia("compilado", alvo), { base, raiz: alvo === "kiro", versao });
+}
+
 async function instalarAlvo(alvo, inv, opcoes) {
-  const fw = sabia("framework");
+  const fw = compilarPara(alvo, sabia("framework"));
   if (alvo === "kiro") {
     const nosso = inv.alvos.kiro?.power;
     // o painel Powers instala em ~/.kiro/powers/installed/sabia: fora do inventário, é de outra instalação
@@ -314,11 +315,9 @@ async function instalarAlvo(alvo, inv, opcoes) {
   }
   const reg = (inv.alvos[alvo] ||= { copias: {}, mcp: [] });
   for (const s of skillsDoFluxo(fw)) await copiar(path.join(fw, "skills", s), path.join(PASTA_SKILLS[alvo](), s), reg.copias, opcoes);
-  if (!opcoes.semMcp) await registrarMcps(alvo, fw, reg);
-  if (alvo === "opencode") {
-    const velhas = fs.existsSync(PASTA_SKILLS.opencode()) ? fs.readdirSync(PASTA_SKILLS.opencode()).filter((d) => /^sdd/.test(d)) : [];
-    if (velhas.length) ctx.log(`aviso: skills antigas no opencode concorrem com as sa-*: ${velhas.join(", ")} (remova se não usa mais)`);
-  }
+  if (!opcoes.semMcp) await registrarMcps(sabia("framework"), reg);
+  const velhas = (fs.existsSync(PASTA_SKILLS.opencode()) ? fs.readdirSync(PASTA_SKILLS.opencode()) : []).filter((d) => /^sdd/.test(d));
+  if (velhas.length) ctx.log(`aviso: skills antigas no opencode concorrem com as sa-*: ${velhas.join(", ")} (remova se não usa mais)`);
 }
 
 /** Baixa o framework para uma pasta temporária e diz o que muda em relação a ~/.sabia/framework/. */
@@ -353,7 +352,7 @@ export async function instalar(opcoes = {}) {
   fs.rmSync(sabia("framework"), { recursive: true, force: true });
   fs.mkdirSync(sabia(), { recursive: true });
   fs.cpSync(novo.pasta, sabia("framework"), { recursive: true });
-  inv.framework = { versao: novo.versao, sha: novo.sha, fonte: novo.fonte, instalado_em: new Date().toISOString() };
+  inv.framework = { versao: novo.versao, sha: novo.sha, fonte: novo.fonte, compilador: VERSAO, instalado_em: new Date().toISOString() };
   ctx.log(`Sabiá ${novo.versao} em ~/.sabia/framework`);
   try {
     for (const alvo of await escolherAlvos(opcoes)) await instalarAlvo(alvo, inv, opcoes);
@@ -369,13 +368,18 @@ export async function atualizar(opcoes = {}) {
   if (!inv.framework) throw new Error("o Sabiá não está instalado: rode `sabia instalar`");
   const novo = baixarFramework({ fonte: inv.framework.fonte === REPO ? undefined : inv.framework.fonte, ...opcoes });
   ctx.log(`Sabiá ${inv.framework.versao} → ${novo.versao}`);
-  if (!mostrarDiferencas(diferencas(sabia("framework"), novo.pasta))) return ctx.log("nada mudou");
+  // o compilador também conta: a mesma fonte compilada por outro CLI pode dar outra skill
+  const compilador = inv.framework.compilador === VERSAO ? null : `compilador ${inv.framework.compilador || "—"} → ${VERSAO}`;
+  if (!mostrarDiferencas(diferencas(sabia("framework"), novo.pasta)) && !compilador) return ctx.log("nada mudou");
+  if (compilador) ctx.log(`  ${compilador}`);
   if (!/^s/i.test(await ctx.perguntar("Atualizar? [s/N]", "n"))) return ctx.log("nada foi alterado");
   fs.rmSync(sabia("framework"), { recursive: true, force: true });
   fs.cpSync(novo.pasta, sabia("framework"), { recursive: true });
-  inv.framework = { ...inv.framework, versao: novo.versao, sha: novo.sha, instalado_em: new Date().toISOString() };
+  inv.framework = { ...inv.framework, versao: novo.versao, sha: novo.sha, compilador: VERSAO, instalado_em: new Date().toISOString() };
   try {
     for (const alvo of Object.keys(inv.alvos)) {
+      // alvo que saiu do Sabiá (o claude, na 2.0): fica como está; `sabia desinstalar --alvo <ele>` apaga as cópias
+      if (!ALVOS.includes(alvo)) { ctx.log(`${alvo}: não é mais alvo do Sabiá (${ALVOS.join(", ")}) — ignorado; tire com sabia desinstalar --alvo ${alvo}`); continue; }
       if (alvo !== "kiro") {  // skill que saiu do framework sai da ferramenta
         const copias = inv.alvos[alvo].copias;
         const fica = new Set(skillsDoFluxo(sabia("framework")).map((s) => curto(path.join(PASTA_SKILLS[alvo](), s))));
@@ -401,16 +405,15 @@ export async function desinstalar(opcoes = {}) {
       for (const tk of Object.values(inv.toolkits)) if (tk.alvos?.[alvo]) { await apagar(tk.alvos[alvo].copias, opcoes); delete tk.alvos[alvo]; }
       if (alvo === "kiro") ctx.exec("kiro-cli", ["powers", "uninstall", reg.power]);
       else await apagar(reg.copias, opcoes);
-      for (const nome of reg.mcp || []) {
-        if (alvo === "claude") ctx.exec("claude", ["mcp", "remove", "--scope", "user", nome]);
-        else tirarMcpDoOpencode(nome);
-      }
+      if (alvo === "opencode") for (const nome of reg.mcp || []) tirarMcpDoOpencode(nome);
+      else if (reg.mcp?.length) ctx.log(`${alvo}: os MCPs ${reg.mcp.join(", ")} ficam (o Sabiá não mexe mais no ${alvo}); tire à mão se não usa`);
       if (alvo !== "kiro" && Object.keys(reg.copias).length) continue;  // ficou cópia alterada à mão
       delete inv.alvos[alvo];
       ctx.log(`${alvo}: Sabiá desinstalado`);
     }
     if (!Object.keys(inv.alvos).length) {
       fs.rmSync(sabia("framework"), { recursive: true, force: true });
+      fs.rmSync(sabia("compilado"), { recursive: true, force: true });
       inv.framework = null;
     }
   } finally {
@@ -421,7 +424,7 @@ export async function desinstalar(opcoes = {}) {
 // ---------- toolkits ----------
 
 /** Erros do toolkit.json: campos, nome, caminhos presos à pasta e arquivos que existem (o schema completo é o da setup). */
-export function validarToolkit(pasta, nomeEsperado = null) {
+export function validarToolkit(pasta, nomeEsperado = null, fw = null) {
   const f = path.join(pasta, "toolkit.json");
   if (!fs.existsSync(f)) return ["falta o toolkit.json"];
   let m;
@@ -440,9 +443,17 @@ export function validarToolkit(pasta, nomeEsperado = null) {
     try { if (!fs.existsSync(path.join(pasta, dentro(c, de)))) erros.push(`${de}: não existe ${c}`); } catch (e) { erros.push(e.message); }
   };
   const agentes = new Set((m.agentes || []).map((a) => a.nome));
+  // sem o framework (toolkits baixar antes do instalar), o gancho é conferido na setup
+  const ganchos = fw && fs.existsSync(path.join(fw, "fluxo")) ? carregar(fw) : null;
   for (const s of m.skills || []) {
     existe(s.caminho, "skills");
     if (s.passo?.agente && !agentes.has(s.passo.agente)) erros.push(`passo de ${s.caminho}: agente ${s.passo.agente} não está em agentes`);
+    if (s.passo?.passo && ganchos) {
+      const [sk, fl, id] = s.passo.passo.split(".");
+      const x = ganchos.fluxos[`${sk}.${fl}`]?.passos.find((p) => p.id === id);
+      if (!x) erros.push(`passo de ${s.caminho}: ${s.passo.passo} não existe no Sabiá instalado`);
+      else if (!x.desvio) erros.push(`passo de ${s.caminho}: ${s.passo.passo} não aceita desvio de toolkit`);
+    }
   }
   for (const s of m.steering || []) existe(s.caminho, "steering");
   for (const a of m.agentes || []) {
@@ -488,7 +499,7 @@ export async function baixarToolkit(alvo, opcoes = {}) {
   const [nomeOuUrl, versaoOuRef] = separarRef(alvo);
   const e = ehUrl ? { nome: null, url: nomeOuUrl, ref: versaoOuRef } : acharNoIndice(nomeOuUrl, versaoOuRef, opcoes);
   const { pasta, sha } = baixar(e.url, e);
-  const erros = validarToolkit(pasta, e.nome);
+  const erros = validarToolkit(pasta, e.nome, sabia("framework"));
   if (erros.length) throw new Error(`toolkit recusado:\n- ${erros.join("\n- ")}`);
   const m = JSON.parse(fs.readFileSync(path.join(pasta, "toolkit.json"), "utf8"));
   const destino = sabia("toolkits", m.nome);
@@ -524,7 +535,8 @@ export async function instalarToolkit(alvo, opcoes = {}) {
   // mesmos nomes de skill e de agente: as duas no usuário se sobrescreveriam
   if (rival) throw new Error(`${baixado} e ${rival} são versões do mesmo toolkit (base ${familia}); instale um só: sabia toolkits remover ${rival}`);
   const tk = (inv.toolkits[baixado] ||= { versao: m.versao, alvos: {} });
-  const alvos = opcoes.alvo ? opcoes.alvo.split(",") : Object.keys(inv.alvos).length ? Object.keys(inv.alvos) : await escolherAlvos(opcoes);
+  const doInv = Object.keys(inv.alvos).filter((a) => ALVOS.includes(a));
+  const alvos = opcoes.alvo || !doInv.length ? await escolherAlvos(opcoes) : doInv;
   try {
     for (const a of alvos.filter((x) => x !== "kiro")) {
       const reg = (tk.alvos[a] ||= { copias: {} });
@@ -570,7 +582,7 @@ export async function atualizarToolkits(nome, opcoes = {}) {
     const origem = JSON.parse(fs.readFileSync(sabia("toolkits", n, ".origem.json"), "utf8"));
     const alvo = origem.indice ? n : `${origem.url}${origem.ref ? "@" + origem.ref : ""}`;
     await instalarToolkit(alvo, { ...opcoes, atualizar: true, indice: origem.indice || opcoes.indice,
-      alvo: Object.keys(inv.toolkits[n]?.alvos || {}).join(",") || "kiro" });
+      alvo: Object.keys(inv.toolkits[n]?.alvos || {}).filter((a) => ALVOS.includes(a)).join(",") || "kiro" });
   }
 }
 
@@ -618,13 +630,178 @@ export function listarToolkits(opcoes = {}) {
   return linhas;
 }
 
+// ---------- rota (diagnóstico, para pessoas) ----------
+
+// toolkit 1.x (passo.papel, e "codificador" antes do renome): o mesmo mapa do gerar_agentes.py
+const GANCHO_1X = { desenvolvedor: "sa-codificar.codificar.tarefa", codificador: "sa-codificar.codificar.tarefa", especificador: "sa-prd.prd.escrever" };
+const lerJson = (f, padrao) => (fs.existsSync(f) ? JSON.parse(fs.readFileSync(f, "utf8")) : padrao);
+const lerFm = (f) => (fs.existsSync(f) ? partes(fs.readFileSync(f, "utf8")).dados || {} : null);
+
+/** Glob do `passo.arquivos`: `**` atravessa `/`; `*` e `?` não. */
+export function casaGlob(glob, arquivo) {
+  const rx = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\/|\*\*|\*|\?/g, (t) => ({ "**/": "(?:.*/)?", "**": ".*", "*": "[^/]*", "?": "[^/]" })[t]);
+  return new RegExp(`^${rx}$`).test(arquivo);
+}
+
+/** Colunas alinhadas; a última sem preenchimento. */
+const colunas = (linhas) => {
+  const w = [];
+  for (const l of linhas) l.slice(0, -1).forEach((c, i) => { w[i] = Math.max(w[i] || 0, c.length); });
+  return linhas.map((l) => l.map((c, i) => (i < l.length - 1 ? c.padEnd(w[i]) : c)).join("  ").trimEnd()).join("\n");
+};
+
+/** Framework instalado (ou --framework), projeto (ou --projeto) e os desvios ligados nele, como o gerador os resolve. */
+function contextoRota(opcoes) {
+  const fw = path.resolve(opcoes.framework || sabia("framework"));
+  if (!fs.existsSync(path.join(fw, "fluxo"))) throw new Error(`${curto(fw)} não tem fluxo/: rode \`sabia instalar\` ou passe --framework`);
+  const projeto = path.resolve(opcoes.projeto || process.cwd());
+  const cfg = lerJson(path.join(projeto, ".sabia", "config", "agentes.json"), {});
+  const m = carregar(fw);
+  const desvios = (cfg.passos || []).flatMap((e) => {
+    const pasta = cfg.toolkits?.[e.toolkit]?.pasta;
+    const dir = !pasta ? sabia("toolkits", e.toolkit) : pasta.startsWith("~/") ? longo(pasta) : path.resolve(projeto, pasta);
+    const man = lerJson(path.join(dir, "toolkit.json"), null);
+    const ext = man?.skills?.find((x) => x.caminho === e.skill && x.passo)?.passo;
+    if (!ext) { ctx.log(`aviso: toolkit ${e.toolkit} sem passo em ${e.skill} (${curto(dir)})`); return []; }
+    // como o gancho() do gerador: só passo do framework com "desvio": true (senão o gerador recusa e o prompt não o tem)
+    const passo = ext.passo || GANCHO_1X[ext.papel], [sk, f, p] = (passo || "").split(".");
+    if (!m.fluxos[`${sk}.${f}`]?.passos.find((x) => x.id === p)?.desvio) {
+      ctx.log(`aviso: toolkit ${e.toolkit}: ${passo ? `o passo ${passo}` : `o papel ${ext.papel}`} não aceita desvio de toolkit (o gerador recusa) — ignorado`);
+      return [];
+    }
+    const agente = e.agente && ext.agente ? ext.agente : null;
+    const skills = agente ? (man.agentes || []).find((a) => a.nome === agente)?.skills || [] : [e.skill];
+    return [{ toolkit: e.toolkit, versao: man.versao, passo, para: ext.para, arquivos: ext.arquivos || [],
+      agente, skill: path.basename(path.dirname(e.skill)), skills: skills.map((x) => path.basename(path.dirname(x))) }];
+  });
+  return { fw, projeto, m, versao: lerJson(path.join(fw, "plugin.json"), {}).version || "?", desvios };
+}
+
+/** Os passos do fluxo `q` na ordem, com o que o projeto mudou: origem sabia | projeto (corpo trocado) | inserido | removido. */
+function resolverFluxo(c, q) {
+  const fl = c.m.fluxos[q.replace("/", ".")];
+  if (!fl) throw new Error(`fluxo ${q} não existe em ${curto(c.fw)} (use skill.fluxo, ex.: sa-codificar.codificar)`);
+  const dir = path.join(c.projeto, ".sabia", "fluxo", fl.skill, fl.fluxo);
+  const ops = lerFm(path.join(dir, `${fl.fluxo}.md`)) || {};
+  const doProjeto = (id) => path.join(dir, "passos", `${id}.md`);
+  const passos = fl.passos.map((x) => {
+    const base = lerFm(doProjeto(x.id));
+    const origem = (ops.remover || []).includes(x.id) ? "removido" : base ? "projeto" : "sabia";
+    return { ...x, origem, base: base?.base, arq: base ? doProjeto(x.id) : x.arq };
+  });
+  let falta = [...(ops.inserir || [])];
+  while (falta.length) {  // em qualquer ordem, inclusive depois de outro inserido
+    const prontos = falta.filter((o) => passos.some((x) => x.id === o.depois));
+    if (!prontos.length) { ctx.log(`aviso: ${q}: inserir ${falta.map((o) => `${o.id} depois de ${o.depois}`).join(", ")}: o 'depois' não existe`); break; }
+    for (const o of prontos) {
+      let i = passos.findIndex((x) => x.id === o.depois);
+      while (passos[i + 1]?.depois === o.depois) i++;
+      passos.splice(i + 1, 0, { id: o.id, depois: o.depois, origem: "inserido", arq: doProjeto(o.id) });
+    }
+    falta = falta.filter((o) => !prontos.includes(o));
+  }
+  return { fl, q: `${fl.skill}.${fl.fluxo}`, passos };
+}
+
+const travasDe = (fl, x) => [...new Set([...(fl.d.travas_gerais || []), ...(x?.travas || [])])].join(", ") || "—";
+
+/** `sabia rota <arquivo>`: o passo com gancho cujo desvio casa com o arquivo, o dono, o toolkit, o motivo e as travas. */
+export function rota(arquivo, opcoes = {}) {
+  const c = contextoRota(opcoes);
+  let rel = path.relative(c.projeto, path.resolve(arquivo));
+  if (rel.startsWith("..")) rel = arquivo;  // fora do projeto: o caminho como veio
+  rel = rel.split(path.sep).join("/");
+  const ganchos = Object.entries(c.m.fluxos).flatMap(([q, fl]) => fl.passos.filter((x) => x.desvio).map((x) => `${q}.${x.id}`));
+  let casou = null;
+  for (const d of c.desvios) { const g = d.arquivos.find((a) => casaGlob(a, rel)); if (g) { casou = { d, g }; break; } }
+  // sem casar: o passo dos desvios por arquivo do projeto (o de código), senão o primeiro gancho do framework
+  const pid = casou?.d.passo || c.desvios.find((d) => d.arquivos.length)?.passo || ganchos[0];
+  if (!pid) throw new Error(`${curto(c.fw)} não tem passo com desvio de toolkit`);
+  const { fl, passos } = resolverFluxo(c, pid.split(".").slice(0, 2).join("."));
+  const x = passos.find((y) => y.id === pid.split(".")[2]);
+  if (!x) throw new Error(`o desvio aponta para ${pid}, que não é passo do Sabiá instalado`);
+  const agentes = [`.opencode/agents/${fl.d.dono}.md`, `.kiro/agents/${fl.d.dono}.json`].filter((f) => fs.existsSync(path.join(c.projeto, f)));
+  const linhas = [
+    ["passo", pid, x.origem === "projeto" ? `${path.relative(c.projeto, x.arq)} (projeto)` : `${curto(x.arq)} (Sabiá ${c.versao})`],
+    ["dono", fl.d.dono, agentes.join(", ") || "agente não gerado neste projeto"],
+  ];
+  if (casou) linhas.push(["desvio", casou.d.agente || `skill ${casou.d.skill}`, `toolkit ${casou.d.toolkit} ${casou.d.versao}`],
+    ["motivo", `casou ${casou.g}`], ["skills", [fl.skill, ...casou.d.skills].join(", ")]);
+  else {
+    linhas.push(["desvio", "— fluxo padrão", "nenhum padrão casou"]);
+    for (const d of c.desvios.filter((y) => y.passo === pid)) linhas.push(["pelo texto", `"${d.para}" → ${d.agente || `skill ${d.skill}`}`, "o modelo decide pela tarefa"]);
+  }
+  linhas.push(["travas", travasDe(fl, x)]);
+  return colunas(linhas);
+}
+
+const sid = (t) => t.replace(/[^A-Za-z0-9_]/g, "_");
+const rotulo = (t) => t.replace(/[;:]/g, ",").replace(/[`"#]/g, "");
+
+/** `sabia rota --fluxo <skill.fluxo>`: a tabela resolvida (com o que o projeto mudou) e o diagrama de estados. */
+export function rotaFluxo(q, opcoes = {}) {
+  const c = contextoRota(opcoes);
+  const r = resolverFluxo(c, q), { fl } = r;
+  const desvios = c.desvios.filter((d) => d.passo?.startsWith(`${r.q}.`));
+  const origem = (x) => ({ sabia: "Sabiá", projeto: `projeto${x.base ? ` (base ${x.base})` : ""}`,
+    inserido: `projeto, inserido depois de ${x.depois}`, removido: "removido no projeto" })[x.origem];
+  let n = 0;
+  const tabela = [["#", "passo", "origem", "chama", "travas", "saídas"], ...r.passos.map((x) => [
+    x.origem === "removido" ? "-" : String(++n), x.id + (x.desvio ? " ⇢" : ""), origem(x), [].concat(x.chama || []).join(", ") || "—",
+    (x.travas || []).join(", ") || "—", Object.entries(x.saidas || {}).map(([k, v]) => `${k} → ${v.replace(/^→ /, "passa a ")}`).join("; ") || "—"])];
+  const cab = [["fluxo", r.q, `dono ${fl.d.dono}`, `Sabiá ${c.versao}`], ["travas", (fl.d.travas_gerais || []).join(", ") || "—"],
+    ...desvios.map((d) => ["desvio ⇢", `${d.passo.split(".")[2]}: ${d.arquivos.join(", ") || `"${d.para}"`}`, `→ ${d.agente || `skill ${d.skill}`}`, `toolkit ${d.toolkit} ${d.versao}`])];
+
+  const out = ["stateDiagram-v2"], declarados = new Set();
+  const estado = (id, nome = id) => {
+    const s = sid(id);
+    if (s !== nome && !declarados.has(s)) { declarados.add(s); out.push(`  state "${nome}" as ${s}`); }
+    return s;
+  };
+  const ativos = r.passos.filter((x) => x.origem !== "removido");
+  ativos.forEach((x, i) => {
+    const a = estado(x.id), prox = ativos[i + 1];
+    if (!i) out.push(`  [*] --> ${a}`);
+    for (const [cond, dest] of Object.entries(x.saidas || {})) {
+      if (dest === "fim") out.push(`  ${a} --> [*]: ${rotulo(cond)}`);
+      else if (dest.startsWith("→ ")) { const q2 = dest.slice(2).trim(); out.push(`  ${a} --> ${estado(`x_${q2}`, q2)}: ${rotulo(cond)} (passagem)`); }
+      else if (ativos.some((y) => y.id === dest)) out.push(`  ${a} --> ${estado(dest)}: ${rotulo(cond)}`);
+    }
+    out.push(prox ? `  ${a} --> ${estado(prox.id)}${prox.origem === "inserido" ? ": projeto (inserido)" : ""}` : `  ${a} --> [*]`);
+    const nota = [x.chama && `chama ${[].concat(x.chama).join(", ")}`, x.origem === "projeto" && `corpo do projeto${x.base ? ` (base ${x.base})` : ""}`,
+      x.desvio && desvios.length && `desvio ⇢ ${desvios.filter((d) => d.passo === `${r.q}.${x.id}`).map((d) => d.agente || d.skill).join(", ")}`].filter(Boolean);
+    if (nota.length) out.push(`  note right of ${a}: ${rotulo(nota.join(" · "))}`);
+  });
+  return [colunas(cab), "", colunas(tabela), "", "```mermaid", ...out, "```"].join("\n");
+}
+
+/** `sabia rota --mapa`: as arestas entre fluxos de todo o framework (chama e passagens), em Mermaid. */
+export function rotaMapa(opcoes = {}) {
+  const c = contextoRota(opcoes);
+  const out = ["flowchart LR"], nos = new Set(), vistas = new Set();
+  const no = (q) => { const s = sid(q); if (!nos.has(s)) { nos.add(s); out.push(`  ${s}["${q}"]`); } return s; };
+  for (const [q, fl] of Object.entries(c.m.fluxos))
+    for (const x of fl.passos) {
+      const arestas = [...[].concat(x.chama || []).map((d) => [d, "-->"]),
+        ...Object.values(x.saidas || {}).filter((d) => d.startsWith("→ ")).map((d) => [d.slice(2).trim(), "-.->"])];
+      for (const [d, seta] of arestas) {
+        const q2 = d.split(".").slice(0, 2).join(".");
+        if (vistas.has(`${q} ${seta} ${q2} ${x.id}`)) continue;
+        vistas.add(`${q} ${seta} ${q2} ${x.id}`);
+        out.push(`  ${no(q)} ${seta}|${x.id}| ${no(q2)}`);
+      }
+    }
+  return [`Fluxos do Sabiá ${c.versao}: --> chama (volta ao passo) · -.-> passagem (o fluxo termina e segue no outro); rótulo = passo de origem`,
+    "", "```mermaid", ...out, "```"].join("\n");
+}
+
 // ---------- linha de comando ----------
 
 const AJUDA = `${BANNER}
 
-sabia ${VERSAO} — instala o Sabiá e os toolkits no Kiro, no Claude Code e no opencode
+sabia ${VERSAO} — instala o Sabiá e os toolkits no Kiro e no opencode
 
-  sabia instalar   [--alvo kiro,claude,opencode] [--versao X] [--fonte <pasta|url-git>[@ref]]
+  sabia instalar   [--alvo kiro,opencode] [--versao X] [--fonte <pasta|url-git>[@ref]]
   sabia atualizar  [--versao X]
   sabia desinstalar [--alvo …]
   sabia toolkits listar   [--indice <url-git|pasta>]
@@ -632,6 +809,10 @@ sabia ${VERSAO} — instala o Sabiá e os toolkits no Kiro, no Claude Code e no
   sabia toolkits instalar <nome>[@versao] | <url-git>[@ref]  [--alvo …]   (sem argumento, no projeto: as versões dele)
   sabia toolkits atualizar [<nome>]
   sabia toolkits remover  <nome>
+  sabia rota <arquivo>               o passo com desvio de toolkit, o dono, o toolkit, o motivo e as travas
+  sabia rota --fluxo <skill.fluxo>   o fluxo resolvido no projeto (tabela e diagrama Mermaid)
+  sabia rota --mapa                  as arestas entre fluxos (chama e passagens), em Mermaid
+      [--projeto <pasta>] (padrão: a atual) [--framework <pasta>] (padrão: ~/.sabia/framework)
 
   --sim       responde "sim" às confirmações (cópia alterada à mão continua perguntando, salvo --forcar)
   --forcar    sobrescreve o que não foi instalado pelo Sabiá ou foi alterado à mão
@@ -646,14 +827,17 @@ export function lerArgs(argv) {
     const a = argv[i];
     if (!a.startsWith("--")) { posicionais.push(a); continue; }
     const chave = a.slice(2).replace(/-(\w)/g, (_, c) => c.toUpperCase());
-    if (["sim", "forcar", "semMcp", "ajuda", "help"].includes(chave)) opcoes[chave] = true;
+    if (["sim", "forcar", "semMcp", "mapa", "ajuda", "help"].includes(chave)) opcoes[chave] = true;
+    else if (argv[i + 1] === undefined || argv[i + 1].startsWith("--")) throw new Error(`--${a.slice(2)} precisa de um valor`);
     else opcoes[chave] = argv[++i];
   }
   return { posicionais, opcoes };
 }
 
 export async function main(argv = process.argv.slice(2)) {
-  const { posicionais: [cmd, sub, arg], opcoes } = lerArgs(argv);
+  let args;
+  try { args = lerArgs(argv); } catch (e) { console.error(`sabia: ${e.message}`); return 1; }
+  const { posicionais: [cmd, sub, arg], opcoes } = args;
   if (opcoes.sim) {  // cópia alterada à mão continua perguntando: só o --forcar passa por cima
     const antes = ctx.perguntar;
     ctx.perguntar = async (texto, padrao) => (/alterado à mão/.test(texto) ? antes(texto, padrao) : /\[s\/N\]/.test(texto) ? "s" : padrao);
@@ -667,6 +851,8 @@ export async function main(argv = process.argv.slice(2)) {
     else if (cmd === "toolkits" && sub === "instalar") await (arg ? instalarToolkit(arg, opcoes) : instalarDoProjeto(opcoes));
     else if (cmd === "toolkits" && sub === "atualizar") await atualizarToolkits(arg, opcoes);
     else if (cmd === "toolkits" && sub === "remover" && arg) await removerToolkit(arg, opcoes);
+    else if (cmd === "rota" && (sub || opcoes.fluxo || opcoes.mapa))
+      ctx.log(opcoes.mapa ? rotaMapa(opcoes) : opcoes.fluxo ? rotaFluxo(opcoes.fluxo, opcoes) : rota(sub, opcoes));
     else { ctx.log(AJUDA); return cmd && !opcoes.ajuda && !opcoes.help ? 1 : 0; }
     return 0;
   } catch (e) {