sabia 1.1.3 → 2.0.0-beta.1

package/compilar.mjs

@@ -0,0 +1,579 @@
+// Compilador as-built do Sabiá: fluxo/ + padrao/ + skills/ (a fonte, no framework) → skills comuns (SKILL.md +
+// references/) numa pasta de staging, uma por alvo.
+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])));
+
+export const VIZINHOS = "## Entrada: vizinhos";
+export const SPRINT = ["exige", "nao"];
+
+/** As linhas "- <estado> → <destino>" da seção Entrada: vizinhos do corpo do mestre (null sem a seção). */
+function vizinhos(corpo, pulo) {
+  const ls = corpo.split("\n"), i = ls.findIndex((l) => l.trim() === VIZINHOS);
+  if (i < 0) return null;
+  const out = [];
+  for (let j = i + 1; j < ls.length && !/^#{1,6} /.test(ls[j]); j++) {
+    if (!ls[j].trim()) continue;
+    const t = ls[j].trim(), k = t.lastIndexOf(" → ");
+    out.push({ n: pulo + j + 1, ...(t.startsWith("- ") && k > 2 ? { estado: t.slice(2, k), destino: t.slice(k + 3) } : {}) });
+  }
+  return out;
+}
+
+/** Lê a fonte inteira: fluxos, passos, regras, padrões, travas, tipos e papéis. */
+export function carregar(fw) {
+  const m = { fw, fluxos: {}, regras: {}, padroes: {}, travas: {}, tipos: {}, 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;
+  if (fs.existsSync(path.join(dirFluxo, "tipos.json"))) m.tipos = json(path.join(dirFluxo, "tipos.json")).tipos || {};
+  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) => {
+        // passo compartilhado ({"de": "entrada"}): o corpo vem de fluxo/<de>.md, não de passos/
+        const arq = x.de ? path.join(dirFluxo, `${x.de}.md`) : 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, vizinhos: vizinhos(p.corpo, p.pulo) };
+    }
+  }
+  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))) }));
+  // os passos de "desviavel" são o ponto de desvio por tipo (⇢): a skill de um toolkit escreve esse artefato
+  for (const [sg, t] of Object.entries(m.tipos))
+    if (!t.pendente && Array.isArray(t.desviavel)) for (const c of t.desviavel) { const r = resolverId(m, c); if (r?.passo) (r.passo.tipos ||= []).push(sg); }
+  return m;
+}
+
+/** a < b em versão semântica (os três números). */
+function versaoMenor(a, b) {
+  const [x, y] = [a, b].map((v) => String(v).split(/[.-]/).slice(0, 3).map(Number));
+  const i = x.findIndex((n, k) => n !== y[k]);
+  return i >= 0 && x[i] < y[i];
+}
+
+/** O arquivo `f` está dentro da pasta `raiz` (caminhos relativos ou absolutos)? */
+// como o dentro() do gerador: relativo, com /, sem ~, \\, unidade nem ..
+const relativo = (c) => typeof c === "string" && !/^[/~]|\\|^[A-Za-z]:/.test(c) && !c.split("/").includes("..");
+const sob = (raiz, f) => path.resolve(f).startsWith(path.resolve(raiz) + path.sep);
+
+/**
+ * Erros do toolkit na pasta `tk` contra o Sabiá `fw`: requer, tipos (o tipo vai para uma skill do toolkit, com o fluxo e
+ * o padrão do tipo, arquivos da pasta lidos pelo caminho) e rubricas. O Sabiá não compila conteúdo de toolkit.
+ */
+export function validarToolkitFonte(fw, tk) {
+  const m = carregar(fw), man = json(path.join(tk, "toolkit.json")), erros = [];
+  const versaoSabia = fs.existsSync(path.join(fw, "plugin.json")) ? json(path.join(fw, "plugin.json")).version : null;
+  if (man.requer?.sabia && versaoSabia && versaoMenor(versaoSabia, man.requer.sabia))
+    erros.push(`requer o Sabiá ${man.requer.sabia}; o instalado é o ${versaoSabia}`);
+  for (const [sg, q] of Object.entries(man.tipos || {})) {
+    const t = m.tipos[sg];
+    if (!t) erros.push(`tipo ${sg}: fora do catálogo do Sabiá (o toolkit não cria tipo)`);
+    else if (!t.desviavel?.length) erros.push(`tipo ${sg}: não é desviável no catálogo`);
+    else if (t.pendente) erros.push(`tipo ${sg}: pendente no Sabiá instalado (ainda sem o passo que o cria)`);
+    if (!q || typeof q !== "object") { erros.push(`tipo ${sg}: use {"skill", "fluxo", "padrao"} (a skill do toolkit; o fluxo e o padrão do tipo, opcionais)`); continue; }
+    const sk = (man.skills || []).find((s) => s.caminho === q.skill);
+    if (!sk) erros.push(`tipo ${sg}: a skill ${q.skill} não está em skills`);
+    // o gerador liga a skill ao dono de cada passo de desvio: sem o papel em "papeis", o toolkit não declara esse uso
+    else if (t?.desviavel) for (const c of t.desviavel) {
+      const papel = resolverId(m, c)?.fl.d.dono?.replace(/^sa-/, "");
+      if (papel && !(sk.papeis || []).includes(papel)) erros.push(`tipo ${sg}: a skill ${q.skill} não traz o papel ${papel} em papeis (dono do passo de desvio ${c})`);
+    }
+    for (const k of ["fluxo", "padrao"].filter((k) => k in q))
+      if (!relativo(q[k]) || !sob(tk, path.join(tk, q[k])) || !fs.statSync(path.join(tk, q[k]), { throwIfNoEntry: false })?.isFile()) erros.push(`tipo ${sg}: falta o ${k} ${q[k]} na pasta do toolkit`);
+  }
+  const doSabia = new Set([...(m.padroes["sa-revisar"]?.find((p) => p.nome === "rubricas.md")?.corpo || "").matchAll(/^\| ([A-Z]\d+) \|/gm)].map((r) => r[1]));
+  const ids = (man.rubricas || []).map((r) => r.id);
+  for (const r of man.rubricas || []) {
+    if (!/^[A-Z]+\d+$/.test(r.id ?? "")) erros.push(`rubrica ${r.id ?? "?"}: id como EX1 (maiúsculas e número)`);
+    else if (doSabia.has(r.id) || ids.filter((x) => x === r.id).length > 1) erros.push(`rubrica ${r.id}: repetida ou já do Sabiá (o toolkit só acrescenta itens)`);
+    if (!String(r.verificacao ?? "").trim()) erros.push(`rubrica ${r.id ?? "?"}: sem verificacao`);
+    if (!["BLOQUEANTE", "IMPORTANTE", "SUGESTÃO"].includes(r.severidade)) erros.push(`rubrica ${r.id ?? "?"}: severidade "${r.severidade ?? ""}" (use BLOQUEANTE, IMPORTANTE ou SUGESTÃO)`);
+  }
+  return erros;
+}
+
+/** As siglas na ordem de publicação: cada uma depois das do seu "depois" (a ordem do catálogo desempata); null com ciclo. */
+export function ordemTipos(tipos) {
+  const feitos = [], resto = Object.keys(tipos);
+  while (resto.length) {
+    const i = resto.findIndex((s) => (tipos[s].depois || []).every((d) => feitos.includes(d) || !tipos[d]));
+    if (i < 0) return null;
+    feitos.push(...resto.splice(i, 1));
+  }
+  return feitos;
+}
+
+const padraoExiste = (m, ref) => { const [s, n] = ref.split("/"); return !!m.padroes[s]?.some((p) => p.nome === n); };
+
+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. 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`);
+    if (fl.passos.some((x) => x.de) && !fl.vizinhos?.length)
+      e(fl.arq, 2, `passo entrada sem a seção "${VIZINHOS}" no corpo do mestre (uma linha "- <estado> → <dona>" por vizinho)`);
+    for (const v of fl.vizinhos || []) {
+      const alvos = v.destino ? [...v.destino.matchAll(ID)].map((r) => r[1]) : [];
+      if (!alvos.length && !v.destino?.endsWith("■")) { e(fl.arq, v.n, 'vizinho fora do formato "- <estado> → `sa-x.f[.p]`" ou "- <estado> → <frase> ■"'); continue; }
+      for (const q2 of alvos) {
+        const r = resolverId(m, q2);
+        if (!r) continue;  // o id inexistente já sai na varredura do texto
+        if (r.fl === fl) e(fl.arq, v.n, `vizinho → ${q2}: é deste fluxo → declare como saída do passo entrada ("saidas" no mestre)`);
+        else if (!m.subag[r.fl.d.dono]) e(fl.arq, v.n, `vizinho → ${q2}: o dono ${r.fl.d.dono} não é agente do papeis.json`);
+        else if (r.passo && r.fl.d.dono !== d.dono) e(fl.arq, v.n, `vizinho → ${q2}: passo de outro agente (${r.fl.d.dono}) → use o fluxo (${r.fl.skill}.${r.fl.fluxo})`);
+        else if (r.fl.d.dono !== d.dono && !(v.estado + " → " + v.destino).includes("agente `" + r.fl.d.dono + "`")) e(fl.arq, v.n, `vizinho → ${q2}: dono ${r.fl.d.dono} é outro agente → acrescente "(agente \`${r.fl.d.dono}\`)" na linha`);
+      }
+    }
+    for (const x of fl.passos) {
+      if (x.id === "grafo") e(fl.arq, 2, "passo grafo: id reservado (o compilador gera references/<fluxo>/grafo.md)");
+      if (x.id === "entrada" && !x.de) e(fl.arq, 2, 'passo entrada: id reservado ao passo compartilhado → {"id": "entrada", "de": "entrada", "sprint": "exige|nao"}');
+      if (x.de) {
+        if (!SPRINT.includes(x.sprint)) e(fl.arq, 2, `passo ${x.id}: sprint "${x.sprint ?? ""}" (use ${SPRINT.join(" ou ")})`);
+        if (fs.existsSync(path.join(path.dirname(fl.arq), "passos", `${x.id}.md`))) e(fl.arq, 2, `passo ${x.id}: vem de fluxo/${x.de}.md; apague passos/${x.id}.md`);
+        if (!fs.existsSync(x.arq)) { e(fl.arq, 2, `passo ${x.id}: de "${x.de}" sem fluxo/${x.de}.md`); continue; }
+      }
+      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 || {})) {
+        const r = dest.startsWith("→ ") ? resolverId(m, dest.slice(2).trim()) : null;
+        if (r?.passo && r.fl.d.dono !== d.dono)
+          e(fl.arq, 2, `passo ${x.id}: saída "${cond}" passa ao passo ${dest.slice(2).trim()}, de outro agente (${r.fl.d.dono}) → use o fluxo (→ ${r.fl.skill}.${r.fl.fluxo})`);
+        if (dest === "fim" || ids.includes(dest) || r) continue;
+        e(fl.arq, 2, `passo ${x.id}: saída "${cond}" → "${dest}" (use id do fluxo, fim ou "→ skill.fluxo[.passo]" existente)`);
+      }
+    }
+  }
+
+  const arqTipos = path.join(m.fw, "fluxo", "tipos.json");
+  const rubrica = new Set([...(m.padroes["sa-revisar"]?.find((p) => p.nome === "rubricas.md")?.corpo || "").matchAll(/^\| ([A-Z]\d+) \|/gm)].map((r) => r[1]));
+  let forma = true;
+  for (const [sg, t] of Object.entries(m.tipos)) {
+    const naoLista = ["cria", "desviavel", "depois", "embute", "rubrica"].filter((k) => t[k] != null && !Array.isArray(t[k]));
+    for (const k of naoLista) e(arqTipos, 1, `tipo ${sg}: ${k} tem de ser lista`);
+    if (naoLista.length) { forma = false; continue; }
+    if (!/^[A-Z]{2,4}$/.test(sg) || !t.nome) e(arqTipos, 1, `tipo ${sg}: sigla de 2 a 4 maiúsculas e nome`);
+    // sigla única: o JSON.parse junta chaves repetidas; a conferência é no texto
+    else if ((ler(arqTipos).match(new RegExp(`"${sg}"\\s*:\\s*\\{`, "g")) || []).length > 1) e(arqTipos, 1, `tipo ${sg}: sigla repetida`);
+    if (!["DOORS", "ETM"].includes(t.elm)) e(arqTipos, 1, `tipo ${sg}: elm "${t.elm ?? ""}" (use DOORS ou ETM)`);
+    if (!t.cria?.length) e(arqTipos, 1, `tipo ${sg}: sem cria`);
+    for (const c of t.desviavel || []) if (!t.cria?.includes(c)) e(arqTipos, 1, `tipo ${sg}: desviavel ${c} fora de cria`);
+    // tipo pendente: declarado antes do padrão e do fluxo que o escrevem
+    for (const c of t.pendente ? [] : t.cria || []) if (!resolverId(m, c)?.passo) e(arqTipos, 1, `tipo ${sg}: cria ${c} não é passo de fluxo`);
+    if (t.padrao && !t.pendente && !padraoExiste(m, t.padrao)) e(arqTipos, 1, `tipo ${sg}: padrão ${t.padrao} inexistente`);
+    for (const d of [...(t.depois || []), ...(t.embute || [])]) if (!m.tipos[d]) e(arqTipos, 1, `tipo ${sg}: ${d} fora do catálogo`);
+    for (const r of t.pendente ? [] : t.rubrica || []) if (!rubrica.has(r)) e(arqTipos, 1, `tipo ${sg}: rubrica ${r} fora de rubricas.md`);
+    if (t.pendente && t.cria?.length && t.cria.every((c) => resolverId(m, c)?.passo) && (!t.padrao || padraoExiste(m, t.padrao)))
+      e(arqTipos, 1, `tipo ${sg}: cria e padrão já existem; tire o "pendente"`);
+  }
+  if (forma && !ordemTipos(m.tipos)) e(arqTipos, 1, `ciclo no "depois" dos tipos`);
+
+  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 [...new Set(erros)];  // o passo compartilhado repete os mesmos erros em cada fluxo
+}
+
+// ---------------------------------------------------------------- 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, ctx) {
+  const { fw, base, m } = ctx;
+  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` : "");
+
+export const LEGENDA = "↓ segue · ↑ volta · ↺ repete · ⇄ chama · ⇒ passa a (o fluxo termina) · ↪ vizinhos da entrada (diga a dona, ou a frase da linha ■, e pare) · ■ fim · 🔒 trava · ⇢ passo com desvio de toolkit (pelo para e arquivos, ou pelo tipo que o passo cria)";
+
+/** O passo aceita desvio de toolkit: pelo para e arquivos ("desvio": true) ou pelo tipo do catálogo que ele cria. */
+export const temDesvio = (x) => !!(x.desvio || x.tipos?.length);
+
+/**
+ * O grafo ASCII do fluxo `fl` (de carregar): uma caixa por passo de `passos` (o rota passa os resolvidos no projeto) e, à
+ * direita, chama, travas e saídas. `notas(x)` acrescenta linhas no topo das anotações (origem, desvio ligado).
+ */
+export function grafoAscii(fl, passos = fl.passos, { notas = () => [] } = {}) {
+  const ids = passos.map((x) => x.id), out = [];
+  const rot = (x, i) => `${i + 1} ${x.id}${x.sprint ? ` [${x.sprint}]` : ""}${temDesvio(x) ? " ⇢" : ""}`;
+  // 26 colunas cabem os ids do Sabiá; um id longo inserido pelo projeto alarga a caixa (par, por causa do ┬ central)
+  const W = 2 * Math.ceil(Math.max(26, ...passos.map((x, i) => rot(x, i).length + 4)) / 2);
+  const cond = (c) => (c.length > 60 ? c.slice(0, 57) + "…" : c);
+  out.push(`${fl.skill}.${fl.fluxo}   dono ${fl.d.dono}   travas ${(fl.d.travas_gerais || []).join(", ") || "—"}`, "");
+  passos.forEach((x, i) => {
+    const lado = [...notas(x)];
+    // os vizinhos numa linha só: a entrada diz a dona e para, não é passagem de trabalho (⇒)
+    const viz = x.de ? (fl.vizinhos || []).filter((v) => v.destino).map((v) => [...v.destino.matchAll(ID)][0]?.[1] || `■ ${cond(v.estado.replace(/`/g, ""))}`) : [];
+    if (viz.length) lado.push(`↪ vizinhos (diga e pare): ${[...new Set(viz)].join(" · ")}`);
+    if (x.tipos?.length) lado.push(`⇢ por tipo: ${x.tipos.join(", ")}`);
+    if (x.chama) lado.push(`⇄ chama ${[].concat(x.chama).join(", ")}`);
+    if (x.travas?.length) lado.push(`🔒 ${x.travas.join(", ")}`);
+    for (const [c, dest] of Object.entries(x.saidas || {})) {
+      const j = ids.indexOf(dest);
+      const seta = dest.startsWith("→ ") ? `⇒ passa a ${dest.slice(2).trim()}` : dest === "fim" ? "■ fim" : dest === x.id ? `↺ ${dest}` : j >= 0 && j < i ? `↑ volta a ${dest}` : `↓ ${dest}`;
+      lado.push(`${seta}  (${cond(c)})`);
+    }
+    const ultimo = i === passos.length - 1;
+    out.push(`  ┌${"─".repeat(W - 2)}┐`);
+    out.push(`  │ ${rot(x, i).padEnd(W - 4)} │${lado[0] ? `──▶ ${lado[0]}` : ""}`);
+    out.push((ultimo ? `  └${"─".repeat(W - 2)}┘` : `  └${"─".repeat(W / 2 - 2)}┬${"─".repeat(W / 2 - 1)}┘`) + (lado[1] ? `    ${lado[1]}` : ""));
+    for (const l of lado.slice(2)) out.push(`${" ".repeat(W + 6)}${l}`);
+    if (!ultimo) out.push(`  ${" ".repeat(W / 2 - 1)}▼`);
+  });
+  return out.join("\n");
+}
+
+const grafoMd = (fl) => [`# Grafo de ${fl.skill}.${fl.fluxo}`, "", "```", grafoAscii(fl), "```", "", LEGENDA, ""].join("\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. Num passo ⇢, o desvio de toolkit sai pela skill dele: o agente dono a tem no
+prompt; sem agente, valem a seção **Desvios de toolkit** (desvio por passo) e a **Tipos com skill de toolkit** (desvio por
+tipo, com a skill, o fluxo e o padrão do tipo, arquivos do toolkit lidos pelo caminho, e os itens de rubrica que ele
+acrescenta à revisão) do \`.sabia/sabia.md\`.
+`;
+
+/** 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 e removidos pelo`,
+      "projeto não entram, e os desvios de toolkit (⇢) valem pelas seções **Desvios de toolkit** (desvio por passo) e",
+      "**Tipos com skill de toolkit** (desvio por tipo) do `.sabia/sabia.md`.", "");
+    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}\`${temDesvio(x) ? ` ⇢${x.tipos?.length ? ` (${x.tipos.join(", ")})` : ""}` : ""} | [${x.id}.md](${arq}) | ${cel(chama)} | ${cel((x.travas || []).join(", ") || "—")} | ${cel(saidas)} |`);
+    });
+    out.push("", `Grafo: [grafo.md](${base}/${s}/references/${fl.fluxo}/grafo.md)`);
+    out.push("", "Ao começar um passo, leia o arquivo dele (não os dos outros passos) e o que ele mandar ler. Nenhuma Saída casou (ou o passo não tem Saídas) → o",
+      `próximo da lista; depois do último passo, o fluxo termina. 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");
+}
+
+/** references/tipos.md da skill sabia: o catálogo de fluxo/tipos.json em tabela, com a ordem de publicação. */
+function tiposMd(m, ctx) {
+  const { base } = ctx;
+  const ord = ordemTipos(m.tipos), sim = (b) => (b ? "sim" : "não"), lista = (xs) => (xs?.length ? xs.join(", ") : "—");
+  const padrao = (t) => !t.padrao ? "— (corpo no passo que cria)" : t.pendente ? `\`${t.padrao}\`` : `[\`${t.padrao}\`](${base}/${t.padrao.replace("/", "/references/padrao/")})`;
+  const out = ["# Tipos de artefato", "",
+    "Catálogo fechado: todo artefato da especificação e do ELM é de um destes tipos, e um toolkit não cria tipo. A coluna",
+    "Desviável diz os passos de Cria que são o ponto de desvio (⇢): neles, o toolkit que traz uma skill com o fluxo e o",
+    "padrão do tipo (`tipos` no `toolkit.json`) escreve esse artefato; nos outros passos de Cria, o tipo é sempre do Sabiá. O envelope OKF de todos",
+    `é o do [\`okf-elm.md\`](${base}/sa-prd/references/okf-elm.md) da \`sa-prd\`; o corpo é o do padrão do tipo. Tipo **pendente** está declarado, mas ainda não tem padrão nem fluxo: não é criado nem publicado.`, "",
+    "| Sigla | Nome | Arquivo | Cria | Padrão | ELM | Requisito | Desviável | Publica depois de | Embute | Rubrica |",
+    "|---|---|---|---|---|---|---|---|---|---|---|"];
+  for (const sg of Object.keys(m.tipos)) {
+    const t = m.tipos[sg];
+    out.push(`| \`${sg}\`${t.pendente ? " (pendente)" : ""} | ${cel(t.nome)} | \`${cel(t.arquivo || "—")}\` | ${t.cria.map((c) => `\`${c}\``).join("<br>")} | ${padrao(t)} | ${t.elm} | ${sim(t.requisito)} | ${t.desviavel?.length ? t.desviavel.map((c) => `\`${c}\``).join("<br>") : "não"} | ${lista(t.depois)} | ${lista(t.embute)} | ${lista(t.rubrica)} |`);
+  }
+  const pub = ord.filter((sg) => m.tipos[sg].requisito && !m.tipos[sg].pendente);
+  out.push("", `**Ordem de publicação dos requisitos** (coluna Requisito, de baixo para cima, para cada um nascer com os ids que cita): ${pub.map((sg) => `\`${sg}\``).join(" → ")}.`,
+    "Os tipos de Embute entram em embed (`embutir`) no texto de quem os cita; os demais links ficam hyperlink.", "");
+  return reescrever(out.join("\n"), path.join(m.fw, "skills/sabia/references/tipos.md"), ctx);
+}
+
+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;
+}
+
+/** Uma skill compilada em `out`: a árvore com os links reescritos e, se tem fluxo, o SKILL.md, os passos e o grafo. */
+function escreverSkill(m, s, out, ctx, versao = null) {
+  const { fw, base } = ctx, dir = path.join(fw, "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 (fluxosDa(m, s).length) {
+    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)) {
+      fs.mkdirSync(path.join(out, "references", fl.fluxo), { recursive: true });
+      fs.writeFileSync(path.join(out, "references", fl.fluxo, "grafo.md"), grafoMd(fl));
+      const linhaSprint = (x) => (x.de ? `Sprint deste fluxo: \`${x.sprint}\`. Vizinhos: a seção Entrada: vizinhos do [Fluxo ${fl.fluxo}](${base}/${s}/SKILL.md#${slug(`Fluxo ${fl.fluxo}`)}).\n\n` : "");
+      for (const x of fl.passos)
+        fs.writeFileSync(path.join(out, "references", fl.fluxo, `${x.id}.md`), italico(x.dados.resumo) + linhaSprint(x) + 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+/, ""));
+  }
+}
+
+/**
+ * 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 };
+  for (const s of skillsDe(fw)) escreverSkill(m, s, path.join(staging, "skills", s), ctx, versao);
+  if (Object.keys(m.tipos).length && fs.existsSync(path.join(staging, "skills/sabia"))) {
+    fs.mkdirSync(path.join(staging, "skills/sabia/references"), { recursive: true });
+    fs.writeFileSync(path.join(staging, "skills/sabia/references/tipos.md"), tiposMd(m, ctx));
+  }
+  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-beta.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, grafoAscii, LEGENDA, partes, temDesvio, validarToolkitFonte } 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"),
 };
 
@@ -193,13 +193,31 @@ export function separarRef(fonte) {
  * Baixa `url` (ou copia a pasta local) na `ref`, confere o `sha` e devolve { pasta, sha }. Clona com o git da
  * pessoa (credencial, SSH, CA), sem submódulos; nunca guarda token nem executa nada do que baixou.
  */
+// as cópias baixadas são lidas e copiadas para ~/.sabia durante o comando; somem quando o processo termina
+const temporarios = new Set();
+process.on("exit", () => { for (const t of temporarios) fs.rmSync(t, { recursive: true, force: true }); });
+
 export function baixar(url, { ref = null, sha = null, subpasta = null } = {}) {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "sabia-"));
+  temporarios.add(tmp);
   const repo = path.join(tmp, "repo");
   let atual = null;
   if (fs.existsSync(url) && fs.statSync(url).isDirectory()) {
-    fs.cpSync(url, repo, { recursive: true, filter: (f) => path.basename(f) !== ".git" });
-    if (fs.existsSync(path.join(url, ".git"))) atual = git(["rev-parse", ref || "HEAD"], url);
+    const topo = ctx.exec("git", ["rev-parse", "--show-toplevel"], { cwd: url });
+    if (ref) {
+      // com @ref, a pasta vem do commit (git archive), não da árvore de trabalho; ref inexistente é recusada
+      if (topo.status !== 0) throw new Error(`${url}: @${ref} pede uma pasta dentro de um repositório git`);
+      atual = git(["rev-parse", "--verify", `${ref}^{commit}`], url);
+      const rel = path.relative(fs.realpathSync(topo.stdout.trim()), fs.realpathSync(url)).split(path.sep).join("/");
+      const tar = path.join(tmp, "a.tar");
+      git(["archive", "--format=tar", "-o", tar, rel ? `${atual}:${rel}` : atual], url);
+      fs.mkdirSync(repo);
+      const r = ctx.exec("tar", ["-xf", tar, "-C", repo]);
+      if (r.status !== 0) throw new Error(`tar: ${(r.stderr || "").trim()}`);
+    } else {
+      fs.cpSync(url, repo, { recursive: true, filter: (f) => path.basename(f) !== ".git" });
+      if (topo.status === 0) atual = git(["rev-parse", "HEAD"], url);
+    }
   } else {
     git(["clone", "--quiet", "--depth", "1", "--no-recurse-submodules", ...(ref ? ["--branch", ref] : []), url, repo]);
     atual = git(["rev-parse", "HEAD"], repo);
@@ -228,7 +246,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 +294,31 @@ 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`);
   }
 }
 
+/** Onde as skills do Sabiá ficam no alvo (caminho com ~). */
+const baseSabia = (alvo) => (alvo === "kiro" ? "~/.kiro/powers/installed/sabia/skills" : curto(PASTA_SKILLS[alvo]()));
+
+/** Compila o framework para o alvo em ~/.sabia/compilado/<alvo>/. */
+function compilarPara(alvo, fw) {
+  const versao = JSON.parse(fs.readFileSync(path.join(fw, "plugin.json"), "utf8")).version;
+  return compilar(fw, sabia("compilado", alvo), { base: baseSabia(alvo), 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
@@ -308,17 +329,11 @@ async function instalarAlvo(alvo, inv, opcoes) {
     if (r.status !== 0) throw new Error(`kiro-cli powers install: ${(r.stderr || r.error?.message || "").trim()}`);
     inv.alvos.kiro = { power: "sabia" };
     ctx.log("power sabia instalado no Kiro");
-    if (fs.existsSync(path.join(home(), ".kiro", "powers", "installed", "sdd")))
-      ctx.log("aviso: o power antigo sdd ainda está no Kiro e concorre com o sabia (desinstale pelo painel Powers se não usa mais)");
     return;
   }
   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);
 }
 
 /** Baixa o framework para uma pasta temporária e diz o que muda em relação a ~/.sabia/framework/. */
@@ -353,14 +368,14 @@ 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);
   } finally {
     gravarInventario(inv);
   }
-  ctx.log('Pronto: skills e MCPs instalados. Os agentes são de cada projeto: abra a ferramenta na raiz dele, na sessão\n' +
+  ctx.log((opcoes.semMcp ? 'Pronto: skills instaladas (MCPs não registrados: --sem-mcp).' : 'Pronto: skills e MCPs instalados.') + ' Os agentes são de cada projeto: abra a ferramenta na raiz dele, na sessão\n' +
     'padrão, e peça "configurar o Sabiá" (ou, num projeto já configurado, "atualizar os agentes do Sabiá").');
 }
 
@@ -369,11 +384,14 @@ 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)) {
       if (alvo !== "kiro") {  // skill que saiu do framework sai da ferramenta
@@ -399,18 +417,18 @@ export async function desinstalar(opcoes = {}) {
       const reg = inv.alvos[alvo];
       if (!reg) { ctx.log(`${alvo}: nada instalado pelo Sabiá`); continue; }
       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 === "kiro") {
+        const r = ctx.exec("kiro-cli", ["powers", "uninstall", reg.power]);
+        if (r.status !== 0) { ctx.log(`kiro: kiro-cli powers uninstall falhou: ${(r.stderr || r.error?.message || "").trim()}`); continue; }
+      } else await apagar(reg.copias, opcoes);
+      if (alvo === "opencode") for (const nome of reg.mcp || []) tirarMcpDoOpencode(nome);
       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 {
@@ -420,8 +438,13 @@ export async function desinstalar(opcoes = {}) {
 
 // ---------- toolkits ----------
 
+/** O passo do framework (`m` do carregar) que o `passo` de um toolkit assume, pelo id — a mesma regra do gancho() do
+ * gerar_agentes.py. */
+const ganchoDe = (m, ext) => Object.entries(m.fluxos).flatMap(([q, fl]) => fl.passos.map((x) => ({ id: `${q}.${x.id}`, x })))
+  .find(({ id }) => id === ext.passo);
+
 /** 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 +463,23 @@ 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");
+    // a skill do toolkit não ocupa um nome do Sabiá: a cópia dela trocaria a do Sabiá sem aviso
+    const sk = path.basename(path.dirname(String(s.caminho)));
+    if (sk.startsWith("sa-") || sk === "sabia") erros.push(`skill ${s.caminho}: nome do Sabiá (sa-* ou sabia); use outro nome de pasta`);
     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 && !s.passo.passo) erros.push(`passo de ${s.caminho}: use o id do passo (passo.passo)`);
+    else if (s.passo && ganchos) {
+      const g = ganchoDe(ganchos, s.passo);
+      if (!g) erros.push(`passo de ${s.caminho}: ${s.passo.passo} não existe no Sabiá instalado`);
+      else if (!g.x.desvio) erros.push(`passo de ${s.caminho}: ${s.passo.passo} não aceita desvio de toolkit${g.x.tipos ? ` (o tipo ${g.x.tipos.join(", ")} vai por \`tipos\`)` : ""}`);
+    }
+  }
+  if (ganchos && (m.tipos || m.rubricas || m.requer)) {
+    try { erros.push(...validarToolkitFonte(fw, pasta)); } catch (e) { erros.push(e.message); }
   }
   for (const s of m.steering || []) existe(s.caminho, "steering");
   for (const a of m.agentes || []) {
@@ -485,28 +522,36 @@ function acharNoIndice(nome, versao, opcoes) {
 
 export async function baixarToolkit(alvo, opcoes = {}) {
   const ehUrl = /[:/]/.test(alvo) && !/^[a-z0-9-]+(@[\w.-]+)?$/.test(alvo);
-  const [nomeOuUrl, versaoOuRef] = separarRef(alvo);
-  const e = ehUrl ? { nome: null, url: nomeOuUrl, ref: versaoOuRef } : acharNoIndice(nomeOuUrl, versaoOuRef, opcoes);
+  // `<url>[@ref]#<subpasta>`: o toolkit numa subpasta de um repositório (monorepo de toolkits)
+  const [semSub, subpasta = null] = ehUrl ? alvo.split("#") : [alvo];
+  const [nomeOuUrl, versaoOuRef] = separarRef(semSub);
+  const e = ehUrl ? { nome: null, url: nomeOuUrl, ref: versaoOuRef, subpasta } : 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);
   const dif = diferencas(destino, pasta);
+  dif.removidos = dif.removidos.filter((f) => f !== ".origem.json");  // é nossa, regravada abaixo
+  let mudou = true;
   if (fs.existsSync(destino)) {
     ctx.log(`toolkit ${m.nome}: ${JSON.parse(fs.readFileSync(path.join(destino, "toolkit.json"), "utf8")).versao} → ${m.versao}`);
-    if (!mostrarDiferencas(dif)) { ctx.log("nada mudou"); return m.nome; }
-    if (!/^s/i.test(await ctx.perguntar("Substituir? [s/N]", "n"))) { ctx.log("nada foi alterado"); return null; }
-    fs.rmSync(destino, { recursive: true, force: true });
+    mudou = mostrarDiferencas(dif);
+    if (!mudou) ctx.log("nada mudou");
+    else if (!/^s/i.test(await ctx.perguntar("Substituir? [s/N]", "n"))) { ctx.log("nada foi alterado"); return null; }
+    else fs.rmSync(destino, { recursive: true, force: true });
   }
-  fs.mkdirSync(path.dirname(destino), { recursive: true });
-  fs.cpSync(pasta, destino, { recursive: true });
-  const origem = { indice: e.indice || null, url: e.url, ref: e.ref || null, sha, versao: m.versao };
+  if (mudou) {
+    fs.mkdirSync(path.dirname(destino), { recursive: true });
+    fs.cpSync(pasta, destino, { recursive: true });
+  }
+  // mesmo sem mudar o conteúdo, a origem pode ter mudado (da pasta local para o índice, por exemplo)
+  const origem = { indice: e.indice || null, url: e.url, ref: e.ref || null, subpasta: e.indice ? null : e.subpasta || null, sha, versao: m.versao };
   fs.writeFileSync(path.join(destino, ".origem.json"), JSON.stringify(origem, null, 2) + "\n");
   const inv = lerInventario();
   inv.toolkits[m.nome] = { ...(inv.toolkits[m.nome] || { alvos: {} }), versao: m.versao, sha, fonte: e.url };
   gravarInventario(inv);
-  ctx.log(`toolkit ${m.nome} ${m.versao} em ~/.sabia/toolkits/${m.nome}`);
+  if (mudou) ctx.log(`toolkit ${m.nome} ${m.versao} em ~/.sabia/toolkits/${m.nome}`);
   return m.nome;
 }
 
@@ -524,7 +569,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);
+  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: {} });
@@ -562,13 +608,18 @@ export async function removerToolkit(nome, opcoes = {}) {
     gravarInventario(inv);
   }
   ctx.log(`toolkit ${nome} removido`);
+  const f = path.join(process.cwd(), ".sabia", "config", "agentes.json");
+  if (fs.existsSync(f) && JSON.parse(fs.readFileSync(f, "utf8")).toolkits?.[nome])
+    ctx.log(`aviso: este projeto ainda usa o ${nome}; peça "atualizar os agentes do Sabiá" para desligá-lo`);
 }
 
 export async function atualizarToolkits(nome, opcoes = {}) {
   const inv = lerInventario();
   for (const n of nome ? [nome] : Object.keys(inv.toolkits)) {
-    const origem = JSON.parse(fs.readFileSync(sabia("toolkits", n, ".origem.json"), "utf8"));
-    const alvo = origem.indice ? n : `${origem.url}${origem.ref ? "@" + origem.ref : ""}`;
+    const fo = sabia("toolkits", n, ".origem.json");
+    if (!fs.existsSync(fo)) throw new Error(`toolkit ${n}: sem ~/.sabia/toolkits/${n}/.origem.json; baixe de novo: sabia toolkits baixar <nome|url>`);
+    const origem = JSON.parse(fs.readFileSync(fo, "utf8"));
+    const alvo = origem.indice ? n : `${origem.url}${origem.ref ? "@" + origem.ref : ""}${origem.subpasta ? "#" + origem.subpasta : ""}`;
     await instalarToolkit(alvo, { ...opcoes, atualizar: true, indice: origem.indice || opcoes.indice,
       alvo: Object.keys(inv.toolkits[n]?.alvos || {}).join(",") || "kiro" });
   }
@@ -618,26 +669,244 @@ export function listarToolkits(opcoes = {}) {
   return linhas;
 }
 
+// ---------- rota (diagnóstico, para pessoas) ----------
+
+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 dirTk = (nome) => { const pasta = cfg.toolkits?.[nome]?.pasta; return !pasta ? sabia("toolkits", nome) : pasta.startsWith("~/") ? longo(pasta) : path.resolve(projeto, pasta); };
+  // os tipos dos toolkits do projeto viram o desvio por tipo: a skill do toolkit, com o fluxo do tipo, se o traz
+  const tipos = [];
+  for (const nome of Object.keys(cfg.toolkits || {})) {
+    const man = lerJson(path.join(dirTk(nome), "toolkit.json"), null);
+    if (!man) continue;
+    for (const [sigla, q] of Object.entries(man.tipos || {})) {
+      if (typeof q?.skill !== "string") { tipos.push({ sigla, fluxo: "(inválido: o tipo no toolkit.json precisa de {\"skill\"}; o gerador recusa)", toolkit: nome, versao: man.versao }); continue; }
+      const sk = path.basename(path.dirname(q.skill));
+      tipos.push({ sigla, fluxo: q.fluxo ? `skill ${sk} (${q.fluxo})` : `skill ${sk}`, toolkit: nome, versao: man.versao });
+    }
+  }
+  const desvios = (cfg.passos || []).flatMap((e) => {
+    const dir = dirTk(e.toolkit);
+    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 []; }
+    if (!ext.passo) {
+      ctx.log(`aviso: toolkit ${e.toolkit}: o passo de ${e.skill} não tem o id: use o id do passo (passo.passo)`
+        + ` e reinstale o toolkit (\`sabia toolkits atualizar ${e.toolkit}\`) — ignorado`);
+      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 g = ganchoDe(m, ext), passo = g?.x.desvio ? g.id : null;
+    if (!passo) {
+      ctx.log(`aviso: toolkit ${e.toolkit}: o passo ${ext.passo} 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, tipos };
+}
+
+/** 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(", ") || "—";
+
+/** A tarefa `id` do tasks.md (`1`, `2.1`; `T-2` também): o texto do bloco dela (a linha e as de baixo, mais
+ * recuadas) e o que ela cita entre crases, sem espaço (os arquivos, classes e métodos). */
+export function lerTarefa(arquivo, id) {
+  if (!fs.existsSync(arquivo)) throw new Error(`${arquivo} não existe`);
+  const norm = (t) => t.replace(/^T-?/i, "").split(".").map(Number).join(".");
+  const linhas = fs.readFileSync(arquivo, "utf8").split("\n");
+  let achado;
+  const i = linhas.findIndex((l) => (achado = l.match(/^\s*- \[.\]\*? (\d+(?:\.\d+)*)\.? /)) && norm(achado[1]) === norm(id));
+  if (i < 0) throw new Error(`${arquivo}: não há a tarefa ${id} (use o número dela, ex.: #2 ou #2.1)`);
+  let fim = i + 1;
+  // linha em branco entre as subtarefas não fecha o bloco; fecha a primeira linha com recuo igual ou menor
+  for (let k = i + 1; k < linhas.length; k++) {
+    const r = linhas[k].search(/\S/);
+    if (r < 0) continue;
+    if (r <= linhas[i].search(/\S/)) break;
+    fim = k + 1;
+  }
+  const texto = linhas.slice(i, fim).filter((l) => l.trim()).map((l) => l.trim().replace(/^- (?:\[.\]\*? )?/, "")).join(" · ");
+  return { id: achado[1], texto, arquivos: [...new Set([...texto.matchAll(/`([^`\s]+)`/g)].map((m) => m[1]))] };
+}
+
+/** `sabia rota <arquivo>` (ou `<tasks.md>#<tarefa>`, pelos arquivos que ela cita): o passo com gancho cujo desvio
+ * casa, o dono, o toolkit, o motivo e as travas. */
+export function rota(arquivo, opcoes = {}) {
+  const c = contextoRota(opcoes);
+  const t = arquivo.match(/^(.+\.md)#(.+)$/), tarefa = t && lerTarefa(t[1], t[2]);
+  const relativo = (a, base) => {
+    const r = path.relative(c.projeto, path.resolve(base, a));
+    return (r.startsWith("..") ? a : r).split(path.sep).join("/");  // fora do projeto: o caminho como veio
+  };
+  // a tarefa cita os arquivos como no repositório: relativos à raiz do projeto
+  const alvos = tarefa ? tarefa.arquivos.map((a) => relativo(a, c.projeto)) : [relativo(arquivo, process.cwd())];
+  const ganchos = Object.entries(c.m.fluxos).flatMap(([q, fl]) => fl.passos.filter((x) => x.desvio).map((x) => `${q}.${x.id}`));
+  let casou = null;
+  achar: for (const d of c.desvios) for (const a of alvos) { const g = d.arquivos.find((x) => casaGlob(x, a)); if (g) { casou = { d, g, a }; break achar; } }
+  // 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 = [
+    ...(tarefa ? [["tarefa", tarefa.id, tarefa.texto]] : []),
+    ["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}${tarefa ? ` em ${casou.a}` : ""}`], ["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), o grafo ASCII 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}.`));
+  // desvio por tipo: o tipo que o passo cria tem skill de toolkit no projeto
+  const porTipo = (x) => c.tipos.filter((t) => x.tipos?.includes(t.sigla));
+  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 + (temDesvio(x) ? " ⇢" : ""), 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}`]),
+    ...r.passos.flatMap((x) => porTipo(x).map((t) => ["tipo ⇢", `${x.id}: ${t.sigla}`, `→ ${t.fluxo}`, `toolkit ${t.toolkit} ${t.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(", ")}`,
+      ...porTipo(x).map((t) => `tipo ${t.sigla} ⇢ ${t.fluxo}`)].filter(Boolean);
+    if (nota.length) out.push(`  note right of ${a}: ${rotulo(nota.join(" · "))}`);
+  });
+  const notas = (x) => [x.origem !== "sabia" && `origem: ${origem(x)}`,
+    ...desvios.filter((d) => d.passo === `${r.q}.${x.id}`).map((d) => `⇢ desvio → ${d.agente || `skill ${d.skill}`} (toolkit ${d.toolkit} ${d.versao})`),
+    ...porTipo(x).map((t) => `⇢ tipo ${t.sigla} → ${t.fluxo} (toolkit ${t.toolkit} ${t.versao})`)].filter(Boolean);
+  return [colunas(cab), "", colunas(tabela), "", grafoAscii(fl, ativos, { notas }), "", LEGENDA, "", "```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 atualizar  [--versao X]
+  sabia instalar   [--alvo kiro,opencode] [--versao X] [--fonte <pasta|url-git>[@ref]]
+  sabia atualizar  [--versao X] [--fonte <pasta|url-git>[@ref]]
   sabia desinstalar [--alvo …]
   sabia toolkits listar   [--indice <url-git|pasta>]
-  sabia toolkits baixar   <nome>[@versao] | <url-git>[@ref]
-  sabia toolkits instalar <nome>[@versao] | <url-git>[@ref]  [--alvo …]   (sem argumento, no projeto: as versões dele)
-  sabia toolkits atualizar [<nome>]
+  sabia toolkits baixar   <nome>[@versao] | <url-git|pasta>[@ref][#subpasta]  [--indice <url-git|pasta>]
+  sabia toolkits instalar <nome>[@versao] | <url-git|pasta>[@ref][#subpasta]  [--alvo …] [--indice <url-git|pasta>]   (sem argumento, no projeto: as versões dele)
+  sabia toolkits atualizar [<nome>]  [--indice <url-git|pasta>]
   sabia toolkits remover  <nome>
+  sabia rota <arquivo>               o passo com desvio de toolkit, o dono, o toolkit, o motivo e as travas
+  sabia rota <tasks.md>#<tarefa>     o mesmo pelos arquivos que a tarefa (#2, #2.1) cita; sem casar, o texto dela
+  sabia rota --fluxo <skill.fluxo>   o fluxo resolvido no projeto (tabela, grafo ASCII e 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
   --sem-mcp   não registra os MCPs
 
-Tudo fica em ~/.sabia/ (framework/, toolkits/, inventario.json).`;
+Tudo fica em ~/.sabia/ (framework/, compilado/, toolkits/, inventario.json e indices.json).`;
 
 export function lerArgs(argv) {
   const posicionais = [];
@@ -646,14 +915,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 +939,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) {