@ryanstark24/sfgraph-skills 1.1.3 → 1.2.0

package/dist/__tests__/installer.test.js

@@ -11,11 +11,11 @@ afterEach(() => {
     rmSync(home, { recursive: true, force: true });
 });
 describe("skills installer", () => {
-    it("installs all 16 skills to the claude target", async () => {
+    it("installs all 20 skills to the claude target", async () => {
         const results = await install("claude", { homeOverride: home });
         const skillNames = await listSkillsBundled();
-        expect(skillNames.length).toBe(16);
-        expect(results.length).toBe(16);
+        expect(skillNames.length).toBe(20);
+        expect(results.length).toBe(20);
         for (const r of results) {
             expect(r.target).toBe("claude");
             expect(r.action).toBe("created");
@@ -26,11 +26,11 @@ describe("skills installer", () => {
     });
     it("installs to the cursor target as .mdc files in Cursor's frontmatter shape", async () => {
         const results = await install("cursor", { homeOverride: home });
-        expect(results.length).toBe(16);
+        expect(results.length).toBe(20);
         const cursorDir = join(home, ".cursor", "rules");
         const files = readdirSync(cursorDir);
         expect(files.every((f) => f.endsWith(".mdc"))).toBe(true);
-        expect(files.length).toBe(16);
+        expect(files.length).toBe(20);
         // Cursor-shaped frontmatter (the three keys Cursor's rule loader reads).
         const sample = readFileSync(join(cursorDir, files[0] ?? ""), "utf8");
         expect(sample).toMatch(/^description:/m);
@@ -48,9 +48,9 @@ describe("skills installer", () => {
         const claudeCount = results.filter((r) => r.target === "claude").length;
         const cursorCount = results.filter((r) => r.target === "cursor").length;
         const vscodeCount = results.filter((r) => r.target === "vscode").length;
-        expect(claudeCount).toBe(16);
-        expect(cursorCount).toBe(16);
-        expect(vscodeCount).toBe(16);
+        expect(claudeCount).toBe(20);
+        expect(cursorCount).toBe(20);
+        expect(vscodeCount).toBe(20);
         expect(existsSync(join(home, ".claude", "skills"))).toBe(true);
         expect(existsSync(join(home, ".cursor", "rules"))).toBe(true);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanstark24/sfgraph-skills",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/skills/sf-cross-layer-trace/SKILL.md

@@ -1,19 +1,12 @@
 ---
 name: sf-cross-layer-trace
-description: Trace a field, component, or method end-to-end across LWC, Apex, Flow, and data layer. PROACTIVELY volunteer this skill whenever the focal artifact is an LWC bundle, Aura component, ApexPage, or a custom field — even on explain-style questions ("explain this LWC", "what does this component do", "where is X used"). After answering the surface question, offer a cross-layer trace so the user sees what the artifact ultimately touches through Apex / Flow / SObject.
+description: Trace a Salesforce field, LWC/Aura/VF component, or method end-to-end across UI → Apex → Flow → SObject. Use when the user asks "where is X used" or wants the full call chain across layers. For a plain-English explanation of one code unit only, prefer sf-explain-code. For schema/ERD views of objects, prefer sf-schema-overview. May be offered as a follow-up after sf-explain-code completes on a UI artifact, but do not auto-invoke alongside it — let the user opt in.
 triggers:
   - "UI to DB"
   - "trace this LWC"
   - "end-to-end"
   - "where is this field used"
   - "where does this come from"
-  - "explain this LWC"
-  - "explain this component"
-  - "what does this component do"
-  - "what does this LWC do"
-  - "explain this Aura"
-  - "explain this VisualForce"
-  - "explain this ApexPage"
   - "where is this component used"
   - "what pages embed"
   - "which pages use"
@@ -72,6 +65,10 @@ flowchart TD
 
 If the resolved trace has >30 nodes, ask the user to narrow to a single layer-pair before rendering — a sprawling layered diagram is more misleading than no diagram.
 
+## Trace-tool noise defaults
+
+If you drop down to `trace_upstream` / `trace_downstream` for a raw dependency walk, note they **hide security-grant and inferred edges by default**. A class granted to 100+ profiles, or a Vlocity node with reflection-walker string-name matches, would otherwise drown the real dependencies. The response tells you "N edges hidden". Only pass `include_security: true` for an access-centric question, or `include_inferred: true` when the user explicitly wants low-confidence reflection links. Use `rel_types: [...]` to pin a walk to specific relationships (e.g. `["CALLS","IS_TEST_FOR"]`). `cross_layer_flow_map` is unaffected — it already follows curated layer edges.
+
 ## Staleness check
 
 Before calling `cross_layer_flow_map`, invoke `staleness_check` for the target org. If the report says stale, surface a warning to the user:

package/skills/sf-cross-org-diff/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: sf-cross-org-diff
-description: Compare metadata between two orgs (sandbox vs prod, two sandboxes) and summarise drift.
+description: Compare metadata between TWO DIFFERENT ORGS (sandbox vs prod, sandbox vs sandbox) and summarise configuration drift between them. Use only when the user names two orgs or clearly contrasts environments. For "what changed since deploy" in a single org use sf-what-broke; for comparing point-in-time snapshots of one org use sf-snapshot-compare.
 triggers:
   - "sandbox vs prod"
-  - "what changed"
-  - "org diff"
-  - "compare orgs"
-  - "drift"
+  - "compare these two orgs"
+  - "org-to-org diff"
+  - "drift between orgs"
+  - "what's different between <orgA> and <orgB>"
 tools_used:
   - cross_org_diff
   - point_in_time_diff

package/skills/sf-dead-code-audit/SKILL.md

@@ -12,6 +12,7 @@ tools_used:
   - freshness_report
   - trace_upstream
   - staleness_check
+  - find_similar
 ---
 
 # sf-dead-code-audit
@@ -20,9 +21,9 @@ Use when the user wants to inventory metadata that appears unreferenced. Output
 
 ## Playbook
 
-1. Call `dead_code_audit` over the user's chosen scope (entire org, single namespace, or one metadata category). Capture every candidate plus the evidence the tool used (no incoming edges, no inclusion in deploy manifests, etc.).
+1. Call `dead_code_audit` for the org. The tool **summarizes by confidence (`high`/`medium`/`low`) and by metadata type**, then renders a capped list (`limit`, default 50). On a large org there can be thousands of candidates — do NOT try to retrieve them all inline; work from the summary counts and drill in with `confidence: "high"` (most-likely-dead first) or raise `limit`. For the complete machine-readable set, use `export_sarif`. Each row carries a score + reasons (`no_incoming_edges`, `stale_freshness`).
 2. Call `freshness_report` to layer last-touched timestamps onto each candidate. Stale + unreferenced is stronger evidence than unreferenced alone.
-3. For any candidate the user names interactively, call `trace_upstream` to confirm absence of indirect callers (dynamic Apex, Flow lookups, callable interfaces).
+3. For any candidate the user names interactively, call `trace_upstream` to confirm absence of indirect callers (dynamic Apex, Flow lookups, callable interfaces). Optionally call `find_similar(qname=<candidate>, k=5)` — if the candidate has near-neighbours (similarity > 0.6) that ARE referenced, the candidate may be a copy-paste duplicate of live code and worth deleting; if every neighbour is also in the dead list, you've found a whole disused subsystem worth flagging as a group.
 4. Sort candidates into three buckets:
    - **confident-dead** — no incoming edges, no dynamic-invocation signature match, freshness > 12 months, no inclusion in active permission sets / page layouts.
    - **likely-dead** — no incoming edges, but at least one weak signal (recently modified, referenced from a managed package boundary, or named in a metadata file we don't parse fully).

package/skills/sf-debug-log-analysis/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: sf-debug-log-analysis
+description: Read and analyse a Salesforce Apex debug log — exceptions/FATAL_ERROR, governor-limit consumption (SOQL/DML/CPU/heap), the execution call tree, and slow or repeated code units — then ground every finding in the org graph (map the log's code units/methods to qnames and explain WHY with trace/governor/analyze_field). Use when the user pastes or points to a debug log, an `sf apex get log` output, or asks to interpret a System.debug / stack trace / "Too many SOQL queries" / CPU-time log. Pairs with sf-debug-root-cause (log = symptom, graph = cause).
+triggers:
+  - "debug log"
+  - "read this log"
+  - "analyze this log"
+  - "apex log"
+  - "Too many SOQL queries"
+  - "Apex CPU time limit"
+  - "System.debug output"
+  - "FATAL_ERROR"
+  - "LIMIT_USAGE"
+  - "sf apex get log"
+  - "stack trace from the log"
+tools_used:
+  - find_nodes
+  - explain_code
+  - trace_upstream
+  - trace_downstream
+  - analyze_field
+  - governor_risk_check
+  - staleness_check
+---
+
+# sf-debug-log-analysis
+
+A Salesforce debug log is the ground truth of what *actually executed* — but on its own
+it's a wall of pipe-delimited lines and it can't tell you *why* (what other code calls the
+slow method, where the in-loop SOQL is declared, what writes the field that reverted).
+This skill reads the log, extracts the signal, and **grounds each finding in the org graph**
+so the answer is "the CPU went here because `OrderTriggerHandler.recalc` runs a SOQL inside
+a `for` over `Trigger.new` — here are its 3 callers", not "looks like a CPU issue".
+
+Format reference: <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_debugging_debug_log.htm>
+
+## Getting the log (if the user hasn't supplied one)
+
+- Salesforce CLI: `sf apex list log` → `sf apex get log --log-id <id> > debug.log`, or live: `sf apex tail log --color none`.
+- Setup → Debug Logs (trace flags on the user), then download.
+- Tell the user the log level matters: `Apex Code = FINE`/`FINER` captures method entry/exit and SOQL; `Apex Profiling`/`System = FINE` captures the `CUMULATIVE_LIMIT_USAGE` block. `FINEST` is huge and often truncated at the 20 MB cap — prefer `FINE`/`FINER` unless you need variable-level detail.
+
+## Reading the log (format)
+
+The header line lists the API version + per-category log levels. Every subsequent line is
+`HH:mm:ss.SSS (elapsedNanos)|EVENT_TYPE|details`. The event types that carry signal:
+
+| Event | What it tells you |
+|---|---|
+| `CODE_UNIT_STARTED` / `_FINISHED` | The unit boundaries — triggers, `Class.method`, flows, VF, anonymous. Top of the call tree. |
+| `METHOD_ENTRY` / `METHOD_EXIT` | Method call tree (needs Apex Code ≥ FINER). Indentation/elapsed time = where time goes. |
+| `SOQL_EXECUTE_BEGIN` / `_END` | Each query + `Rows:` returned + aggregations. **Count them** — repeated identical SOQL = in-loop. |
+| `SOSL_EXECUTE_*`, `DML_BEGIN` / `_END` | SOSL and DML operations + row counts. |
+| `CALLOUT_REQUEST` / `_RESPONSE` | HTTP callouts + endpoints + timing. |
+| `EXCEPTION_THROWN` | The thrown exception + type + the offending `Class.method: line`. |
+| `FATAL_ERROR` | The uncaught error + full Apex stack trace — the prime anchor for a failure. |
+| `USER_DEBUG` | `System.debug()` output the developer planted. |
+| `LIMIT_USAGE_FOR_NS` / `CUMULATIVE_LIMIT_USAGE` | **The governor scorecard** — SOQL queries, query rows, DML statements/rows, CPU time, heap, callouts used vs limit. |
+| `HEAP_ALLOCATE`, `STATEMENT_EXECUTE`, `VARIABLE_*` | FINEST-only, very noisy — skip unless chasing a heap/variable bug. |
+| `FLOW_*` / `WF_*` | Flow elements and Workflow-rule evaluation (order-of-execution bugs). |
+
+## Method
+
+1. **If the log is large, filter before reading.** Don't load a 20 MB log into context. Grep for the signal first:
+   `grep -nE 'FATAL_ERROR|EXCEPTION_THROWN|CUMULATIVE_LIMIT_USAGE|LIMIT_USAGE_FOR_NS' debug.log` for failures + limits;
+   `grep -c 'SOQL_EXECUTE_BEGIN' debug.log` for query count;
+   `grep -E 'CODE_UNIT_(STARTED|FINISHED)' debug.log` for the unit skeleton.
+   Read only the relevant slices.
+2. **Classify the problem** from the evidence: an uncaught failure (`FATAL_ERROR`), a governor breach (limit at/over 100% in the cumulative block, or a `System.LimitException`), a performance issue (one `CODE_UNIT` dominating elapsed time), or just `USER_DEBUG` tracing.
+3. **Extract the anchor:**
+   - Failure → the exception type + the top in-org frame `Class.method: line` from the stack trace.
+   - Governor → which limit, the count vs cap, and the `CODE_UNIT`/method where consumption spiked (repeated SOQL/DML lines under one unit).
+   - Performance → the `CODE_UNIT`/method with the largest elapsed delta.
+4. **Ground it in the graph** (the part a log reader alone can't do):
+   - `find_nodes ApexClass:<Name>` / `ApexMethod:<Name>.*` to resolve the anchor to a qname; `explain_code` on the method to read the offending source.
+   - `trace_upstream` — who invokes this unit, and in what context (trigger vs batch vs LWC). Order-of-execution and "why was this even called" answers live here.
+   - `trace_downstream` — what it calls/reads/writes; a NullPointer or limit usually originates in a callee.
+   - Governor breach → `governor_risk_check` scoped to the class to pinpoint the SOQL/DML-in-loop **source line** the log proved is hot.
+   - Field misbehaviour seen in the log → `analyze_field` for every trigger/Flow/validation that fires on that field (competing automation).
+5. **State a single root-cause hypothesis** backed by *both* the log evidence and the graph evidence, then hand the fix to the right design skill (`sf-architect-apex` / `sf-architect-performance` / `sf-governor-risk-fix`) — grounded, never generic.
+
+## Staleness
+
+If you'll ground in the graph, call `staleness_check` first. A stale graph maps the log's
+code units to outdated source — warn and recommend `sfgraph ingest --org <alias>`. The log
+itself is always current; the mismatch is on the graph side.
+
+## Response shape
+
+- **Verdict** — one line: failure / governor breach / performance / trace-only, with the anchor `Class.method:line`.
+- **Log evidence** — the decisive lines (exception, the cumulative-limit row that breached, the repeated SOQL count, the dominant code unit) — quote them, don't paraphrase.
+- **Graph grounding** — callers, callees, competing automation, or the in-loop source line that explains the log.
+- **Root cause** — one hypothesis, confidence, tied to both evidence sources.
+- **Fix** — described and handed off to a design skill; not auto-applied.
+- **Mermaid** — optional call-tree or caller→unit→callee path when it clarifies.
+
+## Don't
+
+- Don't load a multi-MB log wholesale — filter with grep first, then read slices. Say what you filtered so nothing looks silently dropped.
+- Don't stop at the log. The log shows *what*; grounding in the graph shows *why* — that's the value. A log-only answer is a guess about the cause.
+- Don't trust `FINEST` noise (`STATEMENT_EXECUTE`/`VARIABLE_ASSIGNMENT`) as signal — anchor on CODE_UNIT/SOQL/DML/limit/exception events.
+- Don't edit code here — produce evidence + root cause; design hands off.
+- Don't confuse a logged, *caught* `EXCEPTION_THROWN` with the actual failure — the uncaught `FATAL_ERROR` (if present) is the one that ended the transaction.

package/skills/sf-debug-root-cause/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: sf-debug-root-cause
+description: Root-cause a SPECIFIC Salesforce failure — an Apex exception or stack trace, a failing test, a flow fault, or "this field/record isn't behaving right" — by grounding the symptom in the org graph (callers, callees, recent changes, automation on the object, test coverage). Use when the user reports a concrete error/symptom and wants to know WHY. For "what changed since deploy" broadly use sf-what-broke; for pre-commit blast radius use sf-wip-impact.
+triggers:
+  - "why is this failing"
+  - "debug this error"
+  - "this test fails"
+  - "stack trace"
+  - "NullPointerException"
+  - "System.LimitException"
+  - "this trigger isn't firing"
+  - "field isn't updating"
+  - "flow fault"
+  - "root cause"
+tools_used:
+  - find_nodes
+  - explain_code
+  - trace_upstream
+  - trace_downstream
+  - analyze_field
+  - what_broke
+  - test_gap_intelligence_from_git_diff
+  - staleness_check
+---
+
+# sf-debug-root-cause
+
+Use when the user has a **concrete failure** and wants the cause, not a guess. Salesforce
+failures are rarely in the one method that threw — they come from another trigger on the
+same object, a recent change upstream, an order-of-execution surprise, or automation the
+developer forgot exists. The graph makes those visible. Debug by narrowing with evidence,
+never by pattern-matching the error message to a generic fix.
+
+## Method (scientific, evidence-first)
+
+0. **If a debug log is available, start there.** A debug log is the strongest anchor — it
+   has the exact `FATAL_ERROR` stack frame and the real governor scorecard. Hand the log to
+   **`sf-debug-log-analysis`** to extract the anchor + limit evidence, then continue this
+   playbook from step 2 with that anchor. Without a log, anchor from the error text/symptom:
+
+1. **Anchor the symptom to a node.** Parse the error / test name / symptom for the failing
+   unit and resolve its qname:
+   - Apex class/method in the trace → `find_nodes ApexClass:<Name>` / `ApexMethod:<Name>.*`.
+   - Failing test → the test method, then its `IS_TEST_FOR` target.
+   - "Field X isn't updating" → `analyze_field` on `<Object>.<Field>`.
+   If you can't anchor it, ask the user for the class/object name — don't guess.
+
+2. **Read the failing unit.** `explain_code(qname=<ApexMethod>)` — get the source + branch
+   annotation. Confirm the line in the trace maps to a real branch (SOQL, DML, deref).
+
+3. **Look outward for the real cause — this is where graphs beat grep:**
+   - `trace_downstream(qname)` — what it calls / reads / writes. A `System.NullPointer` or
+     `LimitException` usually originates in a callee or a SOQL/DML it triggers.
+   - `trace_upstream(qname)` — who invokes it, and with what context (trigger vs batch vs
+     LWC). Order-of-execution bugs hide here.
+   - For an object symptom: `sf-flow-impact` / `analyze_field` — every trigger, Flow,
+     Process Builder, and validation rule that fires on the object. "Trigger isn't firing"
+     and "field reverts" are almost always a competing automation.
+   - Governor `LimitException` → hand to `sf-governor-risk-fix` scoped to the class to find
+     the SOQL/DML-in-loop.
+
+4. **Check what recently changed.** `sf-what-broke` (or `what_broke`) for the org since the
+   last deploy/ingest — if the failing node or any node it depends on changed recently,
+   that's your prime suspect. Correlate the failure's first-seen time with the change.
+
+5. **Check test coverage of the suspect path** — `test_gap_intelligence_from_git_diff` (if a
+   diff exists) or the `IS_TEST_FOR` edges — a path with no test is where regressions live.
+
+6. **State a single hypothesis, then confirm it** against the graph before recommending a
+   fix. "I think X because the graph shows Y." If the evidence doesn't support it, form a
+   new hypothesis — don't stack speculative fixes.
+
+## Staleness check
+
+Call `staleness_check` first. A stale graph misleads root-cause analysis (the change that
+caused the bug may not be ingested yet). If stale, warn and recommend
+`sfgraph ingest --org <alias>` before trusting the upstream/recent-change steps.
+
+## Response shape
+
+- **Symptom** — the error/test/behaviour, anchored to a qname.
+- **Evidence chain** — the graph facts that narrow the cause (callers, callees, competing
+  automation, recent changes, coverage gaps), each tied to the tool that surfaced it.
+- **Root-cause hypothesis** — one, with the supporting evidence. Confidence level.
+- **Recommended fix** — described, not auto-applied; hand to `sf-architect-apex` /
+  `sf-architect-ui` / `sf-governor-risk-fix` to design it, grounded in this evidence.
+- **Mermaid** — optional: the failing path (caller → unit → callee/field) when it clarifies.
+
+## Don't
+
+- Don't propose a fix before anchoring the symptom to a real node and reading its source.
+- Don't ignore competing automation — on object symptoms it's the most common root cause and
+  the thing a stack trace alone never shows.
+- Don't stack multiple speculative fixes; one hypothesis, confirmed, at a time.
+- Don't edit code here — root-cause + evidence is the deliverable; design hands off.
+- Don't trust a stale graph for "what recently changed" without flagging it.

package/skills/sf-explain-code/SKILL.md

@@ -1,9 +1,11 @@
 ---
 name: sf-explain-code
-description: Explain an Apex method, LWC handler, or other code unit; highlight conditional branches; cache the explanation back to the graph.
+description: Explain a single Salesforce code unit (Apex method/class/trigger, LWC handler, Aura controller method) in plain English with conditional-branch annotation, then cache the explanation back to the sfgraph store. Salesforce metadata only — do NOT use for non-Salesforce code (e.g. Node, Python, ingest pipeline scripts) even when asked inside this repo. Scope is one named code unit; for end-to-end UI→DB tracing across layers use sf-cross-layer-trace, for whole-object schema views use sf-schema-overview.
 triggers:
-  - "explain this method"
-  - "what does <ClassName.method> do"
+  - "explain this Apex method"
+  - "explain this trigger"
+  - "explain this LWC handler"
+  - "what does <ApexClass.method> do"
   - "walk me through <qname>"
   - "annotate the conditionals"
 tools_used:
@@ -11,6 +13,7 @@ tools_used:
   - trace_upstream
   - trace_downstream
   - staleness_check
+  - find_similar
 ---
 
 # sf-explain-code
@@ -19,7 +22,7 @@ Use this skill when the user wants a plain-English explanation of a specific cod
 
 ## Playbook
 
-1. **Resolve the target qname.** Most users say "explain `AccountSvc.calculate`" — that maps to the qname `ApexMethod:AccountSvc.calculate(N)` where N is the arity. If the arity is unknown or the name is ambiguous, call `trace_upstream` with a partial match to enumerate candidates and confirm with the user.
+1. **Resolve the target qname — it must be METHOD-level.** Snippets are stored only for Apex methods, so `explain_code` needs `ApexMethod:AccountSvc.calculate(N)` (N = arity), **not** a class qname like `ApexClass:AccountSvc` (that returns "No snippet stored"). If the user names a class, first enumerate its methods with `find_nodes(pattern="ApexMethod:AccountSvc.*")` and either pick the method they meant or explain each in turn. For declarative metadata (fields, objects, Flows) there is no snippet — redirect to `analyze_field` / `sf-cross-layer-trace` instead. If the arity is unknown or the name is ambiguous, use `find_nodes` to enumerate candidates and confirm with the user.
 2. **`staleness_check`** for the linked org. If stale, surface a warning so the user knows the cached source may not reflect production.
 3. **`explain_code(qname=X)`** — pull the stored snippet and any prior cached explanation. The tool returns the source text in a fenced code block.
 4. **Generate the explanation**, structured as:
@@ -58,9 +61,22 @@ Continue the playbook either way; just flag the risk.
 - **Mermaid** — only when conditional structure justifies it.
 - **Cached** — confirm the explanation was cached back, with the qname.
 
+## Follow-up: "what else is like this?"
+
+After delivering the explanation, offer a one-line follow-up:
+
+> _Want me to find semantically similar code? I can run `find_similar` on this qname._
+
+If the user says yes, hand off to `sf-find-similar` with mode=qname and the same qname. Don't pre-emptively run it — the embedding query takes a moment and the user may not want it. The chain is most useful when:
+
+- The user is reviewing legacy code and wants to spot duplicates.
+- The method does something domain-specific (taxes, compliance, pricing) and the user wants to find every place that handles the same concept.
+- The agent already produced an explanation but the user wonders "is this the only place this logic lives?".
+
 ## Don't
 
 - Don't modify the source. This skill is read-only against the local graph.
 - Don't write anything to Salesforce.
 - Always render the source inside a fenced code block tagged with the `sourceFormat` returned by `explain_code` (`apex`, `js`, `html`, etc.).
 - Don't fabricate behaviour — if the source is empty or stubbed, say so plainly.
+- Don't pass a class/trigger/field qname expecting source — only `ApexMethod:...(N)` has a snippet. On "No snippet stored", resolve to a method qname rather than reporting failure.

package/skills/sf-find-similar/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: sf-find-similar
+description: Find Salesforce metadata that is semantically similar to an existing node OR a free-text concept. Two modes — pass a qname to anchor on an existing node (e.g. "show me other Apex methods like BillingSvc.run"), or pass free text to discover code by meaning when no name fits (e.g. "find code that handles order cancellation"). Use when exact-name search misses, when an agent wants to surface near-misses for review, or when the user describes a concept rather than a node. Powered by the MiniLM-L6 embeddings produced during ingest and the `vec0` SQLite KNN index. Filter by label to restrict to one node type. Do NOT use for structural edge traversal — for "what does X call" / "who reads field Y" use trace_downstream / analyze_field, which give exact answers; this skill is for fuzzy / conceptual matches.
+triggers:
+  - "find similar"
+  - "show me code like"
+  - "what else is like"
+  - "find nodes similar to"
+  - "semantically similar"
+  - "find code that handles"
+  - "where do we"
+  - "anything related to"
+  - "fuzzy search"
+  - "more like this"
+tools_used:
+  - find_similar
+  - explain_code
+  - trace_downstream
+  - analyze_field
+  - staleness_check
+---
+
+# sf-find-similar
+
+Use this skill when the user wants discovery rather than exact lookup: *"what other Apex methods are like this one"*, *"find code that handles order cancellation"*, *"is there anything similar to `accountTile`?"*. Powered by the in-process MiniLM-L6 embeddings sfgraph produces during every ingest.
+
+## When to choose this vs. the other tools
+
+| Question shape | Use |
+|---|---|
+| "What does X call?" / "Who reads field Y?" | `trace_downstream` / `analyze_field` — exact graph edges |
+| "Explain method X" | `sf-explain-code` |
+| "What else is like X?" / "Find code that does Y" | **`sf-find-similar`** |
+| "What changed?" / "What broke?" | `sf-what-broke`, `sf-cross-org-diff`, `sf-impact-from-diff` |
+
+If the user mentions an exact qname *and* asks for relationships, prefer the structural tool. Reach for `find_similar` when names don't match or the user is describing a concept.
+
+## Two modes
+
+### Mode A — anchored on an existing node (`qname`)
+
+```
+find_similar(org="my-org", qname="ApexClass:BillingSvc", k=10, label="ApexClass")
+```
+
+Use when the user names a node and wants "more like this." Pass `label` when restricting matters (e.g. "other LWCs like accountTile" — set `label="LWC"`).
+
+### Mode B — free-text concept (`text`)
+
+```
+find_similar(org="my-org", text="code that computes compliance fees", k=10)
+```
+
+Use when the user describes the *what* but not the *which*. The query is embedded on the fly with the same MiniLM-L6 pipeline the ingest uses. Most useful when:
+
+- The user couldn't recall an exact class/method name.
+- The concept spans multiple classes — semantic match surfaces them all.
+- The user explicitly says "find code that does X" / "where do we Y".
+
+## Playbook
+
+1. **Pick the mode** based on whether the user named a node or described a concept.
+2. **`staleness_check`** for the org. If stale, warn — embeddings may not reflect production code.
+3. **`find_similar`** with the chosen mode. Use `k=10` by default; raise to 20–30 only if the user asks "more results."
+4. **Read the response** — it returns a ranked table of `(qname, label, similarity, distance)`. Similarity is 0–1, higher is closer.
+5. **Filter the noise.** Similarity < ~0.4 is usually unrelated text overlap, not real semantic match. Drop those before surfacing to the user unless they explicitly asked for everything.
+6. **Offer to drill in.** For each hit the user seems interested in, propose chaining to `sf-explain-code` (what does this one do?) or `trace_downstream` (where does it flow?).
+
+## Visualization
+
+When the result set has 5+ hits, render a horizontal bar chart (Mermaid `xychart-beta`) of similarity scores so the user can eyeball the cluster vs. tail. For ≤4 hits the table alone is fine.
+
+```
+xychart-beta
+  title "Similarity to BillingSvc"
+  x-axis [OrderInvoiceSvc, CreditMemoSvc, TaxCalcSvc, RebateSvc]
+  y-axis "similarity" 0 --> 1
+  bar [0.82, 0.79, 0.71, 0.55]
+```
+
+## Common failure modes & how to handle them
+
+- **`reason: vector_index_unavailable`** — the org's graph was ingested before embeddings were wired up, or the optional `@ryanstark24/sfgraph-models` install was skipped. Tell the user verbatim what the tool's markdown suggests: re-install with `npm install -g @ryanstark24/sfgraph` and re-ingest with `--rebuild`.
+- **`reason: no_focal_vector`** (qname mode) — the qname is wrong or its label isn't embedded. Confirm the qname spelling. If correct, suggest re-trying with `text` mode using the user's description of the node.
+- **`reason: embedder_unavailable`** (text mode) — the MiniLM runtime isn't present. Fall back to qname mode if the user can name a similar node.
+- **`reason: no_neighbours`** — genuinely no similar nodes. Suggest dropping the `label` filter, or running structural `trace_upstream` / `trace_downstream` instead.
+
+## Response shape
+
+- **TL;DR** — "Top N matches for `<focal>`."
+- **Ranked table** — qname, label, similarity (3 decimal places), distance.
+- **Drop-low note** — if you filtered out scores <0.4, say so: "Skipped 3 results below the 0.4 noise floor."
+- **Follow-ups** — propose `explain_code` / `trace_downstream` for the top hit.
+
+## Don't
+
+- Don't claim semantic match implies a structural edge. If the user wants "who actually calls X", route to `trace_upstream`. Similarity ≠ dependency.
+- Don't surface scores below ~0.4 unless the user explicitly asked for a wider net. They are usually statistical noise from the embedding space.
+- Don't use this for "what changed" / "what broke" questions — those need diff-style tools, not semantic neighbours.

package/skills/sf-governor-risk-fix/SKILL.md

@@ -17,11 +17,32 @@ tools_used:
 
 Use when the user wants to find Apex code that risks hitting governor limits at scale. The skill produces a prioritised remediation checklist; it never rewrites Apex automatically.
 
+## What the tool actually emits
+
+`governor_risk_check` reports only the risk types the analyzer can prove from
+the graph. As of the edge-based detector these are:
+
+- **`soql_in_loop`** — a SOQL query whose `EXECUTES_SOQL` edge is tagged
+  `inLoop` (AST-verified: the query sits inside a for/while/do-while body).
+- **`dml_in_loop`** — same, for DML statements.
+- **`no_bulk`** — a trigger that doesn't iterate `Trigger.new` (body-scan path).
+
+Do **not** promise `UNBOUNDED_QUERY`, `NON_SELECTIVE_QUERY`, `CALLOUT_IN_LOOP`,
+`LARGE_HEAP`, or `RECURSIVE_TRIGGER` — the tool does not produce them. (Unbounded-
+query was removed: on a real org ~100% of SOQL has no WHERE/LIMIT in the captured
+query head, so it was pure noise.)
+
+**Live-ingest prerequisite:** `inLoop` tagging comes from the Apex AST parser. A
+graph ingested before that parser change has zero `inLoop` edges, so the check
+returns nothing. If `governor_risk_check` returns empty on an org you believe has
+in-loop SOQL, the fix is a re-ingest (`sfgraph ingest --org <alias> --rebuild`),
+not "the org is clean" — say so explicitly rather than reporting a false all-clear.
+
 ## Playbook
 
-1. Call `governor_risk_check` over the requested scope (single class, namespace, or full org). The tool returns risk records with rule id (`SOQL_IN_LOOP`, `DML_IN_LOOP`, `UNBOUNDED_QUERY`, `NON_SELECTIVE_QUERY`, `CALLOUT_IN_LOOP`, `LARGE_HEAP`, `RECURSIVE_TRIGGER`), location (class + method + line), and severity.
-2. Group findings by rule id; within each group, sort by call-site fan-in (more callers = higher blast radius).
-3. For each finding, describe the canonical fix pattern (e.g. "extract the SOQL above the loop and key the result by `Id`") in one or two sentences — do not write the code.
+1. Call `governor_risk_check` over the requested scope (single class, namespace, or full org). The tool returns risk records keyed on the **method** qname (`ApexMethod:Class.method(n)`) with `risk_type` (`soql_in_loop` / `dml_in_loop` / `no_bulk`) and evidence (the query text or DML target).
+2. Group findings by `risk_type`; within each group, sort by call-site fan-in (more callers = higher blast radius). Use `trace_upstream` on the owning class to get fan-in.
+3. For each finding, describe the canonical fix pattern (e.g. "extract the SOQL above the loop and key the result by `Id`") in one or two sentences — do not write the code. To actually design the bulkified fix, hand off to **`sf-architect-apex`** (or **`sf-architect-performance`** for LDV/query-plan work) with these call sites as grounding, so the rewrite respects the org's real selectors and trigger framework rather than a generic template.
 4. Render the Mermaid heat-map (class-by-rule) from the tool response.
 5. Produce a checklist the user can copy into a ticket: `- [ ] ClassName.methodName:line — rule — recommended pattern`.
 6. Recommend `sf-impact-from-diff` after the user applies fixes, to verify nothing downstream regressed.
@@ -60,5 +81,6 @@ Then continue with the playbook.
 
 - **Never auto-apply fixes.** This skill does not edit Apex.
 - Do not flatten severities — the bucket ordering matters.
-- Do not invent additional rules; only report what `governor_risk_check` returns.
+- Do not invent additional rules; only report what `governor_risk_check` returns (`soql_in_loop`, `dml_in_loop`, `no_bulk`).
+- Do not report "no governor risks" without first checking staleness — an empty result on a pre-AST-parser ingest means the graph lacks `inLoop` tags, not that the code is clean. Recommend a re-ingest.
 - Do not silently exclude managed-package code; mention it was filtered out if so.

package/skills/sf-graph-router/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sf-graph-router
+description: Start here for ANY Salesforce development, design, or debugging task on an org sfgraph has ingested. Routes intent to the right sfgraph skill + MCP tool, and enforces the grounding-first rule — query the org graph for real schema / dependencies / security / governor facts BEFORE generating or changing Apex, LWC, Flow, or config. Use when the user asks to build, design, refactor, review, or debug Salesforce metadata and you are unsure which skill or tool applies, or when about to write Salesforce code from memory.
+triggers:
+  - "help me build"
+  - "design a"
+  - "write a trigger"
+  - "write apex"
+  - "create an LWC"
+  - "refactor this"
+  - "review my"
+  - "is this safe to deploy"
+  - "which sfgraph tool"
+  - "where do I start"
+  - "debug this"
+  - "why is this failing"
+tools_used:
+  - find_nodes
+  - analyze_field
+  - find_similar
+  - staleness_check
+---
+
+# sf-graph-router — start here
+
+sfgraph has a **local, queryable graph of the real org** (every Apex class, LWC, Flow,
+field, profile, Vlocity/OmniStudio component, and the edges between them). That graph is
+the antidote to the #1 failure of LLM-assisted Salesforce work: **hallucinating field
+names, classes, and call chains that don't exist in this org.** This skill decides which
+specialised skill/tool to use, and enforces one rule above all.
+
+## The grounding-first rule (non-negotiable)
+
+**Before you generate or modify any Salesforce metadata — Apex, LWC, Flow, validation
+rule, permission set — query the graph to ground yourself in what the org actually
+contains.** Designing from training data alone is how you invent `Account.Tier__c` when
+the org has `Account.Customer_Tier__c`, call a method arity that doesn't exist, or write a
+trigger that ignores the three triggers already on the object.
+
+Minimum grounding before writing code that touches object/field `X` or class `Y`:
+
+1. `find_nodes` — confirm the qnames exist (`CustomField:Account.*`, `ApexClass:*Order*`).
+2. `analyze_field` — for any field you'll read/write: who already reads/writes it, its type.
+3. `find_similar` — is there existing code that already does this? Reuse beats regenerate.
+4. For changes to existing Apex: `trace_upstream` (callers / blast radius) + `explain_code`.
+
+If `staleness_check` says the ingest is old, say so — your grounding may be out of date —
+and recommend `sfgraph ingest --org <alias>`. If the org isn't ingested at all, say the
+grounding step is unavailable and proceed with explicit low-confidence caveats.
+
+Only after grounding do you hand off to a design/knowledge skill (`sf-architect-*`) to
+write the code. Ground → design → verify. Never design → hope.
+
+## Route by intent
+
+### DEVELOPMENT — writing or changing code
+| Intent | Ground with | Then design with |
+|---|---|---|
+| "Write/extend Apex on `<Object>`" | `sf-schema-overview` (`<Object>`) + `find_nodes ApexClass:*<Object>*` + `find_similar` | `sf-architect-apex` |
+| "Build an LWC for `<feature>`" | `find_similar` (existing LWCs) + `analyze_field` (bound fields) | `sf-architect-ui` |
+| "Add an integration / callout" | `find_nodes NamedCredential:*` + `find_similar` | `sf-architect-integrations` |
+| "Reuse — is this already built?" | `sf-find-similar` (free-text concept mode) | — |
+| "Explain this method/class" | `sf-explain-code` (needs `ApexMethod:Class.m(n)`) | — |
+
+### DESIGN — architecture & data model
+| Intent | Skill |
+|---|---|
+| "Show the data model / ERD for `<Object>`" | `sf-schema-overview` |
+| "Trace `<field/LWC/method>` UI → DB" | `sf-cross-layer-trace` |
+| "Where is `<field>` used / what writes it" | `sf-flow-impact` (Flow/automation) or `analyze_field` (all layers) |
+| "Find duplicate / similar logic to consolidate" | `sf-find-similar` |
+
+### DEBUGGING — something is wrong
+| Intent | Skill |
+|---|---|
+| "This Apex/test fails / this error — why" | `sf-debug-root-cause` |
+| "Read/interpret this debug log / stack trace / 'Too many SOQL' / CPU-time log" | `sf-debug-log-analysis` |
+| "What broke after the last deploy" | `sf-what-broke` |
+| "Will my uncommitted change break anything" | `sf-wip-impact` |
+| "Blast radius + test gaps of this PR/branch" | `sf-impact-from-diff` |
+| "Compare two points in time / snapshots" | `sf-snapshot-compare` |
+
+### QUALITY / GOVERNANCE — review before ship
+| Intent | Skill |
+|---|---|
+| "Governor-limit risks (SOQL/DML in loops)" | `sf-governor-risk-fix` |
+| "FLS / sharing / who-has-access audit" | `sf-security-audit` |
+| "What's unused / safe to delete" | `sf-dead-code-audit` |
+| "Generate a deployment manifest" | `sf-deployment-manifest` |
+| "Diff two orgs (sandbox vs prod)" | `sf-cross-org-diff` |
+| "Vlocity ↔ OmniStudio migration inventory" | `sf-omnistudio-migration-audit` |
+| "Is the graph fresh / how do I refresh" | `sf-metadata-refresh` |
+| "Show me the graph visually" | `sf-web-explorer` |
+
+## Disambiguation (commonly confused)
+- **Committed vs uncommitted vs post-deploy change analysis:** PR/branch/commit → `sf-impact-from-diff`; uncommitted working tree → `sf-wip-impact`; already deployed, something regressed → `sf-what-broke`.
+- **Two orgs vs two snapshots vs one org over time:** different orgs → `sf-cross-org-diff`; named snapshots of one org → `sf-snapshot-compare`; "since last deploy" → `sf-what-broke`.
+- **Explain one unit vs trace across layers:** plain-English of one method → `sf-explain-code`; full UI→DB chain → `sf-cross-layer-trace`.
+
+## Don't
+- Don't generate Salesforce code before grounding when the org is ingested — that's the whole point of the graph.
+- Don't re-implement the routing logic in prose every turn; pick the skill and go.
+- Don't block on grounding if the org isn't ingested — degrade gracefully with a stated caveat.
+- Don't treat this skill as a destination; it hands off. Its job is selection + the grounding rule.

package/skills/sf-impact-from-diff/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: sf-impact-from-diff
-description: Compute downstream blast radius and test-coverage gaps for a git diff before merge.
+description: Compute downstream blast radius and test-coverage gaps for a COMMITTED git diff (a PR, a branch, a commit range) before merge. Requires the changes to already exist in git history. For uncommitted working-tree changes, use sf-wip-impact instead.
 triggers:
   - "what does this PR break"
-  - "impact of this diff"
-  - "before I merge"
-  - "blast radius"
-  - "what does this change affect"
+  - "impact of this PR"
+  - "blast radius of this branch"
+  - "before I merge this PR"
+  - "test gaps for this diff"
 tools_used:
   - impact_from_git_diff
   - test_gap_intelligence_from_git_diff
   - staleness_check
+  - find_similar
 ---
 
 # sf-impact-from-diff
@@ -25,6 +26,7 @@ Use when the user wants to understand the downstream consequences of a pending c
 4. Group findings by risk tier — **direct edits**, **first-degree dependents**, **transitive (depth ≥ 2)** — and call out anything that crosses metadata layers (LWC -> Apex -> Flow).
 5. Render the Mermaid impact graph returned by the tool. If the impact set is large (>40 nodes), summarise by category and offer a follow-up call scoped to a single changed file.
 6. If test gaps exist, list the specific impacted classes + methods that lack assertions, not just totals.
+7. **Semantic-sibling check (optional).** For each top-level changed file, call `find_similar(qname=<changed-node>, k=5)` and surface any near-neighbour (similarity > 0.6) that is NOT in the structural impact set. Rationale: copy-paste duplicates of the changed logic often live elsewhere in the codebase without a structural edge linking them. The diff doesn't touch them, but a behaviour change to the original probably should propagate. Flag these as "siblings worth reviewing" — don't add them to the at-risk list automatically (similarity ≠ dependency), but offer them for the user to scan.
 
 ## Visualization
 

package/skills/sf-security-audit/SKILL.md

@@ -20,8 +20,10 @@ Use when the user asks about who can read or write a field/object, what sharing
 
 ## Playbook
 
-1. Resolve the target. Call `analyze_field` if the user gave `SObject.Field`; otherwise treat as SObject-level.
-2. Call `security_audit` with the resolved target. Capture profiles, permission sets, permission set groups, sharing rules (criteria + owner-based), OWD, and any `without sharing` Apex that touches the field.
+1. Resolve the target. Call `analyze_field` if the user gave `SObject.Field`; otherwise treat as SObject-level. `analyze_field` takes **separate `object` and `field`** params (not a single `Account.Status` string) — split before calling.
+2. Call `security_audit` with the resolved target (`object` / `field` to narrow; whole-org if neither). Capture full-access sharing rules and the FLS gap list.
+   - **FLS gaps are pre-filtered** to FLS-relevant fields: Custom Metadata Type (`__mdt`), platform-event (`__e`), big-object (`__b`), and standard system/audit fields (Id, CreatedById, SystemModstamp, …) are excluded as noise. The response notes `+N CMDT/system fields hidden`. Only pass `include_non_fls_fields: true` if the user explicitly wants that raw set — never lead with it.
+   - The inline gap list is capped (`limit`, default 30). Narrow with `object`, or raise `limit`, rather than dumping thousands of rows.
 3. Build the access matrix: Profile/PSet -> Read / Edit / Delete / View All / Modify All.
 4. Identify sharing exposure: OWD setting, sharing rules expanding access, role-hierarchy inheritance toggles.
 5. Flag risks: `without sharing` Apex selectors, missing `stripInaccessible` / `WITH SECURITY_ENFORCED`, guest user access, Experience Cloud profile reach.

package/skills/sf-snapshot-compare/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: sf-snapshot-compare
-description: Compare two sfgraph snapshots (or one snapshot against current) to see what changed point-in-time.
+description: Compare two named sfgraph SNAPSHOTS of the same org (or one snapshot against current) for arbitrary point-in-time analysis. Use when the user explicitly references snapshots by name/id, wants to "rewind" to a prior state, or compare arbitrary points in time. For post-deploy regressions use sf-what-broke; for comparing two different orgs use sf-cross-org-diff.
 triggers:
   - "compare snapshots"
-  - "what changed between these snapshots"
+  - "diff snapshot <a> and <b>"
   - "point in time diff"
-  - "rewind"
-  - "show me the state before"
+  - "rewind to snapshot"
+  - "show me the state before <snapshot>"
 tools_used:
   - snapshot_list
   - snapshot_create

package/skills/sf-what-broke/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: sf-what-broke
-description: Identify what regressed in an org since a recent deploy or snapshot using point-in-time diffs.
+description: Identify what regressed in a SINGLE org since a recent deploy or sync — post-deployment regression triage. Use when the user reports something stopped working after a deploy, or asks what changed since the last ingest. For comparing two distinct orgs use sf-cross-org-diff; for arbitrary point-in-time snapshot comparison use sf-snapshot-compare.
 triggers:
-  - "what broke"
+  - "what broke after the deploy"
   - "post-deploy regression"
-  - "since deploy"
+  - "since the last deploy"
   - "what changed since last sync"
   - "regression triage"
 tools_used:

package/skills/sf-wip-impact/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: sf-wip-impact
-description: Dry-run the impact of uncommitted local changes against the org graph before you commit.
+description: Dry-run the blast radius and test gaps for UNCOMMITTED local working-tree changes against the org graph — use before you commit. For committed PR/branch diffs use sf-impact-from-diff instead.
 triggers:
-  - "dry-run this change"
-  - "what would this PR do"
-  - "local impact"
-  - "uncommitted changes"
+  - "dry-run my local changes"
+  - "impact of my uncommitted changes"
   - "wip impact"
+  - "before I commit"
+  - "what would my working-tree changes affect"
 tools_used:
   - wip_impact
   - wip_test_gap