sf-intelligence

A grounded, fail-closed backend for AI assistants working in one Salesforce org. Your AI host (Claude, or any MCP client) asks it questions in plain language; it answers from the org's real metadata — never a guess — and labels every claim with how much to lean on it.

sf-intelligence is an offline, read-only, MCP-first knowledge base for a single Salesforce org. You run one retrieve (sf project retrieve); it builds a local Markdown vault and a DuckDB dependency graph. From then on every answer is served locally by default — offline-first, no network egress for vault answers. An opt-in live read-only plane (sfi.live_*) can answer record counts and samples when enabled. Private by design. MIT + Commons Clause.

It is not a standalone chatbot — it has no chat surface. It is the evidence layer an AI host consumes: a router that advises (ranked tool candidates plus explicit disclosures), a host LLM that decides (picks and runs the tools), and an engine that grounds every answer in the vault and fails closed — refusing, disclosing a gap, or asking a clarifying question — when it cannot.

Ask it like a person

You don't need to know the exact API name of anything. The front door is a typo-tolerant resolver that turns messy phrasing into the right component — and when it isn't sure, it asks you a clarifying question instead of guessing:

You: where's the emale field?

It: I found several matches for "email" — which did you mean? · Email__c on Account · Email__c on Contact · Alternate_Email__c on Lead

You: what about the paymnet object?

It: Payment__c — one confident match.

You: is there a "warranty fee" field?

It: Nothing matched that confidently. Your vault was last refreshed on 2026-05-20 — want to pull fresh metadata from the org (/sfi-refresh) in case it's new, or rephrase?

That is the headline behavior for resolution and routing: they never silently commit to a guess. Resolution is always heuristic and labeled as such. When several components are plausible it hands you a clarifying question; when nothing matches it offers to refresh from the org or stop. A high match score is string similarity, not proof. Source grep tools (sfi.search_apex_source, sfi.search_flow_metadata) walk the vaulted source/ tree from your last refresh — run /sfi-refresh before trusting an empty grep result.

Advisory routing — the funnel advises, the host decides

Under the hood a semantic router (sfi.route_question) reads each question and returns a meaning-ranked shortlist (toolCandidates) of the sfi.* tools that can answer it — so your AI host picks and runs them without you ever typing a tool name. It runs fully offline (a small TF-IDF model over the tool catalog — no network, no embeddings service) and it advises rather than dictates: the candidates are the primary output; the deterministic route that rides along is a non-authoritative hint. The host LLM decides which tools to run, in what order.

Confidence semantics are explicit. When no deterministic intent matches but the semantic funnel's top candidate scores above a fixed floor, the router returns a funnel-advisory route — the top funnel tools, confidence low by construction, reason flagged FUNNEL-DERIVED — an advisory pick for the host to verify (resolve the named component, then ground), never a command. Each candidate row also carries cosine, its raw semantic score, so a host can tell real semantic support from a regex-rule assertion.

The router also tags each question with the plane that answers it — the offline vault (metadata, dependencies, permissions), the live org (counts, samples, limits, inactive users — read-only, opt-in), or a hybrid of both (e.g. "is this field actually populated?"). Every answer is stamped with its provenance (offline_snapshot, live_org, or hybrid) and freshness. Clarifying questions are a last resort: a qualifier already in the question ("the X object", an object word next to a same-named field, a literal API name) auto-resolves instead of blocking, and offered options are hygienic — fuzzy lookalike junk never appears as a choice. But when two genuinely competing components remain, or the best-fitting tools diverge on something consequential (one destructive-simulation, one read-only), the router stops and asks which you meant instead of letting the host silently commit. When nothing fits, it says so rather than guessing (and can log the gap locally — opt-in via logGap: true). (A deterministic, no-LLM routing mode is available via SFI_ROUTER_MODE=offline for CI / air-gapped hosts.)

An experimental, opt-in RRF hybrid embeddings layer is available for early adopters (SFI_EMBEDDINGS=1 + npm i @huggingface/transformers). It fuses the TF-IDF candidates with a locally cached neural model (~23 MB) via Reciprocal Rank Fusion. The model is not bundled with the npm package and isn't fetched automatically — it requires the separate peer-dependency install above, and the download-on-first-use path is still being hardened, so treat it as a manual opt-in step, not something that happens for you. Off by default either way — the lexical path is byte-identical when unset, and if the model isn't installed or cached the funnel silently falls back to lexical-only. The honesty/refusal decision and the deterministic route.tools plan are not affected. See docs/configuration.md for details.

Refusal behavior — fail closed, offer the read

Some questions should never route to an executable tool, no matter how well they score. Score-independent refusal gates run on the raw question before any intent matching, and a refusal is non-executable by shape (tools: [] plus a structured route.refusal disclosure):

• Write imperatives ("delete the X field for me", "go ahead and merge these profiles") → refused-write, with a read-only alternative offered instead (safe_to_delete_field, what_if_merge_profiles, get_impact, … by verb family) — the product has no write path; the refusal names the simulation that answers the underlying question safely.
• Prompt injection / record-value exfiltration ("ignore your previous instructions…", "dump all SSN values") → refused-injection, with candidates and guidance suppressed entirely.
• Runtime telemetry no tool models → honest-gap-runtime, naming the nearest real reads. Non-Salesforce asks → out-of-scope.

Legitimate reads are explicit excluders — "am I allowed to edit…", "who can delete…", "is it safe to…" are permission questions and route normally. On a 2,000-question real-org evaluation, the gates cut genuine over-confident routes from 69 to 11 with zero answerable questions falsely refused.

Conversation context — follow-ups without server-side memory

The product stores no conversation state. Instead, the host may pass an optional context.previous on each route_question call describing what the prior turn was about, and terse follow-ups ("does it fire on delete too?", "what about on Contact?", "the second one") resolve against it — pronoun substitution is an exact-id lookup (never fuzzy), an inherited tool is an advisory continuation capped at medium confidence, and a clarification pick re-dispatches through the normal clarification contract (out-of-range ordinals re-ask, stale ids are rejected). A self-contained question ignores context entirely, and refusal gates run before any context logic — context never bypasses them. Host-side, after routing "who can edit the SSN field?" and running the tools:

// next turn: "can Support Agents specifically edit it?"
{
  "question": "can Support Agents specifically edit it?",
  "context": {
    "previous": {
      "question": "who can edit the SSN field?",
      "tool": "sfi.field_access_audit",
      "componentId": "CustomField:Contact.SSN__c"
    }
  }
}

When (and only when) context changes the route, the response discloses it in route.contextApplied. See docs/routing.md for the full host contract.

Honesty guarantees

The design rule across the surface is fail closed, disclose first:

• Grounded or refused. Every answer path ends in real tool output against the vault (or the consented live org); when no tool covers the ask, the router returns an honest gap — never a lookalike tool, never general Salesforce knowledge dressed up as org fact.
• Premise checks. A question naming a component the resolver cannot find still routes (the tools fail closed on the unknown id), but confidence is downgraded and a PREMISE CHECK disclosure warns that no such component exists in the vault — and a funnel-advisory route is never granted on a failed premise.
• Disclosure-first. Coverage caveats, staleness warnings, live-consent notices, refusals, and context application are structured fields the host renders before the answer — not fine print after it.

How it works

One read-only refresh turns your org into a local vault; from then on every question is answered offline — your AI host asks the router for a shortlist, picks the tools, runs them against the vault, and grounds the answer. The host decides; the router only advises.

flowchart TB
    subgraph REFRESH["Refresh — once, and whenever the org changes"]
        direction LR
        ORG[("Salesforce org")] -->|"sf project retrieve (read-only)"| SRC["source/ raw metadata"]
        SRC -->|"extract + parse Apex / Flow / XML"| VAULT[("Graph A · Local vault<br/>your org, grounded<br/>Markdown + DuckDB graph")]
    end

    subgraph CONCEPT["Concept Model — ships with the package · no org data, ever"]
        CM[["Graph B · Concept Model<br/>153 org-independent concepts / 207 rules<br/>save-order · relationships · sharing · code-shape"]]
    end

    subgraph ASK["Ask — every question, offline on your machine"]
        direction TB
        Q["Your question<br/>(plain language)"] --> HOST["Host LLM<br/>(Claude, etc.)"]
        HOST -->|"1 · route_question"| FUNNEL["Semantic funnel<br/>offline TF-IDF — no network"]
        FUNNEL -->|"toolCandidates + guidance<br/>(ranked shortlist — advises)"| HOST
        HOST -->|"2a · retrieve: picks and runs"| TOOLS["sfi.* retrieval tools"]
        TOOLS -->|"read"| VAULT
        TOOLS -.->|"opt-in, read-only, capped"| LIVE[("Live org")]
        HOST -->|"2b · reason: resolve"| RESOLVE["sfi.resolve<br/>fix the component"]
        RESOLVE -->|"interpret"| INTERPRET["sfi.interpret · deterministic OFFLINE JOIN<br/>Concept Model × grounded vault slice<br/>no LLM · no live org read"]
        INTERPRET -->|"cited, confidence-tiered<br/>structural-implication claims"| SYNTH["3 · synthesize_answer"]
        TOOLS --> SYNTH
        SYNTH --> ANS["Grounded answer<br/>+ provenance + freshness<br/>+ cited canonical ids"]
    end

    VAULT ==>|"grounded slice · Graph A"| INTERPRET
    CM ==>|"concept rules · Graph B"| INTERPRET

Every box on the Ask path runs on your machine; the dotted edge to the live org is the only one that can touch Salesforce, and only after you opt in. Retrieval (route_question → sfi.* → synthesize_answer) reports what's in the org; the reasoning path (resolve → interpret → synthesize_answer) reports what its shape implies. sfi.interpret is a deterministic, offline join of the org-independent Concept Model (Graph B — 153 concepts / 207 rules, which never touches your org) against a grounded slice of the vault (Graph A); it runs with no LLM and no live read, and every claim it feeds synthesize_answer is cited and confidence-tiered. The deterministic SFI_ROUTER_MODE=offline mode collapses step 1 to a single routed plan for hosts with no LLM in the loop.

Reasoning, not just retrieval

Retrieval tells you what's in the org. It doesn't tell you what a structure implies — that a master-detail parent delete cascade-deletes its children, that two active before-save flows on one object run in an undefined order, or that an @AuraEnabled method is an entry point where Apex does not auto-enforce field-level security. SfIntelligence answers those with a small second graph.

Alongside the org's grounded vault, the product ships a Concept Model: 153 org-independent, curated concepts and 207 rules that encode general Salesforce truth — save-order phases, relationship semantics, sharing posture, code-shape signals. No org data lives in it; the org enters reasoning only through the grounded slice at query time. The sfi.interpret tool joins the two: it assembles a minimal graph slice around one component and fires the applicable rules to produce cited, confidence-tiered structural-implication claims. It is deterministic and offline — no LLM, no live org read — and its claims are also folded into sfi.synthesize_answer so they reach a normal answer, hedged and attributed, on any MCP host.

The concept families are curated structural patterns, not vulnerability detection. A sample of what fires today:

• Relationships — master-detail cascade-delete + read-only roll-up summary; junction (two-master) many-to-many; formula/roll-up fields are read-only, so a write to one is write-hostile.
• Automation — multiple active record-triggered flows in one trigger context (undefined execution order); a firing condition that tests a field another automation writes in the same save (cross-phase coupling); before/after trigger phases; a flow fault-path rollback gap.
• Sharing & security surface — organization-wide default (OWD) posture; without sharing system-context Apex; an external API surface (@RestResource / @AuraEnabled / @InvocableMethod) where FLS/CRUD are not auto-enforced; async boundaries; connected-app OAuth scope.
• Code shape — Apex SOQL-injection / bulkification / CRUD-FLS / swallowed- exception / hardcoded-id gaps; a test with no assertions.

Every claim is grounded or it does not exist. Each interpretation carries a groundedIn list of the exact component ids it matched — no citation ⇒ no claim — and its confidence is computed, never asserted: the weakest of the rule's ceiling and the grounding edges it matched (see the two-axis note below). An empty result means "no concept rule fired," never "nothing depends on it." And the governor/security concepts reason about static code shape — they name a surface or a coupling, not a live limit breach or a proven runtime vulnerability. For a worked resolve → interpret → synthesize example, see docs/guides/asking-questions.md §2b; for the design rationale, ADR-008.

What you can ask

Eight capability areas, each answerable in natural language (ask sfi.capabilities, or just "what can you do?", for the live map):

These are advisory, read-only briefings — e.g. automation_build_advisor, apex_build_advisor, field_change_advisor synthesize what the org already shows so you make a better build decision; find_dependency_cycles, apex_test_coverage, live_drift_check, and org_history serve architects and developers. None of them write to the org.

Every org artifact the product names is backed by a tool call and cited with its canonical ID (CustomObject:Account, CustomField:Account.Industry__c), and every relationship is cited with its confidence (declared, parsed, or heuristic).

Trust & confidence glossary

Every answer is tagged so you know how much to lean on it. These tags match the runtime values verbatim (the trust block on analysis tools, the per-edge confidence, and synthesize_answer's provenance.stamp).

Edge confidence — how a relationship was derived. This is the per-edge tier you see on dependency answers:

• declared — Salesforce metadata states it directly (a layout assignment, a field's referenceTo, a permission grant). Highest trust.
• parsed — produced by AST/XML parsing of source (the parser-grade Apex pass that runs on every refresh by default — resolved field reads/writes, cross-class calls, field-level SOQL — plus the formula tokenizer, Flow elements, a profile's <layoutAssignments>). High trust.
• heuristic — produced by regex / token / dynamic-string analysis (the Apex recall scanner that supplements the parsed pass, name-pattern detection). May have false positives — spot-check before acting.

Claim confidence — a different axis: how well a reasoning claim from sfi.interpret is grounded. It uses the same declared | parsed | heuristic words, but it is computed, not read off one edge: a claim's confidence is the weakest of the concept rule's ceiling and the grounding edges the claim matched. An absence-shaped claim under non-complete coverage reads unknown. Do not conflate the two — edge confidence describes a single relationship; claim confidence describes an interpretation that rests on one or more such edges and can never exceed the weakest of them.

Provenance — where the answer came from:

• offline_snapshot — the last /sfi-refresh vault. The default for every vault tool.
• live_org — an opt-in, capped, read-only sfi.live_* SOQL read.
• hybrid — fuses vault + live and discloses both provenances.

Completeness — how much of what the answer depends on was actually retrieved:

• complete — the refresh modeled every metadata family the answer needs.
• partial — a family the answer depends on was not retrieved; absence means "not checked", never "none" (a coverageCaveat names the gap).
• unknown — coverage could not be determined.

Two tools make this concrete. sfi.coverage_report lists what the retrieve manifest requested and returned; sfi.retrieve_blindspot_report lists what the graph references but never retrieved — automation/code/config that depends on a component the vault never pulled — so an "X is unused / nothing references X" answer carries a known-coverage caveat instead of a silent blind spot.

How much it models

What it does NOT do

Boundaries are explicit, and the product tells you plainly when it hits one rather than papering over the gap with general Salesforce knowledge:

• Offline by default. Vault tools never call Salesforce mid-conversation. Run /sfi-refresh to update metadata. Opt-in live tools (sfi.live_*) run read-only SOQL with strict caps and label answers provenance: live_org. The live plane is off until you grant once per org with sfi.live_consent { grant: true } (binds OrgId+principal, scopes+expiry; persists locally) or set SFI_LIVE_PLANE_ENABLED=1. Per-call liveEnabled: true is intent only — not a consent substitute. Step up sample / users scopes for row samples and user-identity tools. Hybrid answers fuse vault + live and disclose both provenances plus the active grant. Live never backfills stale vault claims, and the product never auto-picks which org to query.
• No record-level data. The vault stores schema and source, not rows. "How many Opportunities closed last quarter" is a question for your org directly.
• Static analysis, not runtime. Dependency edges are derived from metadata and source. Dynamic SOQL, reflective Apex, and runtime metadata lookups are invisible to static analysis — a "no references found" result means "no static evidence", not "definitely unused".
• Reasoning is deterministic rule-match, not an LLM and not a live check. sfi.interpret fires curated concept rules against the offline grounded slice. Its claims are structural implications of the code and metadata shape — it names a pattern (a cascade-delete, an undefined flow order, an unenforced entry point), and cites the ids it matched. A governor or security concept is a static-shape signal, not a proven runtime limit breach or a proven vulnerability; a claim with no citation is never made, and an empty result means "no rule fired," not "nothing depends on it."
• Read-only. The product never writes to your org. It has no write path.
• Tested scale (CI budgets). Three separate ceilings are gated in CI:
  • Graph import: 10,000 nodes in <90s (packages/graph/test/scale-import.test.ts, SCALE_IMPORT_BUDGET_MS).
  • Full refresh: 1,000 CustomObject+CustomField files by default in <10m (packages/cli/test/scale-refresh.test.ts, SCALE_REFRESH_FIELD_COUNT, SCALE_REFRESH_BUDGET_MS).
  • Resolve: p95 under 2s on the CI vault (pnpm eval:scale, SCALE_BUDGET_MS). Very large production orgs may still need narrowed retrieves or multiple vaults.

Review changes before you deploy (PR gate)

sfi.review_change is the pre-deploy gate: hand it the components a PR / package.xml / git diff touches and it returns a per-component risk verdict (blocking / risky / review / safe), each one's direct dependents, and the tests to run — most-dangerous first, entirely offline against the target org's last vault refresh. A deleted component with any dependent fails closed (blocking); a modified component with firm dependents is risky; overallVerdict is the worst across the set. Point it at another vault (againstVault) to answer "will this changeset break anything in prod?" against that org's graph.

The same analysis ships as a GitHub Action — the composite Action at .github/actions/review-change emits SARIF 2.1.0 (findings show up inline on the PR's "Files changed" tab and in the Security tab) plus a markdown PR comment, with a 0/1/2 exit-code gate. Copy docs/ci/review-change-pr-gate.example.yml into your org repo to wire it up. It never runs sfi refresh and never calls the sf CLI — it only reads an already-built vault.

Try it now — no Salesforce org needed

Want to see it work before pointing it at your own org? One command serves a built-in synthetic demo org ("Verdant Energy," a fictional solar installer) over MCP — fully offline, no auth, no sf CLI:

# Register the demo server with Claude Code (or any MCP client):
claude mcp add --transport stdio --scope user sf-intelligence-demo -- npx -y sf-intelligence demo

Then ask it things like:

• What happens when I save a Project?
• What breaks if I delete Invoice__c.Amount__c?
• Why can't an Installer see an Invoice?
• Which Apex has governor-limit risk?

The first run builds the demo vault in a few seconds (cached under ~/.sf-intelligence/demo); every run after is instant. Nothing leaves your machine. When you're ready for your real org, follow Install below.

Install

sf-intelligence is distributed on npm as sf-intelligence — an MCP server plus the sfi command-line tool. Register the server with your MCP client once, then drive everything through sfi (or, inside Claude Code, the /sfi-* slash commands that wrap it).

Requirements: Node.js 20+ and an authenticated Salesforce CLI (sf) pointed at the org you want to vault. npx fetches everything else.

Register the MCP server

Every host launches the same command; each reads a different config file in a different format. Pick yours — the full per-host, per-platform detail (exact paths for macOS and Windows, where the logs are, what to do when it doesn't connect) is in docs/guides/mcp-hosts.md.

Claude Code — from your Salesforce DX repo, add it project-scoped (writes a .mcp.json at the repo root that your team can commit):

claude mcp add --scope project sf-intelligence -- \
  npx -y sf-intelligence mcp --vault "$PWD/org-kb"

Claude Desktop — add this block to the client's MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows), then quit and reopen the app:

{
  "mcpServers": {
    "sf-intelligence": {
      "command": "npx",
      "args": ["-y", "sf-intelligence", "mcp", "--vault", "/abs/path/to/org-kb"]
    }
  }
}

VS Code + GitHub Copilot — create .vscode/mcp.json in your project. Note the top-level key is servers, not mcpServers; pasting the Claude block here parses fine and registers nothing:

{
  "servers": {
    "sf-intelligence": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sf-intelligence", "mcp"],
      "cwd": "${workspaceFolder}",
      "env": { "SFI_VAULT": "${workspaceFolder}/org-kb" }
    }
  }
}

Codex — codex mcp add sf-intelligence -- npx -y sf-intelligence mcp --vault /abs/path/to/org-kb, or the TOML equivalent in ~/.codex/config.toml.

Restart the client. The sfi.* tools are now available — ask sfi.capabilities for the live tool map.

Always pass an absolute --vault path. The server looks for ./org-kb relative to its own working directory, and most hosts pick that directory for you — Claude Desktop and a user-scope VS Code server never run inside your Salesforce project. --vault is what makes the config work anywhere.

Before your first sfi refresh the server starts in setup mode: it connects and offers one tool, sfi.setup_status, which tells your chat exactly what to run next. That is expected — just ask your assistant to set it up.

Tip: npm install -g sf-intelligence puts an sfi command on your PATH, so first-run setup is sfi init / sfi refresh instead of the longer npx -y sf-intelligence … form.

Optional: full roster vs compact core

Default is the 25-tool core roster (AUDIT-F6; includes sfi.live_consent) so MCP hosts don't pay a ~250 KB tools/list tax. Non-core tools stay reachable via sfi.run_analysis (byte-identical) and are not directly invokable under core. Set SFI_TOOL_PROFILE=full (or add "env": { "SFI_TOOL_PROFILE": "full" } in the config block above) to advertise and directly invoke the entire roster. See docs/configuration.md for the full reference.

Install as a Claude Code plugin

The MCP registration above gets you the sfi.* tools. Installing sf-intelligence as a Claude Code plugin additionally gets you 26 skills that auto-activate on Salesforce vocabulary (no need to remember tool names) and 5 slash commands (/sfi-onboard, /sfi-init, /sfi-refresh, /sfi-status, /sfi-field-audit) that wrap the sfi CLI. Install it from this repo's marketplace:

/plugin marketplace add PranavNagrecha/Salesforce-Intelligence
/plugin install sf-intelligence@sf-intelligence

Run /reload-plugins (or restart Claude Code) to pick it up in the current session; /plugin list confirms it's installed and enabled. The plugin manifest registers the same MCP server shown above, so once it's installed you don't need a separate claude mcp add step.

First run

Work from your per-org repository — the Salesforce DX project you want to vault (the directory with sfdx-project.json). The first refresh is read-only: it retrieves metadata and builds a local knowledge base; it never deploys or mutates Salesforce data.

# 0. New here? The guided path walks install → auth → init → refresh → ask,
#    with real starter questions at the end.
sfi quickstart

# 1. Create the local org-kb/ vault layout and record which sf org alias to use.
sfi init

# 2. Retrieve metadata and build the vault.
sfi refresh --target-org my-org-alias

# 3. Confirm vault freshness, source-tree hash, and component counts any time.
sfi status

# sfi doctor checks the sf CLI, the vault, target-org auth, freshness, and the
# graph file, and prints an actionable fix for each problem.
sfi doctor

How long does a refresh take? A small sandbox builds in a few minutes; a production-scale org is typically ~10–12 minutes under the defaults — the retrieve dominates, and the default build also runs the parser-grade Apex pass (seconds per few hundred classes) and pulls the top 500 reports/dashboards by actual usage (a minute or two on report-heavy orgs; --no-reports skips it). In a hurry on a big org? sfi refresh --staged serves a skeleton vault in seconds and the ten priority metadata families within minutes, then finishes the full build behind the scenes — see the first-refresh guide. Re-refreshes re-extract and rebuild the graph in full by default (results always match a cold build); --incremental reuses the per-file parse cache for the same result, faster, and --incremental-graph additionally re-imports only the changed nodes/edges into the graph instead of rebuilding it — combine both for the largest win. --types <list> scopes either flag to specific metadata types (e.g. sfi refresh --types Flow --incremental-graph); a scoped refresh only ever touches the requested type(s) — every other type in the vault is left as-is.

No global install? Prefix each with npx -y sf-intelligence, e.g. npx -y sf-intelligence init.

Then ask anything the vault can answer, in whatever MCP client you registered:

What fields does the Account object have?

What breaks if I delete CustomField:Account.Industry__c?

Why can't the Standard User profile see Opportunities?

Give me a tour of this org.

Running sf-intelligence as a Claude Code plugin? The same operations are available as slash commands — /sfi-onboard (guided first run), /sfi-init, /sfi-refresh, /sfi-status — and the coaching skills auto-activate when Salesforce vocabulary appears. See Install as a Claude Code plugin above if you haven't installed it that way yet.

Serve it over HTTP (read-only)

sfi mcp is the stdio server your MCP client launches. To share one vault with other machines or clients, the same server speaks streamable HTTP:

# From the vault directory: prints a bearer token once, listens on 127.0.0.1:8787.
sfi serve --http --generate-token

# Team path: JSON token→identity map (annotation writes attribute to the caller).
# sfi serve --http --tokens-file ./tokens.json

The remote posture is deliberately strict: a bearer token is required on every request (solo --token / --generate-token, or --tokens-file for per-caller identity), the bind is loopback unless you pass --host (a non-loopback host warns and refuses to run tokenless), and the live plane is hard-disabled over HTTP — a remote caller can never spend your Salesforce API budget, even if the host has standing live consent. A refresh underneath a running server is safe: readers keep answering from the old graph until the new one swaps in.

Give the vault a memory

# One-time, from the vault directory: inits a git repo INSIDE org-kb/
# (rebuildable surfaces like graph/ and snapshots/ are gitignored).
sfi vault git enable

From then on every refresh commits the vault's source and rendered Markdown, so "when did this component change?" (sfi.component_history — one timeline entry per source-changing refresh) and "what did it look like before?" (sfi.component_as_of) become answerable from the vault's own history. A vault without git answers those honestly (available: false plus this enable hint) — never an error.

Privacy

Everything stays on your machine. The vault (org-kb/) is local; the MCP server defaults to SFI_NETWORK_MODE=off and makes no network calls while answering vault questions. Optional egress is explicit: npm update-check only when SFI_UPDATE_CHECK=1 (or updates-only mode); Salesforce retrieve/live only when refresh or an authorized live tool elevates to salesforce-read. This public repository ships zero org data — a release privacy guard scans the shipping set on every release and fails the build if a real org identifier leaks. What you vault is yours.

Roadmap

The product is read-only today by design; that is the major axis of future work.

• Deeper code resolution. Parsed Apex call edges carry the called method names today; the remaining composite tools still reason at class granularity — method-level reachability across them is the next step.
• A careful write side. A small, opt-in set of proposal tools (e.g. draft a permission-set diff or a validation-rule edit for human review) once the read side is mature. The default will always be read-only.

(Earlier roadmap entries shipped: Tooling-API-backed stale-vault detection is now the sfi watch daemon + drift badges; remote read-only serving is sfi serve --http.)

Feedback

A weak or wrong answer, or a question it couldn't route? That's the most useful thing you can send back. It's captured locally — nothing phones home:

sfi feedback mark "where is the SSN field used" --wrong   # or --weak
sfi feedback export                                       # → sfi-feedback.json (scrubbed)

sfi feedback export bundles the local route-gap log plus your ratings into one file with org PII (emails, URLs, record ids) stripped — component/api names are kept because they're the signal. Exports are scoped to the current vault by default: the log file is machine-global (~/.sf-intelligence/), but each gap is stamped with the vault it was asked against, and only the current vault's gaps are exported (the file reports how many were excluded). --all exports the whole machine-global log — review it before sharing if you work across multiple orgs. Share it (or just describe the gap) at https://github.com/PranavNagrecha/Salesforce-Intelligence/issues.

License

sf-intelligence is licensed under the MIT License with the Commons Clause (see also NOTICE). In plain English:

• ✅ Free to use for any purpose — including at work, inside a company. Evaluate, study, modify, self-host for your own use, fork, redistribute, and contribute — all free.
• 🚫 You may not Sell it without a commercial license — i.e. provide it to third parties, for a fee, as a product or service whose value derives substantially from the Software. That includes offering it (or a hosted / SaaS / derivative version) as a paid product or service, reselling it or paid access to it, or charging for hosting/support whose value derives substantially from it.

For a commercial ("Sell") license, contact pranav.sfintelligence@gmail.com. (Plain-English summary; the LICENSE controls. Not legal advice.)

Documentation

• Documentation index — guides, architecture, configuration
• Contributing · Security

The build harness (a sibling repo, separate from this product) vendors Addy Osmani's agent-skills under MIT. Copyright (c) Addy Osmani; full MIT license text travels with the harness. None of that content is redistributed in this product directory; the attribution is recorded here for completeness.