sf-intelligence 0.1.11 → 0.1.12

package/dist/index.js

@@ -1345,11 +1345,11 @@ var init_resolve_index = __esm({
     };
     cache = /* @__PURE__ */ new WeakMap();
     getResolveIndex = async (store, options) => {
-      const cached = cache.get(store);
-      if (cached !== void 0) {
+      const cached2 = cache.get(store);
+      if (cached2 !== void 0) {
         const [countRow] = await runRows2(store, `SELECT count(*)::INT AS c FROM nodes`, []);
-        if (countRow !== void 0 && Number(countRow["c"]) === cached.nodeCount) {
-          return cached;
+        if (countRow !== void 0 && Number(countRow["c"]) === cached2.nodeCount) {
+          return cached2;
         }
       }
       if (options?.graphDbPath !== void 0) {
@@ -26946,7 +26946,7 @@ var init_capabilities = __esm({
     ROUTING_GUIDANCE = {
       startHere: "On a vague or broad question, call sfi.route_question first \u2014 it returns the plane (vault | live | hybrid | unknown) and the tools to run. Default to the offline vault. Use sfi.live_* only for record counts, samples, population, describe, org limits, or inactive users \u2014 and only when the org has live consent (sfi.live_consent), SFI_LIVE_PLANE_ENABLED=1, or liveEnabled: true. Before destructive verdicts, call sfi.coverage_report.",
       onAmbiguous: "On ambiguous resolution, clarify the component first. If the user wants live data and live is disabled, say so and offer to enable it once with sfi.live_consent { grant: true } (read-only) \u2014 do not guess from the vault.",
-      onNone: "On none, offer /sfi-refresh for metadata gaps. For live-record questions when offline, name sfi.live_count or sfi.live_sample and the consent requirement \u2014 never invent counts. On a route_question unknown, say the capability is not built yet (the gap is logged) rather than fabricating.",
+      onNone: "On none, offer /sfi-refresh for metadata gaps. For live-record questions when offline, name sfi.live_count or sfi.live_sample and the consent requirement \u2014 never invent counts. When route_question returns toolCandidates (no rule placed the question, or it matched only weakly), follow its `guidance`: those candidates are an advisory shortlist \u2014 pick the right tool(s) from them, resolve any named component, run them, then synthesize. Do NOT say the capability is unbuilt when candidates are offered. Only a true unknown with NO candidates means the capability is not built yet (the gap is logged).",
       groundAnswer: "Run the routed tools, then synthesize ONE answer from their output via sfi.synthesize_answer { question, draft }. It returns hallucinatedIds \u2014 any canonical id you wrote that no tool returned. Strip those before answering; cite only ids the tools produced, with their provenance."
     };
     BOUNDARIES4 = [
@@ -46749,6 +46749,283 @@ var init_retrieve_blindspot_report = __esm({
   }
 });
 
+// ../mcp/dist/src/semantic-funnel.js
+var STOPWORDS, SYNONYMS, tokenize6, TOOL_KEYWORDS, expand, buildToolDocs, cached, buildIndex, getFunnelIndex, semanticCandidates;
+var init_semantic_funnel = __esm({
+  "../mcp/dist/src/semantic-funnel.js"() {
+    "use strict";
+    init_capabilities();
+    init_tools();
+    STOPWORDS = /* @__PURE__ */ new Set([
+      "the",
+      "a",
+      "an",
+      "of",
+      "to",
+      "in",
+      "on",
+      "for",
+      "and",
+      "or",
+      "is",
+      "are",
+      "do",
+      "does",
+      "did",
+      "what",
+      "which",
+      "show",
+      "me",
+      "my",
+      "this",
+      "that",
+      "these",
+      "those",
+      "how",
+      "where",
+      "when",
+      "who",
+      "whom",
+      "can",
+      "could",
+      "i",
+      "it",
+      "its",
+      "have",
+      "has",
+      "had",
+      "with",
+      "from",
+      "get",
+      "give",
+      "list",
+      "tell",
+      "about",
+      "all",
+      "any",
+      "our",
+      "we",
+      "us",
+      "you",
+      "your",
+      "be",
+      "been",
+      "there",
+      "here",
+      "into",
+      "at",
+      "by",
+      "as",
+      "so",
+      "if",
+      "then",
+      "will"
+    ]);
+    SYNONYMS = {
+      // permissions / access / sharing
+      access: ["permission", "permissions", "sharing", "visibility", "visible", "crud", "grant"],
+      permission: ["access", "permissions", "grant", "profile", "permissionset", "effective"],
+      permissions: ["permission", "access", "effective", "profile"],
+      see: ["access", "visibility", "visible", "sharing", "view"],
+      visible: ["access", "visibility", "see", "sharing"],
+      create: ["access", "crud", "object", "insert"],
+      read: ["access", "crud", "view"],
+      edit: ["access", "crud", "modify", "write", "update", "editable"],
+      modify: ["edit", "write", "change", "access"],
+      delete: ["access", "crud", "remove", "deletion", "deletable"],
+      remove: ["delete", "deletion"],
+      admin: ["permission", "permissions", "modify", "view", "risk", "effective"],
+      profile: ["permission", "permissions", "permissionset", "effective"],
+      // usage / dependency / impact
+      references: ["usage", "usages", "used", "reference", "depends", "uses", "find"],
+      reference: ["usage", "usages", "references", "used"],
+      referenced: ["usage", "usages", "references", "used"],
+      used: ["usage", "usages", "references", "uses", "find"],
+      uses: ["usage", "usages", "used"],
+      depends: ["dependency", "usage", "usages", "impact", "depend", "references"],
+      depend: ["dependency", "usage", "depends", "impact"],
+      break: ["impact", "depend", "dependency", "breaks", "affected"],
+      // schema / enumeration
+      objects: ["object", "sobject", "components", "schema", "list"],
+      object: ["sobject", "table", "entity", "components"],
+      fields: ["field", "columns", "components", "list"],
+      list: ["components", "enumerate", "inventory"],
+      relationship: ["lookup", "child", "parent", "schema", "related"],
+      child: ["lookup", "relationship", "parent", "components"],
+      // counts / live records
+      how: ["count", "many", "number"],
+      many: ["count", "number"],
+      show: ["sample", "records"],
+      sample: ["records", "show"],
+      // change / audit / freshness
+      changed: ["modified", "change", "history", "audit"],
+      change: ["modified", "history", "changed"],
+      fresh: ["health", "stale", "freshness", "vault", "current"],
+      stale: ["fresh", "freshness", "health", "outdated", "current"],
+      inactive: ["active", "disabled", "draft", "obsolete"],
+      // meaning / docs / misc
+      help: ["meaning", "explain", "description", "text"],
+      meaning: ["explain", "field", "help"],
+      doc: ["document", "documentation", "handbook", "overview"],
+      compare: ["diff", "difference", "across"],
+      pii: ["sensitive", "personal", "compliance", "privacy"],
+      run: ["execute", "fire", "trigger", "runs", "execution"],
+      user: ["profile", "permissionset", "member"],
+      field: ["column", "attribute"],
+      // Intent verbs (generalize across phrasings, unlike tool-specific keywords).
+      touches: ["impact", "depend", "dependency", "affected", "usage", "references", "uses"],
+      relies: ["depend", "dependency", "impact", "usage", "references"],
+      falls: ["break", "breaks", "impact", "affected"],
+      dump: ["list", "inventory", "enumerate", "components"],
+      inventory: ["list", "enumerate", "components", "all"],
+      exist: ["list", "count", "inventory", "many"],
+      blow: ["governor", "limit", "risk", "exceed"],
+      populated: ["population", "filled", "fill", "usage"],
+      required: ["mandatory", "needed", "blank", "null"],
+      walk: ["explain", "trace", "describe", "order", "execution"]
+    };
+    tokenize6 = (text) => {
+      const raw = text.toLowerCase().replace(/[‘’ʼ']/g, "'").replace(/[^a-z0-9]+/g, " ").split(/\s+/).filter((t2) => t2.length > 1 && !STOPWORDS.has(t2));
+      const out = [];
+      for (const t2 of raw) {
+        out.push(t2);
+        if (t2.length > 3 && t2.endsWith("s") && !t2.endsWith("ss"))
+          out.push(t2.slice(0, -1));
+      }
+      return out;
+    };
+    TOOL_KEYWORDS = {
+      "sfi.list_components": "list inventory enumerate catalog all what do we have how many exist objects fields flows classes triggers profiles permission sets layouts record types validation rules approval processes reports dashboards omniscripts custom standard relationship child parent inactive active picklist values",
+      "sfi.capabilities": "what can you do help capabilities what can i ask how do i use",
+      "sfi.automation_risk_report": "objects more than one multiple triggers per object trigger quality automation risk",
+      "sfi.live_group_count": "how many users assigned to profile membership group count",
+      "sfi.annotations": "who owns owner steward responsible curated note",
+      "sfi.last_modified": "who changed when modified last edited touched",
+      "sfi.search_flow_metadata": "find flows matching named sync search flow by name",
+      "sfi.who_can_access_object": "who can access object which profiles can read create edit delete",
+      "sfi.live_sample": "show me sample example first few records rows give me",
+      "sfi.governor_limit_risks": "queries soql governor limit large data volume bulk dml",
+      "sfi.what_if_change_method_signature": "change method signature parameter argument breaks",
+      "sfi.layout_for_user": "which layout does the profile user see page on object",
+      "sfi.integration_map": "api limits at risk integration volume callout capacity external",
+      "sfi.find_apex_usages": "which flows invoke call use apex classes methods from",
+      "sfi.live_folder_access": "who can access report dashboard folder pipeline see view shared"
+    };
+    expand = (tokens) => {
+      const out = [...tokens];
+      for (const t2 of tokens) {
+        const syn = SYNONYMS[t2];
+        if (syn !== void 0)
+          out.push(...syn);
+      }
+      return out;
+    };
+    buildToolDocs = () => {
+      const docs = /* @__PURE__ */ new Map();
+      for (const tool of V01_TOOLS) {
+        const nameWords = tool.name.replace(/^sfi\./, "").replace(/_/g, " ");
+        const keywords = TOOL_KEYWORDS[tool.name] ?? "";
+        docs.set(tool.name, `${nameWords} ${nameWords} ${tool.description} ${keywords}`);
+      }
+      for (const cat of CATEGORIES) {
+        const catText = ` ${cat.title} ${cat.description} ${cat.exampleQuestions.join(" ")}`;
+        for (const toolName of cat.tools) {
+          const prev = docs.get(toolName);
+          if (prev !== void 0)
+            docs.set(toolName, prev + catText);
+        }
+      }
+      return docs;
+    };
+    cached = null;
+    buildIndex = () => {
+      const docs = buildToolDocs();
+      const toolCategory = /* @__PURE__ */ new Map();
+      for (const cat of CATEGORIES) {
+        for (const tool of cat.tools)
+          if (!toolCategory.has(tool))
+            toolCategory.set(tool, cat.id);
+      }
+      const docTokens = /* @__PURE__ */ new Map();
+      const df = /* @__PURE__ */ new Map();
+      for (const [tool, doc] of docs) {
+        const toks = tokenize6(doc);
+        docTokens.set(tool, toks);
+        for (const term of new Set(toks))
+          df.set(term, (df.get(term) ?? 0) + 1);
+      }
+      const n2 = docs.size;
+      const idf = /* @__PURE__ */ new Map();
+      for (const [term, d2] of df)
+        idf.set(term, Math.log((n2 + 1) / (d2 + 1)) + 1);
+      const vectors = /* @__PURE__ */ new Map();
+      for (const [tool, toks] of docTokens) {
+        if (toks.length === 0) {
+          vectors.set(tool, /* @__PURE__ */ new Map());
+          continue;
+        }
+        const tf = /* @__PURE__ */ new Map();
+        for (const t2 of toks)
+          tf.set(t2, (tf.get(t2) ?? 0) + 1);
+        const vec = /* @__PURE__ */ new Map();
+        let norm = 0;
+        for (const [term, f2] of tf) {
+          const w2 = f2 / toks.length * (idf.get(term) ?? 0);
+          vec.set(term, w2);
+          norm += w2 * w2;
+        }
+        norm = Math.sqrt(norm) || 1;
+        for (const [term, w2] of vec)
+          vec.set(term, w2 / norm);
+        vectors.set(tool, vec);
+      }
+      return { vectors, idf, toolCategory };
+    };
+    getFunnelIndex = () => cached ??= buildIndex();
+    semanticCandidates = (question, k2 = 8) => {
+      const idx = getFunnelIndex();
+      const qTokens = expand(tokenize6(question));
+      if (qTokens.length === 0)
+        return [];
+      const qtf = /* @__PURE__ */ new Map();
+      for (const t2 of qTokens)
+        qtf.set(t2, (qtf.get(t2) ?? 0) + 1);
+      const qvec = /* @__PURE__ */ new Map();
+      let qnorm = 0;
+      for (const [term, f2] of qtf) {
+        const w2 = f2 / qTokens.length * (idx.idf.get(term) ?? 0);
+        if (w2 > 0) {
+          qvec.set(term, w2);
+          qnorm += w2 * w2;
+        }
+      }
+      qnorm = Math.sqrt(qnorm) || 1;
+      if (qvec.size === 0)
+        return [];
+      const scored = [];
+      for (const [tool, vec] of idx.vectors) {
+        let dot = 0;
+        const [small, large] = qvec.size <= vec.size ? [qvec, vec] : [vec, qvec];
+        for (const [term, w2] of small) {
+          const o2 = large.get(term);
+          if (o2 !== void 0)
+            dot += w2 * o2;
+        }
+        if (dot <= 0)
+          continue;
+        const score = dot / qnorm;
+        scored.push({
+          tool,
+          score: Math.round(score * 1e3) / 1e3,
+          category: idx.toolCategory.get(tool) ?? null
+        });
+      }
+      scored.sort((a2, b2) => b2.score - a2.score || a2.tool.localeCompare(b2.tool));
+      return scored.slice(0, k2);
+    };
+  }
+});
+
 // ../mcp/dist/src/tools/tool-profile.js
 var CORE_PROFILE_TOOLS, toolProfile;
 var init_tool_profile = __esm({
@@ -46781,7 +47058,7 @@ var init_tool_profile = __esm({
 // ../mcp/dist/src/tools/route-question.js
 import { createHash as createHash6 } from "node:crypto";
 import { z as z113 } from "zod";
-var RESOLVE_FALLBACK_MAX_TOKENS, tryResolveFallback, routeQuestionInputSchema, routeTrust, clarificationIdFor, selectedEntityArgsForRoute, extractEntityQuery, inferEntityTypes, refineEntityResolution, applyGlossaryAliases, entityAmbiguityRequiresClarification, splitCompoundQuestion, mixedInventoryAndStoragePlan, routeQuestionHandler;
+var RESOLVE_FALLBACK_MAX_TOKENS, tryResolveFallback, routeQuestionInputSchema, routeTrust, clarificationIdFor, selectedEntityArgsForRoute, extractEntityQuery, inferEntityTypes, refineEntityResolution, applyGlossaryAliases, entityAmbiguityRequiresClarification, splitCompoundQuestion, mixedInventoryAndStoragePlan, PLAN_FAMILY, ASSESSMENT_FAMILY, rerankForMode, guidanceForMode, routerMode, routeQuestionHandler;
 var init_route_question = __esm({
   "../mcp/dist/src/tools/route-question.js"() {
     "use strict";
@@ -46789,6 +47066,7 @@ var init_route_question = __esm({
     init_src();
     init_answer_render();
     init_intent_router();
+    init_semantic_funnel();
     init_resolve2();
     init_tool_profile();
     RESOLVE_FALLBACK_MAX_TOKENS = 3;
@@ -46844,7 +47122,16 @@ var init_route_question = __esm({
       clarificationResponse: z113.object({
         clarificationId: z113.string().min(1),
         selection: z113.string().min(1)
-      }).optional()
+      }).optional(),
+      /**
+       * CAE-04 output mode — shapes how the host LLM should answer and which candidate
+       * tools to favor. 'ask' = a quick grounded answer (the default behavior);
+       * 'plan' = an ordered change plan (favors the what_if_* / impact tools);
+       * 'assessment' = a full evaluation (favors the *_risk_report / readiness /
+       * coverage tools). When set, toolCandidates + a mode-specific guidance line are
+       * always attached, regardless of the deterministic route's confidence.
+       */
+      mode: z113.enum(["ask", "plan", "assessment"]).optional()
     });
     routeTrust = () => ({
       provenance: "offline_snapshot",
@@ -46852,7 +47139,7 @@ var init_route_question = __esm({
       freshness: {},
       completeness: { status: "complete" },
       limitations: [
-        "Routing is a deterministic heuristic over the question text \u2014 it suggests tools, it does not answer. A short, otherwise-unroutable phrase that names a real vault component is rescued to sfi.resolve (a vault lookup), so that one path also consults the vault. Resolve any named component and confirm the plane before trusting an answer."
+        "In the default hybrid mode the meaning-ranked toolCandidates are PRIMARY and the host LLM decides which to run; the deterministic route is a non-authoritative hint, not the answer (SFI_ROUTER_MODE=offline makes the route authoritative for no-LLM hosts). A short phrase that merely names a real vault component is rescued to sfi.resolve so that path also consults the vault. Resolve any named component and confirm the plane before trusting an answer."
       ]
     });
     clarificationIdFor = (sourceTreeHash, route) => {
@@ -47034,6 +47321,30 @@ var init_route_question = __esm({
         }
       ];
     };
+    PLAN_FAMILY = /^sfi\.(what_if_|get_impact|safe_to_delete|downstream_effects|tests_for_change|field_lineage)/;
+    ASSESSMENT_FAMILY = /(_risk_report$|^sfi\.release_readiness|^sfi\.promotion_readiness|^sfi\.coverage_report|^sfi\.tech_debt_score|^sfi\.governor_limit_risks|^sfi\.crud_fls_audit)/;
+    rerankForMode = (cands, mode) => {
+      if (mode === void 0 || mode === "ask")
+        return cands.slice(0, 8);
+      const fam = mode === "plan" ? PLAN_FAMILY : ASSESSMENT_FAMILY;
+      const lead = cands.filter((c2) => fam.test(c2.tool));
+      const rest = cands.filter((c2) => !fam.test(c2.tool));
+      return [...lead, ...rest].slice(0, 8);
+    };
+    guidanceForMode = (mode) => {
+      const tail = " The candidates are an advisory shortlist, not a route \u2014 YOU pick. Resolve any named component first, ground the final answer with sfi.synthesize_answer, and never answer from a tool name alone.";
+      switch (mode) {
+        case "plan":
+          return "PLAN mode: produce an ORDERED change plan. Favor the what_if_* / get_impact / safe_to_delete candidates, sequence them by dependency, and present numbered steps, each with its risk." + tail;
+        case "assessment":
+          return "ASSESSMENT mode: produce a full EVALUATION. Favor the *_risk_report / readiness / coverage candidates, run them, and present findings with severity + recommended actions." + tail;
+        case "ask":
+          return "ASK mode: answer concisely. Pick the candidate(s) that most directly answer, run them, and synthesize ONE short grounded answer." + tail;
+        default:
+          return "These toolCandidates are the meaning-ranked shortlist \u2014 they are PRIMARY and YOU decide. A deterministic `route` is also attached, but only as a HINT (a suggested tool order plus any resolved entity ids / suggestedArgs) \u2014 never follow it blindly. Plan: read the question \u2192 resolve any named component with sfi.resolve \u2192 pick the tool(s) to run from the candidates (sequence them if compound) \u2192 run them \u2192 ground the answer with sfi.synthesize_answer. Never answer from a tool name alone.";
+      }
+    };
+    routerMode = () => (process.env.SFI_ROUTER_MODE ?? "").trim().toLowerCase() === "offline" ? "offline" : "hybrid";
     routeQuestionHandler = async (ctx, input2) => {
       let route = classifyQuestion(input2.question);
       if (route.plane === "unknown" && route.intent === "unrouted") {
@@ -47213,6 +47524,9 @@ var init_route_question = __esm({
         const args = i2 === primaryIdx ? route.suggestedArgs ?? {} : {};
         return CORE_PROFILE_TOOLS.has(tool) ? { tool, args } : { tool: "sfi.run_analysis", args: { name: tool, args } };
       }) : void 0;
+      const wantCandidates = routerMode() === "hybrid";
+      const toolCandidates = wantCandidates ? rerankForMode(semanticCandidates(input2.question, input2.mode !== void 0 ? 12 : 8), input2.mode) : [];
+      const guidance = toolCandidates.length > 0 ? guidanceForMode(input2.mode) : void 0;
       return ok({
         data: {
           route,
@@ -47220,8 +47534,12 @@ var init_route_question = __esm({
           ...entityEvidence !== void 0 ? { entityEvidence } : {},
           ...clarificationResolution !== void 0 ? { clarificationResolution } : {},
           gapLogged: logged !== null,
-          rendered: renderRouteMarkdown(route),
+          rendered: toolCandidates.length > 0 ? `${renderRouteMarkdown(route)}
+
+**Candidate tools (the shortlist \u2014 ranked by meaning; the route above is only a hint). You pick, then run:** ${toolCandidates.map((c2) => c2.tool).join(", ")}` : renderRouteMarkdown(route),
           trust: routeTrust(),
+          ...toolCandidates.length > 0 ? { toolCandidates } : {},
+          ...guidance !== void 0 ? { guidance } : {},
           ...invoke !== void 0 ? { invoke } : {}
         },
         vaultState: {
@@ -50293,9 +50611,9 @@ var init_tests_for_change = __esm({
       }
       const nodeCache = /* @__PURE__ */ new Map();
       const loadNode2 = async (id) => {
-        const cached = nodeCache.get(id);
-        if (cached !== void 0)
-          return ok(cached);
+        const cached2 = nodeCache.get(id);
+        if (cached2 !== void 0)
+          return ok(cached2);
         const r2 = await getNodeById(ctx.graph, id);
         if (!r2.ok) {
           return err({ kind: "internal", message: `graph query failed: ${r2.error.message}` });
@@ -53191,7 +53509,7 @@ var init_what_if_remove_picklist_value = __esm({
 
 // ../mcp/dist/src/tools/what-if-split-profile.js
 import { z as z138 } from "zod";
-var PROFILE_PREFIX2, PERMISSION_SET_PREFIX, SPLIT_DEFAULT_LIMIT, SPLIT_MAX_LIMIT, DISCLOSURE18, whatIfSplitProfileInputSchema, tokenize6, makeCandidate, resolveTargets, overlapCount, keywordMatch, domainClusterMatch, assignGrant, splitGrants, fetchProfile2, sortAssignments, sortUnassigned, whatIfSplitProfileHandler;
+var PROFILE_PREFIX2, PERMISSION_SET_PREFIX, SPLIT_DEFAULT_LIMIT, SPLIT_MAX_LIMIT, DISCLOSURE18, whatIfSplitProfileInputSchema, tokenize7, makeCandidate, resolveTargets, overlapCount, keywordMatch, domainClusterMatch, assignGrant, splitGrants, fetchProfile2, sortAssignments, sortUnassigned, whatIfSplitProfileHandler;
 var init_what_if_split_profile = __esm({
   "../mcp/dist/src/tools/what-if-split-profile.js"() {
     "use strict";
@@ -53209,7 +53527,7 @@ var init_what_if_split_profile = __esm({
       limit: z138.number().int().min(1).max(SPLIT_MAX_LIMIT).optional(),
       offset: z138.number().int().min(0).optional()
     });
-    tokenize6 = (raw) => {
+    tokenize7 = (raw) => {
       const spaced = raw.replace(/[._\-/]/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").replace(/([A-Z])([A-Z][a-z])/g, "$1 $2");
       return spaced.split(/\s+/).map((t2) => t2.toLowerCase().trim()).filter((t2) => t2.length > 0 && t2 !== "c" && t2 !== "__c");
     };
@@ -53218,7 +53536,7 @@ var init_what_if_split_profile = __esm({
       return {
         id,
         apiName: stripped,
-        tokens: new Set(tokenize6(stripped))
+        tokens: new Set(tokenize7(stripped))
       };
     };
     resolveTargets = async (ctx, targetIds) => {
@@ -53265,7 +53583,7 @@ var init_what_if_split_profile = __esm({
       return count;
     };
     keywordMatch = (settingId, candidates) => {
-      const settingTokens = new Set(tokenize6(settingId));
+      const settingTokens = new Set(tokenize7(settingId));
       if (settingTokens.size === 0)
         return null;
       let best = null;
@@ -53289,7 +53607,7 @@ var init_what_if_split_profile = __esm({
       }
       if (parent === null || parent.length === 0)
         return null;
-      const parentTokens = new Set(tokenize6(parent));
+      const parentTokens = new Set(tokenize7(parent));
       if (parentTokens.size === 0)
         return null;
       for (const candidate of candidates) {
@@ -56554,7 +56872,7 @@ var init_tools = __esm({
       },
       {
         name: "sfi.route_question",
-        description: "Front-door router: map a plain-language question to the plane that answers it (vault | live | hybrid | unknown) and the ordered sfi.* tools to call \u2014 so the user never types a tool name. Read-only; it suggests a route, it does not answer. Compound questions carry step ids and `dependsOn` edges: independent steps may run in parallel; a `then`-linked step waits for its prerequisite. On ambiguity it fails closed with `executionBlocked`, a clarification id, and offered options; resume deterministically by calling again with the exact same question plus `clarificationResponse: { clarificationId, selection }`. Stale ids and invented selections are rejected. Tells you when to sfi.resolve a named component first, whether the opt-in live plane is required, surfaces `suggestedArgs` (heuristic per-intent hints \u2014 e.g. `event: 'update'` for a save-order question so you can call `what_happens_on_save` without guessing the DML event), and \u2014 when the question hits a capability we lack \u2014 returns an honest 'unknown'/gap and logs it for the backlog instead of fabricating; under `SFI_TOOL_PROFILE=core` the response also carries `invoke`: the routed tools as EXECUTABLE calls (core tools direct, everything else as the byte-identical `sfi.run_analysis` gateway envelope, suggestedArgs threaded) (a short phrase that merely NAMES a real vault component, with no question, is instead routed to sfi.resolve rather than 'unknown'). Call this first on a vague/broad question to decide which tool(s) to run.",
+        description: "Front-door router: for a plain-language question, surface a meaning-ranked shortlist of the sfi.* tools that can answer it \u2014 your host LLM picks which to run \u2014 plus the plane it belongs to (vault | live | hybrid | unknown), so the user never types a tool name. Read-only; it advises, it does not answer. Compound questions carry step ids and `dependsOn` edges: independent steps may run in parallel; a `then`-linked step waits for its prerequisite. On ambiguity it fails closed with `executionBlocked`, a clarification id, and offered options; resume deterministically by calling again with the exact same question plus `clarificationResponse: { clarificationId, selection }`. Stale ids and invented selections are rejected. Tells you when to sfi.resolve a named component first, whether the opt-in live plane is required, surfaces `suggestedArgs` (heuristic per-intent hints \u2014 e.g. `event: 'update'` for a save-order question so you can call `what_happens_on_save` without guessing the DML event), and \u2014 when the question hits a capability we lack \u2014 returns an honest 'unknown'/gap and logs it for the backlog instead of fabricating; under `SFI_TOOL_PROFILE=core` the response also carries `invoke`: the routed tools as EXECUTABLE calls (core tools direct, everything else as the byte-identical `sfi.run_analysis` gateway envelope, suggestedArgs threaded) (a short phrase that merely NAMES a real vault component, with no question, is instead routed to sfi.resolve rather than 'unknown'). In the default hybrid mode the meaning-ranked `toolCandidates` are PRIMARY: every routable question carries the shortlist (offline TF-IDF over the capability map, no neural model, no network) plus a `guidance` line stating the loop YOU own \u2014 read the candidates \u2192 resolve any named component \u2192 pick/sequence the tool(s) \u2192 run them \u2192 ground via sfi.synthesize_answer. YOU decide which to run; the deterministic `route` rides along only as a non-authoritative HINT (suggested tool order + any resolved entity / suggestedArgs). Set `SFI_ROUTER_MODE=offline` for a deterministic, no-LLM route (Design A) where the route is authoritative and candidates are omitted \u2014 for CI / air-gapped hosts. An optional `mode` ('ask' | 'plan' | 'assessment') tailors the guidance and reranks the candidates toward that mode's family \u2014 'plan' favors the what_if_* / impact tools (an ordered change plan), 'assessment' favors the *_risk_report / readiness / coverage tools (a full evaluation), 'ask' is a quick grounded answer. Call this first on a vague/broad question to decide which tool(s) to run.",
         inputSchema: ROUTE_QUESTION_INPUT_SCHEMA
       },
       {
@@ -58026,7 +58344,7 @@ var init_server = __esm({
 
 How to use it well:
 - To orient a fresh session, or to answer "what can you do / what can I ask?", call \`sfi.capabilities\` (no arguments). It returns the categorized capability map, the live tool count, and the recommended conversational pattern.
-- For a vague, broad, or compound question ("how many Accounts", "who can edit SSN", "which reports are useless", "what runs on save"), call \`sfi.route_question\` FIRST. It returns the plane, ordered tools, and a dependency-aware plan. If \`executionBlocked\` is true, STOP and ask \`route.clarification.question\` before running any routed tool. Resume only with the exact offered \`clarificationId\` + selection; never invent an option. Execute plan steps only after their \`dependsOn\` steps. On an \`unknown\` route, tell the user the capability is not built rather than guessing.
+- For a vague, broad, or compound question ("how many Accounts", "who can edit SSN", "which reports are useless", "what runs on save"), call \`sfi.route_question\` FIRST. In the default hybrid mode it returns \`toolCandidates\` \u2014 a meaning-ranked shortlist of tools \u2014 as the PRIMARY output, plus a \`guidance\` line: YOU read the candidates, resolve any named component, pick/sequence the tool(s), run them, and ground via \`sfi.synthesize_answer\`. The deterministic \`route\` (plane, ordered tools, dependency-aware plan) rides along as a non-authoritative HINT \u2014 use it to inform your pick, not as a command. If \`executionBlocked\` is true, STOP and ask \`route.clarification.question\` before running any routed tool; resume only with the exact offered \`clarificationId\` + selection, never an invented option. When neither the candidates nor the route place a question, tell the user the capability is not built rather than guessing. (A no-LLM host can set \`SFI_ROUTER_MODE=offline\` to make the deterministic route authoritative and omit candidates.)
 - When the user names a component informally ("the email field", "the payment object", a typo), call \`sfi.resolve\` FIRST. It returns ranked candidates with a disposition: exact | ambiguous | none. Never guess a canonical id from memory. On \`ambiguous\`, ask the user to pick from the candidates; on \`none\`, offer \`/sfi-refresh\` (the vault may be stale) or stop \u2014 never fabricate a match.
 - Every org artifact you name must come from an \`sfi.*\` tool call and be cited with its canonical id (e.g. \`CustomField:Account.Industry__c\`). Disclose provenance per claim: \`offline_snapshot\` for vault answers, \`live_org\` for live answers (stamp the as-of time from \`trust.freshness\`), \`hybrid\` when you fuse both \u2014 never let a live count imply the vault proved something, or vice-versa.
 - Answers are only as fresh as the last refresh; if \`sfi.health_check\` reports stale or missing, tell the user to run \`/sfi-refresh\`. Record-level data (counts, samples, field population, org limits, inactive users) is LIVE, read-only, and queried at call time. The live plane is opt-in PER ORG: enable it once with \`sfi.live_consent { grant: true }\` (persists across sessions; still strictly read-only) \u2014 or SFI_LIVE_PLANE_ENABLED=1, or \`liveEnabled: true\` for a single call. If it is disabled, say so and offer to enable it; never infer record values from the vault.`;
@@ -58243,6 +58561,7 @@ var init_src7 = __esm({
     init_server();
     init_serve_http();
     init_tools();
+    init_semantic_funnel();
   }
 });
 
@@ -59448,7 +59767,7 @@ var init_package_version = __esm({
     "use strict";
     readCliPackageVersion = () => {
       if (true)
-        return "0.1.11";
+        return "0.1.12";
       for (const rel of ["../package.json", "../../package.json"]) {
         try {
           const raw = readFileSync3(fileURLToPath(new URL(rel, import.meta.url)), "utf8");
@@ -126264,7 +126583,7 @@ import { appendFile as appendFile4, mkdir as mkdir12, readdir as readdir6, readF
 import { tmpdir as tmpdir2 } from "node:os";
 import { join as join26, resolve as resolve4 } from "node:path";
 import { promisify as promisify4 } from "node:util";
-var execAsync, SF_API_VERSION2, EMPTY_COUNTS, EMPTY_SKIPPED, failed, PACKAGE_VERSION, extractCachePath, loadExtractCache, saveExtractCache, applyApexAstEdges, runRefresh, preserveFactsForSideBuild, aggregateFailuresByType, buildCoverageEntries2, decoratePendingCoverage, decorateReportsCapCoverage, countGraphTotals, fullRebuild, importGraph, persistResolveIndexBestEffort, runWithOpenGraph, appendRefreshHistory, appendRiskScores, writeOnboardingDoc, writeOrgCard, diffCounts, sumCounts, metricCounts, signedDelta, findAnnotationOrphans, buildRefreshPulse, computeChangeSummary, TOOLING_API_ENRICHED_TYPES, runToolingApiEnrichment, loadVaultConfig, METADATA_API_NAME2, toApiName, SF_MAX_BUFFER, STANDARD_OBJECTS_TO_MODEL, manifestMembersForType, appendStandardObjectDescribeFields, AUTOMATION_EDGE_TYPES, objectsToExpandManifest, buildPackageXml, getOrgSupportedTypes, selectManifestTypes, classifyRetrieveError, splitTypeBatch, firstErrorLine, summarizeRetrieveFailures, retrieveWithFallback, retrieveTypeBatch, runSfRetrieve, computeReconciledTypes, runSfRetrieveObjects, buildFolderedReportManifest, REPORT_META_SUFFIXES, REPORT_DIR_MARKERS, countLandedReportMembers, collectReportMetaFiles, runSfRetrieveFolderedReports, reportsCap, runSfRetrieveSmartReports, formatFailure, formatBlock, formatChangeSummary, formatRefreshSummary, formatReportsCapSummary, SKIPPED_TOP_N, KNOWN_UNMODELED_SKIP_DIRS, formatSkippedWarning, formatToolingApiSummary, demandCoverageStatusOf, DEMAND_REFUSAL_REASON, classifyForDemandRetrieve, markDemandQueueDrains, runDemandRetrieve, formatDemandRetrieveSummary, registerRefreshCommand;
+var execAsync, SF_API_VERSION2, EMPTY_COUNTS, EMPTY_SKIPPED, failed, PACKAGE_VERSION, extractCachePath, loadExtractCache, saveExtractCache, applyApexAstEdges, runRefresh, preserveFactsForSideBuild, aggregateFailuresByType, buildCoverageEntries2, decoratePendingCoverage, decorateReportsCapCoverage, countGraphTotals, fullRebuild, importGraph, persistResolveIndexBestEffort, runWithOpenGraph, appendRefreshHistory, appendRiskScores, writeOnboardingDoc, writeOrgCard, diffCounts, sumCounts, metricCounts, signedDelta, findAnnotationOrphans, buildRefreshPulse, computeChangeSummary, TOOLING_API_ENRICHED_TYPES, runToolingApiEnrichment, loadVaultConfig, METADATA_API_NAME2, toApiName, SF_MAX_BUFFER, STANDARD_OBJECTS_TO_MODEL, manifestMembersForType, appendStandardObjectDescribeFields, AUTOMATION_EDGE_TYPES, objectsToExpandManifest, buildPackageXml, getOrgSupportedTypes, selectManifestTypes, classifyRetrieveError, splitTypeBatch, salientErrorLine, summarizeRetrieveFailures, retrieveWithFallback, retrieveTypeBatch, runSfRetrieve, computeReconciledTypes, runSfRetrieveObjects, buildFolderedReportManifest, REPORT_META_SUFFIXES, REPORT_DIR_MARKERS, countLandedReportMembers, collectReportMetaFiles, runSfRetrieveFolderedReports, reportsCap, runSfRetrieveSmartReports, formatFailure, formatBlock, formatChangeSummary, formatRefreshSummary, formatReportsCapSummary, SKIPPED_TOP_N, KNOWN_UNMODELED_SKIP_DIRS, formatSkippedWarning, formatToolingApiSummary, demandCoverageStatusOf, DEMAND_REFUSAL_REASON, classifyForDemandRetrieve, markDemandQueueDrains, runDemandRetrieve, formatDemandRetrieveSummary, registerRefreshCommand;
 var init_refresh = __esm({
   "dist/src/commands/refresh.js"() {
     "use strict";
@@ -126473,10 +126792,10 @@ var init_refresh = __esm({
         progress(`Incremental: reused ${walked.reusedCount} unchanged file(s) from cache.`);
       }
       if (!opts.noPull && (requestedTypes === null || requestedTypes.has("CustomObject"))) {
-        const expand = objectsToExpandManifest(walked.results);
-        if (expand.length > 0) {
-          progress(`Auto-expanding retrieve: ${expand.length} object(s) your automation references but the wildcard excluded...`);
-          const pulled2 = await runSfRetrieveObjects(targetOrg, paths.source, expand);
+        const expand2 = objectsToExpandManifest(walked.results);
+        if (expand2.length > 0) {
+          progress(`Auto-expanding retrieve: ${expand2.length} object(s) your automation references but the wildcard excluded...`);
+          const pulled2 = await runSfRetrieveObjects(targetOrg, paths.source, expand2);
           if (pulled2.ok) {
             walked = await walkAndExtract(paths.source, requestedTypes, prevCache);
           } else {
@@ -127397,7 +127716,6 @@ ${card.body}
         /no authorization|not authorized|no auth information|expired access\/refresh token|invalid[_ ]grant/i,
         /org ?login|sfdx[_ ]?login|requires? you to (?:re-?)?authenticate|session expired/i,
         /does not contain a valid salesforce dx project/i,
-        /enotfound|etimedout|econnrefused|enetunreach|getaddrinfo|socket hang up|network error|unable to connect|connection timed out/i,
         /no default (?:environment|org)|no target-?org|no org configured|requires a target org/i
       ];
       return GLOBAL_SIGNALS.some((re2) => re2.test(message)) ? "global" : "per-type";
@@ -127406,17 +127724,24 @@ ${card.body}
       const mid = Math.floor(types.length / 2);
       return [types.slice(0, mid), types.slice(mid)];
     };
-    firstErrorLine = (error) => (error.split("\n")[0] ?? error).trim();
+    salientErrorLine = (error) => {
+      const lines = error.split("\n").map((l2) => l2.trim()).filter((l2) => l2.length > 0);
+      const named = lines.find((l2) => /^Error\b|Error \(|^ERROR\b|UnsafeFilepathError|INVALID_TYPE/.test(l2));
+      if (named !== void 0)
+        return named;
+      const nonWrapper = lines.find((l2) => !l2.startsWith("Command failed:"));
+      return nonWrapper ?? lines[0] ?? error.trim();
+    };
     summarizeRetrieveFailures = (failures) => {
       if (failures.length === 0)
         return "";
-      const uniqueReasons = new Set(failures.map((f2) => firstErrorLine(f2.error)));
+      const uniqueReasons = new Set(failures.map((f2) => salientErrorLine(f2.error)));
       if (uniqueReasons.size === 1) {
         const [reason] = [...uniqueReasons];
         const [first] = failures;
         return failures.length === 1 && first !== void 0 ? `${first.type}: ${reason}` : reason ?? "";
       }
-      return failures.map((f2) => `${f2.type} (${firstErrorLine(f2.error)})`).join("; ");
+      return failures.map((f2) => `${f2.type} (${salientErrorLine(f2.error)})`).join("; ");
     };
     retrieveWithFallback = async (allTypes, retrieveBatch) => {
       const succeeded = [];
@@ -127446,19 +127771,23 @@ ${card.body}
     retrieveTypeBatch = async (targetOrg, sourceDir, types) => {
       const stamp = `${Date.now()}-${types.length}-${types[0] ?? "batch"}`;
       const manifestPath = join26(tmpdir2(), `sfi-refresh-package-${stamp}.xml`);
-      const retrieveDir = join26(tmpdir2(), `sfi-retrieve-${stamp}`);
+      const projectDir = join26(tmpdir2(), `sfi-retrieve-${stamp}`);
+      const pkgDir = join26(projectDir, "force-app");
+      await mkdir12(pkgDir, { recursive: true });
+      await writeFile11(join26(projectDir, "sfdx-project.json"), `{"packageDirectories":[{"path":"force-app","default":true}],"sourceApiVersion":"${SF_API_VERSION2}"}
+`, "utf8");
       await writeFile11(manifestPath, buildPackageXml(types), "utf8");
       try {
-        await execAsync(`sf project retrieve start --manifest "${manifestPath}" --target-org "${targetOrg}" --output-dir "${retrieveDir}"`, { maxBuffer: SF_MAX_BUFFER });
-        const reconcile = await reconcileSourceDeletions(sourceDir, retrieveDir, new Set(types));
-        await syncAuthoritativeRetrieveIntoSource(sourceDir, retrieveDir);
+        await execAsync(`sf project retrieve start --manifest "${manifestPath}" --target-org "${targetOrg}"`, { maxBuffer: SF_MAX_BUFFER, cwd: projectDir });
+        const reconcile = await reconcileSourceDeletions(sourceDir, pkgDir, new Set(types));
+        await syncAuthoritativeRetrieveIntoSource(sourceDir, pkgDir);
         return ok({ deletedCount: reconcile.deletedCount });
       } catch (cause) {
         return err(cause instanceof Error ? cause.message : String(cause));
       } finally {
         await rm5(manifestPath, { force: true }).catch(() => {
         });
-        await rm5(retrieveDir, { recursive: true, force: true }).catch(() => {
+        await rm5(projectDir, { recursive: true, force: true }).catch(() => {
         });
       }
     };
@@ -127775,7 +128104,7 @@ ${typesXml}
         lines.push("", `Errors (${result.errors.length}):`, ...result.errors.map(formatFailure));
       }
       if (result.retrieveFailures !== void 0 && result.retrieveFailures.length > 0) {
-        lines.push("", `Partial retrieve \u2014 ${result.retrieveFailures.length} metadata type(s) skipped (the org may have rejected them; the vault is built from what landed):`, ...result.retrieveFailures.map((f2) => `  ${f2.type}: ${firstErrorLine(f2.error)}`));
+        lines.push("", `Partial retrieve \u2014 ${result.retrieveFailures.length} metadata type(s) skipped (the org may have rejected them; the vault is built from what landed):`, ...result.retrieveFailures.map((f2) => `  ${f2.type}: ${salientErrorLine(f2.error)}`));
       }
       if (result.fatalError !== void 0) {
         lines.push("", `Fatal: ${result.fatalError}`);
@@ -130032,7 +130361,7 @@ init_vault_git();
 init_watch();
 var readVersion = () => {
   if (true)
-    return "0.1.11";
+    return "0.1.12";
   const pkgUrl = new URL("../../package.json", import.meta.url);
   const raw = readFileSync5(fileURLToPath2(pkgUrl), "utf8");
   const parsed = JSON.parse(raw);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sf-intelligence",
-  "version": "0.1.11",
-  "description": "Offline-first, MCP-first knowledge base for a Salesforce org. Ask about your org's metadata, dependencies, permissions, and automation — grounded in real retrieved metadata. Ships the sfi CLI and an MCP server.",
+  "version": "0.1.12",
+  "description": "Offline-first, MCP-first knowledge base for a Salesforce org. Ask about your org's metadata, dependencies, permissions, and automation \u2014 grounded in real retrieved metadata. Ships the sfi CLI and an MCP server.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://salesforce-intelligence.pages.dev",
   "keywords": [
@@ -36,6 +36,11 @@
     "bin",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc --build && node build.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "node ../../scripts/prepublish-check.mjs"
+  },
   "dependencies": {
     "@duckdb/node-api": "1.5.3-r.2",
     "@inquirer/prompts": "^7.0.0",
@@ -45,21 +50,17 @@
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@sf-intelligence/contracts": "workspace:*",
+    "@sf-intelligence/core": "workspace:*",
+    "@sf-intelligence/extractors": "workspace:*",
+    "@sf-intelligence/graph": "workspace:*",
+    "@sf-intelligence/mcp": "workspace:*",
+    "@sf-intelligence/parsers": "workspace:*",
+    "@sf-intelligence/patterns": "workspace:*",
+    "@sf-intelligence/renderers": "workspace:*",
+    "@sf-intelligence/tooling-api": "workspace:*",
+    "@sf-intelligence/vault": "workspace:*",
     "esbuild": "^0.28.0",
-    "vitest": "^1.6.0",
-    "@sf-intelligence/contracts": "0.1.0",
-    "@sf-intelligence/core": "0.1.0",
-    "@sf-intelligence/extractors": "0.1.0",
-    "@sf-intelligence/mcp": "0.1.0",
-    "@sf-intelligence/patterns": "0.1.0",
-    "@sf-intelligence/renderers": "0.1.0",
-    "@sf-intelligence/tooling-api": "0.1.0",
-    "@sf-intelligence/vault": "0.1.0",
-    "@sf-intelligence/parsers": "0.1.0",
-    "@sf-intelligence/graph": "0.1.0"
-  },
-  "scripts": {
-    "build": "tsc --build && node build.mjs",
-    "test": "vitest run"
+    "vitest": "^1.6.0"
   }
-}
+}