sabia 2.0.0-alpha.1 → 2.0.0

package/compilar.mjs

@@ -1,5 +1,5 @@
 // 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.
+// references/) numa pasta de staging, uma por alvo.
 import fs from "node:fs";
 import path from "node:path";
 
@@ -22,11 +22,29 @@ export function partes(texto) {
 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 const VIZINHOS = "## Entrada: vizinhos";
+export const SPRINT = ["exige", "nao"];
+export const BRANCH = ["fatia", "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: {}, subag: {}, skillsAgente: {} };
+  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)) {
@@ -42,18 +60,83 @@ export function carregar(fw) {
       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`);
+        // 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 };
+      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). */
@@ -75,7 +158,7 @@ function modoChamada(m, dono, alvo) {
 
 // ---------------------------------------------------------------- validação
 
-/** Erros "arquivo:linha: mensagem" da fonte (as regras do conferidor da F2.0). Lista vazia = pronta para compilar. */
+/** 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);
@@ -93,7 +176,29 @@ export function validar(m) {
       ? 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", "branch": "fatia|nao"}');
+      if (x.de) {
+        if (!SPRINT.includes(x.sprint)) e(fl.arq, 2, `passo ${x.id}: sprint "${x.sprint ?? ""}" (use ${SPRINT.join(" ou ")})`);
+        if (!BRANCH.includes(x.branch)) e(fl.arq, 2, `passo ${x.id}: branch "${x.branch ?? ""}" (use ${BRANCH.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}`);
@@ -104,12 +209,38 @@ export function validar(m) {
         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;
+        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 });
@@ -161,7 +292,7 @@ export function validar(m) {
       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;
+  return [...new Set(erros)];  // o passo compartilhado repete os mesmos erros em cada fluxo
 }
 
 // ---------------------------------------------------------------- reescrita
@@ -178,7 +309,8 @@ export function mapear(fw, src) {
 }
 
 /** 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 }) {
+export function reescrever(texto, origem, ctx) {
+  const { fw, base, m } = ctx;
   const destino = (alvo) => {
     const [cam, anc = ""] = alvo.split("#");
     let src;
@@ -232,13 +364,57 @@ const destinoId = (base, r) => (r.passo ? `${base}/${r.fl.skill}/references/${r.
 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.
+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. */
@@ -257,8 +433,9 @@ function skillMd(m, s, fmYaml, h1, ctx) {
     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.", "");
+    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));
@@ -279,10 +456,11 @@ function skillMd(m, s, fmYaml, h1, ctx) {
         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(`| ${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("", "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(", ") || "—"}.`, "");
+    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}`), "");
@@ -298,6 +476,29 @@ function skillMd(m, s, fmYaml, h1, ctx) {
   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.`,
+    `Na coluna Arquivo, \`nn\` = 2 dígitos a partir de \`01\`, por tipo, em cada pasta \`elm/\`; na fatia, segue a numeração do épico (a cópia de um conceito do épico fica com o mesmo nome, e o novo continua a série); \`<slug>\` pela regra do \`backlog.md\` da \`sa-fatiar\` (seção Formato).`, "",
+    "| 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) {
@@ -334,6 +535,31 @@ function conferirSaida(staging, base) {
   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}\`. Branch deste fluxo: \`${x.branch}\`. 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.
@@ -344,27 +570,10 @@ export function compilar(fw, staging, { base, raiz = false, versao = null } = {}
   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+/, ""));
-    }
+  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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sabia",
-  "version": "2.0.0-alpha.1",
+  "version": "2.0.0",
   "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": {

package/sabia.mjs

@@ -10,7 +10,7 @@ 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";
+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";
@@ -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);
@@ -290,11 +308,13 @@ async function registrarMcps(fw, reg) {
   }
 }
 
-/** Compila o framework para o alvo em ~/.sabia/compilado/<alvo>/ (seção 11 do plano da 2.0). */
+/** 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;
-  const base = alvo === "kiro" ? "~/.kiro/powers/installed/sabia/skills" : curto(PASTA_SKILLS[alvo]());
-  return compilar(fw, sabia("compilado", alvo), { base, raiz: alvo === "kiro", versao });
+  return compilar(fw, sabia("compilado", alvo), { base: baseSabia(alvo), raiz: alvo === "kiro", versao });
 }
 
 async function instalarAlvo(alvo, inv, opcoes) {
@@ -309,15 +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(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/. */
@@ -359,7 +375,7 @@ export async function instalar(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á").');
 }
 
@@ -378,8 +394,6 @@ export async function atualizar(opcoes = {}) {
   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))));
@@ -403,10 +417,11 @@ 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);
+      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);
-      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`);
@@ -423,6 +438,11 @@ 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, fw = null) {
   const f = path.join(pasta, "toolkit.json");
@@ -447,14 +467,20 @@ export function validarToolkit(pasta, nomeEsperado = null, fw = null) {
   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?.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`);
+    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 || []) {
     if (!nomeOk(a.nome)) erros.push(`agente com nome inválido (kebab-case, sem sa-): ${a.nome}`);
@@ -496,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, 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;
 }
 
@@ -535,7 +569,7 @@ 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 doInv = Object.keys(inv.alvos).filter((a) => ALVOS.includes(a));
+  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")) {
@@ -574,15 +608,20 @@ 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 || {}).filter((a) => ALVOS.includes(a)).join(",") || "kiro" });
+      alvo: Object.keys(inv.toolkits[n]?.alvos || {}).join(",") || "kiro" });
   }
 }
 
@@ -632,8 +671,6 @@ export function listarToolkits(opcoes = {}) {
 
 // ---------- 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);
 
@@ -657,16 +694,32 @@ function contextoRota(opcoes) {
   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 pasta = cfg.toolkits?.[e.toolkit]?.pasta;
-    const dir = !pasta ? sabia("toolkits", e.toolkit) : pasta.startsWith("~/") ? longo(pasta) : path.resolve(projeto, pasta);
+    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 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`);
+    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;
@@ -674,7 +727,7 @@ function contextoRota(opcoes) {
     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 };
+  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. */
@@ -705,15 +758,41 @@ function resolverFluxo(c, q) {
 
 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. */
+/** 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);
-  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 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;
-  for (const d of c.desvios) { const g = d.arquivos.find((a) => casaGlob(a, rel)); if (g) { casou = { d, g }; break; } }
+  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`);
@@ -722,11 +801,12 @@ export function rota(arquivo, opcoes = {}) {
   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}`], ["skills", [fl.skill, ...casou.d.skills].join(", ")]);
+    ["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"]);
@@ -738,19 +818,22 @@ export function rota(arquivo, opcoes = {}) {
 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. */
+/** `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 + (x.desvio ? " ⇢" : ""), origem(x), [].concat(x.chama || []).join(", ") || "—",
+    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}`])];
+    ...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) => {
@@ -769,10 +852,14 @@ export function rotaFluxo(q, opcoes = {}) {
     }
     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);
+      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(" · "))}`);
   });
-  return [colunas(cab), "", colunas(tabela), "", "```mermaid", ...out, "```"].join("\n");
+  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. */
@@ -802,15 +889,16 @@ const AJUDA = `${BANNER}
 sabia ${VERSAO} — instala o Sabiá e os toolkits no Kiro e no opencode
 
   sabia instalar   [--alvo kiro,opencode] [--versao X] [--fonte <pasta|url-git>[@ref]]
-  sabia atualizar  [--versao X]
+  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 --fluxo <skill.fluxo>   o fluxo resolvido no projeto (tabela e diagrama Mermaid)
+  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)
 
@@ -818,7 +906,7 @@ sabia ${VERSAO} — instala o Sabiá e os toolkits no Kiro e no opencode
   --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 = [];