@ryanstark24/sfgraph-skills 1.1.4 → 1.6.0

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

@@ -1,6 +1,6 @@
 ---
 name: sf-governor-risk-fix
-description: Detect governor-limit risks (SOQL/DML in loops, unbounded queries) and produce a remediation checklist.
+description: Detect governor-limit risks (SOQL, SOSL and DML in loops, triggers that are not bulk-safe, unbounded queries) and produce a remediation checklist.
 triggers:
   - "governor limit"
   - "SOQL in loop"
@@ -17,24 +17,61 @@ 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.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
+## What the tool actually emits
+
+`governor_risk_check` reports only the risk types the analyzer can prove from
+the graph. Each record has `risk` (one of the kinds below), the method or trigger
+qname, and evidence (the query text or DML target):
+
+- **`soql_in_loop`** (high): a SOQL query whose `EXECUTES_SOQL` edge is tagged
+  `inLoop` (AST-verified: the query sits inside a for/while/do-while body).
+- **`sosl_in_loop`** (high): the same for SOSL (`EXECUTES_SOSL`).
+- **`dynamic_soql_in_loop`** (high): `Database.query(...)` inside a loop.
+- **`dml_in_loop`** (high): the same for DML statements.
+- **`no_bulk`** (high): a trigger that doesn't iterate `Trigger.new` (body-scan path).
+- **`unbounded_query`** (medium): a query with no `WHERE` and no `LIMIT`. Only the
+  body-scan path (project ingests, where the full query text is available) emits it;
+  live-org ingests do not, because the captured query head makes it pure noise.
+
+Medium and above are listed by default; `min_severity: "high"` keeps only the loop and
+bulk findings. `includeTests: true` adds test code. There is no class or namespace
+parameter: the tool scans the whole org, so filter its findings to the scope the user
+asked about, and say that you did.
+
+The check is per method: SOQL in a method that is *called* from a loop is not flagged.
+Say so when the user asks about a call chain.
+
+Do **not** promise non-selective queries, callouts in loops, heap size or trigger
+recursion: the tool does not check them.
+
+**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.
-4. Render the Mermaid heat-map (class-by-rule) from the tool response.
+1. Call `governor_risk_check` for the org, then keep the findings in the requested scope (a class, a namespace, or the whole org). Records are keyed on the **method** qname (`ApexMethod:Class.method(n)`) or the trigger, with `risk` (one of the six kinds above) and evidence (the query text or DML target).
+2. Group findings by `risk`; 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 a Mermaid heat-map (class-by-rule) yourself from the tool's table findings — `governor_risk_check` returns a table + structured data, not a diagram. See **Visualization**.
 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.
 
 ## Visualization
 
-Render a **`flowchart TD`** heat-map: rows are Apex classes (top N by fan-in), columns are rule ids. Cell colour encodes severity (high/medium/low). When the tool returns its own Mermaid heat-map, embed that and skip this template.
+Render a **`flowchart TD`** heat-map: rows are Apex classes (top N by fan-in), columns are rule ids. Cell colour encodes severity (high/medium/low). Build it yourself from the tool's findings — `governor_risk_check` returns a table, not a diagram.
 
 ```
 flowchart TD
-  ClassA -->|SOQL_IN_LOOP: high| Risk1[:::hi]
-  ClassA -->|UNBOUNDED_QUERY: med| Risk2[:::med]
-  ClassB -->|DML_IN_LOOP: high| Risk3[:::hi]
+  ClassA -->|soql_in_loop: high| Risk1[:::hi]
+  ClassA -->|unbounded_query: med| Risk2[:::med]
+  ClassB -->|dml_in_loop: high| Risk3[:::hi]
   classDef hi fill:#fcc,stroke:#900
   classDef med fill:#ffe6cc,stroke:#c60
 ```
@@ -43,6 +80,8 @@ If the scan returns >50 findings, render only the top-10-by-fan-in row and link
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `governor_risk_check`, invoke `staleness_check` for the target org. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
@@ -60,5 +99,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 (the six kinds above).
+- 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-plus-source/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: sf-graph-plus-source
+description: Use when you have file access AND sfgraph tools and the question is about references, flows, field usage, downstream reach or similar code. The graph gives the fast, complete-looking answer; this skill says what to double-check in the source before you finish, so graph speed and your own reading both count.
+triggers:
+  - "where is this used"
+  - "trace downstream"
+  - "analyze field"
+  - "cross layer"
+  - "find similar"
+tools_used:
+  - analyze_field
+  - cross_layer_flow_map
+  - trace_downstream
+  - find_similar
+---
+
+# sf-graph-plus-source
+
+The graph is the starting point, not the last word. Call the tool first, then spend a few file reads on the gaps below. Do not re-derive what the graph already returned.
+
+## Recipe: analyze_field / who reads or writes a field
+1. `analyze_field` for the field. Keep every component it lists.
+2. Grep the source once for the field's API name (`Field__c`). Add a component only if you see the name written in its source (Apex, Flow, LWC, Vlocity JSON). Skip profiles, layouts and permission sets.
+
+## Recipe: cross_layer_flow_map
+1. Call `cross_layer_flow_map` and keep its whole chain.
+2. Check each hop that crosses a layer boundary (LWC to Apex, Apex to Flow, Flow to Apex, OmniScript to Integration Procedure to DataRaptor). Grep for the hop's name; add a missing hop only when its source names the next component.
+
+## Recipe: trace_downstream
+1. Call `trace_downstream`. It is usually complete, and extras are the common error here.
+2. Do not add components from a grep. Only remove or flag one when the source shows it is only mentioned in a comment or string that is not a real reference. Remember objects, fields, validation rules and named credentials are leaves.
+
+## Recipe: find_similar
+1. Call `find_similar`. Open the top few hits and keep only those that do the same job (same inputs and effect), not just similar names.
+
+## Complete the set, then verify each layer
+Before you answer a "list every ..." question:
+1. Write the candidate list, each with its source: the tool, a grep hit, or a file you read.
+2. Go layer by layer (UI, Apex, Flow, OmniStudio, objects and fields) and confirm each candidate in that layer, or drop it with a reason.
+3. Compare your count with the count the tool states (the "Found N" line, the trace total, any "N hidden" note). If they differ, name the difference.
+4. Names built in strings (`'Obj__c'`, `put('Field__c', ...)`, a class name in a variable) can be missing from the graph. Grep for the name before you call the list complete.
+
+## Always
+- Say which parts came from the graph and which you confirmed in source.
+- If the two disagree, trust the source you actually read and say so in a short sentence.
+- Keep the answer plain: lead with the finding, then one short line per component.

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

@@ -0,0 +1,146 @@
+---
+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.
+
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
+## 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-*`, when installed; it is not part of sfgraph, so design directly if it is missing) to
+write the code. Ground → design → verify. Never design → hope.
+
+## When the graph doesn't hold what the analysis needs — pull it from the org
+
+The graph is **metadata structure**, not source code or record data. When an analysis
+genuinely needs something the graph doesn't store, fetch it — don't guess and don't analyse
+a stub. Two cases, with very different guardrails:
+
+- **Source code & metadata definitions (fetch freely).** The graph stores source for Apex
+  methods (`ApexMethod:…`), trigger bodies (`ApexTrigger:…`), and Flow definitions
+  (`Flow:…`) — but NOT whole classes, LWC JS, or managed/`(hidden)` code, and some metadata
+  isn't ingested. Get the real definition when you need more: read the
+  **local sfdx file** (`force-app/main/default/{classes,triggers,flows,objects}/…`) first, else
+  retrieve from the org (`sf project retrieve start -m "ApexTrigger:<Name>"` / `Flow:<Name>` /
+  `CustomObject:<Name>`, or Tooling `SELECT Body FROM ApexClass WHERE Name='…'`).
+- **CONFIG / metadata RECORDS (fetch when needed).** Custom Metadata records, Custom Setting
+  rows, picklist/record-type values, Named Credential config — these are deploy-time config,
+  not customer data. Pull them with `sf data query -q "SELECT … FROM <Type>__mdt"` (or the
+  setting `__c`, or Tooling for record types/picklists) when a trace/debug needs the value the
+  config resolves to. (1.4.0+ ingests CMDT/label/setting values into the graph, but older
+  graphs or un-ingested types may lack them — fetch then.)
+- **BUSINESS SObject records (the bounded EXCEPTION — pull minimally, with care).** sfgraph is
+  deliberately **local-first and metadata-only**; actual records (Account/Contact/Opportunity
+  rows, etc.) are out of the graph by design, and they are **real, possibly-PII customer data**.
+  Only when analysis truly requires it — e.g. to see a misbehaving field's real value shape or
+  confirm a data-skew assumption — pull a **small bounded sample**: always `LIMIT` (≤ a handful
+  of rows), prefer `COUNT()`/aggregates over raw rows, never bulk-dump, and **tell the user
+  you're stepping outside the local-first boundary to read live records**. If aggregates answer
+  the question, don't pull rows at all.
+
+State which source you used (graph / local file / org metadata / live records) so the reader
+knows the provenance and whether it left the local-only guarantee.
+
+## 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/trigger/Flow" | `sf-explain-code` (a class: explain its methods, `ApexMethod:Class.m(n)`) | — |
+| "Who calls / uses `<method/class>`" | `trace_upstream` on its qname (`depth: 1` for direct callers) | — |
+| "Which tests cover `<class>`" | `trace_upstream` with `rel_types: ["IS_TEST_FOR"]` | — |
+
+### 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` |
+| "Export findings for CI / code scanning (SARIF)" | `export_sarif` |
+
+When you also have the project's source files, follow **`sf-graph-plus-source`** after the tool call: it says which parts of a graph answer to double-check in the source.
+
+Most skills start with `staleness_check`. With `SFGRAPH_TOOLS=core` the server does not offer it (nor `list_orgs`, `snapshot_*` or `freshness_report`): skip those steps and say the graph's freshness was not checked.
+
+## 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

@@ -16,13 +16,17 @@ tools_used:
 
 # sf-impact-from-diff
 
-Use when the user wants to understand the downstream consequences of a pending change in their working tree (uncommitted or branch-vs-base) before merging.
+Use when the user wants to understand the downstream consequences of committed changes (a PR, a branch or a commit range) before merging. For uncommitted or staged work, use **sf-wip-impact**, which reads the working tree itself.
+
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
 
 ## Playbook
 
-1. Confirm the diff source: working tree, staged, or a branch range (e.g. `origin/main...HEAD`). If unspecified, default to staged + unstaged against the merge-base of `origin/main`.
-2. Call `impact_from_git_diff` with the resolved diff scope. Expect a list of changed metadata nodes plus their downstream dependents grouped by edge type (`READS_FIELD`, `CALLS_METHOD`, `INVOKES_FLOW`, `RENDERS_COMPONENT`, …).
-3. Call `test_gap_intelligence_from_git_diff` on the same diff scope. Cross-reference impacted nodes against existing Apex test coverage and surface the uncovered set.
+1. Get the diff text yourself: the tools take the unified diff as their `diff` argument and do not run git. Confirm the range with the user (a PR's base and head, a branch, or a commit range); if unspecified, use `git diff origin/main...HEAD`.
+2. Call `impact_from_git_diff(diff=…, depth=…)`. Expect a list of changed metadata nodes plus their downstream dependents grouped by edge type (`READS_FIELD`, `CALLS`, `FLOW_INVOKES_APEX`, `EMBEDS_LWC`, …).
+3. Call `test_gap_intelligence_from_git_diff` with the same `diff` text. Cross-reference impacted nodes against existing Apex test coverage and surface the uncovered set.
 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.
@@ -30,7 +34,7 @@ Use when the user wants to understand the downstream consequences of a pending c
 
 ## Visualization
 
-Render a **`flowchart LR`** impact graph. Changed nodes are leftmost (highlighted), first-degree dependents in the middle, transitive (depth >= 2) on the right. Edge style encodes edge type (`CALLS_METHOD`, `READS_FIELD`, `INVOKES_FLOW`, `RENDERS_COMPONENT`).
+Render a **`flowchart LR`** impact graph. Changed nodes are leftmost (highlighted), first-degree dependents in the middle, transitive (depth >= 2) on the right. Edge style encodes edge type (`CALLS`, `READS_FIELD`, `FLOW_INVOKES_APEX`, `EMBEDS_LWC`).
 
 ```
 flowchart LR
@@ -44,6 +48,8 @@ When the impact set exceeds 40 nodes, summarise per category and offer the user
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `impact_from_git_diff`, invoke `staleness_check` for the linked org. A stale graph will under-report dependents added since the last sync. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.

package/skills/sf-metadata-refresh/SKILL.md

@@ -18,12 +18,16 @@ tools_used:
 
 Use when the user asks whether their sfgraph data is current, how to refresh it, or wants to see both graph staleness and org-side dead-metadata freshness.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
 1. Call `staleness_check` for the target org. Report the exact age in days and whether it's stale.
-2. If stale, call `start_ingest_job` — it does NOT run the ingest. It returns
-   `{ executed: false, run_this_command: "sfgraph ingest --org <alias>" }`.
-   Surface that command verbatim to the user. Do not promise the MCP server
+2. If stale, call `start_ingest_job`. It does NOT run the ingest: its report says
+   nothing was started and shows the command to run (for example
+   `sfgraph ingest --org <alias>`). Surface that command verbatim to the user. Do not promise the MCP server
    will run it. After the user has executed the ingest in a shell, MCP tools
    will see the new data on their next invocation.
 3. Suggest the right shape of the command for their situation:
@@ -54,6 +58,8 @@ Pair it with the bucketed freshness table from `freshness_report` for the org-si
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 `staleness_check` _is_ the first step here — the whole skill is the staleness check. If `staleness_check` returns `stale=false`, still continue to `freshness_report` so the user sees the org-side picture.
 
 ## Response Shape

package/skills/sf-omnistudio-migration-audit/SKILL.md

@@ -8,6 +8,8 @@ triggers:
   - "omnistudio audit"
   - "migrate from vlocity"
 tools_used:
+  - find_nodes
+  - trace_downstream
   - cross_org_diff
   - staleness_check
 ---
@@ -16,11 +18,17 @@ tools_used:
 
 Use when the user is mid-migration from Vlocity CMT (managed package) to OmniStudio on Core and wants to verify parity by category.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
-1. Enumerate Vlocity-CMT node categories present in the graph: `vlocity_cmt__DataRaptor`, `vlocity_cmt__IntegrationProcedure`, `vlocity_cmt__OmniScript`, `vlocity_cmt__VlocityCard`.
-2. Enumerate the OmniStudio-on-Core equivalents: `OmniDataTransform`, `OmniIntegrationProcedure`, `OmniProcess` (OmniScript), `OmniUiCard`.
-3. For each pair, count nodes on both sides and count `CANONICAL_OF` edges that mirror a CMT asset to its OmniStudio twin. Report `cmt_count`, `core_count`, `canonical_pairs`, `unmirrored_cmt`, `unmirrored_core`.
+No tool computes these counts; you build them from `find_nodes` and `trace_downstream` results, and say so. The graph labels are the same whatever the org's namespace (there is no `vlocity_cmt__` prefix on a label).
+
+1. List the Vlocity-CMT assets with `find_nodes(label=…)` for each of `DataRaptor`, `IntegrationProcedure`, `OmniScript` and `VlocityCard`. Raise `limit` until the result is not truncated.
+2. List the OmniStudio-on-Core twins the same way: `OmniDataTransform`, `OmniIntegrationProcedure`, `OmniProcess` (OmniScript) and `OmniUiCard`. The pairs are DataRaptor ↔ OmniDataTransform, IntegrationProcedure ↔ OmniIntegrationProcedure, OmniScript ↔ OmniProcess, VlocityCard ↔ OmniUiCard.
+3. For each CMT asset, `trace_downstream(qname, depth=1, rel_types=["CANONICAL_OF"])` finds its twin (the edge is written both ways when the names match). With many assets, check a sample and say so. Per pair of labels, report the CMT count, the Core count, the mirrored pairs, and the unmirrored assets on each side.
 4. If the user provided two orgs (typically a CMT-only sandbox vs an OmniStudio-on-Core sandbox), call `cross_org_diff` to highlight assets present in one and not the other.
 5. Bucket findings:
    - **fully migrated** — pair exists, `CANONICAL_OF` edge present, no logic drift.
@@ -35,13 +43,13 @@ Render a **`flowchart LR`** parity diagram. Left subgraph is Vlocity-CMT; right
 ```
 flowchart LR
   subgraph CMT
-    D1[vlocity_cmt__DataRaptor:Foo]
+    D1[DataRaptor:Foo]
   end
   subgraph Core
     D2[OmniDataTransform:Foo]
   end
   D1 -. CANONICAL_OF .-> D2
-  D3[vlocity_cmt__OmniScript:Bar]:::unmirrored
+  D3[OmniScript:Bar]:::unmirrored
   classDef unmirrored stroke-dasharray:4 4,fill:#fdd
 ```
 
@@ -49,6 +57,8 @@ For orgs with >50 CMT assets, swap the diagram for a per-category counts table
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before running the audit, invoke `staleness_check` for each org in scope. A stale ingest means recently-created CANONICAL_OF edges or new OmniStudio twins are missing, which inflates the "not started" bucket. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.

package/skills/sf-schema-overview/SKILL.md

@@ -19,14 +19,18 @@ tools_used:
 
 Use when the user wants a high-level picture of the data model — which objects exist in a domain, how they connect via Lookup/MasterDetail, and which Apex/Flow/LWC artifacts depend on them.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
 1. Identify the focal object(s) from the user's question. If they named a domain ("the Order schema"), pick the lead object and include its first-degree neighbours.
 2. Call `staleness_check` for the org. Warn if stale.
-3. For each focal object, call `trace_downstream` with `qname=CustomObject:<name>` to enumerate Lookup/MasterDetail references coming out of it.
+3. For each focal object, call `trace_downstream(qname="CustomObject:<name>", depth=2, rel_types=["DEFINES_FIELD", "REFERENCES_OBJECT"])`. A relationship shows up as two hops: the object defines a lookup field, and the field references the target object (`CustomObject:Invoice__c` → `CustomField:Invoice__c.Account__c` → `CustomObject:Account`). For relationships pointing **into** an object, call `trace_upstream(qname="CustomObject:<name>", depth=1, rel_types=["REFERENCES_OBJECT"])`: it lists the lookup fields on other objects.
 4. Call `trace_upstream` for the same object to find what depends on it (Apex selectors, Flows, LWCs, layouts).
 5. If the user named a specific field, call `analyze_field` to get its readers/writers and a precise role description.
-6. Produce an ERD-like diagram with one entity per object and relationship lines for each Lookup/MasterDetail edge.
+6. Produce an ERD-like diagram with one entity per object and one relationship line per lookup field. The report does not say whether a relationship is a Lookup or a Master-Detail: read the field's metadata (`objects/<Object>/fields/<Field>.field-meta.xml`, `<type>`) when the cardinality matters, or draw it as a plain relationship and say so.
 
 ## Visualization
 
@@ -43,6 +47,8 @@ When the schema has >20 entities, prune to the focal object's two-hop neighbourh
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before tracing, invoke `staleness_check` for the org. New custom objects/fields and recently-added relationships are invisible in a stale graph. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.

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

@@ -18,14 +18,20 @@ tools_used:
 
 Use when the user asks about who can read or write a field/object, what sharing rules apply, or whether FLS / CRUD is consistent with intent.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## 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.
-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.
-6. Render the Mermaid access matrix returned by the tool.
+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 field access matrix: for one field, the report lists every profile and permission set that grants read or edit ("Granted by"); a profile or permission set whose entry denies access is not counted. Run the audit per field you need in the matrix.
+4. Report sharing exposure from what the tool returns: the sharing rules that give edit or full access. The tool does **not** report org-wide defaults, the role hierarchy, object CRUD per profile, or `without sharing` Apex; say so, and check those in the source or the org if the user needs them (label them as not graph-confirmed).
+5. Flag risks you can back with evidence: full-access sharing rules and FLS gaps from the tool; `without sharing` classes, missing `stripInaccessible` / `WITH SECURITY_ENFORCED`, guest user and Experience Cloud reach only from source you read.
+6. Render the access matrix as Mermaid yourself from the report's "Granted by" lists. The tool does not draw a diagram. See **Visualization** below.
 
 ## Visualization
 
@@ -43,6 +49,8 @@ When more than 25 Profiles/PSets have access, collapse to a count table and only
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `security_audit`, invoke `staleness_check` for the target org. Permission set/profile assignments change frequently; a stale graph misrepresents access. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.

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

@@ -18,6 +18,10 @@ tools_used:
 
 Use when the user wants to compare two named points in time — typically a pre-deploy checkpoint vs current, or two milestone snapshots taken during a release.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
 1. Call `snapshot_list` for the org. Present available snapshots with their `id`, `label`, `createdAt`, and `kind` (auto/manual).
@@ -45,6 +49,8 @@ If `gitGraph` isn't supported by the client, fall back to a small **`flowchart L
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `point_in_time_diff` with `to='current'`, invoke `staleness_check` for the org. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.

package/skills/sf-web-explorer/SKILL.md

@@ -7,7 +7,8 @@ triggers:
   - "open the web view"
   - "see the relationships visually"
   - "render the whole org"
-tools_used: []
+tools_used:
+  - staleness_check
 when_to_use: Visual exploration of an ingested org. Pairs with `analyze_field`, `trace_upstream`, `trace_downstream`, and `cross_layer_flow_map` when the markdown answers are not enough and the user wants to click around.
 ---
 
@@ -17,6 +18,10 @@ The MCP tool surface is great for answering specific questions, but sometimes th
 
 This skill does not call any MCP tool. It instructs the user how to launch the viewer and what to do once it's open.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
 1. Confirm the org has been ingested (use `staleness_check` if uncertain).