@ryanstark24/sfgraph-skills 1.1.0 → 1.1.4

package/dist/__tests__/installer.test.js

@@ -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(15);
+        expect(results.length).toBe(16);
         const cursorDir = join(home, ".cursor", "rules");
         const files = readdirSync(cursorDir);
         expect(files.every((f) => f.endsWith(".mdc"))).toBe(true);
-        expect(files.length).toBe(15);
+        expect(files.length).toBe(16);
         // 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(15);
-        expect(cursorCount).toBe(15);
-        expect(vscodeCount).toBe(15);
+        expect(claudeCount).toBe(16);
+        expect(cursorCount).toBe(16);
+        expect(vscodeCount).toBe(16);
         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.0",
+  "version": "1.1.4",
   "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"

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
@@ -22,7 +23,7 @@ Use when the user wants to inventory metadata that appears unreferenced. Output
 
 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.).
 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-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
@@ -58,6 +61,18 @@ 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.

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-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-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